CIP-17: Verifiable State Read RPC

​

1. Abstract

​

2. Motivation

1. Single point of trust. A Gateway fetching from one Runner has no way to detect a malicious or stale response. The Runner could return a forged routes table redirecting traffic.
2. Cache invalidation theory only. CIP-15 v2.r2 §6 says “poll manifest_root every MANIFEST_POLL_INTERVAL blocks.” But polling for state_root changes requires a verifiable read in the first place — otherwise the polled value is itself a trust assumption.
3. CIP-19 tools/list consequence. CIP-19 §10.1 step 1 reads the routes table identically. The same trust gap applies.

​

3. Design Goals

• Verifiable. Response carries everything a client needs to reconstruct the actor’s state-root commitment for the read leaf, with no further round-trip.
• Cheap on the server. The proof is a single QMDB/MMR operation proof; the node maintains the authenticated state anyway (CIP-4) so generation is microseconds, not milliseconds.
• Stateless on the client. No subscription, no session, no pagination. One KV → one response.
• Reusable. Applicable to any system actor or user actor; not specialized to Gateway routes.
• Compatible with light clients. A future Cowboy light client (per CIP-25 §1.4 native-light-client backend) consumes the same proofs.

​

4. Non-goals

• Handler invocation. That is CIP-14 v2.r2 §5 read_handler.
• Streaming subscriptions. A future CIP may add SUBSCRIBE_STATE (push notifications when a key changes); v1 here is pull-only.
• Multi-key proofs. v1 returns one proof per call. Batch reads with a combined proof are a future optimization.
• Cross-actor proofs. v1 proves inclusion of one (actor_address, key, value) operation against the unified state root. Cross-actor relations require multiple GET_STATE calls.
• Full archival history. v1 serves the latest committed block plus a single retained snapshot height (GET /state/at/{height}/..., §5.1). Arbitrary-depth historical reads across all pruned heights (needed by CIP-25 §1.4 cross-chain backends) remain out of scope.

​

5. RPC Endpoint

​

5.1 HTTP route

GET  /state/{actor_address}/{key_hex}

• actor_address — 20-byte hex-encoded address with 0x prefix (e.g. 0x0000...000D)
• key_hex — hex-encoded raw KV key bytes with 0x prefix; same encoding as used by the actor when writing via state_set

• prove: boolean, default true. If false, behaves identically to the existing /actors/{address}/storage lookup — value only, no proof. Provided for parity with cheap unverified reads.

​

5.2 Response

{
  "actor_address":  "0x0000…000D",
  "key":            "0x...",
  "value":          "0x..."  | null,
  "state_root":     "0x...",
  "block_height":   12345678,
  "block_hash":     "0x...",
  "proof": {
    "proof_version":        1,
    "loc":                  42,
    "chunk":                "0x...",
    "mmr_leaves":           100,
    "inactive_peaks":       0,
    "digests":              ["0x...", "0x...", ...],
    "partial_chunk_digest": "0x..."  | null,
    "ops_root":             "0x..."
  },
  "encoded_operation": "0x...",
  "exclusion_proof":   null,
  "absent":            false
}

• value — raw bytes of the KV value, hex-encoded with 0x prefix. null if the key does not exist (see absent below).
• state_root — the node’s global unified state root at block_height (the single QMDB authenticated keyspace covering accounts, actors, and all actor-storage slots). Cowboy has no per-actor storage trie; the proof authenticates the (actor_address, key) operation directly against this one root. Equals the block header’s state root at block_height.
• block_height — the block height at which the proof was generated; always the latest committed block at the time of RPC handling.
• block_hash — block-header hash for cross-verification with the node’s block-explorer view.
• proof — the QMDB/MMR operation-inclusion proof (SerializableStateProof), the implementation-pinned proof form. It authenticates the codec-encoded state operation (the MMR leaf) against the operations-MMR root, which is then compared to state_root. It is not an MPT Merkle path. Sub-fields:
  • proof.proof_version — wire-format version (currently 1).
  • proof.loc — the operation’s location (leaf index) in the QMDB operations MMR.
  • proof.chunk — the activity-bitmap chunk (hex, 32 bytes) covering loc.
  • proof.mmr_leaves — the MMR leaf count the proof is taken against.
  • proof.inactive_peaks — number of inactive peaks committed by the proof, required to recompute the root under commonware’s BackwardFold peak-bagging policy.
  • proof.digests — the MMR range-proof digests (hex, each 32 bytes Blake3).
  • proof.partial_chunk_digest — partial chunk digest from the status-bitmap tail (hex); null when absent.
  • proof.ops_root — the operations-MMR root (hex, 32 bytes Blake3).
