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
- Base URL:
https://gavelr.mrnetwork.techfor the hosted server, or wherever you runserver.mjs(http://localhost:4173by default). - Responses are JSON. Errors are
{ "ok": false, "error": "…" }with a 4xx status, or 500 for anything unexpected; an unknown/api/path is 404 "Unknown API route". - Unix times are seconds. A few integers read from the chain, such as
settlement.settledAt, come back as strings. - Reads are cached in the server's memory: escrow v2 for 15 seconds, the version 1 job list for 30 seconds, the trial-court docket for 4 seconds.
- No CORS headers are sent, so a web page on another origin cannot read the API; call it from a server or an agent.
Escrow v2
| Method | Route | Purpose |
|---|---|---|
| GET | /api/v2/jobs | Every 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", … }
}
| Field | Meaning |
|---|---|
| status | None, Funded, Delivered, Disputed, Released, Refunded or Settled. |
| agentName | A name the server knows for the agent id, or null. Only #342133 has one. |
| deliveredAt, disputedAt | Null until that step happens. |
| settlement | Null until settled. mode is 1 for a court ruling, 2 for an agreement, 3 for the 7-day timeout. |
| courtCase | The court's whole case once the job is disputed and heard, else null. The list route returns ruling, the shorter verdict, instead. |
| transactions | Hashes from a saved run, or null for jobs run outside this repository's scripts. |
Records and version 1
| Method | Route | Purpose |
|---|---|---|
| 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>.svg | The agent's badge as SVG, cacheable for 60 seconds. See the grade and the badge. |
| GET | /api/job | Case 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/deliverable | The file Case No. 3's seller delivered, served from the repository's evidence/ folder. |
| GET | /api/state | Every 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.json | The 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>.
| Method | Route | Purpose |
|---|---|---|
| GET | /api/templates | The five SLA templates. |
| POST | /api/snapshot | { url }: fetches a public https file and returns { url, sha256, bytes, truncatedForJury, preview, fetchedAt }. |
| GET | /api/court | The trial court's deployment, the two trial account addresses, and the docket. |
| GET | /api/cases | The docket. |
| POST | /api/cases | Files 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>/adjudicate | Asks 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/precedents | The trial court's case law and which cases cited each holding. |
Security limits
- No authentication. Anyone who can reach the server can read everything and file trial cases on Studionet.
- The POST routes that write to the trial court (filing a case, a rebuttal, a request for a ruling, an appeal) are rate-limited per IP address, 10 a minute.
- Request bodies must be JSON, at most 200 KB; a larger body is refused with 413.
/api/snapshotfetches only https URLs. The host is resolved first and refused if any of its addresses is private, loopback, link-local, CGNAT (100.64.0.0/10) or multicast. Redirects are followed by hand, up to 3 hops, and each hop is checked the same way.POST /api/casesaccepts only https evidence URLs; the server does not fetch them itself, the trial court does./api/snapshotgives up after 15 seconds and refuses an empty file or one over 2,000,000 characters; its hash is the SHA-256 of the trimmed UTF-8 text.- A case needs a rubric of at least 20 characters, a claim of at least 10, and a 0x SHA-256. Writes go out one at a time per test key.
- The attestation route signs only after its checks, and its signature alone cannot move money: the escrow needs a second, different signer.
- No route returns a private key;
/api/courtreturns the trial accounts' addresses only. Static files are served only frompublic/.
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
| Error | Means |
|---|---|
| BadAmount | hire sent no BNB. |
| BadParty | The seller is zero, the buyer, or the verifier, or the verifier is hiring; or someone other than buyer or seller called expireDispute. |
| BadWindow | The deadline is not in the future, or the dispute window is outside 10 minutes to 30 days. |
| NotAgentOwner | The seller does not own the ERC-8004 agent id given. |
| WrongStatus | The job is not in the status the call needs. |
| OnlyBuyer, OnlySeller | The wrong party called. |
| TooLate | Delivery after the deadline, or a dispute after the window. |
| TooEarly | reclaim before the deadline, claim before the window ends, or expireDispute within 7 days. |
| EvidenceRequired | deliver with a zero hash. |
| TooLong | Terms, kind or reason is empty or over its limit, or a URI or URL is over 300 bytes. |
| EvidenceMismatch | The verdict is for other evidence than the frozen hash. |
| VerdictHashMismatch | The verdict hash does not match the verdict's numbers. |
| BadSplit | Refund and payout do not add up to 10,000 basis points. |
| BadDecision | The decision is not 1, 2 or 3, or the score is over 100. |
| Expired | The verdict is past its expiresAt. |
| BadSignature | A signature is not 65 bytes, is malleable, or recovers no address. |
| SameSigner | Both signatures come from the same key. |
| NotAParty | A signer is not the buyer, the seller or the verifier. |
| TransferFailed | Sending BNB to a party failed. |
| Reentrant | A 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