# 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.

```json
{
  "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

<Cards>
  <Card title="CLI" href="/docs/reference/cli" description="Every command, its exact arguments, what it reads, what it prints, and what it deliberately refuses to do." />

  <Card title="Request authorization" href="/docs/reference/authorization" description="One signature per request, no login and no API key — the scheme in full, with TypeScript." />

  <Card title="HTTP API" href="/docs/reference/api" description="Every public route, who may call it, what it takes, and what it returns." />

  <Card title="The subgraph" href="/docs/reference/subgraph" description="What a subgraph is, why it is the authoritative read model, and how to query it directly." />

  <Card title="References and addresses" href="/docs/reference/addresses" description="Chain, contracts, token, subgraph endpoint, API base URL, and how to read the values that change." />

  <Card title="Glossary" href="/docs/reference/glossary" description="The exact vocabulary, and the words Elgora deliberately does not use." />
</Cards>