feat(platform)!: token shielded pools

[QuantumExplorer]

Issue being fixed or feature implemented

Tokens have no privacy: every balance and transfer is public. The credit shielded pool cannot hold tokens because the Orchard construction Platform uses has no asset base (a note carries a value, not an asset id), so one pool cannot keep token A and token B apart.

What was done?

Protocol version 15 lets a token own its own shielded pool, laid out exactly like the credit pool and rooted under the token. Seven batch token transitions move tokens in, out and inside it, document costs can be paid out of it, and three identity-less state transitions move tokens with the fee paid from the credit shielded pool, so no identity appears anywhere. The identity-paid transitions stay; the identity-less ones are additions.

This PR now targets v4.3-dev and carries its own PV15 scaffolding: v15.rs, DRIVE_VERSION_V10, DRIVE_ABCI_METHOD_VERSIONS_V11, DRIVE_ABCI_VALIDATION_VERSIONS_V11 and CONTRACT_VERSIONS_V7; the v14 tables keep their released values. It will conflict with #4730, which adds the same scaffolding for its own feature; whichever merges second rebases.

Configuration

• TokenConfiguration::V1 (format version 1) adds hasShieldedPool. CONTRACT_VERSIONS_V7 admits format versions 0 and 1 (token_configuration_format bounds); earlier versions admit only 0, and contract create/update reject anything else with UnsupportedVersionError. The flag is immutable on update.
• A pool makes freezing and confiscation unenforceable (shielded notes belong to no identity account), so a token with the flag must permanently disable freezeRules, unfreezeRules and destroyFrozenFundsRules (no action takers and no admins); contract create and update reject anything else with TokenShieldedPoolIncompatibleRulesError (10277). Pause still applies to every pool operation.
• Inserting or updating a contract with the flag creates the pool trees; the token pools root tree is created by transition_to_version_15 and by create_initial_state_structure v4 (a genesis-versus-upgrade equivalence test pins the two paths to the same bytes).

Storage (rs-drive)

• Pools live at [Tokens, TOKEN_SHIELDED_POOLS_KEY(224), token_id] (SumTree under a BigSumTree) with the credit pool's five children. The credit pool primitives were made pool-agnostic and given token twins, so notes, nullifiers, balances and anchors share one implementation.
• Composite operations for shield, unshield, shielded transfer, mint to pool and burn from pool, and the TokenOperationType lowering for them. calculate_total_tokens_balance v1 adds the pool balances to the conservation check: identity balances + pool balances == total supply.
• verify_* twins for the six shielded proofs and execution-proof queries for every new transition.

Batch transitions (rs-dpp, rs-drive-abci), identity-signed and paid in credits

