HTTP API and contracts

server.mjs answers a small JSON API under /api/: live reads of the escrow and the court, the court verifier, and the Lab's trial court. There is no authentication and no API key. Read routes are public; the write routes only spend the server's own Studionet test keys, and none of them moves money.

Conventions

Escrow v2

MethodRoutePurpose
GET/api/v2/jobsEvery job on escrow v2, newest first (up to 50), each with its settlement and, once disputed, the court's ruling from get_verdict_json. Also returns deployed, count and deployment (the contents of sdk/deployments.json).
GET/api/v2/jobs/<id>One job with its ruling: the escrow's record, the court's full case from get_case_json, and the transaction hashes from contracts/v2-job-<id>-proof.json where a saved run exists, because the escrow does not store them. 404 if there is no such job.
GET/api/v2/attest/<jobId>?tx=<hash>The court verifier: checks a ruled job and returns its signature. Request, response and errors are on Settlement and the verifier.

One job

curl https://gavelr.mrnetwork.tech/api/v2/jobs/1
{
  "id": 1,
  "status": "Settled",
  "buyer": "0xCd0a2370F2dC12c1802707B7d9aB3fec891E3c02",
  "seller": "0x3a24656F75312b0250Eb377C8f8B08Aa539b867b",
  "agentId": 342133,
  "agentName": "Bazar Contract Safety",
  "amountBnb": "0.00002",
  "kind": "bsc-pool-audit/v1",
  "terms": "1) Freshness: every audited PancakeSwap pool …",
  "createdAt": 1795186735,
  "deliverBy": 1795193935,
  "disputeWindow": 3600,
  "deliveredAt": 1795186923,
  "disputedAt": 1795186928,
  "greenfieldUri": "gnfd://gavelr-security-feeds/v2-job-1-bsc-new-pools-audit.json",
  "evidenceUrl": "https://greenfield-sp.bnbchain.org/view/gavelr-security-feeds/v2-job-1-bsc-new-pools-audit.json",
  "evidenceSha256": "0x60423e130baeb77cb9107429085f353031e35ce90e7c82c0920bd1940931d79e",
  "disputeReason": "The buyer's agent re-checked the delivered audit against live BSC state. …",
  "settlement": {
    "verdictHash": "0xb210893bdb117364a6e48c2c32121ae51a83554751fadde4788d19565575d70d",
    "courtTxDigest": "0x785b6d228364e8789f54637bea71411712e4b719917b1ddede1256912a962173",
    "decision": 2, "buyerRefundBps": 4000, "score": 60, "mode": 1,
    "settledAt": "1795187017"
  },
  "courtCase": { "decision_label": "PARTIAL_SLASH", "findings": [ … ], "greenfield": { … }, … },
  "transactions": {
    "hire": "0xed85…6467", "deliver": "0xf8fa…f821", "dispute": "0xa099…431c",
    "hearing": "0x19a9…c9c7", "settle": "0xf3cb…8517"
  },
  "deployment": { "escrow": "0xd16e…dfb5", "court": "0xc8A2…942F", … }
}
FieldMeaning
statusNone, Funded, Delivered, Disputed, Released, Refunded or Settled.
agentNameA name the server knows for the agent id, or null. Only #342133 has one.
deliveredAt, disputedAtNull until that step happens.
settlementNull until settled. mode is 1 for a court ruling, 2 for an agreement, 3 for the 7-day timeout.
courtCaseThe court's whole case once the job is disputed and heard, else null. The list route returns ruling, the shorter verdict, instead.
transactionsHashes from a saved run, or null for jobs run outside this repository's scripts.

Records and version 1

MethodRoutePurpose
GET/api/agents/<id>An agent's record: v2 (escrow v2 counters), escrowed (version 1 rulings), totals with the grade over the rulings on both escrows, onChainStats (version 1 counters), trial (Lab cases, never graded), name and registry.
GET/badge/<id>.svgThe agent's badge as SVG, cacheable for 60 seconds. See the grade and the badge.
GET/api/jobCase No. 3 as recorded: ready, the SLA, the pool court's deployment, the version 1 escrow, the bucket, and the whole saved run under proof.
GET/api/job/deliverableThe file Case No. 3's seller delivered, served from the repository's evidence/ folder.
GET/api/stateEvery job on the version 1 escrow, read live, with its GenLayer verdict and hashMatch: whether the verdict hash on GenLayer, the hash the escrow recomputes and the hash it settled are all the same.
GET/api/evidence/job-1-bsc-pools-audit.jsonThe pool-audit dataset from version 1 jobs 1 and 2, the repository's evidence/job-1-bsc-pools-audit.json.
GET/api/replay/<n>Replay data for version 1 jobs 1, 2 and 3, from the saved runs plus live GenLayer data for jobs 1 and 2.