• encoded_operation — hex of the codec-encoded MMR leaf (Operation::Update{key, value, next_key}) that proof authenticates. Supplied so a client verifies without re-deriving commonware’s wire codec. Present only for a present key (an absent key ships its leaf inside exclusion_proof).
• absent — true iff the key does not exist at block_height. When absent, proof is omitted and a separate exclusion_proof object is returned instead (the two are mutually exclusive). exclusion_proof is a tagged (kind) union:
  • kind: "span" — the absent key falls strictly between two adjacent active keys: { op_proof, span_key, span_value, span_next_key, encoded_operation }, where op_proof is a SerializableStateProof authenticating the bounding operation and encoded_operation is the codec-encoded bounding Operation::Update leaf.
  • kind: "empty" — the keyspace is empty through the latest commit: { op_proof, commit_value?, encoded_operation } (bounding Operation::CommitFloor). A client verifies exclusion by MMR-checking op_proof over encoded_operation against state_root (same primitive as inclusion) and confirming the absent key lies in the proven span.

​

5.3 Proof verification (client-side)

def verify_state_read(response, trusted_state_root):
    # 1. Confirm response.state_root == the state root of the block the client
    #    trusts out-of-band (block subscription / block_hash from a trusted source).
    if response.state_root != trusted_state_root:
        return False
    # 2. Take the codec-encoded MMR leaf: response.encoded_operation for a present
    #    key, or response.exclusion_proof.encoded_operation for an absent key.
    if response.absent:
        op, proof = response.exclusion_proof.encoded_operation, response.exclusion_proof.op_proof
    else:
        op, proof = response.encoded_operation, response.proof
    # 3. MMR-verify the operation proof against the unified state root. This
    #    reconstructs the operations-MMR root from (loc, digests, chunk,
    #    inactive_peaks, ...) and checks it equals response.state_root.
    #    (node/proof-verifier/src/state.rs::verify_state_proof →
    #     mmr::verify_operation_proof)
    if not mmr_verify_operation_proof(op, proof, response.state_root):
        return False
    # 4. For an absent key, additionally confirm the queried key lies in the
    #    proven span (span_key < key < span_next_key) or that the keyspace is empty.
    return True

​

5.4 Error responses

404 Not Found  (code: not_found)      — actor_address does not exist (non-system user actor), or state at this height has been pruned ("use an archive node")
400 Bad Request (code: invalid_request / invalid_address) — malformed/odd-length/oversized key hex, or malformed address
500 Internal Server Error (code: storage_error / internal_error) — node-side proof generation failure (should not occur)
503 Service Unavailable  (code: node_not_synced) — node's latest block is staler than STATE_READ_STALENESS_GRACE_MS (default 60000 ms); a stale read is refused rather than served

​

6. Use Cases

​

6.1 CIP-15 v2.r2 Gateway routes fetch (primary motivator)

# NOTE: as of this revision only Cowboy full nodes expose /state/* (node/rpc/); a Runner
# does not yet proxy GET_STATE. Point the Gateway at a full node until Runner exposure ships.
state_resp = http_get(f"https://node.example.com/state/{actor_address}/0x{hex('__cowboy/routes')}")
if not verify_state_read(state_resp, actor_address):
    log_warning("Runner returned invalid proof; trying another runner")
    continue
routes_cbor = state_resp.value
if state_resp.state_root == cache[actor_address].state_root:
    continue  # nothing changed