• TokenShield, TokenUnshield, TokenShieldedTransfer (value balance -amount, +amount, 0).
• TokenMintToPool and TokenBurnFromPool follow the manual minting and burning rules; a group action stores a digest of the notes (serialized_actions_digest) so every signer commits to the same bundle. TokenClaimToPool releases a distribution into a note (a perpetual claim names the cycle-aligned moment it claims up to, resolved by the shared resolve_token_claim). TokenDirectPurchaseToPool pays credits at the direct purchase price for tokens minted into the pool.
• Sighash binding: an unshield binds token_id || owner_id || recipient_id || amount, a shielded transfer token_id || owner_id, a burn token_id || burner_id || amount where the burner is the batch owner or, for a group action, its proposer (the group action pins the digest of the signed actions, so every signer submits the proposer's bundle and the sighash cannot depend on whose batch carries it); outputs-only bundles bind nothing extra since the identity signature covers the batch. The proof verification fee is charged by the action transformers, so CheckTx admission and block execution price a bundle identically and an invalid proof is a paid failure with a nonce bump.
• CheckTx proof admission is keyed by the identity contract nonce (ShieldedProofAdmissionKey), and below protocol version 15 the batch is rejected with StateTransitionNotActiveError.

Documents paid from the pool

• TokenPaymentInfo::V1 carries a TokenShieldedPayment (a spend bundle in the payment token's pool whose value balance is the document action's token cost; boxed so the payment info stays small). The base action carries it, the transformer checks the amount against the document type's cost (TokenShieldedPaymentAmountMismatchError 40723, TokenShieldedPaymentNotRequiredError 40724), document base state validation v1 skips the owner's balance checks, the pool side and the proof (bound to token, owner, contract, document and amount) are validated after the document action, and the lowering pays the cost from the pool into the contract owner's balance or out of the supply.

Identity-less transitions (types 23, 24, 25)

• TokenShieldedTransferWithShieldedFee, TokenUnshieldWithShieldedFee and TokenPurchaseFromShieldedPool carry a bundle in the token's pool and a fee bundle in the credit pool, both authorized only by spend keys. The token bundle binds the type byte, the token id and the transparent fields; the fee bundle binds the type byte, the token id and a digest of the token bundle's actions, so the two cannot be re-paired.
• The minimum-fee validation pins credit_amount to the two-bundle fee (compute_token_pool_paid_shielded_fee: the base fee of each bundle plus the flat storage written outside the pools; a purchase adds the agreed price). Execution is a PaidFromShieldedPool event; uniqueness is by the spent nullifiers of both bundles; a purchase credits the contract owner and respects the pricing schedule and the max supply.

Block end: every touched pool (batch transitions, documents paid from a pool, identity-less transitions) is collected in the processing result and record_token_shielded_pool_anchors records its anchor and prunes old ones, always keeping the newest.

Queries and clients

• The six shielded pool requests take an optional token_id; handlers route through a ShieldedPoolSelector, the proof verifier routes on the same field, and the Rust SDK adds TokenShieldedPoolQuery, TokenShieldedEncryptedNotesQuery, TokenShieldedNullifiersQuery.
• DPP builders for every transition (build_token_*_transition, build_document_shielded_token_payment, and the identity-less builders taking a TokenPoolSpender and a ShieldedFeePayer).
• wasm-dpp2 wrappers for every transition, TokenPaymentInfo.shieldedPayment with a TokenShieldedPayment wrapper, hasShieldedPool and formatVersion on TokenConfiguration, TokenEventVariant entries; wasm-dpp arms and error mapping.

Not in this PR: the generated dapi-grpc JS, Python and Objective-C clients were not regenerated (the Docker-based protoc image was unavailable on the build machine); the proto change is a single optional field on six requests plus two group-action event messages, so a regeneration run can follow separately.

Docs: book chapter "Token Shielded Pools" (batch transitions, documents paid from the pool, identity-less transitions), the token sections of the shielded fees chapter, and the v15 module doc.

How Has This Been Tested?

• drive-abci integration tests with real Orchard proofs: shield, unshield, shielded transfer and a replay (nullifier already spent), pool not enabled, balance too low, paused token, frozen account, invalid proof as a paid failure with nonce bump, unknown anchor, protocol version 14 rejection of every new transition and of a version 1 configuration, contract create creating the pool and rejecting a pooled token with freeze rules; mint to pool by the owner, past max supply, by an unauthorized identity; burn from pool after a shield and its replay, a burn from the pool by a group of two with a substituted bundle rejected; a pre-programmed claim into the pool; a direct purchase into the pool with underpayment rejected; a document created with a shielded payment burning the cost and paying it to the contract owner, an amount mismatch, a replay; the three identity-less transitions with their fee accounting, a replay and an underpaid purchase; token conservation asserted after every successful step.
• The genesis-v15 versus upgrade-to-v15 equivalence of the token pools root.
• drive unit tests for pool creation, the composite operations, estimation, and anchor record/prune.
• dpp tests for structure validation, JSON and Value round trips of every new transition and of TokenPaymentInfo::V1, the frozen sighash layouts, the state error discriminants, the builders, the fee formulas; query selector tests, proof verifier tests.

Breaking Changes

None for released protocol versions. The new configuration format, trees, transitions and queries are gated on protocol version 15; TokenPaymentInfo is no longer Copy.

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 made corresponding changes to the documentation
• I have added "!" to the title and described breaking changes in the corresponding section if my changes might not be backward compatible

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 23e09162-1cfb-4f69-800d-e4cf6c820317

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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]

⚠️ DEGRADED — Blockers found — Phase 2 deferred (commit e305b85) · triage: critical · stand-in models (primary models out of quota)
Canonical validated blockers: 1

[github-actions]

📖 Book Preview built successfully.

Download the preview from the workflow artifacts.
To view locally: download the artifact, unzip, and open index.html.

Updated at 2026-09-18T01:55:13.901Z

[codecov]

Codecov Report

