Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Dispute state machine · Boson Protocol
Skip to content

Dispute state machine

A dispute is the side state machine that runs when an exchange is contested. Once raised, the parent exchange sits in DISPUTED until the dispute terminates.

State table

StateWho transitions outToAction
RESOLVINGBuyerRETRACTEDretractDispute(exchangeId) — buyer gives up
RESOLVINGBoth, mutual EIP-712RESOLVEDresolveDispute(exchangeId, buyerPercent, sigB, sigS)
RESOLVINGBuyer (after window)ESCALATEDescalateDispute(exchangeId)
RESOLVINGAnyoneEXPIREDexpireDispute(exchangeId)
ESCALATEDDRDECIDEDdecideDispute(exchangeId, buyerPercent)
ESCALATEDDRREFUSEDrefuseEscalatedDispute(exchangeId)
ESCALATEDBuyerRETRACTEDretractDispute(exchangeId) — buyer gives up
ESCALATEDBoth, mutual EIP-712RESOLVEDresolveDispute(exchangeId, buyerPercent, sigB, sigS)
ESCALATEDAnyoneREFUSEDexpireEscalatedDispute(exchangeId)

Funds movement on terminal state

TerminalBuyer getsSeller getsDR gets
RETRACTEDnothing (gives up)price + their deposit backnothing
RESOLVEDbuyerPercent of escrowrestnothing
DECIDEDbuyerPercent of escrowresttheir fee
REFUSEDfull escrow (price + escalation fee)their deposit backnothing
EXPIRED (from RESOLVING)nothingprice + their depositnothing

Where to look in code

SurfaceWhere
ContractsDisputeHandlerFacet
Core SDKDisputes mixin
MCPraise_dispute, retract_dispute, resolve_dispute, escalate_dispute, decide_dispute, refuse_escalated_dispute, expire_dispute(_batch), expire_escalated_dispute, extend_dispute_timeout, create_dispute_resolution_proposal

Common footguns

  • Mutual resolution requires signatures from both buyer and seller. EIP-712 typed-data. See Signing & meta-transactions.
  • DR fees come out of the escrow on DECIDED, but are refunded to the buyer on REFUSED. Plan UX accordingly.
  • The dispute machine doesn't reset the exchange. Once a dispute terminates, the parent exchange goes to COMPLETED (or stays in a terminal state mirroring the dispute outcome) — read both states when reconstructing history.

Next