feat(platform): subscribe to committed state transitions matching document, address, identity, token and contract filters

[PastaPastaPasta]

Issue being fixed or feature implemented

Closes #5274.

Applications that react to Platform activity poll for it today, for example Dash Forge's inbox, CI runners and webhook relay. A wallet watching its addresses and a token payment gateway waiting for a transfer do the same. Polling cost grows with users times feeds, runs into the gateway's per-IP limit, and notices changes late.

This adds subscribeToStateTransitions, a server-streaming Platform RPC. A client describes what it wants to hear about, and DAPI streams each committed, successfully executed state transition that matches. It covers the requests "tell me when this address gets funds", "when a document appears on this contract/type", "when a document matching this query is created", "when this document changes", "when this identity receives credits or tokens" and "when this contract is updated". A client resumes from a checkpoint without gaps.

The closed #2795 was an earlier attempt: drive-abci events for committed blocks and transaction hashes, with no entity filters and no resume. Drive already had DriveDocumentQueryFilter for this purpose (#2761, #2781, #5114), but nothing used it.

What was done?

Filters (dash_platform_queries::subscriptions, shared by DAPI and the SDK)

A request carries 1–16 filters. A transition is delivered when it matches any filter, and every constraint within one filter must hold.

• documents: one data contract, optionally narrowed by:
  • a document type;
  • actions (create / replace / delete / transfer / update price / purchase), each with clauses on the new data, typed like getDocuments V1 where clauses;
  • $id of the document before the transition;
  • the transfer recipient or the buyer;
  • the new price;
  • the batch owner.
• addresses, up to 256 platform addresses, and identities, up to 64, each on a side: SENDER, RECIPIENT or ANY. The roles are classified for every StateTransition variant in one exhaustive match, so a new variant won't compile until it is classified.
• tokens: by token id and/or party.
• data contracts: creation, updates, moderation and fee claims.

Matching reads only what a transition says, so some filters are refused up front rather than accepted and then silently never matching. A clause on the document as it was before the transition is undecidable unless it is on $id. The exception is the delete of an indexOnly document, which carries the document's values. The endpoint doc lists the remaining limits: requested vs credited amounts, mints to the configured destination, shielded parties, and group actions that are proposed but not yet executed.

Drive filter fixes (rs-drive/src/query/filter.rs)

The filter had no consumer and two bugs that made valid filters silently never match:

• Different encodings of the same value never compared equal. Two examples:

  • an identifier sent as bytes vs base58 vs Identifier;
  • a u8 field sent as U64.

  Clause values and the transition values a clause reads are now both brought to the form the schema stores them in. Long values still compare, because the per-type codec is used directly instead of the index-key path, which caps values at 255 bytes.

• Clauses on $ system fields other than $id passed validate() but can never match, because transition data has no $ fields. They are now rejected.

DAPI (rs-dapi/.../subscribe_to_state_transitions)

• Served from the Tenderdash block store, not drive-abci. Each subscription walks committed heights in order with its own cursor. History and new blocks are read the same way. New-block websocket events only wake the tip tracker, so a dropped event delays a block but cannot lose it. No consensus code changes; Drive answers the RPC with unimplemented.
• Never skips a height:
  • A block stored before its results are saved is retried.
  • blockchain returns only the 20 highest heights of a range, so pages are requested 20 at a time and checked complete.
  • A transaction this build cannot decode, or an unknown protocol version, ends the stream at that height instead of advancing past it.
• Stream contract:
  • The first message is a checkpoint at start − 1.
  • Matches are sent in block order, and a checkpoint follows every block with a match.
  • A checkpoint repeats every 10 s otherwise, which keeps quiet streams inside proxy idle timeouts.
  • A checkpoint at h means everything from the first scanned block through h has been sent; resume from h + 1.
• Cost:
  • Reads are single-flight: concurrent misses on one block or metas page share one Tenderdash call, and a block is decoded once for all subscribers.
  • The block cache is bounded by bytes.