❌ Patch coverage is 68.64315% with 2311 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v4.3-dev@df01e75). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...tate_transition/processor/traits/shielded_proof.rs	35.07%	274 Missing ⚠️
packages/rs-dpp/src/tokens/token_event.rs	1.78%	165 Missing ⚠️
..._transition/batched_transition/token_transition.rs	19.44%	116 Missing ⚠️
packages/rs-dpp/src/shielded/sighash.rs	73.27%	93 Missing ⚠️
packages/rs-dpp/src/state_transition/mod.rs	24.76%	79 Missing ⚠️
...pp/src/shielded/builder/token_shielded_transfer.rs	50.00%	70 Missing ⚠️
...ate_transition/processor/traits/basic_structure.rs	30.00%	63 Missing ⚠️
...s-dpp/src/shielded/builder/token_burn_from_pool.rs	67.77%	58 Missing ⚠️
...ges/rs-dpp/src/shielded/builder/token_pool_paid.rs	87.88%	55 Missing ⚠️
...ages/rs-dpp/src/shielded/builder/token_unshield.rs	64.96%	55 Missing ⚠️
... and 99 more

Additional details and impacted files

@@             Coverage Diff             @@
##             v4.3-dev    #4760   +/-   ##
===========================================
  Coverage            ?   75.64%           
===========================================
  Files               ?     2981           
  Lines               ?   431263           
  Branches            ?        0           
===========================================
  Hits                ?   326250           
  Misses              ?   105013           
  Partials            ?        0           

Components	Coverage Δ
dpp	74.43% <0.00%> (?)
drive	77.35% <0.00%> (?)
drive-abci	74.55% <0.00%> (?)
sdk	∅ <0.00%> (?)
dapi-client	∅ <0.00%> (?)
platform-version	∅ <0.00%> (?)
platform-value	86.87% <0.00%> (?)
platform-wallet	∅ <0.00%> (?)
drive-proof-verifier	28.48% <0.00%> (?)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[QuantumExplorer]

Reviewed af95a95d5b8fbbae020a8c854907351c9935f6ec against 62c299cc043e36ec6fc8f746634cc67a68f0cdd1. Found two issues: a P1 proposal-availability failure in paid-error anchor bookkeeping and a P2 omission from token-pool proof fee admission.

All 230 changed files were accounted for. Findings are validated by source tracing; no local runtime reproductions were run. Rust CI passed, including the shielded tests, but the new transition tests do not exercise CheckTx or full block-end processing.

[QuantumExplorer]

[P1] Exclude nonexistent pools from anchor bookkeeping

A correctly signed TokenShield with a valid output-only Orchard proof can pass CheckTx for an existing token whose hasShieldedPool flag is false: CheckTx skips batch state validation, and output-only proof verification does not require a registered pool. Block execution returns the expected paid TokenShieldedPoolNotEnabledError, but this branch still adds the raw token ID to the touched set.

At block-end, record_token_shielded_pool_anchors tries to read that nonexistent pool's commitment tree. The missing-path error propagates through run_block_proposal and prepare_proposal, aborting proposal creation before transaction results and fee/nonce changes can commit. The admitted transaction can therefore disrupt subsequent proposal rounds.

Please collect pools that were actually written, or exclude nonexistent pools before anchor recording. Extend test_token_shield_rejected_when_pool_not_enabled through CheckTx and full proposal/block-end processing; its current helper stops after processing transitions, so it misses this failure.

[QuantumExplorer]

[P2] Include proof compute fees in CheckTx admission

This is the only insertion of the token-pool compute fee, but CheckTx skips batch state validation entirely (validates_full_state_on_check_tx() defaults to false). It therefore never reaches this helper, including the non-Validator return below. Batch execution events also set additional_fixed_fee_cost: None, and the preliminary batch minimum has no Orchard action component.

Consequently, the authoritative affordability check omits the 40,000,000-credit bundle fee plus 22,000,000 credits per action before CheckTx performs Orchard verification. An identity funded for the incomplete estimate can trigger proof work and, with a valid proof, enter the mempool despite lacking enough credits for execution. Block validation then adds this fee and rejects the event as unpaid after verification runs again. Existing nonce windows, weighted permits and proof caching constrain the resource impact but do not correct admission.

Please include exactly one compute fee per bundle in CheckTx's execution-event estimate, keeping block accounting consistent. Add underfunded-credit CheckTx cases for Shield, Unshield and ShieldedTransfer that reject before proof verification; the current low-balance test checks token balance instead.

[thepastaclaw]

Preliminary review — Phase 1 blocker gate

The token shielded pool implementation has three blocking correctness issues. Block-end anchor bookkeeping can turn a paid validation failure for a nonexistent or disabled pool into a proposal-aborting storage error, CheckTx does not account for the token-pool Orchard verification fee, and protocol-v13 nodes can accept newly encoded token transitions instead of rejecting them unpaid, causing version-divergent processing.

