Dispute Resolution

What happens when an asset is contested — and exactly how much of that is built today.

How a dispute works today

A dispute on TAG IT is not a support ticket, and there is no case-filing API. The only dispute mechanism that exists is a lifecycle state on the TAGITCore contract: an asset can be moved into FLAGGED, moved back out by resolvers, or retired permanently. That is the entire surface: flag, batchFlag, approveResolve, resolve and recycle, all on one contract.

The FLAGGED state

Assets move through a seven-state lifecycle. FLAGGED (state 5) is the dispute state, and it is the only state that can move backwards.

The transitions a dispute can take:

{BOUND | ACTIVATED | CLAIMED}  --flag()-->      FLAGGED
FLAGGED                        --resolve()-->   the EXACT pre-flag state
{any live state}               --recycle()-->   RECYCLED  (terminal)

resolve() does not blindly return an asset to CLAIMED. The contract records the state held immediately before the flag and restores that exact state, so a flag followed by a resolve is state-neutral and cannot be used to skip a forward transition such as claim().

Step 1: Read an asset's dispute status

This is the part that works right now, for anyone, with no key and no account. Reads are open. The snippet below runs as written against Base Sepolia.

import { createPublicClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';

// TAGITCore proxy on Base Sepolia (chainId 84532)
const TAGIT_CORE = '0x3aDc7EFDb58Ae85483eFf5D4966D916185f31d1D';

const coreAbi = [
  {
    type: 'function',
    name: 'getAsset',
    stateMutability: 'view',
    inputs: [{ name: 'tokenId', type: 'uint256' }],
    outputs: [
      { name: 'assetOwner', type: 'address' },
      { name: 'timestamp', type: 'uint64' },
      { name: 'state', type: 'uint8' },
      { name: 'flags', type: 'uint8' },
      { name: 'reserved', type: 'uint16' }
    ]
  },
  {
    type: 'function',
    name: 'getResolveApprovalStatus',
    stateMutability: 'view',
    inputs: [{ name: 'tokenId', type: 'uint256' }],
    outputs: [
      { name: 'approvalCount', type: 'uint256' },
      { name: 'recipient', type: 'address' },
      { name: 'quorumReached', type: 'bool' }
    ]
  }
];

const STATES = ['NONE', 'MINTED', 'BOUND', 'ACTIVATED', 'CLAIMED', 'FLAGGED', 'RECYCLED'];

const client = createPublicClient({
  chain: baseSepolia,
  transport: http('https://sepolia.base.org')
});

async function checkDisputeStatus(tokenId) {
  const [assetOwner, timestamp, state] = await client.readContract({
    address: TAGIT_CORE,
    abi: coreAbi,
    functionName: 'getAsset',
    args: [tokenId]
  });

  console.log('owner:      ', assetOwner);
  console.log('state:      ', state, `(${STATES[state]})`);
  console.log('last change:', new Date(Number(timestamp) * 1000).toISOString());

  if (state !== 5) {
    console.log('disputed:    no — asset is not FLAGGED');
    return;
  }

  const [approvalCount, recipient, quorumReached] = await client.readContract({
    address: TAGIT_CORE,
    abi: coreAbi,
    functionName: 'getResolveApprovalStatus',
    args: [tokenId]
  });

  console.log('disputed:    yes — FLAGGED, awaiting resolver approvals');
  console.log('approvals:  ', approvalCount, 'of 2 required');
  console.log('recipient:  ', recipient);
  console.log('resolvable: ', quorumReached);
}

await checkDisputeStatus(50n);

Actual output for token 50, run on 26 July 2026:

owner:       0x458B4d0c3a55006965Fd13D6af7B8509De51Cb3D
state:       4 (CLAIMED)
last change: 2026-07-16T23:56:24.000Z
disputed:    no — asset is not FLAGGED

If you would rather not write code, the same state is rendered by the public verification pages on verify.tagit.network: /asset/<tokenId> for a token (check an asset on-chain), /tag/<uid> for a chip UID, and /01/<gtin>/21/<serial> for a GS1 identifier.

Step 2: Flagging a contested asset

Flagging is capability-gated. TAGITCore.flag(uint256 tokenId) requires the calling address to hold the FLAGGER capability in TAGITAccess (0xb56A1D91995C212342FaA843468F03521340A1D6); the capability id is uint256(keccak256("FLAGGER")). A call from any other address reverts. There is no public "report this item" transaction, and the current owner of an asset cannot flag it unless they separately hold the badge.

The related functions on TAGITCore:

You can check whether an address is allowed to flag or resolve before you try. Replace 0xYOUR_WALLET_ADDRESS with the address you want to test — the rest runs as written:

import { createPublicClient, http, keccak256, toBytes } from 'viem';
import { baseSepolia } from 'viem/chains';

const TAGIT_ACCESS = '0xb56A1D91995C212342FaA843468F03521340A1D6';

const accessAbi = [
  {
    type: 'function',
    name: 'hasCapability',
    stateMutability: 'view',
    inputs: [
      { name: 'account', type: 'address' },
      { name: 'capabilityId', type: 'uint256' }
    ],
    outputs: [{ type: 'bool' }]
  }
];

// TAGITCore derives capability ids as uint256(keccak256("<NAME>"))
const FLAGGER = BigInt(keccak256(toBytes('FLAGGER')));
const RESOLVER = BigInt(keccak256(toBytes('RESOLVER')));

const client = createPublicClient({
  chain: baseSepolia,
  transport: http('https://sepolia.base.org')
});

async function canDispute(address) {
  const [canFlag, canResolve] = await Promise.all([
    client.readContract({ address: TAGIT_ACCESS, abi: accessAbi, functionName: 'hasCapability', args: [address, FLAGGER] }),
    client.readContract({ address: TAGIT_ACCESS, abi: accessAbi, functionName: 'hasCapability', args: [address, RESOLVER] })
  ]);

  console.log(address);
  console.log('  can flag():   ', canFlag);
  console.log('  can resolve():', canResolve);
}

await canDispute('0xYOUR_WALLET_ADDRESS');

Mass-flagging protection

Flagging is rate-limited on chain (NIST IR-4 circuit breaker). The flag that reaches the threshold within the window trips the breaker, and every flag after that reverts with CircuitBreakerCooldown until the cooldown expires; batchFlag counts per item, so batching cannot be used to slip past it. Two read-only views expose the current position, and both are open to anyone:

# Is the breaker tripped, and how long until it resets?
cast call 0x3aDc7EFDb58Ae85483eFf5D4966D916185f31d1D \
  "getFlagCircuitBreakerStatus()(bool,uint256)" \
  --rpc-url https://sepolia.base.org
# false
# 0

# How many more flags fit in the current window?
cast call 0x3aDc7EFDb58Ae85483eFf5D4966D916185f31d1D \
  "getFlagCircuitBreakerCapacity()(uint256)" \
  --rpc-url https://sepolia.base.org
# 50

If you are not a badge holder

There is no self-service route to obtain a FLAGGER badge, and no queue that turns a consumer report into an on-chain flag. If you believe a tagged asset is stolen or counterfeit, raise it with the brand or issuer that tagged it — they hold the capability. For pilot access to write functions, get in touch.

Step 3: Resolving a flag

Coming back out of FLAGGED takes two transactions from two different resolvers, then a third to execute. All three require the RESOLVER capability.

1. approveResolve(uint256 tokenId, address newOwner) — a resolver approves a recipient. The first approver fixes the recipient for that round; any later approver must pass the identical address or the call reverts with RecipientMismatch. No resolver can approve twice in the same round.
2. A second resolver repeats the call with the same newOwner. The quorum constant RESOLVE_QUORUM is 2 — read it yourself from the contract.
3. resolve(uint256 tokenId, address newOwner) — executes once quorum is met. It restores the exact pre-flag state, updates the owner, clears the approvals and bumps the round nonce so stale approvals cannot be reused.

Two rules on newOwner are worth knowing before you design around this:

• For a consumer asset (pre-flag state CLAIMED), the asset is reassigned to the recipient the resolvers approved. This is the lost/stolen recovery path.
• For a manufacturing-phase asset (pre-flag state BOUND or ACTIVATED), newOwner must equal the current owner. Resolvers cannot redirect unsold inventory to a third party.

Progress is public. getResolveApprovalStatus(uint256) returns (approvalCount, recipient, quorumReached) — it is the second read in the Step 1 snippet, and for token 50 it currently returns 0, the zero address, and false, because that asset is not currently flagged.

Events to watch

There are no dispute webhooks. If you need to react to a flag, subscribe to contract logs on Base Sepolia. These are the three events the flag and resolve paths emit, exactly as declared in TAGITCore:

event StateChanged(uint256 indexed tokenId, State from, State to, address actor);

event ResolveApproved(uint256 indexed tokenId, address indexed approver, uint256 approvalCount);

event CustodyTransfer(
    uint256 indexed assetId,
    uint8 fromState,
    uint8 toState,
    address indexed fromOwner,
    address indexed toOwner,
    uint256 timestamp,
    bytes32 prevStateHash
);

State is a Solidity enum, so it appears as uint8 in the ABI. CustodyTransfer.prevStateHash links each transition to the previous one, which is what makes the flag/resolve history a verifiable chain rather than a list of independent events.

AIRP recovery cases — deployed, not yet connected

TAGITRecovery, the AIRP (AI Recovery Protocol) contract, is live on Base Sepolia at 0x6BC3C69367E586810A3B317fA9F0406504e95866. It implements a staked, badge-weighted voting process over recovery cases. Its on-chain parameters, read from the deployment on 26 July 2026:

# Verify those numbers yourself
cast call 0x6BC3C69367E586810A3B317fA9F0406504e95866 \
  "nextCaseId()(uint256)" --rpc-url https://sepolia.base.org
# 1

cast call 0x6BC3C69367E586810A3B317fA9F0406504e95866 \
  "minimumStake()(uint256)" --rpc-url https://sepolia.base.org
# 100000000000000000000 [1e20]

The three gaps

These are why the contract is not usable as a dispute system yet. Each is verifiable in the source and on chain:

• Resolution does not move the asset. executeResolution() settles the stake bond and closes the case. The source carries an explicit note where the transfer would go: "In production, this would call TAGITCore.resolve() to transfer the NFT to the claimant." It does not call it.
• The contract holds no lifecycle capability. TAGITAccess.hasCapability() returns false for the recovery contract on both FLAGGER and RESOLVER, so it could not flag or resolve an asset even if the call were wired in.
• Quarantine is bookkeeping only. isQuarantined(tokenId) is internal to the recovery contract. TAGITCore contains no reference to it and never consults it, so a quarantined asset is not restricted on chain.

Until those are closed, the authoritative dispute path is the one in Step 2 and Step 3: flag, two approveResolve calls, then resolve, all on TAGITCore. When AIRP is connected, this page will document it with a working example — not before.

What does not exist yet

Named plainly, so nobody plans a sprint around it:

What to do today

• Read the state before you trust a claim. getAsset is keyless, free and authoritative about what the ledger holds. State 5 means a badge holder has flagged the asset; state 6 means it is retired for good.
• Insist on a tap, not a link. Only a physical NFC read produces the picc and cmac pair the verification endpoint accepts. A QR code or URL that merely points at a token ID proves nothing about the object.
• Index the events. StateChanged and CustodyTransfer are the audit trail. prevStateHash chains them, so a gap or a fork is detectable.
• Keep the capability set small. FLAGGER and RESOLVER are the whole security model for disputes. The two-approval quorum with a matching recipient is what prevents a single compromised resolver from redirecting an asset — it only helps if the two resolvers are genuinely separate parties.
• Resolve before you recycle. One restores the asset to the state it held before the flag; the other ends it permanently.
• Do not settle real value on this. Base Sepolia is a testnet and the contracts are unaudited.