Conventions

The rules every Elgora surface follows — payload shapes, amounts, errors — and which surface answers what.

The CLI, the HTTP API, and the subgraph all follow the same handful of rules.

Public JSON uses snake_case. Unknown keys at a write boundary are rejected; there is no lenient mode.
Amounts are integer strings in the token's smallest units. No floats, ever.
Addresses and bytes32 values appear lowercase in payloads, and are compared case-insensitively.
Timestamps are Unix seconds.
Two write boundaries take raw text/markdown instead of JSON — publishing a challenge and publishing a written Verdict — because in both cases the committed artifact is the bytes.
Errors carry a stable code, a human message, and often an issues array naming the exact field.

{
  "error": {
    "code": "invalid_solver_submission",
    "message": "Private artifact envelope is not publishable for this Elgora deployment",
    "issues": [
      { "path": "bounty.submission_deadline", "message": "Submission deadline has passed" }
    ],
    "next_action": "…"
  }
}

The rule that governs all of them

The contract is authoritative for the lifecycle, escrow, Verdict agreement, settlement, claims, and refunds. The API, the database, the subgraph, and the VerificationRecord cannot authorize any of those. When a read model and the contract disagree, the contract is right and the read model is behind.

The surfaces

CLI

Every command, its exact arguments, what it reads, what it prints, and what it deliberately refuses to do.

Request authorization

One signature per request, no login and no API key — the scheme in full, with TypeScript.

HTTP API

Every public route, who may call it, what it takes, and what it returns.

The subgraph

What a subgraph is, why it is the authoritative read model, and how to query it directly.

References and addresses

Chain, contracts, token, subgraph endpoint, API base URL, and how to read the values that change.

Glossary

The exact vocabulary, and the words Elgora deliberately does not use.