Validated blockers were found by the Phase-1 review and confirmed by a fresh verifier. Phase 2 is deferred until a fresh same-head revalidation clears the blocker gate.

🔴 3 blocking | 🟡 3 suggestion(s)

Review provenance

Source: reviewer 1: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 2: muse-spark-1.3-contributor (agent: phase1-reviewer, role: architecture-layering); reviewer 3: muse-spark-1.3-contributor (agent: phase1-reviewer, role: ffi-engineer); reviewer 4: muse-spark-1.3-contributor (agent: phase1-reviewer, role: platform-versioning); reviewer 5: muse-spark-1.3-contributor (agent: phase1-reviewer, role: rust-quality); reviewer 6: muse-spark-1.3-contributor (agent: phase1-reviewer, role: security-auditor); final verifier: gpt-6-astra (agent: astra-gate-verifier, role: verifier)

• Triage: critical by gpt-6-astra (effort low) — This is a large, intricate diff that changes consensus validation and execution, cryptographic shielded-proof and signature handling, token funds movement, and persistent Drive storage/migration paths, including functions such as token_shield_operations, token_unshield_operations, token_shielded_transfer_operations, proof verification, and pool initialization.
• Phase 1 reviewers: muse-spark-1.3-contributor — general (completed, effort xhigh); agent phase1-reviewer, muse-spark-1.3-contributor — architecture-layering (completed, effort xhigh); agent phase1-reviewer, muse-spark-1.3-contributor — ffi-engineer (completed, effort xhigh); agent phase1-reviewer, muse-spark-1.3-contributor — platform-versioning (completed, effort xhigh); agent phase1-reviewer, muse-spark-1.3-contributor — rust-quality (completed, effort xhigh); agent phase1-reviewer, muse-spark-1.3-contributor — security-auditor (completed, effort xhigh); agent phase1-reviewer
• Phase 1 model: muse-spark-1.3-contributor — not quota-gated; passed over gemini-3.8-flash-high (antigravity below 15% reserve: weekly 11% left, 5h 100% left), glm-5.3-flash (zai below 15% reserve: 5h 0% left, weekly 53% left)
• Fresh verifier: gpt-6-astra — verifier; agent astra-gate-verifier
• Phase 2 reviewers: not run (deferred by blocker gate)

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/process_raw_state_transitions/v0/mod.rs`:
- [BLOCKING] packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/process_raw_state_transitions/v0/mod.rs:286-297: Paid-invalid token transitions can abort block processing while recording a nonexistent pool
  The touched-pool set is populated from the transition's token ID before execution and is retained for both successful execution and paid consensus errors. A `TokenShield`, `Unshield`, or `ShieldedTransfer` for a token whose pool does not exist, including a token with `hasShieldedPool` disabled, can therefore add a nonexistent pool to the set after returning a paid validation error. At block end, `record_token_shielded_pool_anchors` attempts to read the commitment tree under `[Tokens, TOKEN_SHIELDED_POOLS_KEY, token_id]`; because the pool path is absent, the missing-path error propagates instead of being treated as an ordinary rejected transaction. This can make `run_block_proposal`/`prepare_proposal` fail before results, fees, and nonce changes are committed. The PR's CheckTx behavior allows this path to reach block processing. Record anchors only for pools actually created or mutated, filter the set against pool existence, or make the anchor recorder safely ignore missing pools.

In `packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/token/token_shielded_pool_common/mod.rs`:
- [BLOCKING] packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/token/token_shielded_pool_common/mod.rs:256-293: CheckTx admission omits token-pool Orchard verification fees
  `verify_token_pool_bundle` adds the token-pool compute fee (the fixed bundle cost plus the per-action cost) only during block-path state validation. Batch transitions skip full state validation in CheckTx, while their execution-event estimate leaves `additional_fixed_fee_cost` unset and the preliminary batch estimate contains no Orchard verification component. CheckTx can therefore admit a valid token shielded batch whose identity can pay the incomplete estimate but cannot pay the fee charged during block execution. The transaction still causes proof verification work during admission and is later rejected as underfunded during block validation. Include exactly one token-pool compute fee per bundle in the shared CheckTx/execution-event estimate, and add underfunded admission coverage for all three token transition types.

In `packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v10.rs`:
- [BLOCKING] packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v10.rs:230-235: Token shield transitions are not gated off below protocol version 14
  The new `TokenTransition::{Shield, Unshield, ShieldedTransfer}` variants are appended correctly for serialization, but the nested validation and conversion version slots remain `0` in both the v13 and v14 platform-version tables. The v0 implementations do not check `TOKEN_SHIELDED_POOL_INITIAL_PROTOCOL_VERSION`, and the batch `is_allowed` path does not reject these token transition kinds before nonce/fee processing. Consequently, a v14-encoded batch containing one of these variants can be decoded and paid-processed by a new binary at protocol v13, while an old v13 binary cannot decode the variant and strips or rejects the batch unpaid. That creates divergent transaction acceptance and can halt the chain. Add an unpaid pre-nonce activation gate below v14, following the existing inactive-feature/base-structure pattern, and select the new versioned implementation only in v14.

In `packages/rs-dpp/src/shielded/builder/token_shield.rs`:
- [SUGGESTION] packages/rs-dpp/src/shielded/builder/token_shield.rs:42-56: Token shield builder does not enforce the Orchard amount range or bundle amount consistency
  The token shield builder rejects zero but does not reject amounts greater than `i64::MAX`, even though the Orchard bundle's `value_balance` is `i64`. It also derives the transition amount from `value_balance.unsigned_abs()` without checking that it equals the caller-provided amount. Large inputs therefore fail later with a generic build/proof error, and any future bundle-shape mismatch could produce a transition for a different amount than requested. Apply the same explicit range and equality checks used by the sibling unshield builder.

In `packages/rs-dpp/src/shielded/builder/token_unshield.rs`:
- [SUGGESTION] packages/rs-dpp/src/shielded/builder/token_unshield.rs:59-66: Token unshield builder uses unchecked spend summation
  The builder sums caller-provided note values with `Iterator::sum::<u64>()`. A sufficiently large spend list can overflow: in debug builds this can panic, while in release builds it wraps and may produce an invalid total for subsequent amount and balance checks. Use checked accumulation and return `ShieldedBuildError` on overflow. The same issue is present in the token shielded transfer builder and should be fixed there as well.

In `packages/rs-dpp/src/data_contract/associated_token/token_configuration/accessors/mod.rs`:
- [SUGGESTION] packages/rs-dpp/src/data_contract/associated_token/token_configuration/accessors/mod.rs:247-262: The shielded-pool setter creates a second representation of an unpooled token
  `set_has_shielded_pool(true)` upgrades a V0 configuration to V1, but setting the flag back to false on that V1 leaves the V1 variant in place. This permits both V0 and V1(false) to represent the same semantic unpooled configuration while having different serialized format versions; pre-v14 validation rejects the V1 representation even though it has no pool. A variant-changing setter also makes the format upgrade implicit. Use an explicit upgrade operation or preserve a canonical representation for the false case so callers cannot create V1(false) configurations that are rejected solely because of their hidden format version.

[thepastaclaw]

Re-review — Final validation — Phase 2 only (queue backlog)

The protocol-version, fee-accounting, pool-bookkeeping, and builder-overflow issues from the prior review have been fixed. Two in-scope correctness issues remain: group-authorized pool burns bind the Orchard proof to each individual confirmer instead of a common group action identity, and the purchase builder can panic on an out-of-range public input. The purchase builder also performs a redundant full Orchard proof generation.

🔴 2 blocking | 🟡 1 suggestion(s)

3 finding(s) not shown inline (GitHub refused the PR diff as too large)

🔴 Blocking: Group token burns bind the shielded bundle to each confirmer's identity
packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/token/token_burn_from_pool_transition_action/state_v0/mod.rs:234-250

The burn proof sighash includes the current batch owner_id, while the group-action validation above requires every confirmer to preserve the same amount and serialized_actions_digest. The proposer and a later confirmer have different batch owner identities, so the proposer’s bundle cannot be reused by the confirmer: keeping the original bundle causes the proof verification to use a different owner-bound sighash, while rebuilding the bundle for the confirmer changes the spend-auth signatures and therefore changes serialized_actions_digest, which is rejected as a modification of the group action. As a result, the newly supported group-authorized TokenBurnFromPool flow cannot complete for a group with multiple signers. The sighash needs to bind to a stable group-action identity or otherwise use the same authorization context for every confirmer.

_{source: gpt-6-astra (phase2-reviewer: general)}

🔴 Blocking: Token purchase builder can panic when negating an unchecked out-of-range amount
packages/rs-dpp/src/shielded/builder/token_pool_paid.rs:348-353

token_count is a public u64 input, but the builder only rejects zero before constructing the bundle. For token_count == 1u64 << 63, the later -(token_count as i64) at line 390 panics with integer overflow in debug and test builds; the value is also outside Orchard's signed value-balance range. Malformed caller input therefore causes a process panic instead of returning the documented ProtocolError, and the invalid-range check should occur before the expensive proof generation.

    if token_count == 0 {
        return Err(ProtocolError::ShieldedBuildError(
            "token purchase count must be greater than zero".to_string(),
        ));
    }
    if token_count > i64::MAX as u64 {
        return Err(ProtocolError::ShieldedBuildError(format!(
            "token purchase count {} exceeds maximum allowed value {}",
            token_count,
            i64::MAX as u64
        )));
    }

_{source: gpt-6-astra (phase2-reviewer: rust-quality)}

🟡 Suggestion: Token purchase builder generates and discards a complete Orchard proof
packages/rs-dpp/src/shielded/builder/token_pool_paid.rs:353-388

The first build_output_only_bundle call proves and signs an outputs-only bundle, but its result is never used. The function then reconstructs the same output in the following builder and calls prove_and_sign_bundle again with the purchase-specific sighash. Orchard proof generation is expensive, so every token purchase performs the full proving work twice. Construct and prove the output bundle only once, using the purchase-specific extra sighash data from the start.

_{source: gpt-6-astra (phase2-reviewer: rust-quality)}

Review provenance

Source: reviewer 1: gpt-6-astra (agent: phase2-reviewer, role: general); reviewer 2: gpt-6-astra (agent: phase2-reviewer, role: architecture-layering); reviewer 3: gpt-6-astra (agent: phase2-reviewer, role: platform-versioning); reviewer 4: gpt-6-astra (agent: phase2-reviewer, role: rust-quality); reviewer 5: gpt-6-astra (agent: phase2-reviewer, role: security-auditor); final verifier: gpt-6-astra (agent: astra-verifier, role: final-verifier)

• Triage: critical by gpt-6-astra (effort low) — This large, intricate diff changes consensus validation, cryptographic shielded-proof and signature handling, funds movement, token accounting, peer-facing transition serialization, and storage migrations across protocol version 15.
• Phase 1 reviewers: not run (skipped for throughput: 13 PRs queued, above the 10 limit)
• Fresh verifier: gpt-6-astra — final-verifier; agent astra-verifier
• Phase 2 reviewers: gpt-6-astra — general (completed, effort xhigh); agent phase2-reviewer, gpt-6-astra — architecture-layering (completed, effort xhigh); agent phase2-reviewer, gpt-6-astra — platform-versioning (completed, effort xhigh); agent phase2-reviewer, gpt-6-astra — rust-quality (completed, effort xhigh); agent phase2-reviewer, gpt-6-astra — security-auditor (completed, effort xhigh); agent phase2-reviewer

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/token/token_burn_from_pool_transition_action/state_v0/mod.rs`:
- [BLOCKING] packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/token/token_burn_from_pool_transition_action/state_v0/mod.rs:234-250: Group token burns bind the shielded bundle to each confirmer's identity
  The burn proof sighash includes the current batch `owner_id`, while the group-action validation above requires every confirmer to preserve the same amount and `serialized_actions_digest`. The proposer and a later confirmer have different batch owner identities, so the proposer’s bundle cannot be reused by the confirmer: keeping the original bundle causes the proof verification to use a different owner-bound sighash, while rebuilding the bundle for the confirmer changes the spend-auth signatures and therefore changes `serialized_actions_digest`, which is rejected as a modification of the group action. As a result, the newly supported group-authorized `TokenBurnFromPool` flow cannot complete for a group with multiple signers. The sighash needs to bind to a stable group-action identity or otherwise use the same authorization context for every confirmer.