• Limits:
  • 1024 subscriptions per node.
  • 16 per client address (the last X-Forwarded-For entry; IPv6 per /64).
  • 8 subscriptions catching up on history at once. The permit is held only while reading, so a client that stops reading cannot keep it.
  • Start at most 50k blocks behind or 1k ahead of the tip.
  • A client that does not read for 60 s is dropped with RESOURCE_EXHAUSTED.
• Contract updates: a data contract update in the stream rebinds the document filters on that contract.

SDK (rs-sdk/src/platform/subscriptions.rs)

Sdk::subscribe_to_state_transitions(filters, from_block_height) returns a subscription with next() / into_stream().

• Checks what the node sends. It verifies each transition's hash and re-matches it against the filters, bound to data contracts fetched with proofs. Transitions that don't match are skipped and logged.
• Resumes by itself from the last checkpoint, possibly on another node, with backoff. Delivery is at least once.
• Follows updates of the contracts it filters on, so it matches against the same contract version as the node.

Wiring

• Proto and regenerated clients.
• build.rs and the metrics allowlist.
• An Envoy route with the Core streams' timeouts. It replaces the route for subscribePlatformEvents, which has no RPC.
• The endpoint doc packages/dapi/doc/endpoints/streams/subscribeToStateTransitions.md.

Trust model (stated in the docs)

A client can check every delivered transition: its hash, and that it matches its filters against proved contracts. A client cannot check completeness: a node may leave a match out, and block heights and times are the node's word. Act on an event by reading the changed state with a proved query, and catch up from a proved read's metadata.height + 1.

Design process

• Four codebase explorations, then two rounds of design review by three independent reviewers. The reviewers were two Claude agents, one checking protocol correctness against the Tenderdash source and one checking codebase fit, plus a Codex GPT-6.1 reviewer for API and product.
• An independent code review afterwards. Every finding above MINOR was fixed. Two findings in that category:
  • one client could hold the catch-up capacity;
  • every subscriber issued its own Tenderdash calls per block.

Not in this PR

• wasm-sdk / js-evo-sdk bindings, an async iterator for browsers. The matcher and the Rust SDK already build for wasm32, and rs-dapi-client's grpc-web transport supports server streaming. The JS surface is a follow-up.
• Firehose filters, all transitions of a kind. Explorers are better served by running indexers.

How Has This Been Tested?

• cargo test -p drive --lib query::filter: 67 passed. New tests cover the identifier encodings, long values, rejected system fields and recipients given as bytes.
• cargo test -p dash-platform-queries --lib subscriptions: 12 passed. They cover:
  • roles for identities and addresses;
  • batch attribution across document and token transitions;
  • $id original-document matching;
  • rejected undecidable clauses;
  • limits;
  • the wire round-trip;
  • rebinding.
• cargo test -p rs-dapi --lib: 344 passed. The 21 new tests run the full scan loop against an in-memory chain:
  • replay across pages, then live blocks, without gaps;
  • starting live;
  • checkpoints while idle;
  • start bounds;
  • per-address limits and IPv6 /64 bucketing;
  • a block whose results arrive late;
  • a client that stops reading must not starve another's catch-up;
  • an undecodable transaction ends the stream;
  • meta page validation, including heights below the store base and header-only metas.
• cargo test -p dash-sdk --lib subscriptions. The new network-only test tests/fetch/state_transition_subscriptions.rs compiles under network-testing but has not been run against a live network.
• cargo clippy is clean for every touched crate. dash-sdk checks for wasm32-unknown-unknown. The dashmate Envoy template test passes. check-grpc-coverage.py passes.
• Not done: an end-to-end run on a local dashmate devnet.

Breaking Changes

None. The RPC and messages are new. The drive filter changes affect only DriveDocumentQueryFilter, which nothing else uses and which is not consensus code; no shipped generation changes behaviour.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thepastaclaw]

🕓 Review not started yet because this PR is a draft.

• Request normal review — click when the PR is ready for review.
• Request priority review — click to move this review to the front of the queue.

Commit 5681b07. Normal review starts when eligible; priority review starts as soon as a slot is available.

[PastaPastaPasta]

Superseded by #5285: same branch and commits, opened from the dashpay/platform repository so CI runs. Closing this fork-based PR.

---

🤖 Posted autonomously by Codex on behalf of pasta.