Trial court (Lab)

These routes drive contracts/gavelr_court.py on Studionet with the server's two test keys from .gavelr/keys.json. Each write to the court returns a GenLayer transaction hash at once; follow it with GET /api/tx/<hash>.

MethodRoutePurpose
GET/api/templatesThe five SLA templates.
POST/api/snapshot{ url }: fetches a public https file and returns { url, sha256, bytes, truncatedForJury, preview, fetchedAt }.
GET/api/courtThe trial court's deployment, the two trial account addresses, and the docket.
GET/api/casesThe docket.
POST/api/casesFiles a case: { templateId, evidenceUrl, claim, committedSha256, agentId?, deliveredAt?, rubric?, scoringUnit?, deliverableUri? }. Returns { ref, txHash }.
GET/api/cases/by-ref/<ref>The case id for a filing reference, once GenLayer has accepted it.
GET/api/cases/<id>{ case, txs, agentName }.
POST/api/cases/<id>/rebuttal{ text }, at least 10 characters, before the ruling and only once.
POST/api/cases/<id>/adjudicateAsks the validators to rule on a filed case.
POST/api/cases/<id>/appeal{ role: "buyer" | "seller", grounds }, once per ruled case.
GET/api/tx/<hash>A GenLayer transaction, summarized: status, each validator's model, vote and time, and the consensus timeline. Works for any GenLayer hash, including the court v2 hearings.
GET/api/precedentsThe trial court's case law and which cases cited each holding.

Security limits

Contract reference: GavelrEscrow

Source evm/src/GavelrEscrow.sol; ABI in sdk/escrow-abi.json, exported by the SDK as ESCROW_ABI. Who may call each write, and when, is on The escrow.

// writes
function hire(address seller, uint256 agentId, string kind, string terms, uint64 deliverBy, uint64 disputeWindow) payable returns (uint256 jobId)
function deliver(uint256 jobId, string greenfieldUri, string evidenceUrl, bytes32 evidenceSha256)
function release(uint256 jobId)
function claim(uint256 jobId)
function reclaim(uint256 jobId)
function dispute(uint256 jobId, string reason)
function settle(Verdict v, bytes sigA, bytes sigB)
function expireDispute(uint256 jobId)

// reads
function getJob(uint256 jobId) view returns (Job)
function getSettlement(uint256 jobId) view returns (Settlement)
function getAgentRecord(uint256 agentId) view returns (AgentRecord)
function verdictHash(uint256 jobId, bytes32 evidenceSha256, uint8 decision, uint16 buyerRefundBps, uint16 sellerPayoutBps, uint16 score) pure returns (bytes32)
function hashVerdict(Verdict v) view returns (bytes32)
function domainSeparator() view returns (bytes32)
function jobCount() view returns (uint256)
function courtVerifier() view returns (address)
function court() view returns (address)
function courtChainId() view returns (uint256)
function identityRegistry() view returns (address)

// constants
DISPUTE_TIMEOUT = 7 days      MIN_DISPUTE_WINDOW = 10 minutes      MAX_DISPUTE_WINDOW = 30 days
MAX_TERMS_BYTES = 4000        DECISION_APPROVE_FULL = 1   DECISION_PARTIAL_SLASH = 2   DECISION_REJECT_FULL_REFUND = 3
SETTLED_BY_RULING = 1         SETTLED_BY_AGREEMENT = 2    SETTLED_BY_TIMEOUT = 3

Structs