In `packages/rs-dpp/src/shielded/builder/token_pool_paid.rs`:
- [BLOCKING] packages/rs-dpp/src/shielded/builder/token_pool_paid.rs:348-353: Token purchase builder can panic when negating an unchecked out-of-range amount
  `token_count` is a public `u64` input, but the builder only rejects zero before constructing the bundle. For `token_count == 1u64 << 63`, the later `-(token_count as i64)` at line 390 panics with integer overflow in debug and test builds; the value is also outside Orchard's signed value-balance range. Malformed caller input therefore causes a process panic instead of returning the documented `ProtocolError`, and the invalid-range check should occur before the expensive proof generation.
- [SUGGESTION] packages/rs-dpp/src/shielded/builder/token_pool_paid.rs:353-388: Token purchase builder generates and discards a complete Orchard proof
  The first `build_output_only_bundle` call proves and signs an outputs-only bundle, but its result is never used. The function then reconstructs the same output in the following builder and calls `prove_and_sign_bundle` again with the purchase-specific sighash. Orchard proof generation is expensive, so every token purchase performs the full proving work twice. Construct and prove the output bundle only once, using the purchase-specific extra sighash data from the start.

[QuantumExplorer]

Review round 2 (review 5228577296) addressed in e305b85:

• Group burns bound the bundle to each confirmer (blocking): confirmed. The TokenBurnFromPool sighash now binds the burner rather than the batch owner: the batch owner for a direct burn, the stored group action's proposer for every other signer (token_burn_from_pool_extra_sighash_data(token_id, burner_id, amount)). The group action id cannot serve, since it hashes the digest of the signed actions (circular with the sighash). The builder refuses to prove a fresh bundle for GroupStateTransitionInfoOtherSigner, because the digest check would reject it anyway. New drive-abci test test_token_burn_from_pool_by_group_of_two runs the proposer plus confirmer flow with real proofs, checks nothing leaves the pool after the first signature, rejects a substituted bundle with ModificationOfGroupActionMainParametersNotPermittedError, and asserts the burn and conservation after the second.
• Purchase builder panics on token_count == 1 << 63 (blocking): confirmed. build_token_purchase_from_shielded_pool_transition rejects a count above i64::MAX right after the zero check, before any proving; unit test rejects_a_purchase_count_outside_the_value_balance_range. Consensus was already safe (MAX_DISTRIBUTION_PARAM bound in the structure validation).
• Purchase builder proves a throwaway bundle (suggestion): confirmed. The outputs-only bundle is now built and proven once over the purchase sighash; the unused build_output_only_bundle call is gone.

