Chain events reference

ADR 0013 originally proposed D1 as a near-real-time explorer cache (blocks/extrinsics/account_events, pruned after a few days) with Postgres as the durable, unbounded sink feeding a genuinely new tier: chain_events, the raw all-events firehose. ADR 0014 (accepted 2026-07-10, supersedes 0013) is the current, directly-verified snapshot of what actually shipped.

As of ADR 0014, D1's write paths for blocks, extrinsics, and account_events are retired and those tables are dropped in production. Every one of those tiers' serving flags (METAGRAPH_BLOCKS_SOURCE, METAGRAPH_EXTRINSICS_SOURCE, METAGRAPH_ACCOUNT_EVENTS_SOURCE) is flipped to "postgres" in production, read through the same tryPostgresTier() helper and the same DATA_API service binding this page's chain-events routes use.

So today, the curated explorer views and the deep-history feed both live in Postgres, served by the same Worker. What's still genuinely different between them isn't the store — it's the table:

• The curated explorer surfaces (/blocks/{ref}/events, /accounts/{ss58}/events, /subnets/{netuid}/events) read account_events — decoded and filtered down to a fixed allowlist of “interesting” kinds (Transfer, NetworkAdded, NeuronDeregistered, StakeAdded/Removed, and roughly thirty more), attributed to the account(s) involved.
• The deep-history tier (/chain-events*) reads chain_events — literally every pallet.method event the indexer decodes, no kind filtering, no account attribution. It never had a D1 form; it's been Postgres-only (TimescaleDB) from day one.

GET /api/v1/blocks/{n}/chain-events (raw, unfiltered chain_events) and GET /api/v1/blocks/{ref}/events (curated, filtered account_events) can legitimately report different counts for the identical block. The curated feed is always a subset of the raw one — routine system/consensus events (System.ExtrinsicSuccess, TransactionPayment.TransactionFeePaid, and similar per-extrinsic bookkeeping) show up in chain-events but were never in scope for the curated allowlist.

Don't treat a mismatch between the two as a sync bug or evidence of ingestion drift — cross-checking them for parity is comparing two different, intentionally-scoped views of the same block, not two copies of the same data.

The main API Worker's handleChainEventsProxy (workers/api.mjs) forwards all three routes as-is to a separate Cloudflare Worker (workers/data-api.mjs, the metagraphed-data-api service) over a Worker-to-Worker service binding named DATA_API. That split keeps the postgres.js driver and the Hyperdrive-backed Postgres tiers out of the main Worker's bundle, which is already near its size budget.

There are two distinct failure modes, with two distinct error codes — don't conflate them when triaging:

• data_tier_unavailable — either this Worker's own DATA_API binding isn't wired into this deployment (503, checked before any request even reaches the data Worker), or the data Worker responded but its body couldn't be parsed as JSON (502, an unreadable upstream response).
• data_query_failed (status mirrors the upstream) — the data Worker is reachable and returned readable JSON, but a non-2xx status: its own HYPERDRIVE binding is missing (its own 503) or the query errored. The proxy rewraps whatever status/message the data Worker returned.

All three routes only accept GET (and HEAD, normalized to a GET internally). The proxy doesn't gate the method itself — a POST is forwarded straight through and comes back as the data Worker's own 405, wrapped as data_query_failed rather than a dedicated method-not-allowed code.

Every request to any of the three routes is also capped by a shared, per-client-IP rate limiter (60 requests / 60s), checked before the tier-availability check above — exceeding it returns 429 data_rate_limited with a retry-after: 60 header.

{
  "ok": false,
  "schema_version": 1,
  "data": null,
  "error": {
    "code": "data_tier_unavailable",
    "message": "The all-events data tier is not bound to this deployment."
  },
  "meta": {
    "contract_version": "2026-07-10.1"
  }
}