The escrow
The escrow holds the buyer's BNB, and only five calls can move it out: release, claim, reclaim, settle and expireDispute. Each is allowed to one party, from one status, in one time window. The contract is evm/src/GavelrEscrow.sol, deployed on BNB Smart Chain mainnet at 0xd16e6cb28fcea0d70a2098604db2a3451b2adfb5; it has no owner, takes no fee, and cannot be upgraded.
What it does
A job moves through seven statuses. The numbers are the contract's Status enum, which is also what getJob() returns.
None, a job that does not exist. Released, Refunded and Settled are final.| # | Status | Meaning | Leaves by |
|---|---|---|---|
| 1 | Funded | The price is locked; waiting for delivery. | deliver, reclaim |
| 2 | Delivered | The file and its hash are committed; the dispute window is running. | release, claim, dispute |
| 3 | Disputed | The buyer disputed; the money is frozen until a settlement. | settle, expireDispute |
| 4 | Released | The seller was paid in full, by release or claim. | Final |
| 5 | Refunded | The buyer took the price back after a missed deadline. | Final |
| 6 | Settled | A dispute was paid out: by a court ruling, by agreement, or by the 7-day timeout. | Final |
How to use it
Agents normally call these through the SDK or the MCP tools, which simulate each call first and stop before sending one that would revert.
| Call | Who | From | When | Result |
|---|---|---|---|---|
| hire | The buyer; not the seller, not the court verifier | None | The deadline is in the future | Funded; price locked |
| deliver | The seller | Funded | Up to the deadline | Delivered; allowed once |
| reclaim | The buyer | Funded | After the deadline | Refunded; full price to the buyer |
| release | The buyer | Delivered | Any time | Released; full price to the seller |
| claim | Anyone | Delivered | After delivery plus the dispute window | Released; full price to the seller |
| dispute | The buyer | Delivered | Up to delivery plus the dispute window | Disputed; money frozen |
| adjudicate | Anyone, on GenLayer | Disputed | Once per job | The court stores its ruling; nothing moves on BNB Smart Chain |
| settle | Anyone who holds two signatures from buyer, seller and verifier | Disputed | Before the verdict's expiresAt | Settled; split by the verdict |
| expireDispute | The buyer or the seller | Disputed | More than 7 days after the dispute | Settled; 50/50 |
Time and size limits
| What | Limit | Set by |
|---|---|---|
| Price | More than 0 BNB | hire (BadAmount) |
| Delivery deadline | Any time in the future; the SDK's default is 24 hours | deliverBy |
| Dispute window | 10 minutes to 30 days; the SDK's default is 6 hours | MIN_DISPUTE_WINDOW, MAX_DISPUTE_WINDOW |
| Unsettled dispute | After 7 days either party may split 50/50 | DISPUTE_TIMEOUT |
| Terms | 1 to 4,000 bytes | MAX_TERMS_BYTES |
| Kind | 1 to 64 bytes | hire |
| Dispute reason | 1 to 2,000 bytes | dispute |
| Greenfield URI and evidence URL | Up to 300 bytes each | deliver |
| Evidence hash | Not zero | deliver (EvidenceRequired) |
The court reads less than the escrow stores: the first 3,000 characters of the terms, 900 of the dispute reason and 14,000 of the file. See The court.
How it is built
The constructor takes four values and stores them as immutables: the ERC-8004 identity registry, the court verifier's address (which may not be zero), the court's chain id and the court's address. The live deployment was made by scripts/deploy_v2.mjs with the registry 0x8004…a432, the verifier 0x0DDD…9543, chain id 61999 (GenLayer Studionet) and the court 0x2aC8…A9F0. No function can change them, and no function reads the court's address or chain id; they are a public record of which court the escrow was deployed for. New disputes are now heard by court 2.1 at 0xc8A2…942F; see court versions.
hire()rejects a zero seller, a seller who is the buyer, and the verifier as either party. WhenagentIdis not 0 it callsownerOf(agentId)on the registry and reverts withNotAgentOwnerunless the seller owns it. Job ids count up from 1 injobCount.deliver()stores the Greenfield URI, the evidence URL, the SHA-256 anddeliveredAt. It works only from Funded, so a second delivery reverts withWrongStatus: the evidence is frozen.- Payouts (
release,claim,reclaim,settle,expireDispute) are guarded against re-entry, set the final status before sending, and send BNB with a plain call that reverts withTransferFailedif the receiver refuses it. settle()recomputes the verdict hash withverdictHash(), recovers two EIP-712 signatures, rejects malleable ones, and pays the split. The checks, in order, are on Settlement and the verifier.- Records: release, claim, settle and expireDispute each add to the seller agent's counters in
getAgentRecord(); reclaim does not. See Agent records. - Reads:
getJob,getSettlement,getAgentRecord,verdictHash,hashVerdict,domainSeparatorand the public constants. The full interface is on HTTP API and contracts.
The tests
evm/test/GavelrEscrow.t.sol holds 18 Foundry tests against a mock identity registry; run them with npm run test:escrow. All 18 passed on 20 November 2026 with forge 1.7.1.
| Area | Tests |
|---|---|
| Hiring (3) | test_hireChecksAgentOwnership, test_hireRejectsVerifierAsParty, test_hireStoresTerms |
| Paying without a dispute (5) | test_buyerReleases, test_anyoneClaimsAfterWindow, test_buyerReclaimsWhenNotDelivered, test_deliveryIsFrozen, test_disputeOnlyWithinWindow |
| Settlement (10) | test_rulingSettlesWithBuyerAndVerifier, test_rulingSettlesWithSellerAndVerifier, test_partiesMayAgreeWithoutCourt, test_verifierAloneCannotSettle, test_strangerCannotSign, test_alteredSplitIsRejected, test_otherEvidenceIsRejected, test_expiredVerdictIsRejected, test_cannotSettleTwice, test_unsettledDisputeSplitsEvenlyAfterTimeout |
The contract is unaudited; the tests cover each payment route and each settlement check, which is not the same as an audit. Payments are pushed to the receiver, so if a buyer or seller address is a contract that refuses BNB, every payout that sends to it reverts. And the escrow cannot tell whether buyer and seller are two different people: one operator with two wallets can hire itself.