struct Job {
    address buyer; address seller; uint256 agentId; uint256 amount;
    uint64 createdAt; uint64 deliverBy; uint64 disputeWindow; uint64 deliveredAt; uint64 disputedAt;
    Status status; bytes32 evidenceSha256;
    string kind; string terms; string greenfieldUri; string evidenceUrl; string disputeReason;
}
struct Verdict {
    uint256 jobId; bytes32 evidenceSha256; bytes32 verdictHash; bytes32 courtTxDigest;
    uint8 decision; uint16 buyerRefundBps; uint16 sellerPayoutBps; uint16 score; uint64 expiresAt;
}
struct Settlement {
    bytes32 verdictHash; bytes32 courtTxDigest; uint8 decision; uint16 buyerRefundBps;
    uint16 score; uint8 mode; uint64 settledAt;
}
struct AgentRecord {
    uint32 jobs; uint32 released; uint32 rulings; uint32 upheld;
    uint32 partialSlash; uint32 refunded; uint64 scoreSum;
}

Events

event JobCreated(uint256 indexed jobId, address indexed buyer, address indexed seller, uint256 agentId, uint256 amount, string kind, uint64 deliverBy, uint64 disputeWindow)
event Delivered(uint256 indexed jobId, string greenfieldUri, string evidenceUrl, bytes32 evidenceSha256)
event Released(uint256 indexed jobId, address by, uint256 amount)
event Refunded(uint256 indexed jobId, uint256 amount)
event Disputed(uint256 indexed jobId, string reason)
event Settled(uint256 indexed jobId, uint8 mode, uint8 decision, uint16 buyerRefundBps, uint16 score, bytes32 verdictHash, uint256 toBuyer, uint256 toSeller)

Errors

ErrorMeans
BadAmounthire sent no BNB.
BadPartyThe seller is zero, the buyer, or the verifier, or the verifier is hiring; or someone other than buyer or seller called expireDispute.
BadWindowThe deadline is not in the future, or the dispute window is outside 10 minutes to 30 days.
NotAgentOwnerThe seller does not own the ERC-8004 agent id given.
WrongStatusThe job is not in the status the call needs.
OnlyBuyer, OnlySellerThe wrong party called.
TooLateDelivery after the deadline, or a dispute after the window.
TooEarlyreclaim before the deadline, claim before the window ends, or expireDispute within 7 days.
EvidenceRequireddeliver with a zero hash.
TooLongTerms, kind or reason is empty or over its limit, or a URI or URL is over 300 bytes.
EvidenceMismatchThe verdict is for other evidence than the frozen hash.
VerdictHashMismatchThe verdict hash does not match the verdict's numbers.
BadSplitRefund and payout do not add up to 10,000 basis points.
BadDecisionThe decision is not 1, 2 or 3, or the score is over 100.
ExpiredThe verdict is past its expiresAt.
BadSignatureA signature is not 65 bytes, is malleable, or recovers no address.
SameSignerBoth signatures come from the same key.
NotAPartyA signer is not the buyer, the seller or the verifier.
TransferFailedSending BNB to a party failed.
ReentrantA payout tried to call back into the escrow.

Signatures

Signers sign a Verdict as EIP-712 typed data under this domain; the SDK exports the types as VERDICT_TYPES. The verdict hash inside it is sha256(abi.encode(jobId, evidenceSha256, uint256(decision), uint256(buyerRefundBps), uint256(sellerPayoutBps), uint256(score))), which the court computes in Python and the escrow in Solidity.

const domain = {
  name: "Gavelr",
  version: "2",
  chainId: 56,
  verifyingContract: "0xd16e6cb28fcea0d70a2098604db2a3451b2adfb5",
};
// Verdict(uint256 jobId,bytes32 evidenceSha256,bytes32 verdictHash,bytes32 courtTxDigest,
//         uint8 decision,uint16 buyerRefundBps,uint16 sellerPayoutBps,uint16 score,uint64 expiresAt)

Contract reference: the court

contracts/gavelr_court_v2.py, class GavelrCourt. Its constructor takes the escrow's address and keeps it; there is no function to change it, and no other write.

@gl.public.write
def adjudicate(self, job_id: u256) -> None        # hear a disputed job; once per job

@gl.public.view
def get_verdict_json(self, job_id: u256) -> str   # the ruling (see the SDK's waitForRuling)
def get_case_json(self, job_id: u256) -> str      # the whole case, with findings
def has_verdict(self, job_id: u256) -> bool
def get_bnb_escrow(self) -> str
def get_total_cases(self) -> u256