Book chapter and PR body updated for the burner binding.

🤖 Addressed by Claude Code

[thepastaclaw]

⚠️ DEGRADED — Re-review — Preliminary review — Phase 1 blocker gate

⚠️ DEGRADED review. The primary review models were unavailable (gpt-6-astra unavailable: All credentials for model gpt-6-astra are cooling down (last error: usage_limit_reached: The usage limit has been reache), so this review ran on stand-in models: gpt-5.6-luna → muse-spark-1.3-contributor, gpt-5.6-sol → muse-spark-1.3-contributor, gpt-5.6-terra → muse-spark-1.3-contributor, gpt-6-astra → muse-spark-1.3-contributor. Both review phases and the independent verifiers still ran, but on weaker models, with Phase 1 capped at high effort. Treat the verdict as provisional; a full-strength re-review will run on the next push once the primary models are back.

Protocol version 15 token shielded pools are well-implemented and all 9 prior findings verify as fixed, but the head commit's group-burn proposer binding was only applied to block execution: CheckTx's stateless proof validator still binds the submitter's identity, so every valid multi-sig group burn confirmation is rejected at mempool admission.

Validated blockers were found by the Phase-1 review and confirmed by a fresh verifier. Phase 2 is deferred until a fresh same-head revalidation clears the blocker gate.

🔴 1 blocking

1 finding(s) not shown inline (GitHub refused the PR diff as too large)

🔴 Blocking: CheckTx rejects group token burn confirmations due to mismatched owner_id sighash binding
packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/shielded_proof.rs:1067-1083

Block execution (token_burn_from_pool_transition_action/state_v0/mod.rs:237-246) binds a group burn's sighash to the stored group action's proposer_id, since every signer must submit the proposer's bundle unchanged (pinned by the serialized actions digest). But the stateless CheckTx pass in validate_batch_token_shielded_proofs unconditionally derives extra_sighash_data from batch.owner_id(). When a non-proposing group member submits their confirmation batch, batch.owner_id() is the confirmer, not the proposer, so reconstruct_and_verify_bundle recomputes the sighash with the wrong identity and binding-signature verification fails with InvalidShieldedProofError. Every valid group token burn confirmation is therefore rejected during CheckTx admission and can never enter the mempool. The proposer identity lives in state under the group action tree and is unavailable statelessly, so like ClaimToPool (which already skips this pass because its amount is only known from state), non-proposer group burn confirmations must skip stateless verification and defer to validate_state_v0, where the proposer ID is resolved from state. Only BurnFromPool needs this: it is the sole pool transition with an owner-bound sighash that implements AllowedAsMultiPartyAction (MintToPool and outputs-only bundles bind no extra data; Shield/Unshield/ShieldedTransfer do not support group actions).

            BatchedTransitionRef::Token(TokenTransition::BurnFromPool(t)) => {
                if t
                    .base()
                    .using_group_info()
                    .is_some_and(|info| !info.action_is_proposer)
                {
                    // A group burn confirmation reuses the proposer's bundle, whose burner
                    // identity is only known from state. Proof verification is deferred
                    // to block validation, where the proposer ID is resolved from the
                    // stored group action.
                    continue;
                }
                let extra_sighash_data = dpp::shielded::token_burn_from_pool_extra_sighash_data(
                    &t.base().token_id().to_buffer(),
                    &owner_id,
                    t.amount(),
                    platform_version,
                )?;

_{source: gemini-3.8-flash-high (phase1-reviewer: rust-quality)}

Review provenance

Source: reviewer 1: gemini-3.8-flash-high (agent: phase1-reviewer, role: general); reviewer 2: gemini-3.8-flash-high (agent: phase1-reviewer, role: architecture-layering); reviewer 3: gemini-3.8-flash-high (agent: phase1-reviewer, role: platform-versioning); reviewer 4: gemini-3.8-flash-high (agent: phase1-reviewer, role: rust-quality); reviewer 5: gemini-3.8-flash-high (agent: phase1-reviewer, role: security-auditor); final verifier: muse-spark-1.3-contributor (standing in for gpt-6-astra) (agent: astra-gate-verifier, role: verifier)

• Degraded mode: gpt-6-astra unavailable: All credentials for model gpt-6-astra are cooling down (last error: usage_limit_reached: The usage limit has been reache (detected by probe, since 2026-09-18T05:22:01Z); stand-ins gpt-5.6-luna → muse-spark-1.3-contributor, gpt-5.6-sol → muse-spark-1.3-contributor, gpt-5.6-terra → muse-spark-1.3-contributor, gpt-6-astra → muse-spark-1.3-contributor; Phase 1 effort capped at high
• Triage: critical by muse-spark-1.3-contributor (standing in for gpt-6-astra) (effort low) — Massive 32k-line change adds per-token Orchard shielded pools with new consensus rules, shielded proof verification, sighash/signature binding, and funds-movement/storage logic (e.g. shielded_proof.rs and token_shielded_pool_common execution).
• Phase 1 reviewers: gemini-3.8-flash-high — general (completed, effort high); agent phase1-reviewer, gemini-3.8-flash-high — architecture-layering (completed, effort high); agent phase1-reviewer, gemini-3.8-flash-high — platform-versioning (completed, effort high); agent phase1-reviewer, gemini-3.8-flash-high — rust-quality (completed, effort high); agent phase1-reviewer, gemini-3.8-flash-high — security-auditor (completed, effort high); agent phase1-reviewer
• Phase 1 model: gemini-3.8-flash-high — antigravity quota: weekly 100% left, 5h 100% left
• Fresh verifier: muse-spark-1.3-contributor (standing in for gpt-6-astra) — verifier; agent astra-gate-verifier
• Phase 2 reviewers: not run (deferred by blocker gate)

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/shielded_proof.rs`:
- [BLOCKING] packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/shielded_proof.rs:1067-1083: CheckTx rejects group token burn confirmations due to mismatched owner_id sighash binding
  Block execution (token_burn_from_pool_transition_action/state_v0/mod.rs:237-246) binds a group burn's sighash to the stored group action's proposer_id, since every signer must submit the proposer's bundle unchanged (pinned by the serialized actions digest). But the stateless CheckTx pass in validate_batch_token_shielded_proofs unconditionally derives extra_sighash_data from batch.owner_id(). When a non-proposing group member submits their confirmation batch, batch.owner_id() is the confirmer, not the proposer, so reconstruct_and_verify_bundle recomputes the sighash with the wrong identity and binding-signature verification fails with InvalidShieldedProofError. Every valid group token burn confirmation is therefore rejected during CheckTx admission and can never enter the mempool. The proposer identity lives in state under the group action tree and is unavailable statelessly, so like ClaimToPool (which already skips this pass because its amount is only known from state), non-proposer group burn confirmations must skip stateless verification and defer to validate_state_v0, where the proposer ID is resolved from state. Only BurnFromPool needs this: it is the sole pool transition with an owner-bound sighash that implements AllowedAsMultiPartyAction (MintToPool and outputs-only bundles bind no extra data; Shield/Unshield/ShieldedTransfer do not support group actions).