cache[actor_address] = ActorRoutesCache(
    routes=cbor.decode(routes_cbor),
    state_root=state_resp.state_root,
    last_verified_block=state_resp.block_height,
)

​

6.2 CIP-19 tools/list derivation

​

6.3 Off-chain indexer audit

​

6.4 Light client support (future)

​

7. Implementation Sketch (non-normative)

1. One new HTTP route in node/rpc/src/rpc.rs (after the existing /actors/{address}/storage handler at rpc.rs:378): GET /state/{actor_address}/{key_hex}. (This route + handler now live at rpc.rs:716 / node/rpc/src/handlers/proof.rs.)
2. One new method on the existing storage interface that returns (value, proof) instead of just value. The QMDB store Cowboy uses for state already maintains the operation-proof primitives — exposing them is a few-line API surface addition.
3. One new struct in node/types/src/rpc.rs (or equivalent) for the response envelope.

• Unified QMDB state maintained per node/storage/src/blockchain_storage.rs (per CIP-4).
• Block header / state-root view via node/chain/src/engine.rs.
• HTTP route boilerplate per other endpoints in node/rpc/src/rpc.rs.

​

8. Relationship to Other CIPs

​

9. Security Considerations

• Trust model. A Gateway / indexer / light client verifies the Merkle proof locally before trusting the value. A malicious node returning a forged (value, proof) either trips proof verification (proof doesn’t reconstruct to the claimed state_root) or returns a state_root that doesn’t match the block header the client has from a separate trusted source (e.g. another node, or its own block subscription).
• Stale reads. Responses always reflect the latest committed block at RPC handling time. Clients that need monotonic reads should compare block_height across successive calls and reject regression.
• DoS surface. Proof generation is cheap (a single QMDB/MMR operation proof), but a flood of GET_STATE calls against large actor states could pressure a node. Mitigation: /state/* has a dedicated per-IP rate limiter (state_read_limiter, env STATE_READ_RATE_PER_SEC) in addition to the node’s configurable global RPC limiter (RPC_GLOBAL_RATE_LIMIT_PER_SEC), both in node/rpc/src/rpc.rs. Oversized keys are rejected pre-DB (MAX_ACTOR_KV_KEY_BYTES), and stale-node reads are refused (503) rather than served.
• Absent-key fingerprinting. Returning an exclusion proof reveals “this key does not exist” deterministically. This is the same information already exposed by /actors/{address}/storage; no new leak.
• Key encoding edge cases. Implementations MUST decode key_hex strictly (reject non-hex chars, odd length, etc.) to prevent ambiguity between, e.g., 0x__cowboy/routes (literal nine-byte string) and a typoed escape sequence.

​

10. Backwards Compatibility

​

11. Future Work

• Full archival history. Reads at arbitrary pruned heights — v1 retains only the latest snapshot for the height-pinned read (§5.1); needed by CIP-25 §1.4 native light client backend.
• Batch reads. POST /state/batch with multiple (actor, key) pairs returning combined proofs.
• Subscribe API. WebSocket-based push when a watched key changes — useful for Gateway cache invalidation tighter than CIP-15’s MANIFEST_POLL_INTERVAL.
• Bundled account-trie proof. Resolve §5.3 limitation by returning both the actor’s storage proof AND the account-trie proof for actor_address.state_root in one response.
• CIP-25 cross-chain extension. A cross-chain L1 anchor (CIP-25 §1) can carry GET_STATE-style proofs over the L1 mailbox, allowing destination-chain L3 apps to verify Cowboy state directly.

​

12. References

• node/rpc/src/rpc.rs:370-384 — existing unverified state endpoints; /state/* GET_STATE routes at rpc.rs:716 → node/rpc/src/handlers/proof.rs::get_state
• node/storage/src/blockchain_storage.rs — unified QMDB state + proof generation
• CIP-4 — QMDB / MMR state-proof primitives
• CIP-14 v2.r2 §5 — read_handler (complementary RPC)
• CIP-15 v2.r2 §6 + cip-15-gateway-implementation.md r2 §2.2 — primary use case
• CIP-19 §10.1 — secondary use case
• CIP-25 §1.4 — native light client future use case