blockmachine

Basic health check - always returns OK if server is running

Readiness check - verifies database connectivity. Use this for load balancer health checks.

List all nodes for the authenticated miner, plus their slot allowance.

Create a new node with its initial secret. Validates the secret against the endpoint and applies the compatibility gate before persisting. Nodes that fail the compat gate are rejected so miners get immediate feedback instead of silently entering the network and being demoted on the first sweep.

Get a node by ID

Update a node's alias or endpoint

Delete a node. Nodes flagged ``is_reference`` (admin-owned load-test reference oracles, #453) are guarded: deleting one requires an explicit ``?force=true`` — without it the request 409s so a reference node can never be decommissioned by accident.

Return the audit trail for a single node owned by this miner. Events are returned most recent first. Use ``before_id`` for pagination.

Get secret metadata for a node. Returns version, state, and created_at - NOT the plaintext secret.

Set or rotate a secret for a node. If rotate=False (default): Sets as the active secret, retiring any existing. If rotate=True: Sets as 'next' secret for zero-downtime rotation.

Promote the 'next' secret to 'active', retiring the old active secret. Used to complete a zero-downtime rotation.

List all pricing rules for the authenticated miner.

Create or upsert a pricing rule for the authenticated miner.

Delete a pricing rule by dimension filters.

Get routing metrics for a node from gateway scoring data. The Redis prefix is derived from the node's own chain — gateway writes node scores under ``<region>:<chain>:score:node:<node_id>`` keyed by the gateway's ``GATEWAY_CHAIN``.

Public leaderboard showing all miners' routing scores and work done. Cross-chain: constructs each configured node's exact score key and aggregates live hashes into one ranked list. The successful response is cached for the same 10 seconds advertised to public proxy caches.

ONE ZIP THAT WORKS: the binary, the questions, a run script, a README. Serving a pack on its own and telling an operator to go and find a binary hands them a file and an instruction that fails. This is the shape that was proven by hand before it was built. The binary is the REPLAY build, which links none of the code that talks to our systems — no internal API paths, no header names, no reporting path, no drain machinery. What it does carry is how a node is marked, which is deliberate: an operator who knows they are marked 40% on old-state reads can act on it.

Serve the CLI install script with the registry URL baked in.

Generate a pre-signed S3 URL for downloading a chain snapshot.

List all permanently banned miners.

Submit a ban signal for a miner coldkey. The signal is always recorded. A permanent ban is only executed when the owner-key validator and at least one other validator have both signalled for the same coldkey. A Slack alert is sent for every signal regardless of outcome.

Check if a specific coldkey is banned.

Appeal path: remove a permanent ban and release the coldkey's nodes. Suspended nodes return to ``pending`` so the liveness prober re-validates them before they re-enter any pool. Gateway-API-key authed — an operator action, not a validator one.

Execute a ban from the gateway's proxy-detection pipeline. Unlike validator ban signals there is NO quorum: the canary evidence is deterministic and first-party (we minted a never-seen (account, block) tuple, routed it to exactly one miner, and watched it re-enter our own gateway, then confirmed with a probe burst). Trusted-hotkey protection and the global ban freeze still apply.

Operator release for a DEREGISTRATION suspension (#674). ``suspended`` has two writers and, before this, one reverser: * ``suspend_miner_nodes`` — the consensus ban path, reversed by ``unban_miner`` (``DELETE /bans/{coldkey}``). * ``suspend_hotkey_nodes`` — the chain watcher, when a hotkey falls off the metagraph. It writes no ``banned_miners`` row, so ``unban_miner`` releases nothing for it, and no other endpoint writes a node status. A miner that fell off the metagraph and re-registered used to recover by accident: rotating a node secret promoted it back, which is exactly the bypass #655 closed. Closing it correctly left that state with no legitimate exit, which is what this endpoint is. **A live ban is refused, not overridden** — releasing a banned miner's nodes is the appeal path's job and nothing else's. Nodes go back to ``pending``, never straight to ``active``, so the prober re-validates them first. Every release writes a ``suspension_released`` node event: this reverses enforcement, so it has to be reconstructable afterwards. Gateway-API-key authed — an operator action, not a validator one, the same call ``unban_miner`` makes.

Record (idempotently) payments_watcher's free-tier incentive report for an epoch. Safe to retry: re-POSTing the same epoch applies nothing new.

Inspect base-incentive ledger rows for an epoch (optionally one chain).

Upsert base-incentive truth-ledger rows for an epoch (finalizer feed). A row for a HARD-BANNED hotkey is written ``payable=false`` (issue #763) — VOIDED, not dropped, and with ``topup_usd``/``topup_cu`` left exactly as the finalizer reported them. Reaching here at all means the CU was already emitted into the manifest and the earlier layers (the allocation freeze and the ``GET /allocation`` filter) both missed it, so the row IS the evidence that we paid a banned miner; deleting it or zeroing the amounts would erase the only record of the escape. #763's $21.07 was found precisely by reading ``topup_usd`` off rows like these. THIS MAKES ``payable`` TIME-DEPENDENT, deliberately. The upsert rewrites ``payable`` on conflict, and a replay of an old epoch's rows (the ERROR log in the finalizer's ``_post_ledger_with_retry`` prints the payload precisely so an operator can re-POST it) will therefore flip a row written before the ban to ``false``. That is the intended answer, not a corruption: a ban voids all arrears, so if the settlement had not happened the row is now correctly unpayable, and if it HAD happened the flag is the flag you want reconciliation to trip over. It can only ever move rows belonging to a banned hotkey, never an honest one. Nothing consumes ``payable`` programmatically today (payments_watcher does not read it); if something ever does, decide there whether "banned since" means claw back or ignore.

The most recent epoch at or before ``at_or_before`` whose ledger rows are carryable, with those rows (issue #773). The base-incentive carry sizes from what the pool last actually PAID. Asking for exactly the previous epoch means one epoch without carryable rows — a ledger POST that exhausted its retries, a burn epoch, a floor — pins every later epoch to the static floor for the rest of an outage. This asks for the most recent epoch that has something worth carrying instead. Returns ``{"epoch_id": null, "rows": []}`` when there is none; the caller then takes the floor.

ACTIVE nodes for a chain — the load tester's discovery feed (Stage 4, issue #428; BOTH classes since #977). node_id + miner_hotkey + endpoint + is_reference (#453: the admin-flagged reference oracle, so operators can resolve which candidate LOAD_TESTER_REFERENCE_NODE_ID should point at) + miner_coldkey (#967: the load tester's sybil crush groups nodes by OPERATOR, and the operator is the coldkey — a hotkey is a registration, and minting another one is the manoeuvre being detected) + is_archive (#977: which capacity class the node competes in; the two are measured by different instruments and normalised against separate C_best pools, so the feed has to say which) + software_name (per-node trace dialect: the raw client string the admission probe persisted, so the load tester can ask each node in the trace dialect its client actually serves — run d1a3b3bb zeroed three bsc-geth miners for not speaking the parity namespace the chain's calibration assumed). Null coldkey means the miners row has none yet; the load tester then treats that node as its own operator rather than grouping every unknown together. Null software_name means the admission probe never captured a client string; the load tester falls back to the chain's calibrated dialect. IT WAS ARCHIVE-ONLY UNTIL #977, WHICH IS WHY FULL NODES RODE FREE: no run could see one, so none was ever graded, so the quality gate had nothing to gate them by and handed every one a flat 1.0. Gateway-API-key authed like the rest of the benchmark surface: which nodes are in the running is competitive intel, not a public list.

Set/clear the admin-owned load-test reference marker (#453). Lives on the base-incentive router so it is mounted on the INTERNAL app (as well as public) and gateway-API-key authed (X-API-Key), like the rest of the load-test surface — deliberately NOT miner-JWT: miners must never flag their own nodes as ground-truth reference oracles. Admin/ops internal action only.

The FROZEN eligible set for (epoch, chain) — the finalizer's payout input. Empty list ⇒ nothing frozen; never computed on the fly.

The FROZEN pot allocation for (epoch, chain) — the finalizer's payout input (issue #460). Per-hotkey absolute ``target_usd``; the finalizer converts each to synthetic archive CU at the merged price. Empty list ⇒ nothing frozen (pot unset or job hasn't run): the finalizer injects nothing (fail-safe, never over-pay). Gateway-API-key authed — payout input, not a public surface. HARD-BANNED hotkeys are filtered out HERE, at read time, as well as at the freeze (issue #763). The freeze is immutable and runs ~one epoch before the finalizer reads it, so a ban landing in that gap would otherwise be paid in full: the frozen row is the COMPUTATION, this response is the PAYMENT INSTRUCTION, and only the instruction can honour a ban that arrived after the sum was done. Nothing not yet emitted is paid to a banned coldkey.

A miner's per-epoch base-incentive scoring results (issue #455). Miner-JWT authed; the caller's hotkey scopes the rows. Privacy scope (deliberate, privacy-preserving default): a miner sees ONLY THEIR OWN nodes' rows — score, full-field rank, won/lost, and the benchmark context explaining an exclusion — plus aggregate context (how many slots were won, the cutoff score = lowest winning score, and how many hotkeys competed) so they can see the cut line and their distance from it WITHOUT other miners' identities, node ids, or scores leaking. TODO(#455 follow-up): if Ben opts into full-field visibility later, add an anonymised full-ranking view — do NOT simply drop the hotkey filter here. ``frozen=false`` (empty rows, null context) means the epoch was never frozen for that chain — consistent with ``/eligible``'s fail-safe. Optional ``node_id`` narrows to one of the caller's nodes. ``admission_refusal`` (#1011 Stage 2) is the field that explains a node with a PASSING benchmark and no earnings: the serving predicate refused it admission to the pot at freeze time. ``passed`` still describes the benchmark run and nothing else, so the two together say "your node answered correctly AND we would not route to it" rather than collapsing both into one flag a miner cannot act on. Null means admitted — including on every row frozen before the field existed.

Fleet-wide projection for an in-flight epoch — the operator's view. Answers, per chain and per tier: what is the pot, what is the paid-CU take, what is each miner on track to earn, and is anything obviously broken RIGHT NOW. A chain whose ``verdict`` is ``inconclusive`` has NO usable figures, and its ``reasons`` say why. Do not read its absent rows as "nobody earned".

One miner's projected earnings for the in-flight epoch, and WHY. ``coldkey`` resolves to every hotkey registered under it — which is also how bans work (``banned_miners.coldkey`` is the primary key and reaches every hotkey beneath it), so a banned operator sees the consequence across their whole fleet rather than one puzzling zero.

Your own projected earnings for the in-flight epoch, per chain, per tier. Miner-JWT authed (scope ``subnet:19:miner``), and it takes NO hotkey parameter: the rows are scoped by the token, so there is no argument to get wrong. Omit ``epoch`` and you get the epoch in flight right now. Served from the snapshot the projector wrote (every ~2 minutes) — nothing is computed for your request, so refreshing costs you nothing and costs the epoch's own data path nothing. Every chain carries the time its snapshot was computed and how much of the epoch it had seen. READ BOTH SHARES. ``share_of_chain_pot`` is your slice of your chain. ``share_of_epoch_pot`` is your slice of the whole epoch pot across every chain, and it is the one the payment is computed from — 100% of one chain is about 9% of the epoch, because the pot is split across eleven chains. A chain we could not measure is listed with ``measured: false`` and the reason. It is never a zero and it is never dropped from the response.

Inspect recent benchmark runs (trusted infra only — every node's scores/metrics are competitive intel for gaming the top-K, so this is NOT a public surface, unlike GET /base-incentive/ledger).

Record one benchmark run (load-tester feed). Append-only: every run is inserted as new history — there is deliberately no upsert.

List finalized epochs. Use before_epoch_number for backward pagination (newest first) or after_epoch_number for forward pagination (oldest first).

The most recent finalized epoch at or before ``at_or_before`` that carries a price snapshot — i.e. the last epoch whose miner pool was actually MEASURED (issue #773). The base-incentive carry bounds its value against that pool, so it needs the last real measurement rather than merely the previous epoch. A NULL price_snapshot means the epoch did not measure, so it is skipped rather than reported with a missing figure. Returns ``{"epoch": null}`` when there is no measured epoch at or before the requested one — the caller then declines to carry rather than injecting unbounded.

Get the most recently finalized epoch. Used by validators to know which epoch to validate next.

Register a sentinel finalization for an epoch. Called by the epoch finalizer after every configured chain has finished flushing state for this epoch (or timed out). The manifest covers files from all chains; ``gateway_ids`` is the union across chains.

Return the live epoch_id derived from the registry's subtensor poller. Centralised epoch source-of-truth for gateways. Returns 503 when the tracker is not configured or its cached observation is older than ``stale_threshold_sec`` — the operational signal that the registry's subtensor link is unhealthy and gateways should hold their last-known epoch rather than acting on stale data.

Get a specific finalized epoch by ID. Returns the full manifest including aggregated gateway IDs and S3 file paths across all chains.

Return network-wide validator configuration. Authenticated via validator JWT (same as /bans). Records the validator's version (from X-Validator-Version header) in the DB so the version gate persists across registry restarts.

Return the active compatibility policy. Miner-authenticated so operators can tell their miners where to look when a node fails registration. The response echoes the JSON shape the registry loaded, plus a short stable hash that appears in node event rows so miners can correlate events to the policy version in force.