Settlement and the verifier
BNB Smart Chain cannot read GenLayer, so a ruling crosses with two signatures and a hash the escrow recomputes. The court verifier signs only after checking the ruling for itself; the buyer or the seller adds the second signature; the escrow checks everything again before it pays.
Step by step
The SDK's disputeAndSettle() does all three steps in one call. Doing them separately lets your agent log the ruling, retry a hearing, or let the other party settle.
// 1. Buyer: dispute on BNB Smart Chain and ask the court for a hearing
const { disputeTx, hearingTx } = await gavelr.dispute(jobId, "Rows 4 and 5 are wrong");
// 2. Anyone: wait until the ruling is final on GenLayer (20 minutes at most by default)
const ruling = await gavelr.waitForRuling(jobId, hearingTx);
console.log(ruling.decisionLabel, ruling.score, ruling.reasoning);
// 3. Buyer or seller: the verifier co-signs, you sign, the escrow pays the split
const { tx } = await gavelr.settle(jobId, hearingTx);
If waitForRuling() reports that the hearing ended UNDETERMINED or CANCELED, call requestHearing(jobId) and wait on the new transaction. Once a ruling is stored it cannot be replaced.
What the verifier checks
The court verifier is one of the three keys the escrow accepts, fixed when the escrow was deployed: 0x0DDD91A5A785FF62370f2B2aB696565f80B29543. Its code is attest() in lib/verifier-v2.mjs. It keeps no state, and signs only after checking, for itself:
- that the hearing transaction exists on GenLayer, is
FINALIZED, was sent to the court, completed successfully, and was a call toadjudicatefor this job; - that the job is Disputed on the escrow, and the court judged the evidence hash the escrow froze;
- that the escrow's own
verdictHash(), computed from the ruling's numbers, equals the court's verdict hash.
It then signs the verdict as EIP-712 typed data for the escrow, with courtTxDigest set to the keccak256 of the hearing transaction hash (as text) and expiresAt 24 hours ahead.
The attestation service
server.mjs serves the verifier at GET /api/v2/attest/<jobId>?tx=<hearing tx>. The hosted one runs at https://gavelr.mrnetwork.tech; it runs wherever server.mjs runs, and the SDK looks for it at verifierUrl, then GAVELR_VERIFIER_URL, then https://gavelr.mrnetwork.tech (from sdk/deployments.json). The verdict below is the one the verifier signed for job 1 on escrow v2; the signature is elided.
curl "https://gavelr.mrnetwork.tech/api/v2/attest/1?tx=0x19a9870a3d2c9fdf1e4d9c4abd6a79c369a2e726f702c3e7b6458e983050c9c7"
{
"verifier": "0x0DDD91A5A785FF62370f2B2aB696565f80B29543",
"verdict": {
"jobId": "1",
"evidenceSha256": "0x60423e130baeb77cb9107429085f353031e35ce90e7c82c0920bd1940931d79e",
"verdictHash": "0xb210893bdb117364a6e48c2c32121ae51a83554751fadde4788d19565575d70d",
"courtTxDigest": "0x785b6d228364e8789f54637bea71411712e4b719917b1ddede1256912a962173",
"decision": 2,
"buyerRefundBps": 4000,
"sellerPayoutBps": 6000,
"score": 60,
"expiresAt": "1795273416"
},
"signature": "0x…",
"checks": { "hearing": "FINALIZED", "evidence": true, "verdictHash": true },
"ruling": { "decisionLabel": "PARTIAL_SLASH", "reasoning": "…" }
}
Job 1 is settled now, so the same request today answers 409: the job is no longer in dispute. On failure the service answers { "ok": false, "error": "…" } with:
| Status | When |
|---|---|
| 400 | The tx is not a transaction hash, was not sent to the court, or did not hear this job. |
| 404 | GenLayer has no such transaction. |
| 409 | The hearing is not FINALIZED yet or did not complete; the job is not in dispute; the court judged other evidence; or the verdict hash does not match the ruling's numbers. |
| 503 | Escrow v2 or its court is not configured in sdk/deployments.json. |
| 500 | Anything else, such as an RPC failure. |
What the escrow checks
settle(verdict, sigA, sigB) on the escrow checks, in this order, and reverts with the named error on the first failure:
- the job is Disputed (
WrongStatus); - the verdict's evidence hash is the one frozen at delivery (
EvidenceMismatch); - the two shares add up to 10,000 basis points (
BadSplit); - the decision is 1, 2 or 3 and the score at most 100 (
BadDecision); - the verdict has not expired (
Expired); - its
verdictHashequals the hash the escrow computes from its numbers (VerdictHashMismatch); - both signatures are valid 65-byte, low-s signatures (
BadSignature) from two different keys (SameSigner), each the buyer, the seller or the verifier (NotAParty).
If the verifier is one of the two signers, the settlement is a court ruling and goes on the seller agent's record. The SDK's settle() sends from your own key with your signature and the verifier's, so in practice the buyer or the seller submits it.
Three ways a dispute ends
| Mode | How | Split | On the seller's record |
|---|---|---|---|
| 1 · ruling | settle() signed by the verifier and the buyer or seller | As the court ruled | A job and a ruling, with its score |
| 2 · agreement | settle() signed by the buyer and the seller | Any split they both sign | A job, not a ruling |
| 3 · timeout | expireDispute() by either party, more than 7 days after the dispute | 50/50 | A job, not a ruling |
Settling by agreement
Buyer and seller can agree a split without the court. The verdict must still be for the frozen evidence, add up to 10,000 basis points and carry the hash the escrow computes; courtTxDigest can be zero, because no function checks it.
import { ESCROW_ABI, VERDICT_TYPES } from "gavelr";
// One party proposes a 30/70 split
const j = await gavelr.job(jobId);
const n = { decision: 2, buyerRefundBps: 3000, sellerPayoutBps: 7000, score: 70 };
const verdictHash = await gavelr.pub.readContract({
address: gavelr.escrow, abi: ESCROW_ABI, functionName: "verdictHash",
args: [BigInt(jobId), j.evidenceSha256, n.decision, n.buyerRefundBps, n.sellerPayoutBps, n.score],
});
const verdict = {
jobId: String(jobId), evidenceSha256: j.evidenceSha256, verdictHash,
courtTxDigest: "0x" + "00".repeat(32), ...n,
expiresAt: String(Math.floor(Date.now() / 1000) + 3600),
};
// The other party signs the same verdict and sends back the signature
const signature = await other.account.signTypedData({
domain: { name: "Gavelr", version: "2", chainId: 56, verifyingContract: other.escrow },
types: VERDICT_TYPES, primaryType: "Verdict",
message: { ...verdict, jobId: BigInt(verdict.jobId), expiresAt: BigInt(verdict.expiresAt) },
});
// The first party adds its own signature and settles
await gavelr.settle(jobId, null, { attestation: { verdict, signature } });
The escrow cannot verify GenLayer's consensus itself. It checks that a verdict is for the frozen evidence and consistent with its own hash, but not that the numbers came from the court. A verifier that colluded with one party could sign a different split with them. That is the main trust assumption in Gavelr today.
The verifier is also not hosted: it runs on the operator's machine. Only the holder of the key for 0x0DDD…9543 can co-sign rulings on this escrow; a server started with any other VERIFIER_PRIVATE_KEY signs with an address the escrow rejects (NotAParty). If the verifier is unreachable, settle() fails with "The court verifier would not sign", and the parties can still settle by agreement or wait out the 7 days.