The states
On the ad chain, an order moves through these states:Disputed differ on purpose. The evidence path runs the real settlement and ends in Filled.
A ruling, or the no-ruling default, publishes no proof and ends in Resolved.
Who can file, and when
Only the trade’s two parties, the Maker and the Bridger, can file. They file on the ad chain (AdManager.dispute), while the trade is locked or a
cancel has started, and before the cancel window ends.
Filing does three things: it posts a bond, records the filer’s
evidence, and stops the cancel from completing while the dispute is
open. It pays nobody and decides nothing.
The other party can answer once (respondToDispute), with their own
evidence, before the challenge deadline.
The bond
The bond is a flat amount in the chain’s wrapped native token, the same for every order on the route. On soak it’s 0.001 WETH on Sepolia and 1 XLM on Stellar.Evidence
Evidence is a set of files uploaded to the evidence store. The filing records the hash of its manifest on-chain, so the evidence can’t be changed after filing. Evidence that the trade settled always wins. A co-signed payout, or a proof that the trade settled on the other chain, ends a dispute as settled at any time while it’s open. A dispute can delay a settlement only until someone presents that proof. The co-signed payout counts as evidence too. It goes through on a disputed trade and closes the dispute in the same transaction, so a bond can’t hold a fully signed trade hostage, not even for one round.Rulings
When there’s no proof of settlement, the arbiter service rules. It can rule one of three outcomes: mutual refund, bridger forfeit or maker forfeit. It can’t rule that the trade settles; only evidence can do that. A ruling doesn’t pay out at once. It opens a short window in which proof of settlement still overrides it. After that, anyone can finalize the dispute (finalizeDispute), and the ruling applies.
If no ruling arrives by the challenge deadline, the dispute ends as a
mutual refund. Nothing waits on the arbiter service showing up.
The challenge deadline is the later of the filing time plus the challenge
period (1 hour on soak) and the end of the order’s cancel window.
The four outcomes
The ad chain records each outcome as a leaf the order chain acts on: a
settled leaf, a cancel leaf for a mutual refund or maker forfeit, or a
forfeit leaf for a bridger forfeit.
Where the bond goes
The bond returns to the filer when the outcome was on their side:
One exception: a Bridger who filed because the Maker blocked a co-signed
payout gets the bond back even if the trade then settles.
The nullifier
When evidence ends a dispute, the real payout runs and uses up its nullifier, as in a normal settlement. A ruling publishes no proof, so there is no nullifier to use up. The finalResolved status is what stops the trade from
being settled again.
How it’s tested
The two chains implement disputes separately, in Solidity and in Soroban. One shared set of scenarios runs on both, and each scenario names the result it expects: the final status, the leaf the ad chain writes, and where the bond goes. If the two chains ever disagreed on any of these, a named test would fail; it wouldn’t wait to show up on a live trade. The end-to-end suites also run disputes on local chains, including a ruling overridden by evidence.What the relayer does
The relayer has no dispute authority. When a dispute is filed, it first checks whether the trade settled on the other chain, and if so presents that proof. Otherwise it prepares a case file for the arbiter service. Its only writes are the permissionless calls anyone could send, such asfinalizeDispute and presentSettled.