Route Certification
How Starkscan certifies REST routes, workflow evidence, and nightly correctness.
Route Certification
Starkscan keeps the public contract simple and the internal evidence strict.
Every public OpenAPI operation carries x-starkscan-certification:
| State | Meaning |
|---|---|
certified | Production-safe route with stable schema, monitored path, and current correctness evidence. |
beta | Usable by named clients with explicit limits or incomplete parity breadth. |
experimental | Partner or internal preview; schema or semantics may change. |
unsupported | Not a client contract. |
The public states do not describe the whole proof. The source manifest also tracks internal evidence dimensions:
| Dimension | Examples | Why it matters |
|---|---|---|
oracle | rpc-sampled, indexed-replay, materialized-db-plus-rpc | Names the source of truth. |
evidenceLevel | smoke, sampled, heavy, nightly, deploy-blocking | Tells agents how deep the latest proof is. |
certificationScope | exact-block, pagination, derived-indexed, accounting | Defines what the route is certified for. |
sloClass | hot, warm, cold, batch | Defines latency and error-budget expectations. |
lastEvidence | artifact path, sample size, RPC provider set | Makes the claim auditable. |
Certified launch set
The current certified launch set is intentionally narrow:
GET /v1/{chain}/statusGET /v1/{chain}/block/{number_or_hash}GET /v1/{chain}/block-at-timestampGET /v1/{chain}/tx/{tx_hash}GET /v1/{chain}/token/{token}/total-supplyGET /v1/{chain}/token/{token}/balance-of/{address}
For deterministic token reads, pass a concrete block_tag by block number or
block hash. latest and pending are live state, not replayable accounting
evidence.
Workflow evidence
Endpoint contracts are not enough for agents. Starkscan also defines workflow contracts for multi-step tasks.
The first workflow is the accounting balance path:
timestamp -> block-at-timestamp closest=before -> token balance-of at blockUse it when an accounting team needs one token balance for one account at one point in time. It does not infer historical portfolios or resolve ticker symbols to token contracts.
Nightly evidence
PR and deploy gates stay bounded. The deep checks run separately as the Starkscan Deep Certification Run:
- core RPC exactness for certified routes
- accounting workflow checks over many timestamps/accounts/tokens
- indexed route reconciliation against raw receipts/events
- public-alias browser and library-client checks on
starkscan.co - optional load/abuse thresholds
- optional OpenAPI property probes
Certified route failures block the next deploy until fixed or explicitly downgraded. Beta route failures open/update the owning issue unless the route is part of a named customer workflow.
Certification evidence is published at /route-certification-evidence.json.