Smart contracts on Platform: staged design and implementation plan

[QuantumExplorer]

Smart contracts on Platform: staged design and implementation plan

This document proposes how Dash Platform should add smart contracts: Rust contracts compiled to WebAssembly, executed by an unmodified and pinned wasmi interpreter, with a host layer and guest SDK owned by Dash, delivered in protocol-version-gated stages. Contract state stays document-shaped so proofs, indexes, fees, and refunds apply unchanged, and user code proposes operations that the existing Drive pipeline validates and applies. It records the options that were evaluated and why they were rejected or deferred, the target architecture, six delivery phases with task checklists, the cross-cutting engineering disciplines (determinism, security, fees), the developer-experience plan, and the open questions reviewers are asked to decide. Every checkbox is intended to be one reviewable unit of work.

Status: proposal for review. No DIP, issue, or code existed before this document. Opened 2026-09-08.

This is a proposal, not an approved roadmap, so it is one issue rather than a set of tracking issues. The task lists are here to be argued with: they show the shape and size of each phase. If the plan is accepted, the phases become their own tracking issues carrying these checkboxes, and this issue becomes the rationale they link back to.

How to review: the argument runs in order, so sections 1 to 4 carry the reasoning and the rejected alternatives, sections 5 to 10 are the phases, and sections 11 to 14 are the cross-cutting disciplines and delivery. Please quote the section and heading you are addressing, since the document spans several comments. Section 14 lists the open questions that need a decision before Phase 0 can close.

Contents

1. Summary, goals, non-goals, and design principles
2. Current state of Platform: what exists, what is missing
3. Options considered and why they were rejected or deferred
4. Target architecture
5. Phase 0: decisions, DIP, and groundwork
6. Phase 1: VM-independent infrastructure
7. Phase 2: bounded expression guards
8. Phase 3: WASM validation predicates
9. Phase 4: declared-footprint reads
10. Phase 5: constrained entry points
11. Cross-cutting: determinism, security, and engine governance
12. Cross-cutting: fees and economics
13. Developer experience, SDK, and tooling plan
14. Delivery: sequencing, testing, rollout, success criteria, risks, open questions

---

1. Summary, goals, non-goals, and design principles

Path prefixes as in section 02: abci/ is packages/rs-drive-abci/src, pv/ is packages/rs-platform-version/src/version.

1.1 What is proposed

User-authored contract logic on Dash Platform as Rust compiled to WebAssembly, executed inside Drive on an exactly pinned wasmi 2.0-line interpreter (MSRV 1.86 against the workspace's Rust 1.92, rust-toolchain.toml), behind a host layer and guest SDK that Dash writes and owns. The pin is a criterion, not a version: the earliest 2.0.x that passes section 3.11's differential fuel and trap corpus and has run for a Phase 0-decided number of months under section 13's native harness and fuel corpus before the PV17 PR takes the dependency. wasmi 2.0.0 shipped on 2026-09-01 on a rewritten IR built around three new accumulator registers, with no patch release yet (crates.io, 2026-09-07), and its 1.0 line needed a limit-check fix (1.0.4), an execution fix (1.0.5, rem_s(MAX, -1)) and translation fixes in 1.0.6, 1.0.7, 1.0.8 and 1.0.9, all inside ten weeks of the 1.0 release (1.0.0 on 2025-12-03, 1.0.9 on 2026-02-09; wasmi CHANGELOG), so the bake criterion is an open Phase 0 decision. v0 meters with the engine's operator_cost table; install-time instrumentation (the Internet Computer's model) is the engine-independent fallback if the corpus shows patch-level drift. wasmi has one maintainer and its sponsorship ends in October 2026 (external-engines facts): Dash is maintainer of last resort for a fork if that maintainer leaves, and fork-and-freeze versus co-sponsorship (section 14, question 4) is a Phase 0 decision.

Delivery is staged, one masternode-voted protocol version per stage: VM-independent infrastructure (fuel priced into processing fees, so gas_wanted (abci/abci/handler/check_tx.rs:66-69) carries each transition's full fuel bound to Tenderdash under the genesis block.max_gas (packages/dashmate/configs/defaults/getBaseConfigFactory.js:436), a mempool parameter no Drive code enforces, so Drive adds the consensus-side budget of goal 4; a code-blob channel), with native primitives and oracle feeds as Phase 1b, a value-moving track that no VM phase waits for; then statically costed expression guards, WASM validation predicates on document types, declared-footprint reads, and finally constrained entry points returning a bounded list of proposed document, token and credit operations.

Contract state stays document-shaped under the contract's documents subtree, so proofs, indexes and the end-of-block conservation check apply unchanged. Fee mechanics are unchanged; attribution for entry-point writes is decided in Phase 0 beside D1 and D3 (section 05), default: the signer is balance-checked and pays; each written element carries in its StorageFlags the acting owner the operation names (caller or principal), who gets the refund (refunds fold per identifier, packages/rs-drive/src/fees/op.rs:275-300); entry points touch only documents the caller or the principal owns (deletes are owner-checked today, document_delete_transition_action/state_v0/mod.rs:97-103). Code blobs are immutable, hash-addressed and reference-counted, deletable with refund only at zero references (section 06.2); module bytes pay the disk rate plus a fixed module fee in a new FeeDataContractRegistrationVersion generation (section 12); a contract is permanent unless its config sets can_be_deleted (packages/rs-dpp/src/data_contract/config/v1/mod.rs:25), so a referenced blob's storage is permanent in practice.

Guest code never writes GroveDB: it accepts, rejects or proposes; the pipeline prices under estimated >= actual (goal 4) and applies (principle 2). Authorization is new consensus surface (a Phase 5 task, section 10): a proposed operation may act on assets the caller owns (the caller signed) or on assets the principal owns, the keyless identity subtype a contract holds (section 04.4), authorized solely by that contract's entry point with no key path; principal balances sit in the identity balance tree, so process_block_fees_and_validate_sum_trees (process_block_fees_and_validate_sum_trees/mod.rs:38) covers them.

README.md:49-50 says smart contract support is "planned for Platform v4.0 (targeted for mainnet in 2027)" and the comparison table's smart-contract cell reads "Coming in v4.0" (README.md:63); dash.org lists a VM milestone at v5.0, Q1 2027. The repository has no design, issue or VM dependency behind either. The latest protocol version in tree is 14 (pv/mod.rs:36, unreleased); this plan targets 15 and later (calendar in 1.6).

1.2 Status of this document

A proposal for review, not a decision record: no DIP, code or protocol version exists for this work. After the open questions in section 14 are settled, the consensus design moves to a DIP in dashpay/dips (the platform repository does not accept committed design documents, CLAUDE.md:96-100) and the task lists here become issues and PRs. Repository facts were verified at v4.2-dev commit a3c36f3 on 2026-09-07; external engine facts are dated where they appear. The research synthesis named wasmi 1.0; wasmi 2.0.0 has since shipped, and where they differ this document governs (section 08).

1.3 Goals

1. Let third parties attach network-enforced logic to their own data contracts without a Dash-shipped protocol change per application; today custom rules are Rust data triggers behind a fn-pointer type (batch/data_triggers/mod.rs:26-30), dispatched from a hard-coded per-protocol-version binding list only Dash can extend (batch/data_triggers/bindings/list/mod.rs:11). 1.6 maps which phase delivers which part.
2. Keep all contract-visible state provable to light clients through the existing query and proof machinery, the property the README comparison table sells (README.md:52-63).
3. Execute identically on every node and architecture, including identical error classification (principle 6): user code must never surface as InternalError (validators reject the proposal, abci/abci/handler/process_proposal.rs:285-307) or as a block-event Err (node halt).
4. Bound and price all execution under estimated >= actual, the invariant the code already enforces: the affordability dry run prices with apply_drive_operations(apply = false), execution charges the actual metered cost, execute_event/v0/mod.rs:186-206 records the 2026-08-14/15 mainnet stalls as estimated < actual, and an uncoverable charge is Err (apply_balance_change_from_fee_to_identity/v0/mod.rs:92-100). Fuel is unknowable before a run, so (a) every hook-bearing transition has a fuel bound fixed before execution, the SystemLimits per-call cap for predicates and a caller-declared max_fuel at or below that cap for calls, priced with the instantiation, translation, memory and context terms into one figure: B at PV17 and PV18 (8.2.6), max_fee at PV19 (10.2.4). (b) That bound is checked against the payer before the engine is entered, not after validation: with the signer's PartialIdentity already loaded, the seam requires live balance minus the processing accrued so far in this transition to cover the bound plus the nonce-bump cost, both sides after apply_user_fee_increase, and otherwise returns InsufficientBalanceForHookExecution, paid at the affordable minimum with the nonce bumped and no instantiation (8.2.6, 11.2.3). No literal debit and credit-back. Checking after validation is too late: an unaffordable event executes as UnpaidConsensusExecutionError, no charge and no bump, and check_tx prices each transition against the last committed balance, so one balance admits N sequential-nonce transitions of which N-1 would run to the bound for free. (c) consume_fuel traps at the bound and the charge never exceeds what was priced: out-of-fuel pays the whole bound it consumed, a trap pays fuel to the trap plus the base, so failed executions are paid. (d) A declared bound above the cap is a structural error at check_tx and recheck. The block budget, max_block_processing_credits (new SystemLimits field, section 06.1), is enforced twice: the declared bounds of a proposal's hook-bearing transitions, summed from the decoded transitions at the fuel rate, reject an over-budget proposal before any hook runs; 06.1's running cutoff on accrued processing credits then marks later transitions NotExecuted under a new NotExecutedReason value beside ProposerRanOutOfTime (abci/platform_types/state_transitions_processing_result/mod.rs:13-16), which validators reject. No execution-result variant is added, so the exhaustive rollback match's NotExecuted(_) arm already covers it (process_raw_state_transitions/v0/mod.rs:252-262); the new reason's TxAction classification in prepare_proposal must agree with that arm. The per-transition cap is strictly below the budget, so every transition is includable; failed executions count, since they run and pay. block.max_gas and the budget are calibrated together (section 12) against the proposer-only 5000 ms proposer_tx_processing_time_limit (process_raw_state_transitions/v0/mod.rs:149-158; packages/rs-drive-abci/.env.mainnet:92; validators pass none, process_proposal.rs:235-241).
5. Ship stages that are each independently useful, PV-gated, and reused by the next, so nothing is throwaway if the plan stops early.
6. Give authors a Rust-native loop (guest SDK, native harness under cargo test, simulator; section 13) as a funded precondition: NEAR and Soroban ran SDK teams for years and ink! halted in January 2026 when funding failed (report 07), so Phase 0 records the SDK and developer-tooling commitment (owner, engineer count, funded duration) as a row of its own in section 05's register beside D1 to D13, proposed as D14 and due before the PV17 PR-opening stack; if it is unfunded at Phase 3's PV-opening PR the plan stops at guards. Authors: Phase 2 guards, today's data-contract authors in any SDK (js-evo-sdk, Swift, Kotlin); Phases 3 to 5, Rust developers writing no_std guests against a Dash-specific ABI (bespoke onboarding whatever the language, report 09 on Stacks), a population that today exists only inside Dash's own SDK and FFI crates (packages/rs-sdk, packages/rs-sdk-ffi).
7. Define engine governance before the engine ships (section 11): every activated engine stays compiled in as a vendored fork under its own package name (the soroban-wasmi pattern), since Cargo unifies semver-compatible versions (=2.0.3 and =2.0.4 cannot coexist), selected by wasm_engine_version beside grove_version (pv/drive_versions/mod.rs:40-46); CI replays a recorded block corpus under every shipped engine (abci/replay/runner.rs); fuel vectors are recorded per engine, since 2.0's fuel is "relatively stable" and "less precise" (wasmi docs/migration-v1-to-v2.md); a security patch that changes an executed result activates as a new protocol version with a documented divergence height, never a silent patch bump (1.0.5 is the precedent, 1.1); a previously accepted module that fails to instantiate under a new engine is a class-1 error (fail closed, paid); the upgrade suite instantiates every registered testnet and mainnet module under the candidate engine before the vote; an owner has a re-registration path. Stewardship is governance too: Dash owns the fork if the single maintainer leaves (1.1), and 3.11 scores wasmi and every rejected engine on one test: maintainers, funding horizon, production embedders.
8. Compose with identities, tokens, groups, ChangeControlRules, and DPNS rather than a shadow layer; no in-contract balances outside the sum trees, and principal assets move only under 1.1's authorization rule.

1.4 Non-goals

1. EVM bytecode or Solidity compatibility, an eth JSON-RPC surface, or secp256k1 accounts beside identities: rejected in section 3 on structural cost (account model, a parallel MPT, an RPC node); the 2026 outcomes of the EVM ports corroborate but are not the standard (Aurora down 99% in TVL with a July 2026 halt, Evmos shut down in May 2026, Botanix shut down twelve months after launch; report 06, principle 9).
2. General contract-to-contract calls, reentrancy, or nested revert semantics before Phase 5 has shipped and demand is demonstrated; Phase 5 is one entry point per state transition proposing operations on its own contract, under principle 2's nesting rule.
3. Native AMM or lending primitives; Phase 1b ships only primitives whose mechanism design is settled (section 6).
4. CosmWasm, Move, or SVM ABI compatibility as a delivery target (principle 5 answers CosmWasm), and opaque raw key-value storage as the primary contract state model (section 4).
5. Floating point, SIMD, threads, multiple memories, or a start function in guest modules; all rejected at registration.
6. Off-chain execution (zk-coprocessor, TEEs, optimistic verification) as deliverables; the zk-predicate variant gets a parallel design study (section 14) since Drive already verifies Orchard proofs in consensus.
7. Changes to Tenderdash; where a limit is Tenderdash-coupled (max_state_transition_size 20480, pv/system_limits/v4.rs:23) the plan prefers Drive-side mechanisms.
8. A JIT engine tier: deferred in section 10.7, with no protocol-version assignment here.

1.5 Design principles

1. Engine-independent, protocol-version-frozen metering is the requirement; determinism over speed follows. A divergence halts the chain, validators re-execute with no consensus-visible bound, and the engine is off the critical path at Platform's block cadence (section 3.10), so any deterministic slowdown is affordable and a codegen or stack-depth divergence is not. wasmi over wasmtime 36 LTS with Pulley plus finite-wasm (section 14, question 4(c)): a heap-allocated guest stack, so stack limits are engine numbers rather than native frames; no code generator, while Pulley is Tier 2 (wasmtime docs/stability-tiers.md:93); Soroban's shape. Against: one maintainer, sponsorship ending October 2026, a major released this month, hence 1.1's pin by criterion. The interpreter is the only tier in Phases 3 to 5.
2. User code proposes, Drive disposes. The guest returns a verdict or a bounded list of proposed operations that the native pipeline validates, prices and applies, keeping indexes, proofs, fees and conservation unchanged. Application is sequential: each proposed operation is transformed, validated and applied one at a time in list order, each against the state after its predecessors, inside the transition's transaction under one savepoint per call and one operation per GroveDB batch group, fees summed (section 10.2.3). Validating the whole list against pre-call state instead would let two creates that both pass uniqueness collide at apply as DriveError::CorruptedContractIndexes (packages/rs-drive/src/error/drive.rs:112), an Err and a rejected block on every validator. One operation per group predates Phase 5: the pipeline refuses more than one document operation per GroveDB batch at every protocol version, because flattened operations cannot see each other and leave phantom index groups that still rank and prove (max_transitions_in_documents_batch: 1, pv/system_limits/v1.rs:8-33, pinned at system_limits/mod.rs:114-141); the cross-sibling derived-entry tracking those comments name is a Phase 5 prerequisite. Nesting depth is one: an entry point proposes, a proposed document operation runs its type's guards, predicates and triggers, which only accept or reject, so no predicate re-enters an entry point; all runs share the transition's one fuel bound; proposed operations are capped in SystemLimits; any rejection fails the whole transition as a paid consensus error with nothing applied, so no revert overlay exists.
3. Proofs for everything survive. Contract state is documents, because opaque bytes would exempt exactly the applications people care about from the verification story that differentiates Platform.
4. Every engine change is a protocol version: engine version, operator cost table, host imports and module limits are PlatformVersion table fields activated by masternode vote, under goal 7's coexistence, replay, re-validation and patch rules.
5. No framework import, for reasons that hold. CosmWasm's address format is host-defined and its callbacks return GasInfo with a separate externally_used channel, so neither the account model nor the processing/storage split is the obstacle (report 05). The disqualifiers: a wasmer JIT pinned at =5.0.6 in consensus, source of a metering escape (CWA-2024-007, incorrect gas tracking in Wasmer) alongside a host-panic gas escape in the same patch round (CWA-2024-008); a submessage, reply and migration surface non-goal 2 excludes anyway, whose keeper is wasmd's Go with no maintained Rust port; JSON at every boundary (serde-json-wasm carried CWA-2024-001); cw20/cw721 balances in contract storage that escape conservation. Phase 5 is CosmWasm's Response pattern minus reply and cross-contract dispatch. Why not the cosmwasm-std entry-point and Response ABI on wasmi with Custom messages: the interface_version export ties every guest to cosmwasm-vm's release cadence, which Dash would freeze per protocol version without controlling; JSON costs fuel and bytes under a 20480-byte transition cap; and the libraries that compatibility buys (cw-storage-plus, cw-multi-test) assume flat KV with ordered iteration, which document-shaped state lacks. Its lessons (module limits, capability imports, hash-addressed code) are adopted now; a CosmWasm ABI layer stays a 10.7 option.
6. Failures are typed; only guest-caused failures are consensus errors. Class 1, guest-observable and deterministic (trap, out-of-fuel, memory or table limit, footprint miss, malformed guest pointer or length, bad host-call argument, document not found on a declared read, rejected proposed operation, accepted module that no longer instantiates), maps through one function to typed ConsensusError variants enumerated in dpp and gated per protocol version: paid, nonce bumped. Class 2, anything from Drive or GroveDB storage, stays Err, hence InternalError and a rejected proposal (process_proposal.rs:285-307), a node fault as today. The guard is in the type system: host imports return a host-error enum with no From<drive::Error> impl, so a Drive error cannot become class 1 without a reviewed match (today's trigger seam propagates every Err with ?, data_triggers/executor.rs:47); a test proves every class-1 variant reachable from guest input and no class-2 path. Panics are forbidden: drive-abci builds with panic = "unwind" (root Cargo.toml:72, :82 set abort only for iOS profiles) and process_proposal holds .write().unwrap() (process_proposal.rs:31, :272-273), so a guest-reachable panic poisons the lock on every node at once. Every host import reads guest memory through one bounds-checked accessor returning a class-1 error; the host crate denies clippy::indexing_slicing, clippy::unwrap_used, clippy::expect_used and clippy::arithmetic_side_effects; host imports are fuzzed with arbitrary guest input; a catch_unwind around the engine call is defense in depth, mapping a caught panic to one class-1 variant on every node; any occurrence is a consensus vulnerability.
7. The v0 ABI is designed for the end state. The context struct, capability imports, and fee tables anticipate reads and entry points from the first release, because retrofitting state access onto a predicate-only ABI changes fee model, mempool policy, and ABI in one consensus-breaking step.
8. The guest observes the block and the transition, nothing node-local: block height, time and epoch from BlockInfo; protocol and fee versions; caller identity id; the transition payload; declared reads served from the state the phase names (section 09: committed block N-1 for Phase 4, the block transaction for Phase 5), fixed by protocol version. Excluded: wall clock, node configuration, mempool, the node's ProTxHash, the proposer's fee-version cache. Test rule: the context is built from BlockInfo and the transition alone, with no Platform config reachable from the host import layer. use_document_triggers (abci/config.rs:92-93) is the precedent not to repeat: a hook runs on every validator or none.
9. Precedents are read symmetrically. Of three bespoke-host-on-wasmi embedders, Soroban runs on Stellar mainnet (on a stellar/wasmi fork), Radix is in managed decline (report 09), and Polkadot retired pallet-contracts plus ink! in favour of pallet-revive (Solidity on REVM, live on Polkadot Hub 2026-01-27; PolkaVM early-stage), ink! halting maintenance in January 2026 when treasury funding failed (report 07, external-engines facts). The distinguishers: this plan does not compete for the EVM developer funnel, so the pallet-contracts outcome is not its failure mode; its buyers are existing Platform applications needing enforced rules over document-shaped, proven state, which no imported VM offers; each stage is a voted protocol version useful on its own (goal 5); goal 6's SDK gate is the ink! lesson applied to Dash. No adoption figure is claimed for either path: EVM ports are rejected on structural cost, Soroban is an existence proof.

1.6 How to read this document

Sections 2 to 4 are the baseline (what exists in tree, options rejected or deferred, target architecture); 5 to 10 the six phases, each with Reasoning, Design, Tasks, Tests, Acceptance criteria and Risks; 11 and 12 determinism, security, engine governance and fees; 13 the developer surface; 14 sequencing, rollout, success criteria and open questions. Every - [ ] line is one reviewable unit of work (one PR or one recorded decision) naming the crate or module it touches and the protocol version gating it; nested checkboxes ship with their parent. Phase order is a dependency order; protocol-version assignments are targets, not commitments.

Phase (section)	PV	Goals served	A third party can	Cannot
0 decisions, DIP (05)	none	7 (on paper)	nothing new
1 VM prerequisites (06: 6.1, 6.2, 6.3, the 6.5 queue)	15	4 (block budget)	upload code blobs, permissionless at PV15 (the deployer allowlist starts with guard-bearing contracts at PV16, 11.2.6)	attach logic
1b primitives and feeds (06: 6.4, 6.5)	its own PV, PV15 at the earliest	8 (primitives)	use escrow, allowance and auction primitives and oracle feeds	attach logic; nothing the VM phases need waits for it
2 guards (07)	16	1 (partial), 2, 3	enforce cross-field invariants and authorization with up to ten declared document reads, statically costed	loop, hold state machines, write
3 predicates (08)	17	1 (partial), 3, 4, 6, 7	reject transitions by arbitrary computation over the transition context	read other documents or balances (no cross-document uniqueness, quotas or balance checks)
4 footprint reads (09)	18	1 (wider), 2 (footprint proofs)	read declared documents, indexes and balances of its own contract	write
5 entry points (10)	19	1 (own-contract logic), 8 (principal)	move its own and its principal's documents, tokens and credits through proposed operations	call another contract, write another contract's state

Calendar: v9 to v14 opened on 2025-01-16, 2025-06-29, 2025-12-09, 2026-01-24, 2026-07-17 and 2026-08-03 (git log on pv/), one every 113 days on average; each activates on mainnet only after release, signalling past protocol_version_upgrade_percentage_needed (check_for_desired_protocol_upgrade/v1/mod.rs:16-31) and one to two 9.125-day epochs (section 14.4); v14, five weeks old, is unreleased. At that cadence PV19 opens about fifteen months after PV15, which is not open today, so Phase 5 cannot activate on mainnet before 2028 unless the cadence accelerates, against README.md:49-50's 2027 mainnet target for v4.0 and dash.org's v5.0, Q1 2027. Phase 0's docs PR corrects README and book (section 05); the dash.org milestone goes to its owner with this table.

---

---

This document exceeds GitHub's issue body limit. It continues in the comments below: parts 2 to 14 of 14, in order. Please keep discussion in threads that quote the section you are addressing.

[QuantumExplorer]

Part 2 of 14 of the plan (continued from the issue body above).

2. Current state of Platform: what exists, what is missing

Baseline: v4.2-dev at a3c36f3 (2026-09-07), PV14 in tree, unreleased. Prefixes: abci/ = packages/rs-drive-abci/src, drive/ = packages/rs-drive/src, pv/ = packages/rs-platform-version/src/version, batch/ = abci/execution/validation/state_transition/state_transitions/batch, stp/ = abci/execution/platform_events/state_transition_processing; grovedb paths at pin 6fc7e1e8; versioned method directories unique in the tree are cited by leaf directory.

2.1 What exists

2.1.1 Data triggers: system hooks, validation-only

A fn-pointer table (type DataTrigger, batch/data_triggers/mod.rs:26-30) whose bindings carry the key fields data_contract_id, document_type and transition_action_type (batch/data_triggers/bindings/data_trigger_binding/v0/mod.rs:17-26, compared by is_matching, :67-72), run in validate_state_v0 (batch/state/v0/mod.rs:279-346); rejection is StateError::DataTriggerError plus a paid bump-nonce action (:327-354). Not a user-code seam: code is compiled in; billing is voluntary (add_operation, batch/data_triggers/triggers/dpns/v1/mod.rs:272-279; v0 triggers never bill); an Err return is an InternalError (2.2.4); node config use_document_triggers (abci/config.rs:93) switches a consensus path. Triggers never run in the mempool: validates_full_state_on_check_tx defaults to false (abci/execution/validation/state_transition/processor/traits/state.rs:53-55; only MasternodeVote overrides it, masternode_vote/mod.rs:90-92), so check_tx_verification/v0/mod.rs:320-333 skips validate_state for Batch; should_validate_batch_valid_against_state (batch/mod.rs:45-55) only relaxes the transform (batch/state/v0/mod.rs:374). Existing triggers already diverge between mempool and block: dpns v1 passes is_dry_run into query_documents and skips post-query validation under dry run (dpns/v1/mod.rs:265-282; sanctioned at batch/state/v0/mod.rs:298-312), tolerable for compiled code, the 2.1.7 under-estimate vector for a VM. A second hazard is recorded, not live: drive/cache/data_contract.rs:25-41 documents the class, a read-only query thread populating the global cache from committed state during block execution, which would leave a warm node serializing documents against a different contract than a cold one, a different app hash from the same block; the shipped insert blocks it with an atomic version-guarded check-and-insert returning Op::Nop for the lower version, so no window exists between comparison and write (:51-58). A module cache inherits the class (2.2.7 item 5).

2.1.2 Fee-safe seam and the two execution positions

DriveHighLevelOperationConverter turns every StateTransitionAction into Vec<DriveOperation> (drive/state_transition_action/action_convert_to_operations/mod.rs:20-130). execute_event dry-runs with apply = false, requires balance >= estimate + fixed cost (stp/validate_fees_of_event/v0/mod.rs:102-164; refunds ignored, TODO :138), then applies and charges (stp/execute_event/v0/mod.rs:35-104). Code on a Batch has two possible positions. Position A, the transform (transform_into_action_v0, batch/state/v0/mod.rs:359-380), runs in CheckTx, RecheckTx (check_tx_verification/v0/mod.rs:465-472) and the block; CheckTx dry-runs its action through the converter (abci/execution/check_tx/v0/mod.rs:177-190) and reports the estimate as gas_wanted (abci/abci/handler/check_tx.rs:66-70). The block runs the transform once and applies its converter output twice, a dry-run estimate (validate_fees_of_event/v0/mod.rs:118-128) then apply (execute_event/v0/mod.rs:55-63): guest code there would run once per block, priced by a dry run it cannot see, and again, uncharged, on every gossiping node's CheckTx and RecheckTx. Position B, validate_state, is block-only; whatever it contributes (a PrecalculatedOperation, a reshaped action) is invisible to CheckTx's balance check and gas_wanted. Neither is usable as-is. Required order, carried into sections 8, 9, 10 and 12:

1. Every hook-bearing transition has a bound on its whole cost, covering compute, host reads and write bytes, computed before the guest runs from the wire bytes and committed state. What is declared differs per phase and belongs to the owning section: at PV17 nothing new rides the wire, the per-document-type maxFuel keyword supplies the fuel term under max_hook_fuel_per_call and the host computes B (8.2.6); PV18 adds read_footprint, whose credit bound the host computes (9.2.4); PV19's ContractCall declares max_fuel and max_fee (10.2.4). Host cost is grovedb OperationCost (seek_count, storage_loaded_bytes, hash_node_calls; grovedb costs/src/lib.rs:104-116), the input to Drive's processing fee (drive/fees/op.rs:1602-1634); the host computes it, no transition declares it. Below, "the bound" is B at PV17 and PV18 and max_fee at PV19; the formulas live in their owning subsections and are not restated here.
2. The balance check against the bound runs in CheckTx and again in the block immediately before guest code executes; the block budget of 2.2.2 is charged only for transitions that pass it.
3. The block executes guest code exactly once, in a block-only step, never under a dry run. Each host function charges its OperationCost against the host-cost term before returning data and traps on exhaustion; a SystemLimits bound on key depth under the contract subtree caps each write's seek and hash cost so the write-byte term covers it.
4. Execution charges actuals, once, after the run: fuel used at credits_per_fuel plus the host and byte costs actually incurred, folded into the fee result and provably at most the bound, with no debit before execution and no credit-back (8.2.6, 10.2.4, section 12). Out-of-fuel is the single outcome that pays the whole bound (8.2.7). The block budget of 2.2.2 consumes the declared bound, not the credits paid (4.5, 8.2.6, 11.2.3), so k transitions declaring the cap and returning after a few operators consume k bounds of block budget while paying k small fees: early return buys throughput from nobody. Consumed fuel is reported (gas_used, receipt) and is never the affordability input.
5. gas_wanted reports the bound (abci/abci/handler/check_tx.rs:66-70).
6. CheckTx and RecheckTx never execute guest code: CheckTx applies and bills nothing, and RecheckTx re-runs every mempool transition after every block, so M cap-declaring transitions would cost every gossiping node M caps per block, uncharged, the dpns v1 free-lookup DoS (dpns/v1/mod.rs:261-264) at VM scale. Unique identifiers embed the nonce (packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/state_transition_like.rs:45-60) and CheckTx prices each transition against the last committed balance (check_tx/v0/mod.rs:179-186), so one balance admits N sequential-nonce transitions of which only the first is payable. The answer is a block-time gate, not a mempool ledger beside CheckTxResult (check_tx/mod.rs:54-70): the seam requires balance - accrued >= bound + nonce-bump cost immediately before the guest runs (8.2.6), and 11.2.3 keeps that placement and declines a mempool-level decrement, so CheckTx stays a cheap prefilter. Residual, bounded and accepted: the N-1 unpayable transitions consume admission, gossip and RecheckTx work on every node, all of it shape checks bounded by max_state_transition_size, never guest execution (11.2.3); eviction is per phase, the PV19 ContractCall recheck arm adding balance >= max_fee (10.2.4) where batch recheck reads no identity balance today (check_tx_verification/v0/mod.rs:397-436).
7. No dry_run flag reaches guest code.
8. Guest code writes nothing directly: it returns a bounded list of proposed operations, converted and applied only on Ok; on any other outcome the list is discarded and only bump-nonce plus fee operations apply. The existing dry run prices the emitted list without re-running the guest, and partial writes cannot exist: a paid Trap after three writes would otherwise stay in the block as TxAction::Unmodified with the writes applied on every node (abci/abci/handler/prepare_proposal.rs:207-236; rollback covers only InternalError and Unpaid on the proposer path, 2.1.9).

A post-hoc ValidationOperation cannot feed a pre-execution balance check by construction. Without (2), a hook costing 100x the sender's balance passes CheckTx, runs to completion in the block, fails the fee check, is rolled back and stripped (TxAction::Removed, prepare_proposal.rs:207-236) and resubmitted: proposer CPU at zero cost every round, up to the fuel cap.

2.1.3 Dormant BaseOp gas table; where fuel prices live

BaseOp is an EVM-style opcode enum with fixed costs (Add 12, Mul 20; drive/fees/op.rs:34-110) folded into processing_fee by calculate_fee_v0; all 125 callers pass None. The channel is reusable; the enum is not: the section 11 engine meters per input Wasm operator from a configurable table, and BaseOp was never calibrated against Drive's "~8M credits/ms" CPU anchor (pv/drive_abci_versions/drive_abci_validation_versions/v10.rs:338-343). The charged compute amount is metered fuel and host cost priced at execution and folded into the fee result as a ValidationOperation (execution_operation/mod.rs:74-87), capped by the bound of 2.1.2 rule (1). Fuel and write prices are processing-only, so they belong in a PV-versioned table read at execution time, not in the epoch-keyed table that refunds replay (previous_fee_versions, packages/rs-dpp/src/fee/default_costs/mod.rs:15-16). Registry hazard: FeeVersion::get(n) indexes FEE_VERSIONS[n-1], which holds only FEE_VERSION1 (pv/fee/mod.rs:32), while FEE_VERSION2 carries fee_version_number: 1 (pv/fee/v2.rs:12-13); the refund branch keys on that number and takes CorruptedCodeExecution for any other number when previous_fee_versions is None (drive/fees/op.rs:280-292), which halts a node inside a block event, and persisted per-epoch numbers are rehydrated with expect (abci/platform_types/platform_state/platform_state_for_saving/v1/mod.rs:139-149; as_static, pv/fee/mod.rs:50-52), so a binary lacking a persisted number panics at state load. Any new number must be appended to FEE_VERSIONS with fee_version_number equal to its 1-based index, and the rehydration expect replaced by an error before that number is ever persisted. Section 12 fixes the numbering for every table this plan adds; every other section cites it.

2.1.4 Token distribution functions: precedent with a caveat

DistributionFunction has nine families (distribution_function/mod.rs:49-569), evaluated in checked integer math with a SplitMix64 PRF (evaluate.rs:18-42) under MAX_DISTRIBUTION_PARAM = 2^48 - 1, bounded by max_token_redemption_cycles = 128 (drive/state_transition_action/batch/batched_transition/token_transition/token_claim_transition_action/v0/transformer.rs:428-434). Author formulas run in consensus, but registration validates at the start moment only (distribution_function/validation.rs:269 and siblings), while claim-time rewards_in_interval returns ProtocolError::Overflow (evaluate_interval.rs:1606, :1622, :1665, :1681) that the transformer propagates with ? (transformer.rs:444-483): an Err, so InternalError (2.2.4), not a consensus error. That is a zero-cost re-submission vector today, independent of smart contracts: the claim is TxAction::Removed with a proposer rollback and no fee (stp/process_raw_state_transitions/v0/mod.rs:225-264; prepare_proposal.rs:207-236), costs every proposer the transformer work each block it is resubmitted, and rejects the block wherever a validator classifies it differently. Enumerating the 128 cycles from the start moment at registration proves nothing about later claim windows (the evaluation moment is unbounded), so this document adopts a paid consensus error for evaluation failure in a new versioned transformer, in the same PV as any user-code seam; section 7 reuses the pattern only with that in place.

2.1.5 Provable raw KV and the wasm binding gap

prove_elements_v0 proves any path plus key set (drive/prove/prove_elements/v0/mod.rs:19-42); the handler intentionally allows every path under size caps (abci/query/system/path_elements/v0/mod.rs:17-97). wasm-sdk binds it as getPathElements (packages/wasm-sdk/src/queries/system.rs:1585-1620), proof-verified through rs-sdk's Element::fetch_many (packages/rs-sdk/src/platform/fetch_many.rs:553) and Drive::verify_elements (packages/rs-drive-proof-verifier/src/proof.rs:1824); only wasm-drive-verify's verifyElements is stubbed (packages/wasm-drive-verify/src/system/verify_elements.rs:47-58). Point reads only, and grovedb refuses to prove inside a transaction (grovedb/src/operations/get/query.rs:200-206), so proofs cover committed state. [64, cid] holds exactly [0], the contract element written by add_contract_to_storage (called at drive/drive/contract/insert/insert_contract/v0/mod.rs:173-182, the insert itself at add_contract_to_storage/v0/mod.rs:145), and [1], the documents subtree (insert_contract/v0/mod.rs:184-193). Still true at PV14, which dispatches insert_contract to v1 (insert_contract: 1, pv/drive_versions/drive_contract_method_versions/v3.rs:31): insert_contract_operations_v1 delegates the contract subtree to the v0 body and adds only token trees under other roots. [2] stays reserved and unused: nothing this plan proposes creates it. The code store is a new root tree, RootTree::CodeBlobs (proposed discriminant 68, 6.2), since blobs are hash-addressed and reference-counted across contracts, and creating [2] at insert would change the root hash of every new contract for nothing (2.2.6).

2.1.6 Protocol-version activation template

PLATFORM_V14 bumps eleven sub-tables with // changed: notes (pv/v14.rs:197-230). Subsystems gate through pv/feature_initial_protocol_versions.rs (11, 12), checked first by validate_is_allowed and rejected unpaid (processor/traits/is_allowed.rs:52-101). Lock-in needs 67% of HPMNs at an epoch change, activation the next epoch (9 to 18 days at 788400 s). Hazard: editing a shared sub-table activated shielded reads one PV early (PR #3177; pv/protocol_version.rs:187-232).

2.1.7 Failure charging and negative-balance debt

An invalid transition with an execution event runs a paid bump-nonce event and reports PaidConsensusError { error, actual_fees, address_balance_changes }; without one it is UnpaidConsensusError (stp/process_validation_result/v0/mod.rs:41-133). When actual cost exceeds the estimate the rule is two-tier. into_balance_change makes the storage fee required_removed_balance and storage plus processing desired_removed_balance (packages/rs-dpp/src/fee/fee_result/mod.rs:217-252). A processing shortfall becomes debt in the identity's negative-credit slot (IdentityTreeNegativeCredit = 96 under the identity subtree, drive/drive/identity/mod.rs:347, outside sum trees), repaid from the next credit; the pool receives only what was paid. A storage shortfall returns Err(IdentityInsufficientBalance) (drive/drive/identity/update/methods/apply_balance_change_from_fee_to_identity/v0/mod.rs:91-97) after apply_drive_operations(apply = true) has already written (stp/execute_event/v0/mod.rs:55-63): InternalError with writes applied, the case test_fault_injection models (stp/process_raw_state_transitions/v0/mod.rs:25-58) and the class behind the August 2026 mainnet stalls (:108-125).

Both tiers are guest-reachable unless the bound covers every component. Processing: the fee derives at apply time from OperationCost, which depends on tree depth and sibling sizes the guest never declares, and a host read of a maximum-size element loads bytes fuel does not bound; a throwaway identity funded to exactly the bound, whose hook reads many large elements and writes at maximum depth, leaves the excess as debt on an identity that never receives credits again: unpriced validator work with no collection path, hence the host-cost term and key-depth bound of 2.1.2 rules (1) and (3). Storage: under rule (8) the guest emits its writes before the dry run prices them, so only estimator-versus-apply drift on the emitted operations remains, the class compiled code faces today. Hard requirement for sections 8, 9, 10 and 12: the charged fee is provably at most the bound, the balance check runs against that bound before any apply-time write, and section 10's acceptance list carries test_fault_injection as a required regression. The storage tier must be unreachable everywhere, since its shortfall is the Err; the processing tier only where a phase earns it. At PV19 the degraded-fee floor makes it unreachable for ContractCall (10.2.4 step 4); a hook-bearing batch keeps the same non-fuel under-estimate class documents have today (section 12), so the test that no guest-driven transition yields negative_credit_balance_modified is a PV19 ContractCall test, not a network-wide claim.

Second hazard: the debt slot is overwritten with desired - previous_balance, ignoring any existing value (:102-107), which is debt forgiveness. Unreachable today only because debt arises at balance 0 and add_to_previous_balance_v0 repays it on the previous_balance == 0 branch (drive/drive/identity/update/methods/add_to_previous_balance/v0/mod.rs:28-63); the else branch adds without reading the slot (:67-81). An inflow landing while balance > 0 and debt > 0 (a contract paying an identity mid-block) is never repaid on either branch, and a later under-estimate replaces a large debt with a small one, conserved but uncollected; routing every inflow through add_to_previous_balance is necessary, not sufficient. Section 10 invariant, on state: balance > 0 implies debt == 0, checked after every paid execution in debug builds and by a strategy test, and kept by a new add_to_previous_balance version on the same PV that repays debt on both branches, so it holds however the debt arose.

2.1.8 Sum-tree credit conservation

At block end Misc["D"] must equal the sum of five roots, Balances (96, identity balances), PreFundedSpecializedBalances (40, vote-poll funding), Pools (48), AddressBalances (56) and ShieldedBalances (52) (drive/drive/balances/calculate_total_credits_balance/v2/mod.rs:40-80; keys drive/drive/mod.rs:201-222), or block end returns CorruptedCreditsNotBalanced (abci/execution/platform_events/block_processing_end_events/process_block_fees_and_validate_sum_trees/v0/mod.rs:174-192) and the node halts. Gated by node config verify_sum_trees (abci/config.rs:97): a credit-holding root outside the list fails the equation on every checking node at the first block that funds it while unchecked nodes continue; not an app-hash divergence, a partition by configuration on a valid chain. Contract-held credits therefore live under an existing root or a new root registered in a new calculator version in the same PV; a sum tree under [64] propagates nowhere. The roots differ: 40 drains by vote-poll rules and is invisible to apply_balance_change_from_fee_to_identity and its refund path other_refunds() (:138), so a hook write flagged to a contract balance there never receives its refund. Decision: a principal (the keyless identity subtype of 4.4) holds its balance under 96, and the same PV gates the identity paths a principal must reject: IdentityCreditWithdrawal, IdentityCreditTransfer out and IdentityUpdate (packages/rs-dpp/src/state_transition/mod.rs:168-170). D moves only through SystemOperationType::{AddToSystemCredits, RemoveFromSystemCredits} (drive/util/batch/drive_op_batch/system.rs:18-28), emitted by the asset-lock funding and withdrawal converters and summed per block as block_credit_mints (stp/execute_event/v0/mod.rs:51-65, whose filter DriveOperation::credit_mints counts only AddToSystemCredits, drive/util/batch/drive_op_batch/mod.rs:252-262), which the daily withdrawal limit reads. An identity-to-principal transfer nets to zero against D; only mint and burn host functions touch the system operations and the mint counter, each enumerated against the equation.

2.1.9 Savepoints and rollback

RocksDB savepoints exist (grovedb storage/src/rocksdb_storage/storage.rs:337-347); rollback_to_savepoint unwinds to and pops the most recent one. Drive sets one per transition on the proposer path and rolls back InternalError and Unpaid results (stp/process_raw_state_transitions/v0/mod.rs:108-137, :225-264; the result match is exhaustive); kept ones stay on the stack. Validators never roll back; process_proposal rejects. Rule (8) of 2.1.2 needs no revert for guest failures; any future sub-call revert (cross-contract calls) faces three items. (1) A savepoint set inside the per-transition one and left unbalanced on any exit path makes the transition-level rollback land on the wrong marker, so the proposal is built over leaked writes, the failure the savepoint exists to prevent; discipline is strict nesting with every sub-savepoint consumed on every exit path, enforced by an RAII guard. (2) Rollback runs only when proposing_state_transitions is true (:136-137); a nested revert on the validator path changes what state a received block evaluates to, a PV-gated consensus change (comment :117-125). (3) grovedb caches in-transaction Merk handles (grovedb/src/merk_cache.rs, declared at lib.rs:150; the HashMap<SubtreePath, Merk<PrefixedRocksDbTransactionContext>> threaded through lib.rs:691-878), and nothing in the savepoint API or in any test at the pin establishes whether those handles, or root hashes derived from them, observe a rollback; the proposer-side rollback shipped with test_fault_injection only. Open item, unowned. No speculative read overlay across sub-calls exists.

2.2 Hard gaps

2.2.1 20 KiB transition cap versus module sizes

max_state_transition_size = 20480, enforced before decode (decode_raw_state_transitions/v0/mod.rs:54-66), equals Tenderdash max-tx-bytes (packages/dashmate/templates/platform/drive/tenderdash/config.toml.dot:389). Stored contracts cap at 65000 (insert_contract/v1/mod.rs:58-65); 16384 is an estimation input, not a cap. DataContractCreate carries the whole contract, so code cannot ride inside it: a chunked upload transition, or a raised cap plus a dashmate change (section 6).

2.2.2 No per-block compute budget

Bounds today: max_tx_bytes (abci/abci/handler/prepare_proposal.rs:97-114); a proposer-only proposer_tx_processing_time_limit: Option<u16> ms (abci/abci/config.rs:39; 5000 on mainnet, packages/dashmate/configs/defaults/getMainnetConfigFactory.js:83); Tenderdash block.max_gas = 57631392000 against summed gas_wanted, a genesis consensus parameter (packages/dashmate/configs/defaults/getBaseConfigFactory.js:430-437) applied at reap time and never read by rs-drive-abci. process_proposal passes no timer: validators re-execute unbounded. Block events are unmetered (check_for_ended_vote_polls/v0/mod.rs:83; consequence in 2.2.4). The wall-clock limit is node-local and already a liveness hazard: once it fires, every remaining transition is NotExecuted(ProposerRanOutOfTime) regardless of its own cost (stp/process_raw_state_transitions/v0/mod.rs:147-158). With paid, valid user code, k near-maximum transitions at the head of the mempool starve everything behind them on the proposer, cost slower validators an unbounded re-execution that can fail the round, and recur under the next proposer, with no budget for process_proposal to reject on deterministically. Required: a budget (a) as a PV-versioned SystemLimits constant, max_block_processing_credits, denominated in credits and never in wall clock, with fuel converted into the same number at a fee-table constant so one accumulator covers database and compute work; 6.1 argues the denomination (credits as a time proxy, backed by the per-transition and per-type backstops) and section 12 states what a reprice does to real throughput, since the budget's capacity in work moves with the fee table; (b) enforced by the proposer in prepare_proposal on the sum of declared bounds of transitions that pass the balance check of 2.1.2 rule (2), the remainder delayed; (c) re-checked in process_proposal as a reject condition on the same sum; (d) derived from measured worst-case nanoseconds per credit on the minimum supported validator hardware times a stated fraction of the block interval, recorded in section 12, with a CI benchmark failing on drift: fuel is deterministic, wall time per unit is not, and a constant tuned on a fast proposer lets the slowest validators miss the propose timeout while the next proposer reaps the same transitions. proposer_tx_processing_time_limit stays a proposer heuristic below the budget, never the sole bound. prepare_proposal already returns ConsensusParams updates (prepare_proposal.rs:274; abci/execution/engine/consensus_params_update/v1/mod.rs sends block: None today), so a PV that changes the budget or price table emits a block update at activation keeping max_gas at or above the budget.

2.2.3 No events, receipts, or oracles

ExecTxResult carries only code, info (CBOR consensus error) and gas_used (abci/abci/app/execution_result.rs:10-50); clients learn outcomes by proving affected state. Nothing in rs-drive-abci, rs-dpp or rs-drive mentions an oracle; external data enters only via Core and block time.

2.2.4 Error classification as a liveness vector

Any Err in the per-transition path becomes InternalError (stp/process_raw_state_transitions/v0/mod.rs:343-361), and process_proposal rejects any block holding an InternalError or Unpaid result (abci/abci/handler/process_proposal.rs:285-308). A VM failure classified as a consensus error on one node and as Err on another does not corrupt state; it makes validators reject a block the proposer built: a liveness failure with a perfect interpreter. Two traps in the code the design would copy. validate_is_allowed ends in _ => Err(CorruptedCodeExecution) (processor/traits/is_allowed.rs:97-99): a variant added to has_is_allowed_validation as Ok(true) (:26-48, exhaustive) but not to that match compiles and yields InternalError for every instance, rejecting every block that contains one; the code-blob and contract-call transitions walk straight into it, and the existing tests iterate hand-listed vectors only (helpers at :259-293 and :295-318, consumed at :320-344 by has_is_allowed_validation tests that never drive validate_is_allowed). Trigger execution propagates any Err with ? (batch/state/v0/mod.rs:318-322). By-construction rule: user-code outcomes are a closed enum, accept plus the ValidationModuleError kinds 8.2.7 owns (Rejected { code }, Trapped { kind }, OutOfFuel { budget }, InvalidResult, PrepareFailed { rule }, ModuleUnavailable { reason }), mapped exhaustively to ConsensusError variants at the host boundary; Err(Error), carrying HostFault, is reserved for host invariant violations and unreachable from guest input; resource exhaustion inside the per-instance limits of 2.2.7 item (3) is a host invariant violation that halts the node, never a guest outcome. has_is_allowed_validation and validate_is_allowed are extended in the same change as any new variant, with the wildcard arm replaced or a test that drives validate_is_allowed for every StateTransition variant. Every engine error path is tested against test_fault_injection (:25-58). Block events: an Err in block-end processing halts the node (the CorruptedCreditsNotBalanced path, 2.1.8), with no proposer rollback and no process_proposal reject to absorb it. Rule, carried by whichever section designs a block-event execution path (6.5 and 10.2.6): guest code never runs there unless (a) its outcome is the same closed enum, (b) its fuel and host cost were prepaid at enqueue time from a balance the sum-tree equation covers, and (c) every non-Ok outcome is recorded as data (a failed-callback element), never propagated as Err. Each such workload's cap is a share of max_block_processing_credits, and 6.1 carries the sum constraint over all of them.

2.2.5 No expedited protocol-version path

No shorter vote exists. Precedents: an epoch-index flag day inside a versioned method (TARGET_EPOCH_INDEX = 4, batch/is_allowed/v0/mod.rs:11-35; PR #2138, 2024-09-18); an in-place edit of an already-defined PV table (PLATFORM_V7 validation V4 to V5, pv/v7.rs; PR #2397, 2024-12-19), the hazard class of PR #3177 in 2.1.6; a one-off 51% threshold; and non-consensus hotfixes (4.1.1). is_allowed expresses only "active at PV N"; no PV-free freeze exists (2.2.7 item 4).

2.2.6 Storage flags, refunds and code blobs

[2] staying unused settles nothing about who pays for and who reclaims code bytes. Refunds are attributed to the identity and epoch in element storage flags (StorageFlags::SingleEpochOwned(epoch, owner), grovedb-epoch-based-storage-flags/src/lib.rs:42-54; contracts insert with new_single_epoch(epoch, Some(owner_id)) when deletable or mutable, else None, meaning permanent, drive/drive/contract/insert/insert_contract/v0/mod.rs:42-48) and paid out through other_refunds() (apply_balance_change_from_fee_to_identity/v0/mod.rs:138). Unanswered, each an unpriced-growth or refund-farming path: (1) flag ownership of a hook's raw write: the caller's (a later deleter refunds a stranger; a contract farms refunds to a chosen identity), the principal's (a keyless identity under 96, 2.1.8), or none (permanent, never refundable); (2) abandoned partial code blobs: paid chunks never assembled stay forever without expiry plus refund, and chunk upload fills max_tx_bytes cheaply; (3) hash-addressed code blobs shared across contracts: reference counting, deletion while referenced, refund recipient; (4) creating the proposed RootTree::CodeBlobs on an already-running chain: it must be written both at genesis and in the activating first-block arm, or a node syncing from genesis and a node upgrading in place reach different root hashes. Section 6 answers all four.

2.2.7 Replay and engine drift

No Wasm engine is in the tree today (Cargo.lock). The discipline replay already demands is visible: _v0 trigger bodies stay byte-identical and non-billing so PV11 blocks replay (batch/data_triggers/mod.rs:20-26; batch/state/v0/mod.rs:289-297). For an engine the equivalent is stronger and unstated. (1) The executing PV's engine and fuel table apply to every module whatever PV deployed it (a deploying-PV rule leaves security patches unreachable and replay ambiguous); acceptance is monotone, every module accepted at PV N accepted at PV N+1, enforced by a CI job re-validating every deployed module from mainnet and testnet snapshots against the candidate engine; a load or instantiate failure is the ModuleUnavailable member of the closed enum (2.2.4), never Err; receipts and errors record the executing PV so replay is self-describing; every engine version ever activated stays linkable (a package depends on two versions of one crate only through a renamed dependency entry). That obligation is permanent as the tree stands: no ABCI state-sync handler exists anywhere in packages/ (no offer_snapshot, list_snapshots, load_snapshot_chunk or apply_snapshot_chunk), so a new node bootstraps by replaying history and executes every contract call ever made. Section 14 must carry the retirement rule, the cap on retained engines and the replay-cost measurement, since nothing bounds them today. (2) Fuel tables frozen per PV and never edited in place (the PR #3177 hazard, 2.1.6); fuel per operator shown stable across engine patch releases as a CI gate, or replay from genesis diverges. (3) Fuel counted by the engine on its own instruction stream is deterministic across hosts; the per-host hazard is resource exhaustion: a module at the maximum memory that instantiates on most validators and fails allocation on the rest is Err, so InternalError, on those nodes only, and a rejecting minority above one third fails the round. Per-instance limits (memory pages, stack height, table size, call depth across the host boundary, module size, instances per transition) live in a PV-versioned SystemLimits entry; modules outside them are rejected at registration as a consensus error; inside them the node pre-reserves the maximum at start, so an allocation failure within limits halts that node as a host invariant violation instead of rejecting a block; the validator hardware specification gains a minimum-memory line. (4) The window between an engine CVE disclosure and activation (9 to 18 days, 2.2.5) needs a freeze held in state, not a masternode vote (which takes the PV timeline) and not a config kill switch (which is a fork): the ContractGovernance system contract with frozenGuard, frozenModule, frozenContract and globalFreeze, written by a transition authorized by a threshold signature from a quorum or a registered, rotatable multi-key set. What this section fixes is classification, not placement: the freeze must classify deterministically for transitions already in the mempool at the freeze height, and the template for that is the unpaid gate in the validate_is_allowed position (processor/traits/is_allowed.rs:52-101); 11.2.6 owns the document types, the creation PV, the read model and the key set. A frozen module rejects its guarded transition rather than bypassing it, since bypass silently drops the author's invariants. (5) Any module cache is content-addressed by (code hash, engine version, PV), pure memoization of a deterministic compile, never keyed by contract id and never populated by a query thread during block execution (the drive/cache/data_contract.rs:25-58 class, 2.1.1); test: cold-cache versus warm-cache app hash equality across a code update.

2.3 Stale public statements

Four in-tree claims contradict the tree or the published roadmap. README.md:49-50 and book/src/platform-comparison.md:48-49 promise smart contracts in "Platform v4.0 (targeted for mainnet in 2027)", with table cells at README.md:63 and platform-comparison.md:38-39 reading "Coming in v4.0" and "No VM (data contracts; VM planned for v4.0)", while dash.org/roadmap places on-chain computation at v5.0, Q1 2027, tentative. book/src/state-transitions/lifecycle.md:250-261 says the enum has 15 variants; it has 21 (packages/rs-dpp/src/state_transition/state_transition_types.rs:23-43, last value 20). book/src/versioning/platform-version.md:62-74 says twelve protocol versions and book/src/introduction.md:204 says protocol version 12, against 14 in tree. book/src/sdk-support.md:12-13 lists the Swift and Kotlin SDKs as "Coming in v3.1" and "Coming in v3.2"; both ship with CI. One documentation pull request on v4.2-dev fixes all four: section 13 owns the replacement wording and the grep acceptance criteria, section 5 schedules it.

2.4 Capability table

Capability	Exists	Location	Gap
Hooks on transitions	Compiled-in, PV-versioned, block-only	batch/data_triggers/	User code, forced metering, no config gate, no dry_run to guest, content-addressed module cache
Fee-safe write path	Yes; dry-run then apply	action_convert_to_operations/	Pre-execution bound checked before the guest runs; proposed-operation list applied only on Ok
Compute-to-credits	ValidationOperation; BaseOp dormant	execution_operation/mod.rs	Fuel, host-cost and write-byte pricing; actuals charged once, capped by the bound; PV-keyed price table
Author formulas	9 families, integer math	distribution_function/	Claim-time overflow is InternalError: paid consensus error in a new transformer; tokens only
Provable raw KV	Point reads, proof-verified	prove_elements/v0	Range proofs; wasm-drive-verify stub
Activation gate	Yes	is_allowed.rs	Wildcard arm; no expedited path; in-state freeze on ContractGovernance
Failure charging, debt	Yes; storage shortfall is Err	process_validation_result/v0	Unpaid CPU DoS vector; debt overwrite is forgiveness; invariant balance > 0 implies debt == 0
Credit conservation	End of block, five fixed roots	process_block_fees_and_validate_sum_trees/v0	No per-transition check; node halt gated by config; principals under 96 with gated identity paths
Mempool affordability	Per-transition balance check only	check_tx/mod.rs:54-70	Block-time gate balance - accrued >= bound, no mempool ledger; ContractCall recheck balance arm
Per-block compute budget	No	prepare_proposal.rs:97-114	PV-versioned max_block_processing_credits on declared bounds at reap and in process_proposal; budget at or below max_gas
Events, receipts, oracles	No	execution_result.rs	Receipt design (executing PV recorded); signed feed
Fee table registry	FEE_VERSION2 reuses number 1	pv/fee/mod.rs:32; fee/v2.rs:12-13	Refund branch keys on the number; rehydration expect panics on unknown numbers; PV-keyed fuel table (section 12)
Storage flags, refunds	Owner plus epoch flags; refund to flag owner	drive/drive/contract/insert/insert_contract/v0:42-48	Ownership rule for hook writes; chunk expiry; code-blob refcount
Replay, engine drift	_v0 trigger freeze only	data_triggers/mod.rs:20-26	Executing-PV engine, monotone acceptance; frozen tables; per-instance host limits; in-state freeze; no state sync, so engines stay linked

---

---

Continued in part 3 of 14 below.

[QuantumExplorer]

Part 3 of 14 of the plan (continued from part 2 above).

3. Options considered and why they were rejected or deferred

Each option was judged against section 02's four properties: an app-hash divergence halts the chain and a stray Err in the transition loop becomes an InternalError validators reject (stp/process_raw_state_transitions/v0/mod.rs:212-218, section 02.2.4); credits split into processing and storage fees with epoch refunds through StorageFlags; every client read is a GroveDB proof; every consensus change rides a masternode-voted protocol version. "Does not fit" means "fights one of those structurally". The standard is fit and surface area (section 01, principle 9); commercial outcomes enter only as evidence of who maintains an engine or SDK and for how long, or of how long a bug took to fix (Confio, ComposableFi, Radix, ink!, XRPL, Juno), and 3.3 applies that evidence to the chosen path. Prefixes (abci/, drive/, pv/, batch/, stp/) and the grovedb pin (6fc7e1e8) follow section 02; external facts are as of 2026-09-07 (facts/external-engines-2026.md, cited as facts:line), a 2026-09-08 fetch mark means checked against crates.io or the named upstream file that day, and a "report NN" mark means the claim rests on the research reports and was not re-verified against primary sources.

3.1 A: native declarative primitives only

Ship escrow, subscriptions and auctions as parameterized features, as tokens and trade mode shipped; Platform already runs author-supplied formulas in consensus (DistributionFunction, section 02.1.4), not author-supplied code. Buys halt safety by construction, unchanged proofs, one audit, and no engine or host bug class at all: that class exists only where an engine runs, so it separates A from every other option rather than being shared by them. What A trades away is author-redeployable fixes: a primitive bug hits every user of the primitive and only Dash can patch it, by PV. C gains author redeploy for contract-level bugs and owns the engine and host class on top, mitigated by the section 11.2.6 freeze, not removed. Precedents read to one standard, days to activation: XRPL's fixAMMOverflowOffer (a native fix voted as an amendment, about three weeks from the 2024-03-23 bug report to activation, report 09; the amendment is listed at xrpl.org/resources/known-amendments, fetched 2026-09-08) against Juno's April 2022 stack-overflow halt (an engine-class bug under permissionless wasm, about 48 hours to a patched fork, report 05). On Dash both classes wait for the same window, 9 to 18 days from lock-in (section 02.1.6); the freeze is the only faster path and exists only under C. AMMs and lending are also still evolving. Verdict: adopt as its own stage for the best-ratio primitives (section 06, Phase 1b, off the path to the VM phases), excluding native AMM and lending.

3.2 B: bounded expression guards

Computed constraints and authorization predicates inside the data contract, total and terminating. Phase 2 (section 07) ships a bespoke evaluator, packages/rs-platform-guards (no_std plus alloc; lexer, parser, type checker, static cost model, evaluator; CEL-subset syntax, Cedar's permit/forbid combination); cedar-policy 4.12.0 and cel 0.14.5 (crates.io, 2026-09-08; facts:27 records 0.14.4 of 2026-08-27) are dev-dependency conformance oracles only, never consensus code. Why neither ships: cedar-policy (Apache-2.0, MSRV 1.89, Lean model in cedar-spec) verifies Cedar's semantics, not our embedding, has no division and would need a second grammar for arithmetic; cel (MIT) has IEEE doubles, no metering, and its own harness marks 1150 of 2343 cel-spec v0.25.1 cases as expected failures (cel-rust conformance/src/bin/ignored.txt, generate.rs:247-249). The honest cost: a second consensus-critical language surface beside native primitives and the wasm host, with its own normative grammar and unit table in the DIP appendix, PV-pinned semantics, a static cost model, and a parser every client reaches (one implementation in rs-dpp validation, used by wasm-dpp2 DataContract::from_value and rs-sdk; mobile sends schema JSON unchanged, section 07). Why it is a terminus rather than scaffolding once Phase 3 predicates exist: a guard is JSON in the schema, so wallets, indexers and reviewers read the policy without decoding a module; it has no fuel, no max_fuel, no upload and no engine version, so its cost is a pure function of (schema, guard, fee version) and gas_wanted equals gas_used for read-free guards without running anything in check_tx (section 07 acceptance); its grammar is small enough to freeze per PV indefinitely, where an engine pin rotates; and under section 01 principle 2 every operation an entry point proposes still runs its document type's guards, so guards stay the authorization layer over module writers too, the cheapest rung of a three-rung ladder (guard, predicate, entry point). It also forces the compute fee channel, read cap and per-PV evaluator gating Phase 3 needs. Verdict: adopt as Phase 2, as a stage.

3.3 C: bespoke WASM hooks on wasmi (the chosen core)

Small modules on document types, staged as validation predicates, then declared-footprint reads, then entry points returning proposed operations that the existing pipeline validates and applies. Why it fits: a thin host ABI exposes Drive's semantics instead of an imported KV, gas and actor model; predicates change no state layout, so proofs are untouched; entry points keep state document-shaped, so the existing index, fee, refund and proof stack covers contract state; the seam is the PV-versioned data-trigger table (section 02.1.1). The adoption carries these rules, each a consensus surface with its own PV gate, stated here because the seam violates several today:

1. Error classification. The host boundary returns one closed enum, defined at the ABI and not by the engine: HookOutcome with Accept, Reject(u16), Trapped(TrapKind), OutOfFuel, InvalidResult and Unavailable(reason), the names section 08.2.7 implements. Two candidate members are deliberately absent: a call whose fee exceeds its declared max_fee is not a guest outcome at all, since that bound is checked outside the guest and reported as ContractCallOverMaxFee (10.2.9), and a module that will not translate under the active engine is Unavailable(TranslationFailed) rather than a load outcome of its own. Trap kinds are the easy half; the hard half is host functions calling Drive with guest-supplied keys, ids and payloads. Rule: every guest argument is validated into a typed Drive input before any Drive call; the Error variants a validated call can still return are enumerated and mapped by exhaustive match, no wildcard arm, to ValidationModuleError, a sibling of DataTriggerError in DataTriggerExecutionResult (SimpleValidationResult<DataTriggerError>, batch/data_triggers/mod.rs:36), which the batch path lifts to ConsensusError::StateError (batch/state/v0/mod.rs:330), the variant set being new consensus surface; a remaining Err counts as a host defect only after a fuzz harness has driven every host function with arbitrary guest input and asserted that no Err escapes. Every non-Accept outcome is charged through the paid bump-nonce path (batch/state/v0/mod.rs:324-340), never the unpaid path (stp/process_validation_result/v1/mod.rs:67). Why: today execute(...)? (batch/data_triggers/executor.rs:47; batch/state/v0/mod.rs:317-322) sinks any Err as InternalError; the proposer rolls back and strips it unpaid (stp/process_raw_state_transitions/v0/mod.rs:222-233; abci/abci/handler/prepare_proposal.rs:214-234), Tenderdash drops it from the mempool (td_state_execution.go:279-281) and a one-byte change re-admits a copy through check_tx, which runs no hooks. So a module that burns to within one host call of max_fuel and then issues a malformed read costs the proposer the whole ceiling for nothing, every round, up to proposer_tx_processing_time_limit (5000 ms on mainnet, packages/rs-drive-abci/.env.mainnet:92); and a failure one node classifies differently (an allocation failure, a host-side expect) rejects the block. Panics: the server builds with panic = "unwind" (root Cargo.toml:70-82 set abort only for the iOS profiles) and catch_unwind appears only at FFI and JNI boundaries (packages/rs-sdk-ffi, packages/rs-platform-wallet-ffi, packages/rs-unified-sdk-jni) and in tests (drive/verify/bounded_decode.rs:109 among them), never anywhere in packages/rs-drive-abci, so a panic inside a host function unwinds the ABCI handler today. Hooks therefore run on a dedicated executor thread with a pinned stack size under catch_unwind; a caught panic maps to the paid Trapped(HostPanic) outcome on every node, and any occurrence is a consensus vulnerability (section 01, principle 6). Ceilings never consult host state: memory pages and stack height come from SystemLimits, no limiter reads host RAM. The harness is not test_fault_injection, which only replaces a successful result with InternalError after apply (stp/process_raw_state_transitions/v0/mod.rs:25-58); it is a per-trap-kind, per-host-error-kind test asserting PaidConsensusError with fee equal to consumed fuel, run on x86_64 and aarch64.

2. Block budget, a precondition. proposer_tx_processing_time_limit is Option<u16> defaulting to None (abci/abci/config.rs:39,60), consulted only when proposing (stp/process_raw_state_transitions/v0/mod.rs:149-156); .env.mainnet:92 is operator configuration; process_proposal re-executes with no timer. The bound in force today is Tenderdash's reap of summed gas_wanted (the check_tx estimate's total_base_fee, abci/abci/handler/check_tx.rs:66-70,144) against block.max_gas = 57631392000 (packages/dashmate/configs/defaults/getBaseConfigFactory.js:436; td_state_execution.go:202-212), about 7.2 s at the fee model's 8M credits per ms (pv/drive_abci_versions/drive_abci_validation_versions/v10.rs:338-343), above the 5 s time_iota_ms (:437). The rule names which quantity each check sums, so proposer and validators cannot disagree. (a) At reap, gas_wanted of a hook-bearing transition carries its declared ceiling (rule 3) and max_gas is set from the same SystemLimits constant, max_block_processing_credits (section 06.1). (b) In the processing loop, on every node, the actual charged processing credits of transitions 0..i-1 are summed before executing i; crossing the constant yields NotExecuted(BlockProcessingBudgetExhausted) with the crossing transition kept, and validators reject an over-budget block through the existing gate: NotExecuted already counts as failed (abci/platform_types/state_transitions_processing_result/mod.rs:149-151) and any failed result rejects the proposal (abci/abci/handler/process_proposal.rs:285-307). Actual credits are deterministic (fuel is metered by the pinned engine) and already consensus quantities (they enter the pools). (c) Fairness: no hook sub-budget of its own. max_state_transitions_per_type_per_block (section 06.1) is the starvation control, bounding how many transitions of one type a block admits; transitions past the count are NotExecuted (mapped to TxAction::Delayed, prepare_proposal.rs:236) while other types continue. At PV17 hook-bearing transitions sit inside the documents-batch type and share its count, which is the reason the per-transition ceiling of rule 3 and the derived max_hook_fuel_per_call (08.2.6) carry the load there; at PV19 ContractCall is its own transition type (wire id 24) with its own count, so a call-heavy mempool cannot displace document batches. Derivation of the constant: worst-case fuel per ms measured on the slowest supported validator class by section 12's calibration harness, divided into the Tenderdash round timeout less the propagation and re-execution margin, never the proposer's 5000 ms; revised per PV.

3. Fees. Every hook has a ceiling known before execution, the bound B of 08.2.6: for predicates the document type's declared maxFuel, itself bounded at parse time by max_hook_fuel_per_call (08.2.3), with no guest-initiated reads at all at PV17; for entry points a registration-declared max_fuel plus the declared footprint's read cost (PV18, section 09) plus a declared write-byte reservation, pinned by contract version. Two hard rules beside the fuel ceiling. Storage: every proposed operation carries a write-byte reservation (or the host enforces a per-hook write-byte cap and traps before any write); the storage fee charged is bounded above by it and no apply-time write may exceed it. Affordability: validate_fees_of_event checks the payer's balance against fuel ceiling plus write reservation in the required tier, in check_tx (abci/execution/check_tx/v0/mod.rs:180) and again immediately before execution (stp/execute_event/v0/mod.rs:390); a hook-bearing transition whose payer is short at that point is a paid consensus error, never debt. Execution charges actual fuel and bytes once, after the run; exceeding a ceiling traps to a paid consensus error; fuel-to-credits and operator costs sit in a new FeeVersion table (pv/fee/mod.rs:34-47). Why the tiers matter: apply_balance_change_from_fee_to_identity_v0 books a processing shortfall into the negative-credit slot (drive/drive/identity/update/methods/apply_balance_change_from_fee_to_identity/v0/mod.rs:102-107) but returns Err(IdentityError::IdentityInsufficientBalance) for a storage shortfall (:94-100) after apply_drive_operations(apply = true) has written (execute_event/v0/mod.rs:53-63): InternalError with applied state, the mainnet halt class of section 02.1.7, and a bytes under-estimate, not a fuel one. Without the reservation, an entry point whose actual index and document bytes exceed the check_tx estimate (a branch the dry run never sees, or a contract version bump between check_tx and execution) makes every node apply and then hit the storage-tier Err; the proposer strips, a validator rejects, and the attacker repeats it for the price of check_tx. Why the pre-execution check must carry the live ceiling: check_tx runs no hooks, so the block-time check is the only one that sees a contract version bumped after admission, and N individually affordable transitions from one identity in one block drain the balance under the first; fuel is processing, so either case would otherwise land in the desired tier as debt, and the debt slot is overwritten with desired - previous_balance (apply_balance_change v0/mod.rs:102-107), the forgiveness section 02.1.7 names. test_fault_injection (stp/process_raw_state_transitions/v0/mod.rs:25-58) is a required regression for the storage path, as section 02.1.7 demands.

4. Ownership and refunds. An owned element carries one owner in its flags (SingleEpochOwned, MultiEpochOwned; grovedb-epoch-based-storage-flags/src/lib.rs:53-57), the replace converter stamps the signer (drive/state_transition_action/action_convert_to_operations/batch/document/document_replace_transition.rs:49-50), and when owners differ on update grovedb merges with MergingOwnersStrategy::UseTheirs, transferring the prior owner's refund entitlement to the new payer (update_element_flags.rs:46-56; RaiseIssue would be an Err, lib.rs:123-138). That is right for document transfers and wrong for hook writes. Rule for cross-payer writes: the flags owner is the document's $ownerId (Caller-owned or Principal-owned per proposed operation, rule 7), fixed for the document's life except through the existing transfer path; the payer is always the signer (rule 7); added bytes are booked under the owner's epoch map; refunds on delete go to the owner through the 50-era path (packages/rs-dpp/src/fee/epoch/mod.rs:49-54). A caller who grows a principal-owned document pays and forfeits the entitlement to the principal, a fee to the contract it accepts by calling; no path books bytes to a third identity, because only the owner, or the module acting as Principal on principal-owned documents, may write a document. Strategy test: A creates a principal-owned document through a call, B grows it, the contract deletes it; the refund equals the undistributed remainder of what A and B paid and is credited to the principal; a B call touching an A-owned document is a paid rejection.

5. Code blobs. Measured, not assumed: a minimal no_std predicate (one export, no allocator, opt-level = "z", panic = "abort", LTO, no post-processing) built for wasm32-unknown-unknown with the pinned toolchain (rustc 1.92.0, rust-toolchain.toml:3) is 394 bytes as emitted and 109 bytes with Cargo's strip setting, measured 2026-09-08, so a Phase 3 module could ride inline under max_state_transition_size (20480, pv/system_limits/v4.rs:23). The chunked, hash-addressed channel (section 06.2, PV15) stays the only channel anyway: section 08 caps code at 256 KiB because decoders over platform-value grow modules well past the transition cap, that cap is Tenderdash-coupled and shared with every transition, and one hash-addressed store gives immutability and sharing by hash; a second inline channel would be surface with no consumer after Phase 3. Blobs carry uploader-owned StorageFlags, are deletable with refund, and are size-capped in SYSTEM_LIMITS_V5; verifying keys (3.8) use the same channel. Validation and translation are charged deterministically from module size at registration (fuel_per_bytes_validated, fuel_per_bytes_translated, facts:12) with eager translation, so a module that does not translate never registers; translation fuel is charged again on every invocation as part of the ceiling (a function of the stored size), so the block budget bounds translator wall clock on a cold node, and the compiled artifact is a node-local cache keyed by (code hash, engine PV) that never touches fees. Two requirements this places on section 06.2's channel: staging entries of unassembled blobs expire after a SystemLimits block count with the uploader refunded per epoch flags, and chunk bytes per block are capped in the reap.

6. Credit conservation. The only credit-moving host operations are transfers between identity balances and existing prefunded specialized balances owned by the calling contract (section 12), both under the sum trees. No host function creates a specialized-balance key: those are bare sum items without flags (drive/drive/prefunded_specialized_balances/add_prefunded_specialized_balance_operations/v0/mod.rs:64-76), so a hook that could create keys would grow the PreFundedSpecializedBalances root as perpetual unpaid storage; keys are created only by registration and by Schedule entries priced as flagged writes with a delete-and-refund path. Every credit inflow to an identity, hook transfers included, routes through add_to_previous_balance (drive/drive/identity/update/methods/add_to_previous_balance/v0/mod.rs:28-63) so debt is repaid first. verify_sum_trees is node configuration on ExecutionConfig (packages/rs-drive-abci/src/config.rs:96-97, default at :613), not consensus, and the generation in force at PV14 is calculate_total_credits_balance_v2 (pv/v14.rs:199 selects DRIVE_VERSION_V9, whose calculate_total_credits_balance: 2 is at drive_versions/v9.rs:67), which sums Balances, PreFundedSpecializedBalances, Pools, AddressBalances and ShieldedBalances while excluding negative credit (drive/drive/balances/calculate_total_credits_balance/v2/mod.rs:40-80; v0 summed the first three roots only), so the check alone is not the invariant: strategy tests run it in every hook-bearing scenario and additionally assert, after every hook-bearing block, that the negative-credit set is empty for every principal and that debt and balance never coexist on any identity a hook touched.

7. Principal. A keyless identity subtype whose id is the contract id (sections 04.4, 10.2.2). Creation demands a master key today (MissingMasterPublicKeyError), so the principal is system-created with an empty key map. Payment model, one of two, chosen: the caller pays everything in a caller-initiated transition (fuel, reads, bytes; the model sections 10.2.2 and 12 adopt); the principal's balance moves only through principal-initiated system events (scheduled calls prepaid at scheduling, 10.2.6) and through explicit CreditTransfer proposed operations checked against a ledger of pre-call balances before apply, a shortfall being a paid consensus error charged to the caller. Rejected: a two-debit BalanceChange; the fee pipeline is single-payer (into_balance_change(identity_id), fee_result/mod.rs:217, applied to the signer at execute_event/v0/mod.rs:81, other identities only as refund recipients), and a principal-paid write would let any caller drain a contract for the price of fuel. Principal debt is forbidden by construction (it pays no fee) and asserted by rule 6's test. Each entry point declares at registration a maximum principal outflow per call, so a caller cannot move more than the author budgeted. Migration: principals for contracts registered before the PV are created lazily, at the first module registration that needs one and priced to that transition; eager creation for every contract in perform_events_on_first_block_of_protocol_change is rejected, because it is an unbounded loop in a block event where an Err halts the node and it writes storage nobody pays for (section 14.7). Creation fails if an identity already holds the id (ids are hash_double(owner_id || nonce), packages/rs-dpp/src/data_contract/generate_data_contract.rs:10-18; collision is negligible, the check is stated anyway). Anyone may fund it. No hashed instantiate2-style derivation: contract ids are already unique.

8. Kill switch. Hooks stop without a PV: the ContractGovernance system contract's frozenModule, frozenContract and globalFreeze documents (section 11.2.6) are read once per hook run and once at module registration and blob upload, since validation and translation execute attacker bytes before any hook does; a frozen target maps to one fixed paid rejection. Writer: the governance identity under a key ceremony (11.2.6; a masternode vote is too slow for an incident), gated by the contract's own activation PV. Mechanics: the read is a point read in the block transaction at the transition's position (08.2.5 item 1, 11.2.6), not a once-per-block load of committed state, because in-block binding is what makes the switch faster than a release, priced in the FeeVersion table and billed to the transition, so a freeze written at block N position k binds position k+1 on every node; it goes through the same typed host-read layer as any other read, an absent document meaning not frozen and a Drive Err a host defect under rule 1. Test: a freeze at N/k rejects a hook at k+1 on every node. A vote plus rebuild is the wrong latency for a sandbox or metering escape.

9. Nondeterminism inventory:

Source	Gate	Test
Floats, NaN	parser rejects float types; deterministic feature as second layer	wast runner, corpus
Guest stack, recursion	set_max_stack_height, set_max_recursion_depth from SystemLimits (wasmi 1.0.4 fixed that check, #1727, facts:11)	deep-recursion modules
Native stack	dedicated executor thread with a pinned stack size; hooks never re-enter hooks (section 01, principle 2), so host recursion into Drive is bounded by the call graph, not by guest input	deepest host path under the minimum thread stack
Host panics	catch_unwind on the executor thread to the paid Trap(HostPanic); profile is unwind (root Cargo.toml:70-82)	injected panic in each host function
Wasm proposals	exact wasmparser pin in the fork; registration allowlist	feature-probing modules
Arithmetic edges	exact engine revision (wasmi 1.0.5 fixed rem_s(MAX, -1), facts:11)	spec testsuite, x86_64 vs aarch64
Engine Config	hash of the full Config (feature flags, deterministic, no-start, operator table) in the PV artifact, asserted at startup	startup assertion, mismatched-build test
Memory	page cap in SystemLimits; instances are per call and sequential (one loop, stp/process_raw_state_transitions/v0/mod.rs:146), so live guest memory is one instance's cap; translated-module cache under a node-local byte limit; no host-RAM limiter	small-validator run at the cap
ABI encoding	proposed operations, receipts and error payloads serialized only from ordered containers (BTreeMap); no HashMap in any encoder	golden vectors
Host calls, instantiation	fuel from the FeeVersion table; every failure a rule 1 outcome	golden vectors, fuzzed arguments
Drive reads	transaction-scoped snapshot; never a can_alter_cache path (abci/execution/validation/state_transition/state_transitions/mod.rs:77)	fault injection
Time, randomness	block_info only; no clock or RNG import	import allowlist

Costs accepted. Bill of materials for C, with who maintains each today: the host crate and ABI (new, Dash); module validation in the check_wasm posture (CosmWasm has it, 3.12 ports it); the advisory process (34 CWAs inherited under D, owned alone under C); the guest SDK, dash-contract-sdk, dash-contract-abi, dash-contract-testutils and the dash-contract CLI (section 13; new, Dash alone; under D cosmwasm-std, cosmwasm-schema and cw-storage-plus exist, the ICF funds Hadron Labs through 2027-12-31 (facts:39) and cw-storage-plus sits inside the advisory scope of CosmWasm/advisories SECURITY.md, fetched 2026-09-08, though the funded maintenance scope of the contract libraries is not published); hook-aware decoding in js-evo-sdk, wasm-drive-verify, Swift and Kotlin (every path). Consensus surface every VM path pays, C included: the code blob channel (02.2.1), block budget (02.2.2), events or receipts (02.2.3), the Phase 5 speculative overlay (02.1.9, section 10), the principal (04.4; D needs an address mapping instead) and the freeze registry (11.2.6). So the delta between C and D is the host ABI plus the guest SDK and its tooling, which is exactly where NEAR and Soroban spent dedicated teams (report 07); it is not only the host ABI. Estimate: no point estimate here. Reports 06 and 08 put revm and Move embeddings at 2 to 4 engineer-years each (report_06.md:23, report_08.md:28), and C's total sits in that band once the surfaces above are added; any single figure quoted for phases 3 to 5 is that band's midpoint, not a bottom-up number. Producing the bottom-up number surface by surface (host crate, ABI, prepare pass, seam, guest SDK, CLI, harness, SDK propagation) is the first Phase 0 task, and the two conditions this section turns into gates, the funded SDK commitment (owner, engineers, funded duration; section 01, goal 6) and engine stewardship (3.11; section 13 records the funding decision), each need a row in section 05's decision register with an owner, a due date and a default if undecided. Precedents both ways: Soroban (bespoke host on a stellar/wasmi 0.31.1 fork, CAP-0046-01 Final at protocol 20) is the shape and costs SDF's own host crate (rs-soroban-env, facts:30-33) plus the wasmi sponsorship (facts:15); Plutus is predicate-only user code (report 07); Radix (bespoke engine on upstream wasmi at an exact =0.39.1 pin) is moving its foundation to a community RFP model in 2026 (report 09); ink! plus pallet-contracts halted in January 2026 with Parity behind it and a live treasury (facts:44). Bespoke paths die of SDK and devex funding, not engines; this section makes that funding the gate. Verdict: adopt, conditional on the SDK budget being committed before the PV17 dependency lands and on the 3.11 gate; if the budget is not committed by then, Phase 3 does not start and the plan terminates at A plus B.

3.4 D: CosmWasm, and D': cosmwasm-vm as the engine under a Dash host

D embeds cosmwasm-vm (Apache-2.0, pure Rust; 3.0.9 stable, 3.1.0-rc.1 prerelease of 2026-08-17, facts:39) behind Dash-implemented Storage, BackendApi and Querier traits (CosmWasm's own packages/vm/src/backend.rs on main, fetched 2026-09-08) with its actor model; D' keeps only the engine, staged like C. Fee impedance is not a discriminator: every host callback returns GasInfo { cost, externally_used }, so storage pricing is out-of-band in the host under either path and refund attribution is Dash design work under either (rule 4). Nor is the keeper: C builds dispatch, rollback and code storage itself by Phase 5. Nor is embeddability: wasmvm carries the same three traits across a Go FFI boundary on dozens of mainnets (report 05), so the host surface has no hidden Cosmos hooks; the one non-Cosmos attempt, ComposableFi's no_std rewrite for Substrate, was a fork rather than an embedding, archived February 2024, and its lesson is embed, never fork (report 05). Maintenance is asymmetric, in D's favour: Confio ended maintenance 2025-06-30 but the ICF funds Hadron Labs through 2027-12-31, an advisory pipeline has absorbed 34 CWAs, six of them 2026 (CosmWasm/advisories CWAs directory, fetched 2026-09-08), and dozens of production chains share the incentive to keep the engine, gatekeeper, check_wasm, metering, module cache and advisory process alive; wasmi has one maintainer whose SDF sponsorship ends October 2026, a 2.0.0 six days old at the as-of date, and one production consensus embedder on its upstream line, Radix at an exact 0.39 pin (Soroban runs a fork). Under D Dash is one of many; under C Dash writes and maintains each of those pieces alone from day one (3.12 ports check_wasm rather than depending on it); a fork of last resort is possible under both. The genuine crux is one item: the wasmer = "=5.0.6" JIT pin, two majors behind 7.4.0 and unable to follow it (MSRV 1.95 against the 1.92 toolchain, facts:23,52), native frames (Singlepass targets x86_64 and aarch64, riscv64 experimental; wasmer lib/compiler-singlepass/README.md, fetched 2026-09-08), and the metering history of exactly that design (CWA-2024-007 "Incorrect metering" in wasmer's gas tracking; CWA-2024-008, a host panic that skipped gas reporting; both patched 2024-09-23, CosmWasm/advisories, fetched 2026-09-08), against an interpreter with an owned guest stack whose limits are engine numbers. Pinning 5.0.6 exactly, as every CosmWasm chain does, inherits the shared fixes for that history and for whatever follows; reimplementing check_wasm, the gatekeeper and the advisory process under C is part of the unestimated bill above. Secondary against D and D': a JSON message ABI against platform-value, the cosmwasm-std contract model in the guest SDK, and (D only) cw20-style balances outside the sum trees (rule 6). Juno's April 2022 stack-overflow halt (report 05) is the class rule 1 and the inventory address, not a D-specific reason. Verdict: reject D and D' on the JIT crux, accepting the maintenance asymmetry; take designs (3.12).

3.5 E: EVM (embedded revm; L2 or sidechain)

Embedded: revm (MIT, 43.0.0; crates.io, 2026-09-08) has a Database trait (report 06) that would back onto a GroveDB subtree, but the interpreter is the small part. The rest fights Platform: secp256k1 single-key EOAs beside multi-key identities, unprovable eth_call results, eth_getProof needing a parallel keccak MPT that Ethereum itself proposes replacing (EIP-7864, Draft; eips.ethereum.org, fetched 2026-09-08), 18-decimal conventions and SSTORE refunds against credits and epoch refunds, an eth_* RPC node. L2 or sidechain: Drive cannot verify fraud or validity proofs of an EVM, so a rollup anchored to Platform is a federated sidechain with an LLMQ-signed bridge. Verdict: defer; if demand appears, embed revm behind a PV, precompile-first, without an MPT.

3.6 F: Move VM (Aptos lineage; Sui fork)

The strongest conceptual fit among foreign VMs: a 32-byte Move address is a 32-byte identity id, resources under an address map to a per-identity GroveDB subtree, resources are typed BCS, and the gas algebra has storage deposits and refunds. Why deferred (report 08): the bytecode verifier is consensus-critical with a history of critical bugs, one control-flow bug shared by every fork and fixed silently in the Sui branch (March 2023) before the others, so a fork owner watches three upstreams (Aptos, Sui, Initia) for unannounced patches; Aptos has announced MonoMove, a full VM redesign for 2026, so the internals a fork pins are about to churn; and Aptos Move 2 and Sui Move 2024 are source-incompatible dialects with no shared upstream, so the portable pool is one dialect's share of ecosystems under about 7k developers per chain. Footnote: the VM is not on crates.io (a 2019 move-vm 0.0.0 name reservation only; crates.io, 2026-09-08), so embedding is a vendored fork, which alone would not separate Move from C since 3.11 forks wasmi at an exact revision anyway. Verdict: defer; design study only if programmable identity-bound assets, not general compute, become the product goal.

3.7 G: SVM

solana-svm (Apache-2.0, 4.2.2 stable; crates.io, 2026-09-08) is the best-maintained upstream here and the worst fit: Pubkey-keyed lamport accounts with rent, sysvars, Solana's FeatureSet cadence and the SanitizedTransaction format are load-bearing throughout, and the Anchor tooling that would justify adoption assumes all of them; account state is opaque byte blobs, which discards provable indexed queries. Verdict: reject.

3.8 H: zk-predicates and the zk-coprocessor

Logic runs off-chain; the chain verifies a succinct proof and applies a declared state diff through the existing operation and fee pipeline. Stepping stone: a per-document-type verifying key and a proof over old document, new document and public inputs. Why it deserves a seat: bounded, declared verification cost fits halt-on-divergence, and Platform already verifies zk proofs in consensus (reconstruct_and_verify_bundle, abci/execution/validation/state_transition/state_transitions/shielded_common/mod.rs:83). That precedent uses one system key with cost tied to the action count under the 20 KiB cap (about 2,681 B per action, pv/system_limits/v4.rs); a user-chosen circuit makes cost attacker-declared unless one proof system is fixed per PV and circuit size, public-input count and key size are capped in SystemLimits and priced in FeeVersion, with keys registered through the rule 5 channel. Why not now: proving latency on mobile, key governance, data availability for private inputs. Verdict: defer with a design study from Phase 3 (section 14); section 04's proof-guard reservation carries those fields.

3.9 Also considered

TEEs: reject; SGX attestation centralization, side channels, heterogeneous masternode hardware, no attestation primitive in consensus. Optimistic verification: reject; evonodes post no execution bond and nothing in the tree slashes (the only penalty the tree references is a PoSe ban, "evonodes that are not banned", abci/execution/platform_events/protocol_upgrade/check_for_desired_protocol_upgrade/mod.rs:16), and Drive has no fraud-proof VM, so it degenerates to federation. State channels: an application pattern over documents. PolkaVM and RISC-V: defer; polkavm 0.36.0's README says do not use in production and targets RV32EM, pallet-revive is experimental, ink! halted in January 2026.

3.10 Why throughput is not the discriminator

No report proposes a foreign VM for speed; reports 05 and 08 argue ecosystem, audited code, tooling and shared engine maintenance. Answers: the ecosystem argument assumes an EVM or Cosmos developer funnel this plan does not compete for (section 01, principle 9), and the applications it serves need enforced rules over proven, document-shaped state that no imported VM's libraries model; audit familiarity transfers to the engine only, and under C the engine is a pinned interpreter whose spec testsuite and differential corpus (3.11) are the audit surface while the host ABI is new under every path; shared maintenance is real and 3.4 concedes it as the price of the JIT crux. Throughput itself separates nothing: Solana and Sui throughput comes from consensus latency in the hundreds of milliseconds, parallel execution over declared read and write sets, no per-write merkleization and no per-read proof obligation, and Platform has none of the four (5 s time_iota_ms, getBaseConfigFactory.js:437; one sequential loop, stp/process_raw_state_transitions/v0/mod.rs:146; every write under the app hash; every read proven). The engine question is only whether interpreted execution fits the block, and these numbers are targets for section 12's harness, not measurements: at the 8M credits per ms anchor (v10.rs:338-343), a predicate targeted at 50 us is 0.4M credits and 100 of them 40M; an entry point targeted at 5 ms is 40M credits and 100 of them 4e9 credits, 500 ms; report 07's 10 to 30x interpreter penalty (unsourced there) would recalibrate the same modules to 0.17 to 0.5 ms under a JIT. The binding constraint is re-execution time on the slowest quorum member against the Tenderdash round timeout (rule 2), measured on that hardware class, not a share of the proposer's 5000 ms; the interpreter ceiling binds only when hook-bearing transitions approach a few hundred per block at Phase 5, and by then an engine swap (3.11) is a PV like any other. The one real parallelism lever is declared footprints (section 09), engine-independent.

3.11 Engine choice within WASM

	wasmi 2.0.0	wasmtime 36.0.14 LTS, Pulley only	wasmtime 48.0.1	wasmer 7.4.0	PolkaVM 0.36.0
License; MSRV vs 1.92	MIT/Apache-2.0; 1.86	Apache-2.0 with LLVM exception; 1.86	same; 1.95 (no build)	MIT; 1.95 (no build)	MIT/Apache-2.0; 1.86
Execution; determinism	Interpreter, heap-allocated guest stack; deterministic feature, no-start option	Interpreter over Pulley bytecode emitted by Cranelift, Tier 2 (wasmtime docs/stability-tiers.md:93, :315-318); whether Pulley frames use an owned stack or native frames is unverified (section 14 question 4); NaN canonicalization, threads and relaxed SIMD off	Cranelift JIT, native frames	JIT, native frames; NaN canonicalization (report 05)	RISC-V interpreter; README: goals not all true yet
Metering	Per input operator (PR #2013); operator_cost table and CustomFuelCosts (PR #2025); "relatively stable" across versions, re-calibrate on upgrade (docs/migration-v1-to-v2.md)	operator_cost (PR #12541); stack via finite-wasm instrumentation, engine-independent; epoch_interruption is wall clock only	same	Middleware; CWA-2024-007 escape	GasMeteringKind::Sync hard-coded by pallet-revive (facts:43); granularity unverified
Releases	1.0.0 (2025-12-03) and 1.0.1 yanked (CVE-2025-66627); semantic fixes 1.0.4 (#1727) and 1.0.5 (rem_s), translator fixes 1.0.6 to 1.0.9 (#1748, #1756, #1762, #1779), six in the ten weeks after 1.0.0 (facts:10-11); 1.1.0 2026-06-12; 2.0.0 2026-09-01	LTS: 24 months of security backports (docs/stability-release.md:11-12, fetched 2026-09-08); EOL about 2027-08 is derived, not published: one major per month on the 20th (:44-47), so 36 predates 48.0.0 of 2026-08-20 by twelve; then 48 LTS at MSRV 1.95	48.0.0 2026-08-20	7.0.0 2026-01-28	0.36.0 2026-07-13
Maintenance; precedent	One maintainer, SDF sponsorship ends October 2026; Soroban (0.31.1 fork), Radix (upstream =0.39.1 pin)	Bytecode Alliance; NEAR (nearcore 2.12.0: wasmtime 45.0.0, finite-wasm 0.6.1, exact wasmparser 0.236 pin annotated as protocol-bound, after moving off wasmer)	same	Small company; CosmWasm pins 5.0.6	Parity, work in progress; pallet-revive experimental
Verdict	Adopt, conditional (below)	The alternative; decided by section 14 question 4 (c)	JIT tier only, later	Reject	Defer

wasmi versus Pulley turns on two facts, recorded as section 14 question 4, option (c), rather than asserted here: whether Pulley's stack accounting is engine-independent under finite-wasm (then a stack limit is a protocol number under both and the owned-stack argument for wasmi disappears), and whether Dash prefers a one-maintainer interpreter it will probably fork within a year to a foundation-maintained LTS whose interpreter is Tier 2 with a 24-month backport window. Against wasmi on its own record: 1.0.0 and 1.0.1 yanked for a use-after-free, six semantic or translator fixes in ten weeks, a breaking 2.0 nine months after the "API-stable" 1.0, sponsorship ending in one month; "Soroban is the model" does not support pinning upstream 2.0, since Soroban's model is fork-and-freeze at 0.31.1 with an SDF-funded host team. For wasmi: the guest stack is heap-allocated, so stack limits are engine numbers without instrumentation, and no code generator sits anywhere in the path.

Pin rule: exact git revision in a dashpay fork, as grovedb is pinned (packages/rs-drive/Cargo.toml:55 pins a rev, not a semver); any change, patch included, is a PV activation, the prior revision retained under a renamed package (the soroban-wasmi pattern) selected by a wasm_engine_version field beside grove_version on DriveVersion (pv/drive_versions/mod.rs:40-46) with its operator cost table, wasmparser feature set, Config hash and host ABI version. Nodes on 1.0.4 and 1.0.5 already disagree on rem_s; a semver pin leaves that to Cargo. Shape of the cost: each retained engine is a renamed copy of the whole dependency subtree (wasmi, wasmi_core, wasmi_ir and wasmi_collections, plus the exact wasmparser = "0.228.0" that wasmi's own workspace pins, wasmi-labs/wasmi Cargo.toml:46 at v2.0.0, facts:14; stellar-core carries two full host trees the same way, facts:30), with compile time and binary size measured on rs-drive-abci and a CI gate that the workspace builds with every retained copy. Backport policy: a retained package receives only memory-safety fixes that the differential corpus (result values, fuel, trap kinds, x86_64 and aarch64) plus a full replay of every hook-bearing historical block show app-hash-identical; anything else is a new PV with a new package. A retained engine with a memory-safety bug that cannot be patched that way (CVE-2025-66627 was a use-after-free in linear memory, and replay from genesis executes attacker-registered modules) runs replay out of process in a sandboxed subprocess; a syncing node never executes historical modules in the ABCI process under an unpatched engine. Verdict condition: pin only once the corpus below exists and the chosen revision has survived two upstream patch releases with no fuel or result change. Dates: the 1.0.x cadence was a semantic or translator fix every one to three weeks from 2025-12-10 to 2026-02-09, then no 1.0 patch at all before 1.1.0 four months later; so the criterion is met for 2.0.x at the earliest in mid-October 2026 (2.0.1 and 2.0.2 both clean; 2.0.0 of 2026-09-01 is still the only 2.0 release, crates.io, 2026-09-08), around 2027-Q1 if the 1.0.x pattern repeats, and never on 2.0.x if upstream moves to 2.1 without a clean patch pair. The pin date, not the phase schedule, gates Phase 3, and the PV17 target moves with it; fork-and-freeze versus co-sponsorship is decided before October 2026 (section 13).

Upgrade path: the guest ABI is the only thing an engine swap leaves unchanged; the operator cost table, credits_per_fuel calibration, stack accounting and error classification all change, each a PV-gated artifact, so a JIT tier needs engine-independent stack and gas instrumentation (finite-wasm) designed before Phase 3. Registered modules across that boundary: host imports are additive-only within an ABI major; removing or re-pricing an import auto-freezes, through the rule 8 registry at activation, every module that declares it, rather than failing at instantiation; any activation that changes the fuel table re-validates each module's max_fuel against the new table at first invocation and rejects with a specific paid error naming the required new ceiling, so an affordability computed under PV N never executes under N+1's prices. NEAR's frozen fork followed by a protocol-change migration is the realistic precedent, not a clean swap.

Tasks: engine evidence before section 08 pins a revision

• Build the differential harness as a test target of packages/rs-contract-runtime (new; section 08) over a committed corpus under packages/rs-contract-runtime/tests/corpus/ (the spec-testsuite subset the section 08 registration rules admit, plus wasm-smith modules from a fixed seed), recording result value, fuel and trap kind per (module, export, input); pass condition: byte-identical records across every retained engine package and across x86_64 and aarch64, run as a matrix job on ubuntu-24.04 and ubuntu-24.04-arm (the runners release-docker-image.yml already uses) in a new .github/workflows/tests-engine-corpus.yml; every pin change and backport is gated on it (section 11).
• Add historical replay to the same workflow, twice: blocks produced under PV N replayed by the PV N+1 binary with the retained engine package, and every hook-bearing block of the recorded devnet and testnet corpus replayed under each retained package after any backport, through the existing replay feature (abci/replay/runner.rs); pass condition: identical app hash and identical per-transition fee results at every height.
• Record wasmtime 36.0.14 Pulley operator_cost charging points and finite-wasm 0.6.1 stack accounting against wasmi 2.0's over the same corpus, as a table committed at a new packages/rs-contract-runtime/tests/corpus/ENGINES.md stating per module whether fuel and stack-limit outcomes agree; done when section 14 question 4 (c) can be answered from the table, before any pin.

3.12 What we take from each ecosystem

Tasks: designs adopted from rejected or deferred options

• Port CosmWasm's check_wasm posture (CosmWasm's own packages/vm/src/compatibility.rs:108-116 on main, fetched 2026-09-08: table cap, one memory under an initial-page cap, interface version, required exports, import allowlist and count cap, capability declarations, function count and parameter, result and locals caps, then full function validation) into rs-contract-runtime::prepare (section 08.2.2), which adds Dash's own code-size cap and no-start rule; caps as SystemLimits fields in section 08's generation (max_hook_code_size, max_hook_memory_pages, max_hook_table_elements and the structural caps), validation and translation charged from module size (rule 5); acceptance: a module one unit over each cap fails registration with a paid error naming the cap (section 08, PV17).
• Adopt CosmWasm capability declarations: the dash-contract-abi custom section lists required host capabilities (section 08.2.2 rule 4) and each PV grants an allowlist; acceptance: a module declaring a capability outside the PV's allowlist fails registration with a paid error. Add Dash to the CosmWasm advisories notification list (open by PR per its SECURITY.md) and record a wasmi advisory contact in section 11's runbook; done when both appear there (section 11).
• Check the dash-contract-abi custom section's abi_version and target_protocol_version against the active PV at registration, the Soroban contractenvmetav0 pattern (CAP-0046-01, facts:30), with 3.11's additive-only import policy, activation-time auto-freeze and max_fuel re-validation for modules already registered; acceptance: a module targeting a later PV fails registration with a paid error, and a strategy test carrying a registered module across a PV boundary that re-prices one of its imports shows it frozen at activation rather than failing at instantiation; two engine packages stay linkable across the boundary per the pin rule (sections 08, 11).
• Meter fuel and memory bytes as two dimensions (CAP-0046-10, facts:31), both parameters in FeeWasmVersion inside FEE_VERSION3 (section 12) and frozen per PV, as Plutus freezes cost models per language version (report 07); acceptance: golden vectors record fuel and peak memory bytes per corpus module, and a module one page over max_hook_memory_pages traps to a paid error (section 12).

Deferred to their owning sections rather than listed as tasks here: finite-wasm (NEAR) for engine-independent stack and gas accounting in any JIT tier, and as the fallback if 3.11's corpus shows fuel drift (3.11 upgrade path, section 11); ERC-7562's validation-phase rules, mapped rule by rule to PV18 mechanisms in section 09's table; and registration-time guard cost bounds in the Kubernetes CEL admission style, already max_guard_static_units and max_guard_ast_nodes in section 07.

---

---

Continued in part 4 of 14 below.

[QuantumExplorer]

Part 4 of 14 of the plan (continued from part 3 above).

4. Target architecture

The end state sections 05 to 10 build toward, fixed now so no phase ships an ABI, fee rule or storage layout a later phase must break. Governing rule: user code proposes, Drive disposes. Guest code never touches GroveDB; it returns a verdict (predicates) or a bounded list of proposed operations (entry points); the native pipeline validates, prices, applies and proves them. Every cost, cap and error class below is consensus data in a PV table; nothing about hook execution is node configuration.

4.1 Layering

Layer	Build, take or modify	Why
Engine	Take wasmi unmodified at an exact revision of the 2.0.0 line, named in the DIP and recorded in wasm_engine_version on DriveVersion, not only Cargo.lock, pinned by rev through a dashpay fork as grovedb is (packages/rs-drive/Cargo.toml:55-61)	Interpreter: no JIT stack-depth or codegen divergence. 2.0.0 (2026-09-01) meters fuel on input Wasm bytecode (#2013) through Config::operator_cost and fuel_cost (#2025), supports the Wasm deterministic profile (#1947), and exposes enforced_limits, set_max_recursion_depth, set_max_stack_height, compilation_mode and allow_start_fn.
Host layer (Dash)	Build two new crates: packages/rs-contract-runtime (proposed, node-internal) for module prepare and limits, host functions, metering to credits, capability grants and the HookEngine trait, and packages/rs-contract-abi (proposed, published as dash-contract-abi, no_std) for the ABI types host and guest share	Every Platform-specific invariant lives here: credits not gas, StorageFlags refunds, sum-tree conservation, consensus error classes; nothing importable has them.
Guest SDK and tooling (Dash)	Build a no_std guest crate, packages/rs-contract-sdk (proposed, published as dash-contract-sdk), plus packages/rs-contract-testutils (proposed, published as dash-contract-testutils): a harness with a native mode and a wasm mode (the module through the pinned engine with the PV's cost table)	Prerequisite deliverable with an owner: a std-free value core; platform-value is std-bound (BTreeMap at packages/rs-platform-value/src/lib.rs:31, std::thread_local! at :54, despite a std feature at Cargo.toml:32) and Value carries Float(f64) (:136). The Phase 3 guest ecosystem is this one Rust crate; no non-Rust guest path is planned.

Engine facts as of 2026-09-07 (section 03.11 fact sheet): 2.0.0 is six days old and replaced the 1.0 fuel design; 1.0.0 and 1.0.1 are yanked on crates.io (CVE-2025-66627); 1.0.4 fixed the set_max_stack_height check, 1.0.5 rem_s(MAX, -1), translator fixes ran through 1.0.9; one maintainer whose sponsorship is scheduled to end October 2026. The production precedent this plan examined, Soroban, runs a pinned and still-patched 0.31.1 fork (=0.31.1-soroban.20.0.1 from stellar/wasmi, branch commits dated 2026-08-25 and 2026-09-03), while Radix runs upstream wasmi at an exact pin (wasmi = { version = "=0.39.1" } in radixdlt-scrypto's workspace Cargo.toml, fetched 2026-09-08, annotated there as requiring explicit upgrades for non-determinism testing), so 04's configuration (upstream, unmodified, exact pin) has one production precedent, on the 0.39 line, and the differential corpus (section 11) is its main evidence rather than its only one. Hence: determinism is agreement on the pin, not correctness, so an engine correctness fix is a PV event; pin only after the corpus exists and the revision has survived two upstream patch releases with no fuel or result change; the 14-day minimum soak of section 14.4, or an external consensus deployment, before PV17 activates hooks; fork-and-freeze versus co-sponsorship decided before the PV17 dependency. The wasm harness mode exists because a native-only harness gives the right answer where the chain gives the pinned engine's; native and wasm agreeing on the hook corpus is an SDK CI gate.

Rejected for the engine slot (section 03): wasmtime first, because a JIT needs engine-independent stack and fuel accounting (finite-wasm class, section 03.11) designed before Phase 3 whatever the engine, and toolchain MSRV is not a discriminator (a toolchain bump is not a consensus event); wasmer; PolkaVM; a day-one fork (the soroban-wasmi model is the fallback). The HookEngine trait is engine-agnostic; a swap is a PV event.

Budget: section 03 leaves the cost unestimated and places phases 3 to 5 in the 2 to 4 engineer-year band reports 06 and 08 give for revm and Move embeddings, conditional on commitment before the PV17 dependency; 04 inherits the condition. Uncommitted, phases 1 and 2 still ship FEE_VERSION3 and FEE_VERSION4 (the guards sub-table in FEE_VERSION4) and their own paid StateError variants; [64, contract_id, 2] is never created; engine pin, FeeWasmVersion, principal model, entry-point max_fee, two-payer event and verifier change are deferred, so a declarative-only outcome carries no unused consensus surface.

4.2 Execution model across stages

Stage (section)	Guest sees	Returns	Reads and writes
Pure predicate (08)	HookContextV0: action kind, contract id, document type, owner id, block info, new data, old data for replace, delete and transfer	Accept or Reject(code)	none beyond host-provided input
Declared-footprint read (09)	HookContextV1: the same, plus the documents of a submitter-declared footprint and the granted capabilities	same	footprint reads only (own contract, prefetched, priced up front); no writes
Constrained entry point (10)	CallContextV0: call arguments, footprint, principal balance	Bounded list of proposed operations on own document types, tokens and principal balance, each tagged Caller or Principal	footprint reads only; writes through proposed operations only

Host-provided input beyond the action itself is BlockInfo and nothing else. The freeze state never enters the context: the pre-run gate rejects a frozen module before instantiation, so a running guest is by construction not frozen (08.2.5). That gate reads frozenModule by code hash, frozenContract by contract id and globalFreeze on the ContractGovernance contract (section 11.2.6) as point reads through the block transaction, once per hook run rather than from a per-block cache, billed as a PrecalculatedOperation at the query's own cost (the dpns v1 shape, batch/data_triggers/triggers/dpns/v1/mod.rs:265-278). Per-run is deliberate: a freeze committed earlier in the same block then binds the next transition, which is what makes it the plan's one incident response needing no protocol version. A hit is one fixed paid rejection, ModuleUnavailable { Frozen }; who may write the freeze documents is a PV-gated rule (4.7).

Proposed operations become a new StateTransitionAction variant whose converter arm emits only existing DriveOperation kinds (packages/rs-drive/src/util/batch/drive_op_batch/mod.rs:77-104): DocumentOperation, TokenOperation, PrefundedSpecializedBalanceOperation, and one IdentityOperation shape, a principal balance debit to a named recipient; nonce, revision and key writes are unreachable, asserted in the arm. The reuse claim rests on five rules:

• Owner. Each operation carries Caller or Principal. validate_state_v0 passes the batch signer as owner_id to every per-action validate_state (batch/state/v0/mod.rs:89-156 under packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions) and the converter emits UpdateIdentityContractNonce and StorageFlags for that id (packages/rs-drive/src/state_transition_action/action_convert_to_operations/batch/document/document_create_transition.rs:59-66). The new arm maps the tag to both the per-action validator's owner_id and the StorageFlags owner, and suppresses the nonce bump for principal-owned writes; creationRestrictionMode and token costs are checked against the acting owner, uniqueness and revision against the block transaction plus earlier operations in the list. The arm ships at PV19 with the two-payer ExecutionEvent (4.5), so both tags are live from its first block; nothing before PV19 emits a proposed operation.
• Target-type predicates run against proposed operations after the entry point returns, under the remaining max_fuel, so an entry point cannot bypass a guard direct writes face; no guest runs while another is on the stack, so this is not reentrancy.
• Atomicity: operations transform, validate and apply one at a time in list order under one savepoint per call, each against the state after its predecessors; any failure rolls the whole list back and yields a paid ProposedOperationRejected { index, code } with nonce bump (10.2.3, 10.2.4). Validating the whole list against pre-call state instead would let two creates both pass uniqueness and collide at apply as an Err, a rejected block on every validator.
• Document cap. max_transitions_in_documents_batch: 1 (packages/rs-platform-version/src/version/system_limits/v4.rs:26) is load-bearing for state, not for throughput: within one GroveDB batch the document conversions are blind to each other, two operations that jointly empty an index group strand its tree, and on a ranked index the stranded group keeps ranking with a zero aggregate while integrity checks and proofs pass (system_limits/mod.rs:18-47; pinned by documents_batch_is_capped_at_one_transition_at_every_protocol_version, :115). The limit stays 1 at every PV, but it constrains batch composition, not call size: each proposed document operation is applied in its own apply_drive_operations group, in the dry run and at apply alike, so no two ever share a GroveDB batch (10.2.3), and section 10's per-call ceilings stand at eight document operations inside sixteen operations in SYSTEM_LIMITS_V9. Raising the limit itself would need emptiness computed against committed state plus the whole batch, the two other guards that comment names, and a strategy test emptying a ranked group through two proposed deletes and checking the aggregate mirror; nothing here needs it raised.
• Actual-cost affordability. validate_fees_of_event_v0 estimates with apply_drive_operations(.., false, ..) and compares total_base_fee to balance, refunds excluded by a marked TODO (validate_fees_of_event/v0/mod.rs:118-140, the shortfall comparison for a Batch in the Paid arm at :145-163); actual storage above estimate and balance fails at apply with IdentityInsufficientBalance (packages/rs-drive/src/drive/identity/update/methods/apply_balance_change_from_fee_to_identity/v0/mod.rs:91-100), which no rs-drive-abci path special-cases, so it propagates as Err. Tolerable while the author fixes the operation mix; not when a guest chooses it (index fan-out, ranked, time-range and contested indexes, tokens) and an attacker funds exactly the estimate. Entry points therefore apply their list inside a savepoint (rollback_to_savepoint, used at process_raw_state_transitions/v0/mod.rs:234-236), compare the actual FeeResult to the transition's max_fee and to each payer's balance after that call's own debits, and treat a shortfall as rollback plus a paid degraded outcome with nonce bump (10.2.4); processing may run the caller's balance negative, storage never, a principal never. The proposed-operation shape (count per kind, total index entries) is bounded in SYSTEM_LIMITS_V9 so the estimator surface is enumerable and covered by the strategy corpus.

With those rules the pipeline supplies fees, conservation (credits move only through sum-tree roots the end-of-block check walks), proofs and error classification, because only audited native code touches GroveDB.

Out of scope: raw key-value state; contract-to-contract calls (they need a read overlay plus per-call savepoints; grovedb has RocksDB savepoints, grovedb's storage/src/rocksdb_storage/storage.rs:328-347, but no overlay; deferred, section 14); host-to-guest callbacks; unbounded output (capped by max_call_output_bytes in SystemLimits); host input beyond BlockInfo.

4.3 State model

Contract state is documents in the contract's own document types, owned by the caller and, from PV19 once the two-payer event ships (4.5), by the principal. Each reason is something raw KV forfeits: proofs (document, index, ranked and aggregate proofs already verify in every SDK); a self-describing, indexable schema via document_schemas; economics (every element carries StorageFlags::new_single_epoch(epoch, Some(owner)), document_create_transition.rs:59-60, and refunds flow through the 50-era pipeline); existing size limits.

Key [64, contract_id, 2] is free: under contract_root_path (packages/rs-drive/src/drive/contract/paths.rs:113), which is [64, contract_id], only [0] is written (the contract element, add_contract_to_storage/v0/mod.rs:79) and [1] (the documents subtree, insert_contract/v0/mod.rs:184-193); nothing writes [2]. A raw subtree there would be a third storage pattern, provable only by point reads via getPathElements until a range prove_elements exists, with no refund owner. So: no opaque scratch area, and [2] is never created and stays unreserved; a contract needing a blob uses a private document type with a byteArray property, and code lives in the hash-addressed, reference-counted RootTree::CodeBlobs store (proposed discriminant 68, section 06.2), shared across contracts rather than copied under each. CreationRestrictionMode has only NoRestrictions, OwnerOnly and NoCreationAllowed (packages/rs-dpp/src/data_contract/document_type/restricted_creation/mod.rs:10-14); OwnerOnly limits creation to the contract owner (advanced_structure_v1/mod.rs:125-128 under batch/action_validation/document/document_create_transition_action) and gates creation only. Limiting writes to the principal needs a new mode, PrincipalOnly, enforced there for create plus a replace and delete rule; section 05 records it as D1e below.

4.4 Principal model

Two keyless address spaces qualify; the section costs them instead of asserting one.

(a) Prefunded specialized balances (RootTree::PreFundedSpecializedBalances = 40, packages/rs-drive/src/drive/mod.rs:204; packages/rs-drive/src/drive/prefunded_specialized_balances/): keyless, keyed by 32-byte ids, inside the sum-tree conservation equation, unable to sign or withdraw, operation kind already in the converter set. Missing: refund routing (apply_balance_change_from_fee_to_identity_operations_v0 returns CorruptedCodeExecution when the payer has no [96] balance element, apply_balance_change_from_fee_to_identity/v0/mod.rs:65-75) and document ownership by a non-identity id.

(b) A keyless identity subtype whose id equals the contract id. Identity has one variant with public_keys, balance, revision (packages/rs-dpp/src/identity/identity.rs:45-47; identity/v0/mod.rs:38-44); every creation path demands a master key (MissingMasterPublicKeyError), so the principal is system-created with an empty key map and a balance sum item under [96, id]. It can be named in AuthorizedActionTakers::Identity (change_control_rules/authorized_action_takers.rs:26-33) and cannot sign.

Chosen: (b), because a document's owner_id is an identity id in every consumer, verifier and SDK model, and refunds on deletion route by that id to a [96] element; (a) would need a non-identity owner_id (a second address space in every consumer) plus a second refund destination in FeeRefunds and its consumers, wider than one verifier version plus SDK identity models. (a) stays the fallback if the compatibility work below slips, with entry points restricted to caller-owned writes.

Cascade, stated fully. The client-side verifier every SDK pins rejects a keyless identity: verify_full_identity_by_identity_id_v0 returns ProofError::IncompleteProof when balance and revision are present and keys are empty (packages/rs-drive/src/verify/identity/verify_full_identity_by_identity_id/v0/mod.rs:120-127), so from the first principal on chain any SDK resolving a document owner to a full identity fails proof verification, in mobile SDKs that lag the PV. The first principal can exist at PV19, not before: 10.2.2 creates it lazily in the PV19 generations of insert_contract and update_contract when entry_module is present, and transition_to_version_19 creates none; section 08 creates none when a validationModule is attached, so the date moves to PV17 only if that changes. Creation is paid by the signer of the triggering transition through a storage estimator in the PV19 FeeDataContractRegistrationVersion, its elements flagged principal-owned; there is no backfill, which would be one unpaid identity write per existing contract in a block event. A tagged SDK release is not by itself the mitigation, because builds already installed cannot be reached. The compatibility policy has three parts: a dedicated principal query and proof returning balance and revision, so a client never attempts full-identity verification on a principal; a stated minimum supported client version; and a testnet count, taken before mainnet signalling, of live client versions that would fail on a principal-owned document. Hard invariant, not a lifecycle decision: a principal's balance element is never removed, because the refund path errors CorruptedCodeExecution without it and an Err in the transition loop is InternalError. No contract-delete transition exists today (StateTransitionType ends at 20, packages/rs-dpp/src/state_transition/state_transition_types.rs:23-43), so the invariant is defensive: it binds the zero-balance case a fully drained principal already reaches, and any delete path a later PV might add.

Rejected: owner-as-principal (no separation; the owner drains escrow); group-as-principal (per-contract u16 positions cannot own documents).

Decisions section 05 must record

Section 05's D1 acceptance criterion covers the discriminator, which transitions may target a principal, the audit of key-reading validations and the balance root. Five more sub-rows are needed, cited here as D1a to D1e so later sections have identifiers to reference.

• D1a: principal id derivation (contract id reuse versus hashed), recorded in the DIP; it fixes the proof paths under packages/rs-drive/src/verify.
• D1b: the compatibility policy above, as a dedicated principal query and proof, or a new generation of verify_full_identity_by_identity_id and its by-ids variants admitting an empty key set only for registered principals, in wasm-drive-verify, js-evo-sdk, Swift and Kotlin, together with the minimum supported client version and the testnet count; those releases are a PV19 dependency, or PV17 if section 08 is changed to create a principal on validationModule attachment.
• D1c: whether a principal may hold tokens, join groups and own DPNS names, or only credits and documents; DPNS and contested resources need a rule either way.
• D1d: who may top up a principal; confirm a keyless identity can never withdraw to Core.
• D1e: add PrincipalOnly to CreationRestrictionMode with its replace and delete gate (4.3).

4.5 Fee model

• Fuel to credits: a new FeeWasmVersion sub-table on FeeVersion (packages/rs-platform-version/src/version/fee/mod.rs:34-47) carrying operator costs, CustomFuelCosts, credits_per_fuel, host call, context-byte and per-invocation module preparation costs (proportional to module size, charged on every call, because every validator prepares with a cold cache). It lands with the Phase 3 fee generation, FEE_VERSION5 at PV17. The numbering itself is not this section's to set: section 12 owns the registration mechanism and section 14.2 the values (FEE_VERSION3 to FEE_VERSION7, numbers 3 to 7, under the invariant FEE_VERSIONS[i].fee_version_number == i + 1). 04 fixes only the consequence, a halt hazard rather than bookkeeping: above number 1 the fee_version_number == 1 branch at packages/rs-drive/src/fees/op.rs:280 is not taken for PV15 and later epochs, so every SectionedStorageRemoval takes the other arm, where a None previous_fee_versions is CorruptedCodeExecution (op.rs:291), an Err inside a block event. 37 apply_drive_operations call sites in packages/rs-drive-abci/src pass None today (33 outside test modules), block events included; auditing all of them and a test that every block event runs with Some are gates of the PV that first registers a number above 1, listed here rather than left to section 12 follow-ups.
• Admission affordability, the rule that makes every guest outcome paid. Hooks never run in check_tx (should_validate_batch_valid_against_state is false for CheckTx and RecheckTx, batch/mod.rs:48-54); a Batch's only mempool balance check is validate_estimated_fee (min fees, purchases, collateral; packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/state_transition_estimated_fee_validation.rs:31; document_batch_sub_transition is 100000 credits, fee/state_transition_min_fees/v1.rs:8). In the block, a shortfall in validate_fees_of_event (the Paid arm's comparison at v0/mod.rs:145-163) is UnpaidConsensusExecutionError (execute_event/v0/mod.rs:101-104): stripped and rolled back (process_raw_state_transitions/v0/mod.rs:225-240), no fee, no nonce bump, the same bytes valid next block. So validate_identity_minimum_balance_pre_check for Batch (processor/traits/identity_balance.rs:57-59, run in check_tx_verification/v0/mod.rs:241 and processor/v0/mod.rs:180, both modes) requires balance >= min fee + credits(max_fuel) for a hook-bearing type, where max_fuel is that type's declared validationModule.maxFuel, bounded at parse time by max_hook_fuel_per_call and never clamped at run time, so mempool and block cannot disagree on affordability (08.2.3); for entry points the term is the transition's required max_fee, bounding the whole call across both payers (10.2.1). gas_wanted (today total_base_fee, abci/handler/check_tx.rs:66-70) includes that ceiling. The post-execution check reconciles actual fuel only. Data-trigger query costs have the same shape at a smaller magnitude (batch/data_triggers/triggers/dpns/v1/mod.rs:265-278).
• Entry-point ceiling: registration-declared, static and contract-level. max_fuel, maximum proposed operations and the capability set sit in one MethodDecl { name, max_fuel, max_operations, capabilities } per method inside the contract's EntryModule (4.7, 10.2.1); the read footprint rides the transition. Execution charges actuals; exceeding any declared maximum is a paid trap; changing a declaration is a DataContractUpdate under change_rules, restricted at PV19 to ContractOwner and NoOne (10.2.8).
• Block budget: fuel is processing credits, so section 06's max_block_processing_credits in SYSTEM_LIMITS_V5 is the fuel budget and no separate fuel budget exists. Before invoking a guest the loop adds the transition's pre-computed bound (the instantiate, translate, memory, context and fuel terms of 08.2.6), not its actual, to the running total; over budget yields NotExecuted (TxAction::Delayed, prepare_proposal.rs:236, already an arm of the exhaustive rollback match at v0/mod.rs:252-262), and validators reject an over-budget proposal through the failed_count gate (process_proposal.rs:278). The proposer-only wall clock proposer_tx_processing_time_limit (abci/config.rs:39) is node-local and no substitute. Tenderdash max_gas (57631392000, packages/dashmate/configs/defaults/getBaseConfigFactory.js:436) and the credits budget derive from one constant with a test; gas_wanted at the ceiling makes reaping conservative (under-fill, never over-fill) and Drive's check is authoritative. The other two SYSTEM_LIMITS_V5 fields section 06.1 adds, max_state_transitions_per_type_per_block and max_state_transition_processing_credits, bound what one funded identity can do to proposer time in a block. Worst case from the plan's constants (8M credits per ms, drive_abci_validation_versions/v10.rs:338-343; 5 ms entry-point target, section 03.10; 40e9 credit budget, section 06): about 5 s plus one 5 ms overshoot per block on the hardware class that pins the rate, the whole minimum block interval; section 06 owns the value, section 12's bench the rate.
• Failure charging: reject, trap and out-of-fuel attach BumpIdentityDataContractNonce and execute as StateTransitionExecutionResult::PaidConsensusError, built at process_validation_result/v0/mod.rs:126-132 on the paid path that opens at :41; gas_used is not a field of that variant but is set on conversion to ExecTxResult, from actual_fees.total_base_fee() (packages/rs-drive-abci/src/abci/app/execution_result.rs:32-39). With the bound checked at admission and again against the signer's balance before instantiation, no guest outcome is Unpaid; the post-execution check can fail only through the pre-existing under-estimate class, which 4.2's actual-cost rule closes for entry points.
• Payer. There is no two-payer charge path today: paid_from_identity_function charges one identity (execute_event/v0/mod.rs:81-87) and ExecutionEvent::Paid carries one removed_balance (execution/types/execution_event/mod.rs:28-34). PV19 adds the execute_event generation that splits the FeeResult by owner and writes two balances, both checked in the dry run and after apply. The PV19 rule (10.2.2): the acting owner named on a proposed operation is both the per-action validator's owner_id and the StorageFlags owner of storage that operation creates, so a deletion refunds whoever paid; the caller pays processing (fuel, reads, validation, the nonce bump) plus storage of its Caller operations, the principal pays storage of its Principal operations, a caller never funds principal-owned bytes (so a contract cannot harvest a caller's storage fee by writing and deleting), and a negative balance is forbidden for a principal. No principal-owned write is possible before that event exists, so the Principal tag (4.2) ships with it rather than ahead of it; section 12's open "Storage refund attribution" paragraph closes on this rule. Identifier::default() is forbidden as owner: it routes removals to removed_bytes_from_system with no refund (op.rs:276-279).

4.6 Determinism and error model

Classification is defined at the wasmi Error boundary, not by intent. Every error returned from the instance call (all TrapCode variants, including OutOfFuel, StackOverflow and MemoryOutOfBounds, and every host-raised error from an import) is guest-attributable and, with Reject(code), maps to one new paid StateError::ValidationModuleError carrying contract id, document type, document id and the kind that names it: Rejected { code }, Trapped { kind }, OutOfFuel { budget }, InvalidResult, PrepareFailed { rule } or ModuleUnavailable { reason } (exhaustive table at 08.2.7). Host imports never return Err for argument problems (out-of-range pointer, oversized length, repeated call, undeclared capability); they return a status the guest sees or raise a trap. The only Err channel is HostFault, a closed enum reached before or outside guest entry (module bytes missing for a declared hash, engine construction, allocation failure), unreachable by anything a module or its author does; a module failing re-preparation under a new engine is frozen (4.7), not Err. StateError is append-only (packages/rs-dpp/src/errors/consensus/state/state_error.rs:77-81); the module block is 41000 to 41099, past the 40900 shielded block and clear of the 40500 data-trigger block (codes.rs:406-411), and section 12 allocates the Phase 1 and Phase 2 blocks in the same place so the earlier phases cannot collide with the later ones. No execution result variant is added, so the proposer rollback match (process_raw_state_transitions/v0/mod.rs:225-264) is untouched.

Statically rejected in the prepare pass: float instructions, SIMD, threads and atomics, multi-memory, start sections, imports outside the versioned host namespace, exports beyond the fixed entry names, anything off a fixed allowlist, and any module whose declared memory maximum, table size or byte size exceeds the PV17 hook limits in SYSTEM_LIMITS_V7 (max_hook_code_size, max_hook_memory_pages, in the tens, max_hook_table_elements, max_hook_fuel_per_call, max_distinct_modules_instantiated_per_block), plus consensus recursion depth and stack height. The same values go through Config::enforced_limits, set_max_recursion_depth and set_max_stack_height, so the trap point is consensus data rather than an engine default and no limiter consults host RAM. CompilationMode::Eager is pinned in the PV table so validation errors surface in prepare on every node. Float document properties: the parser admits DocumentPropertyType::F64 ("f64" | "number", packages/rs-dpp/src/data_contract/document_type/property/mod.rs:170,196) and Value::Float(f64) exists (lib.rs:136); DocumentWire carries such a property as the eight big-endian bytes of f64::to_bits, an infallible conversion that drops nothing, and the guest SDK exposes bitwise equality only, no arithmetic; fixed as part of the abi 0 HookContextV0.

Fuel drift: the 2.0.0 changelog calls fuel metering stable because it is tied to the input Wasm bytecode (#2013), and in the same entry qualifies it as less precise but "relatively stable", the same wording the beta.10 entry uses; either way the pin is exact, the differential fuel corpus (section 11) runs against every candidate revision before a pin bump, and every engine bump or FeeVersion recalibration is a PV event. Fee tables are additive per FeeVersion (a PV adds operators, never raises an existing operator's cost), and per-call caps are re-derived at each bump so the corpus's worst-case fuel ratio keeps every previously passing corpus module under cap. Replay from genesis (packages/rs-drive-abci/src/replay/runner.rs:226-275 is a consensus tool) requires every activated engine major to stay linked in the binary and to be selected by the PV active at the replayed height. The precedent is stellar-core, which embeds two full copies of the host dependency tree and switches at a protocol upgrade (CAP-0046-01 item 5); extending that to one vendored wasmi-engine-v<N> package per activated pin under packages/rs-contract-runtime/engines (proposed, section 11) is this plan's own proposal, done by no deployment examined here and carrying no retirement rule, so the linking obligation and its replay cost belong in section 14's risk register. No node-local flag may gate hook execution; execution.use_document_triggers (packages/rs-drive-abci/src/config.rs:92-93) is the anti-pattern section 08 retires; the freeze documents (4.2) are the stop that needs no PV.

Invariants to encode as tests

• Add an rs-drive-abci test asserting every guest outcome maps to a paid consensus error, never InternalError or Unpaid, gated at PV17, with a fuzz over import arguments (pointer, length, repeat calls, undeclared capability) under the same assertion.
• Add a check_tx test: a transition affordable for its base estimate but not for base plus the declared max_fuel is rejected at admission, never executed and stripped.
• Add a prepare-pass corpus in packages/rs-contract-runtime (proposed) rejecting each forbidden feature with a distinct error, plus a grow-to-limit module and a deep-recursion module with expected fuel and trap codes.
• Add a strategy test under packages/rs-drive-abci/tests/strategy_tests running a hook corpus against golden root hashes (test_cases/identity_and_document_tests.rs:438 pattern), covering: a proposed set whose actual storage exceeds its estimate never yields InternalError; a failing proposed operation applies none of the list; a target-type predicate rejects a proposed write; the caller's contract nonce advances exactly once per transition; a principal's balance element survives being drained to zero; a frozen module returns its fixed paid code.
• Add a test deriving Tenderdash max_gas and max_block_processing_credits from one constant.

4.7 Versioning

• ABI marker: each module carries a custom section with a single zero-based abi_version (0 predicates, 1 reads, 2 entry points, deliberately one behind the dash_v<n> namespace number); there is no minor field. Registration rejects versions outside the PV's accepted range and imports from namespaces the PV does not grant (Soroban CAP-0046-01 pattern). Checked at link time in prepare, never at execution, so an activated module cannot fail to link after a PV bump unless the PV retires its version. Behaviour is a separate promise: an engine pin change re-prepares each referenced blob lazily, at the first transition that needs it after activation and at that transition's expense (08.2.7; no first-block sweep, whose cost would grow with adoption and whose Err would halt the node), and one that fails is marked failed_under (every hook on it returns ModuleUnavailable { TranslationFailed }, paid; writes on that type reject and deletes proceed, 08.2.5) rather than Err; fuel for existing operators cannot rise (4.6), and declared max_fuel values are untouched by a PV bump.
• Host namespaces are versioned and additive, one per grant generation: dash_v1 (Phase 3 context imports), dash_v2 (Phase 4 footprint reads), dash_v3 (Phase 5 emit). A function is never changed in place and no namespace is named after a capability; the grant rides the module's declared capabilities vector against a per-PV allowlist in the version tables, so the check stays static.
• Placement: the exact engine revision as wasm_engine_version on DriveVersion, beside grove_version; CompilationMode::Eager and the accepted abi_version range in a new drive_abci sub-table; prices in FeeVersion; caps in SystemLimits; the writer set of the freeze documents (section 11.2.6) as a PV-gated rule in the same sub-table; section 05 decides against a top-level PlatformVersion field.
• Two declarations, two generations, because they sit on different objects. A document type's validationModule (code hash, abiVersion, maxFuel, parsed into ValidationModuleRef) rides the meta-schema generation mechanism, because document types are rebuilt from their schema Value on every load through create_document_types_from_document_schemas (packages/rs-dpp/src/data_contract/v1/serialization/mod.rs:91 for V0 input, :155-167 for V1): this plan proposes meta-schema v6, try_from_schema generation 6, DocumentTypeV5 and CONTRACT_VERSIONS_V9 at PV17, three generations past PV14's meta-schema v3, try_from_schema v3, DocumentTypeV2 and CONTRACT_VERSIONS_V6 (section 14.2 allocates the two in between to PV15 and PV16). The contract-level entry_module (methods with their max_fuel, max_operations and capabilities, plus change_rules, pause_rules and paused) is not on the document type at all: it rides a proposed DataContractInSerializationFormatV2 and DataContractV2 under CONTRACT_VERSIONS_V10 at PV19 (10.2.1). Update policy follows the split: validationModule is immutable once attached, and an update may attach a module only to a type it adds (08.2.3); entry_module is governed by ChangeControlRules, restricted at PV19 to ContractOwner and NoOne (10.2.8).
• Per-node module cache: keyed by code hash plus wasm_engine_version, so it never serves bytes prepared under another PV; a cost optimization, never consensus-visible, and the per-invocation preparation cost (4.5) is charged whether or not it hits.

4.8 Worked example: a guarded "listing" document type

The predicate seam sits right after data triggers in validate_state_v0 (batch/state/v0/mod.rs:317-322):

flowchart TD
  A[Batch ST bytes] --> B[check_tx: balance >= min fee + credits of declared max_fuel]
  B --> C[decode, is_allowed, signatures, nonces, structure]
  C --> D[transform_into_action: contract fetch, schema validation]
  D --> E[validate_state_v0: per-action state checks, data triggers]
  E --> G{{HOOK SEAM: validation module}}
  G -- accept --> H[ExecutionEvent::Paid]
  G -- reject, trap, out of fuel --> I[BumpIdentityDataContractNonce + ValidationModuleError]
  I --> H
  H --> J[validate_fees_of_event, apply, charge]

Loading

Guest sketch (names illustrative):

// SKETCH. Invariant: price > 0, quantity > 0, and a replace
// may not raise price by more than ten percent.
#![no_std]
use dash_contract_sdk::{hook, Action, HookContextV0, Reject};

#[hook(predicate)]
fn listing_guard(ctx: &HookContextV0) -> Result<(), Reject> {
    let new = ctx.new_document().ok_or(Reject::code(1))?;
    let price: u64 = new.get("price")?;
    let quantity: u32 = new.get("quantity")?;
    if price == 0 || quantity == 0 {
        return Err(Reject::code(2));
    }
    if ctx.action() == Action::Replace {
        let old = ctx.old_document().ok_or(Reject::code(3))?;
        let old_price: u64 = old.get("price")?;
        if price > old_price.saturating_add(old_price / 10) {
            return Err(Reject::code(4));
        }
    }
    Ok(())
}

Host sequence for a DocumentReplace:

1. Admission: check_tx requires balance >= min fee + credits(max_fuel) for the hooked type, using that type's declared validationModule.maxFuel (4.5); nothing below runs otherwise.
2. validate_state_v0 reaches the surviving ReplaceAction; the parsed DocumentTypeV5 carries a ValidationModuleRef { code_hash, abi_version, budget }; the freeze gate runs its three point reads through the block transaction (4.2); the host loads the bytes from RootTree::CodeBlobs through the per-node cache keyed by code hash plus wasm_engine_version and charges the preparation cost.
3. The host builds HookContextV0: kind, contract id, document type, owner id, BlockInfo, new data (DocumentReplaceTransitionActionV0.data) and the original document the batch transformer already fetched (rs-drive document_replace_transition_action/transformer.rs:20); the seam must sit where that original is in scope, or the action must carry it.
4. The context is bincode big-endian encoded and charged per byte; fuel is set to the declared budget, bounded at parse time by max_hook_fuel_per_call and never clamped here, so mempool and block price the same run; the guest reads it through the two dash_v1 imports, whose argument errors are a status or a trap, never Err, and returns a status word.
5. Fuel used is converted with the PV17 fee table's FeeWasmVersion credits_per_fuel and pushed with execution_context.add_operation; accept leaves the action in place, while reject, trap or out-of-fuel pushes BumpIdentityDataContractNonce plus StateError::ValidationModuleError and the transition proceeds as paid.

---

---

Continued in part 5 of 14 below.

[QuantumExplorer]

Part 5 of 14 of the plan (continued from part 4 above).

5. Phase 0: decisions, DIP, and groundwork

Phase 0 ships no protocol version: it produces the design DIP, seventeen decisions, a tracking issue, one fee-version registry PR (a Phase 1 merge gate) and documentation fixes.

Reasoning

Phases 1 to 5 ship separately but share one guest ABI, one fee flow, one compute budget and one mempool policy, which cannot be staged. The trap is a Phase 3 v0 ABI that encodes "no state access": no footprint field, no capability imports, a per-call fuel cap as the only DoS bound. Retrofitting reads in Phase 4 then changes three consensus surfaces in one protocol version: the fee model (the affordability dry run at packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/validate_fees_of_event/v0/mod.rs:102-163 prices only the reads implied by the pre-declared operation set, seek and loaded-byte costs plus the fixed fetch_* processing costs, carries no per-read charge for reads a guest chooses at run time, and ignores refunds, TODO at :138), the mempool (check_tx skips batch state validation, state_transitions/batch/mod.rs:47-55, so gas_wanted would understate cost), and the ABI itself.

Two pipeline properties make several decisions structural. Any Err from state transition processing becomes StateTransitionExecutionResult::InternalError (process_raw_state_transitions/v0/mod.rs:343-361), process_proposal then rejects the whole block (packages/rs-drive-abci/src/abci/handler/process_proposal.rs:283-308), and the proposer-side rollback (process_raw_state_transitions/v0/mod.rs:108-135) strips the transition only from that proposer's mempool, so every other proposer repeats it; today only hand-written code reaches that path, with user code any contract author does. And the chain has already halted on an estimate-versus-apply fee gap (mainnet 415652, :115), so every new tree, price and refund path needs an estimation entry and a parity test in the PR that introduces it.

Nothing exists to build on: a search of dashpay/platform issues, pull requests and discussions on 2026-09-07 found no design, issue or PR for this work (the only pull requests matching "smart contract" are documentation PRs #3276 and #3312), and CLAUDE.md:96-100 forbids committing design documents, so the DIP lives in dashpay/dips.

Design

Each decision is a tracking-issue comment (section 14) with fields Status, Context, Options (cost, consensus surface, first affected phase), Decision, Consequences and Reversibility (protocol version and files a reversal touches), folded into the DIP Rationale and "Considered and Deferred" sections (dip-0033.md structure); a reversal is a new superseding record. Names used below are the plan's committed names, which D10's table fixes; a later section needing a new name adds it there rather than coining one in place.

ID	Decision	Owner role	Inputs	Output	Acceptance criterion
D1	Principal model: keyless identity subtype, deployer-owned or a new principal type, and the id derivation	Consensus lead	Identity creation requires a MASTER key (validate_identity_public_keys_structure/v0/mod.rs:101-108, MissingMasterPublicKeyError); signature validation reads keys by id (validate_state_transition_identity_signed/v0/mod.rs:140-157)	DIP "Contract principals"	Discriminator named (identity id equals contract id, or a flag in the identity element) and the derivation fixed. Yes or no per transition that may target a principal (IdentityCreditTransfer in: escrow-style contracts need it; IdentityCreditWithdrawal and key-add: paid consensus errors) or originate from one (none signs; every principal action is host-initiated inside the caller's transition, and the nonce and revision rule for a never-signing identity is stated). Every existing validation that reads identity keys is listed with its behaviour on a keyless identity and a test; none may return Err. Balance stays in the [96] sum tree, so the conservation equation (calculate_total_credits_balance/v2/mod.rs:19-80) gains no term.
D2	State model and write authority: documents only, no raw scratch subtree	Drive lead	Every element carries StorageFlags::new_single_epoch(epoch, Some(owner)), refunding through the 50-era pipeline (PERPETUAL_STORAGE_ERAS, packages/rs-dpp/src/fee/epoch/mod.rs:49; re-export at packages/rs-drive/src/util/storage_flags.rs:1-3); insert_contract/v0/mod.rs:173-193 writes only [0] (through add_contract_to_storage/v0/mod.rs:79) and [1] under [64, contract_id], adding estimation entries per tree (:201-209); CreationRestrictionMode has only NoRestrictions, OwnerOnly and NoCreationAllowed (document_type/restricted_creation/mod.rs:10-14)	DIP "State"	Contract state is documents in the contract's own document types (04.3): no opaque scratch area, and [64, contract_id, 2] stays uncreated and unreserved, since code blobs live in the proposed RootTree::CodeBlobs (06.2), shared and reference-counted rather than copied per contract. Recorded: (a) that policy, with the rejected raw subtree (provable only by point reads through getPathElements, no refund owner) written down; (b) for each tree PV15 does add, the creating PR adds its estimated_costs_only_with_layer_info entry and a test asserting estimated storage fee >= actual for the first write; (c) whether restricting writes to the principal needs CreationRestrictionMode::PrincipalOnly plus replace and delete rules, which 04.3 delegates here, and its PV; (d) credits never enter [64] and no sum tree sits under a contract root, so the conservation check keeps walking only the five root sum trees (96, 40, 48, 56, 52).
D3	Fee flow: bound computed before execution, actuals charged once after	Fees owner	validate_fees_of_event/v0/mod.rs:102-163 estimates with apply=false, then execution applies; the dry run prices GroveDB seek_count and storage_loaded_bytes (packages/rs-drive/src/fees/op.rs:1598-1634) plus the fixed fetch_* costs of FeeProcessingVersion (fee/processing/mod.rs:7-17) and ignores refunds (:138); FEE_VERSIONS holds only FEE_VERSION1 (fee/mod.rs:32), FeeVersion::get indexes by number minus one (:53-63), FEE_VERSION2 carries number 1 (fee/v2.rs:12-13) and the epoch map compares numbers (upgrade_protocol_version/v0/mod.rs:99-113), so the PV9 switch was never recorded and as_static() resolves FEE_VERSION2 to FEE_VERSION1	DIP "Fees"; section 12 baseline	Consensus rules in order: (a) the bound B is computed before execution from bytes and committed state (08.2.6 fixes the formula), at or above the transition's minimum fee; (b) no balance moves before execution: the check compares live balance minus operations already accrued against B, and a shortfall is InsufficientBalanceForHookExecution, paid at the affordable minimum with the nonce bumped and no instantiation; (c) the guest runs under a meter (fuel, host-function costs, storage bytes at the storage-table price) aborting deterministically the instant it would exceed B, as a paid consensus error charging the bound consumed, so no over-bound class exists; (d) the balance is written once after execution at the actual charge, provably at most B: no remainder to credit back, no escrow element in state, no refund code, and pool aggregation (process_proposal.rs:282-283) reads only that charge. Payer (caller or principal) fixed for processing, storage and refunds. Adapter signature Result<GuestOutcome, ConsensusError>: the adapter is the only place Error may be constructed, restricted to storage-layer failures (RocksDB, GroveDB CriticalCorruptedState); every trap kind, host-function failure, fuel exhaustion, memory growth failure and malformed proposed operation is an enumerated ConsensusError with a paid outcome. Gate before Phase 1 merges: the fee-version registry PR lands on v4.2-dev. Section 12 owns the numbering and 14.2's table records what the rest of the plan cites, so this register restates none; that PR carries the index invariant test (each entry's number equals its 1-based index, every PlatformVersion's fee_version resolving through FeeVersion::get), the as_static() caller inventory pinned as known and permitted (one caller, block_processing_end_events/tests.rs:866), a replay test across the PV boundary through previous_fee_versions, and, if a number in use since PV9 changes, an audit of the apply_drive_operations sites passing previous_fee_versions: None (44 of 55 in packages/rs-drive-abci/src), since op.rs:280-292 then returns CorruptedCodeExecution for any SectionedStorageRemoval and halts the node.
D4	Events: provable receipts versus explicit punt (clients prove affected state only)	SDK lead with drive lead	packages/rs-dpp/src/state_transition/proof_result.rs:23-155	DIP "Events and receipts"	Per phase: what a client can prove about one execution and which variant carries it; a punt reserves an ABI event slot and names a revisit phase.
D5	Permissioning and freeze	Product owner with consensus lead	is_allowed expresses only "active at PV N" (processor/traits/is_allowed.rs:52-100); 11.2.6 owns the kill-switch layers, 11.2.5 the engine-upgrade runbook	DIP "Deployment permissions and freeze"	The deployer allowlist on the proposed ContractGovernance system contract (a ChangeControlRules document) versus open deployment: who edits it, how an edit is proven, at which PV deployment opens; list changes need no PV. The kill switches are exactly 11.2.6's four layers (per-PV OptionalFeatureVersion disable, the operator-side proposer denylist, the on-chain frozenGuard, frozenModule, frozenContract and globalFreeze documents, the allowlist). The denylist is the one admitted node-local switch: it is consulted only while proposing and never by a validator, so it decides which transactions a proposer includes and can never diverge state, which is what 04.6 and 11.3 forbid; no other node-local switch joins them. The circular case, a contract whose transitions stop blocks committing and so stop the freeze write, cannot arise from guest code under D3's adapter rule; it is a host bug, and it has two shapes with two answers (11.2.8). A host fault inside a signed call is skipped by the denylist on the transaction path until the fixed binary lands. A host fault inside the scheduled drain (10.2.6), a block event that runs before the transactions of every block, empty blocks included, is reached by no denylist and no freeze write, and goes straight to 11.2.5's coordinated binary behind a network-keyed activation height, which D6 rehearses with a faulting queue entry. Recorded: freeze versus unfreeze thresholds, key-holder set and rotation, globalFreeze expiry.
D6	Expedited path for engine security patches	Release manager with consensus lead	No expedited vote exists. Precedents: in-place rewrite of a shipped PV (PR #2397 re-pointed PV7 at DRIVE_ABCI_VALIDATION_VERSIONS_V5, version/v7.rs:40); testnet-only epoch-index flag day (PR #2134, check_for_ended_vote_polls/v0/mod.rs:60-65); a one-off 51 percent threshold for the PV3 emergency upgrade (check_for_desired_protocol_upgrade/v0/mod.rs:17-30); normal threshold 67 percent (drive_abci_method_versions/v2.rs:53)	DIP "Security Considerations" runbook	Covers only patches that change neither fuel accounting nor module validation (anything else is a PV bump under D13), proven by a fuel-parity test of patched versus unpatched engine over the strategy-tests corpus. Runbook in order: day zero is the 11.2.6 on-chain freeze (by code hash, or globalFreeze if the class is unknown), whose latency is bounded by the run of proposers that decline to include it rather than by consensus; then the non-consensus hotfix under 11.2.5's diff-scope rule; then a normal 67 percent PV (9 to 18 days at 788400 s epochs). A chain already halted has neither, so this record also decides whether Phase 1 builds the network-keyed activation-height table 11.2.5 says the tree lacks, and how it is rehearsed.
D7	Code-blob channel: chunked upload versus raising max_state_transition_size	drive-abci lead	20480 cap (system_limits/v4.rs:23) coupled to Tenderdash max-tx-bytes (packages/dashmate/templates/platform/drive/tenderdash/config.toml.dot:389); StorageFlags carry one OwnerId	DIP "Code storage"	Chunked: manifest first (final hash, total size, chunk count) as a priced transition; chunks keyed by (manifest id, index), immutable once written; a completion transition paying for hashing and validation in proportion to size, failing as a paid consensus error on mismatch; a SystemLimits bound on open manifests per identity; deterministic expiry (epoch-based in a block-end event with a per-block cap, or lazily on that identity's next write) that deletes chunks and refunds through StorageFlags; a dedup policy naming the refund owner. Raise: lists every coupled config. Either way bytes are provable via getPathElements.
D8	check_tx and mempool policy per phase	drive-abci lead	Batch check_tx never runs validate_state (check_tx_verification/v0/mod.rs:278-341, batch/mod.rs:47-55); gas_wanted = total_base_fee in credits (abci/handler/check_tx.rs:66-70); priority = user_fee_increase times 100 (execution/check_tx/v0/mod.rs:32, :149-152)	Table in DIP "Mempool"	Per mode (CheckTx, RecheckTx, Validator) and phase: which stages run and what gas_wanted contains; section 09's table maps ERC-7562's validation-phase rules (OP-011, STO-010, STO-021) to PV18 mechanisms or records each departure. A transition that produced InternalError is evictable network-wide (RecheckTx fails it), since the proposer-side strip is local. No per-identity reservation ledger is kept in the mempool: check_tx stays a cheap prefilter pricing one transition against the last committed balance, and the affordability floor is enforced inside the block immediately before the guest runs (11.2.3), so K transitions on one balance cannot leave K-1 runs as processing debt the pools never receive. No execution-affecting hook configuration lives in PlatformConfig or AbciConfig (packages/rs-drive-abci/src/config.rs:130, abci/config.rs:11).
D9	PV numbering and host branch	Release manager	PV15 does not exist (three-file PR, #4267); no v4.3-dev or v5.0-dev on origin	Tracking issue header	One PV per phase (PV15 to PV19, section 14.2); dev branch named.
D10	Naming: crates, transitions, keywords, limits, error-code blocks	Consensus lead	Every Rust crate lives at packages/rs-<name> while its Cargo package name drops the prefix (packages/rs-dpp is dpp, packages/rs-drive is drive, packages/rs-sdk is dash-sdk); StateTransitionType is repr(u8) 0 to 20 and variants append	Names table in the DIP	One name per new crate (directory form for workspace members and task targets, published package name for what an author depends on), transition variant, schema keyword, SystemLimits field, host namespace, generation number and error-code block, used identically in sections 6 to 13. It allocates all four error-code blocks at once, so Phase 1 and Phase 2 codes cannot collide with the Phase 3 and Phase 5 blocks, and fixes the section 14 question numbers other sections cite.
D11	Threat model	Security lead	Section 11; no SECURITY.md exists in the repository	Tracking-issue threat register; DIP "Security Considerations"	Every entry carries attacker capability, concrete sequence, consensus surface (fee, mempool, app hash, liveness), owning phase, mitigation and test name; the Tasks list below is the initial population.
D12	Per-block compute budget and gas	drive-abci lead with fees owner	Validators re-execute with no timer (process_proposal.rs:235-241 passes proposing=false); the proposer limit is node-configured and proposer-only (AbciConfig::proposer_tx_processing_time_limit, abci/config.rs:37-39, gated at process_raw_state_transitions/v0/mod.rs:149-157); dashmate genesis sets Tenderdash block max_gas 57631392000 (packages/dashmate/configs/defaults/getBaseConfigFactory.js:436) against summed gas_wanted at proposal time, so a credits-denominated budget exists on the mempool side and nothing bounds actual execution on the validator path	DIP "Compute budget"	For hook-bearing transitions gas_wanted equals the pre-execution bound B (max_fee for ContractCall at PV19), and the relation between max_gas and credits is written down. SYSTEM_LIMITS_V5 gains max_block_processing_credits and max_state_transition_processing_credits, in metered processing credits, with fuel converting into the same number at credits_per_fuel from PV17, so no separate fuel budget exists; section 06.1 owns the values and enforcement points, and an over-budget block is rejected in process_proposal (a PV-gated consensus rule). The per-call fuel ceiling is separate and arrives with the engine: max_hook_fuel_per_call in SYSTEM_LIMITS_V7, derived from the block budget in 08.2.6. Calibration is a documented benchmark on D17's profile with a margin keeping a full budget under the Tenderdash propose timeout on the slowest supported masternode.
D13	Engine version pinning and replay	Consensus lead with release manager	PlatformVersion already carries fee_version, drive and drive_abci per PV (packages/rs-platform-version/src/version/protocol_version.rs:38-47); Cargo.lock has no wasmi entry today	DIP "Engine versioning"	wasm_engine_version is a DriveVersion field beside grove_version; multiple engine versions link simultaneously (vendored packages under distinct names) for as long as any block in history needs them; each stored module records the PV it was validated under; an engine patch that changes fuel or validation behaviour is by definition a PV bump; a replay test re-executes a Phase 3 block across an engine bump and matches the app hash.
D14	Tenderdash threshold-recovery behaviour for vote extensions	Consensus lead	Withdrawals use VoteExtensionType::ThresholdRecoverRaw (platform_types/withdrawal/unsigned_withdrawal_txs/v0/mod.rs:162-169); verify_vote_extension rejects any precommit whose extension set differs from the local expectation (abci/handler/verify_vote_extension.rs:70-85); verify_and_match_with_vote_extensions returns None when the commit's extension count differs from the withdrawal count (unsigned_withdrawal_txs/v0/mod.rs:59-61) and finalize then fails with VoteExtensionMismatchReceived (finalize_block_proposal/v0/mod.rs:143-155); Tenderdash changes are out of scope (section 01 non-goal 7)	DIP "Oracle feeds"; tracking-issue comment	Two behaviours established by reading dashpay/tenderdash and reproducing them on a devnet, each recorded with the code path observed: whether a ThresholdRecoverRaw signature is recovered from a strict subset of precommits and at what threshold, and whether the block still commits when recovery fails. Section 06.4's signed-feed upgrade ships only if both are yes; the on-chain median ships either way. Due before the Phase 1 stack opens, since 06.4 branches on it.
D15	SDK and developer-tooling commitment	Product owner with SDK lead	Section 03.3's bill of materials (host crate and ABI, module validation, the advisory process, the published guest crates and CLI of section 13, hook-aware decoding in js-evo-sdk, wasm-drive-verify, Swift and Kotlin); ink! plus pallet-contracts halted in January 2026 when funding failed	Tracking-issue comment; DIP "Rationale"	Named owner, engineer count and funded duration covering dash-contract-sdk, dash-contract-sdk-macros, dash-contract-testutils, the dash-contract CLI and the client-side decoding work, recorded beside the other decisions (section 01 goal 6). Go or no-go rule from 03.3's verdict: if the budget is not committed when the Phase 3 PV-opening PR is raised, Phase 3 does not start and the plan terminates after Phase 2. Section 13's Decisions block carries the same date.
D16	Engine stewardship: fork-and-freeze versus co-sponsorship	Release manager with consensus lead	wasmi has one maintainer and its sponsorship ends in October 2026 (external engine facts, 2026-09-07); wasmi 2.0.0 shipped 2026-09-01 with no patch release yet and the 1.0 line needed 1.0.4 through 1.0.9 within nine weeks (wasmi CHANGELOG); every activated pin stays vendored under its own package name (11.2.5)	DIP "Engine versioning"; tracking-issue comment	One of: co-sponsor upstream, fork and freeze under Dash maintenance, or the wasmtime plus finite-wasm alternative (14.7 question 4), with the maintenance obligation costed: who reviews each upstream security fix against 11.2.5's diff-scope rule, and who owns the fork if the maintainer leaves. The same record fixes section 01.1's bake criterion, the months a candidate pin runs under section 13's harness and the 03.11 differential corpus before the Phase 3 PR takes the dependency. Due by October 2026 and in any case before the Phase 3 stack opens.
D17	Reference and minimum evonode hardware profile, and the evonode cost report	Infrastructure lead with product owner	This repository publishes no minimum spec (11.2.3); credits_per_fuel is calibrated on a named machine whose CPU model and single-thread score sit in the bench crate README (section 12); 02.2.7 item 3 adds a minimum-memory line, since a module at the memory cap that instantiates on most validators and fails allocation on the rest is Err on those nodes only	Published hardware profile; DIP "Security Considerations"	A minimum evonode profile (single-thread floor, memory floor, arm64 and amd64) and a reference profile calibration measures against, in a venue operators read. Every wall-clock criterion cites it (11.2.3's one fifth of timeout.propose, section 12's credits_per_fuel bench, section 13's full-budget block), so it is due before the Phase 1 calibration lands. The same record carries the evonode cost report 14.6's risk mitigation names: the storage and CPU delta a hook-executing node pays, the change to the processing and storage fee mix, and which applications each phase unblocks, since masternodes must signal for a feature that raises their own costs.

Tasks

Design DIP (dashpay/dips)

• Draft dip-<alias>-platform-smart-contracts.md (a new file in dashpay/dips): <pre> header (Chain: Platform, Type: Standard, Status: Proposed, Requires: 11, 30), the dip-0033.md section order including "Considered and Deferred", asterisk bullets, markdownlint-cli2 and cspell clean. Authors must not self-assign a number (dips README, BIP 2 workflow), so the alias filename carries the work until the editor assigns one; the highest merged DIP is 31 and dip-0033.md is claimed by dips PR chore(dashmate): update tenderdash to 0.7.0-dev #188.
• Decide one Standard DIP versus two, consensus plus ABI (precedent for splitting one feature: DIP-17 derivation and DIP-18 encodings, both Type: Standard); recommendation: one now, the ABI DIP (also Standard, since clients implement it) when section 8 freezes the guest interface.
• Open the tracking issue on dashpay/platform with the decision register, the PV per phase (D9) and the consensus change label.

Decision records

• Record D9, D10 and D11 at Phase 0 close.
• Record D1, D2, D3, D7, D12, D13, D14 and D17 before the Phase 1 design review (D14 before Phase 1b's, which it gates) (principal derivation, state model and tree-creation policy, the pre-execution bound, the code-blob channel, the compute budget, the engine field, the Tenderdash evidence, the hardware profile).
• Record D4, D5, D6 and D8 before the Phase 3 design review (context struct, freeze layers, patch runbook, gas_wanted); record D15 and D16 no later than the Phase 3 PV-opening PR, with D16 due by October 2026.

Naming and repository hygiene

• Add a contracts scope to .github/workflows/pr.yml and a CODEOWNERS row for the crates D10 names.
• Open the fee-version registry PR from D3 on v4.2-dev (array membership, the index and caller-inventory tests, the previous_fee_versions: None audit, the replay test); section 12 owns its content and Phase 1 cannot merge before it lands.

Stale documentation (one docs PR on v4.2-dev)

• README.md:49-50, :63 and book/src/platform-comparison.md:38-39, :48-49: "planned for Platform v4.0 (targeted for mainnet in 2027)", "Coming in v4.0", "VM planned for v4.0"; cite the roadmap milestone dash.org listed when this was checked on 2026-09-07 (v5.0, Q1 2027, tentative) and the DIP.
• book/src/introduction.md:204 ("protocol version 12 (as of v3.0.1)") and book/src/versioning/platform-version.md:61-95 ("twelve versions"): the tree is at 14.
• book/src/state-transitions/lifecycle.md:30-49, :83-98, :250-261: 15 variants listed; the wire enum has 21 (state_transition_types.rs:23-43).
• book/src/sdk-support.md:12-13: Swift "Coming in v3.1", Android "Coming in v3.2"; both packages ship with CI.

Threat model

• Write the D11 register; initial entries as capability; sequence; surface; phase; mitigation; test:
  • Guest-reachable InternalError: any deployer; a module makes the host return Err (a Drive read on a guest-built path, a GroveDB cost overflow, serialization of a proposed operation) and every proposer that pulls it builds a block every validator rejects; liveness; Phase 3; D3's adapter rule plus D8 eviction; strategy-tests fuzz asserting no guest-reachable input yields InternalError.
  • Validator re-execution without a timer: a proposer with a high proposer_tx_processing_time_limit; publishes a block whose re-execution exceeds the propose timeout on every validator; liveness; Phase 3; D12's max_block_processing_credits calibrated on D17's profile; over-budget block rejected in process_proposal.
  • Proposer wall-clock griefing: any identity; well-formed hook calls that will trap enter the mempool because batch check_tx never validates state, and burn proposer time; liveness; Phase 3; D8 stage table; proposer-time test over a trapping corpus.
  • Priority flooding: any identity; minimum-priority hook-bearing transitions with a maximal declared bound cannot be out-bid except by paying the user_fee_increase multiplier; mempool; Phase 3; D8 plus 11.2.3's in-block floor; recheck eviction test plus a floor test over K sequential-nonce transitions on one balance.
  • Unpriced decode cost: any identity; many 20 KiB chunk transitions decoded in check_tx; mempool; Phase 1; D7 open-manifest bound plus D8; decode-cost benchmark.
  • Node-config flag on a consensus path: an operator; use_document_triggers (packages/rs-drive-abci/src/config.rs:92-93, read at batch/state/v0/mod.rs:82 and :279) shows the pattern; app hash; Phase 3; D8's rule that no such knob exists for hooks; unit test that the hook path reads no PlatformConfig field.
  • Proposer ordering control (MEV): a proposer; reorders hook-bearing transitions and, for the Phase 1b Dutch auction, moves the price through block_info.time_ms; fee and application state; Phase 1b, revisited at Phase 4; ordering rule in the DIP "Mempool" table, 11.2.9's assessment applied to 6.5 before PV15 signalling; ordering test.
  • Halt with the freeze unreachable: a deployer plus a host bug; blocks stop committing, so the 11.2.6 freeze write cannot land; liveness; Phase 3, and at Phase 5 the drain shape, where the proposer denylist is useless too because the drain runs before the transactions of every block; D6's coordinated binary behind a network-keyed activation height (11.2.5); flag-day rehearsal on a devnet before the first hook PV, repeated with a faulting queue entry before PV19.
  • Abandoned upload growth and chunk replacement: any identity; partial manifests left forever, or chunk k replaced after k+1 was accepted; state growth and proof mismatch; Phase 1; D7 immutability, expiry and open-manifest bound; expiry and replacement-rejection tests.
  • Charge above the bound: any deployer; writes exceed the pre-execution bound; fee and app hash; Phase 3; D3 (c) and (d) make it unreachable; fee-parity test (the single balance write equals the meter and never exceeds B) plus end-of-block conservation (calculate_total_credits_balance/v2).
  • Engine drift: a resyncing node; block N re-executed under a newer engine yields different fuel; app hash; Phase 3; D13; replay test across an engine bump.
  • Conservation bypass by contract-held value: a deployer; credits stored under [64]; app hash; Phase 1; D2's rule; conservation test after every guest outcome.
  • Engine advisory latency: an external attacker; an exploit window before the patch; liveness; Phase 3; D6's runbook and D16's stewardship answer; fuel-parity test of the patched engine.

Tests

Gates: markdownlint and cspell pass on the DIP; every record has all six fields; every register entry has all six fields and names a test a later section's test plan carries; a cross-reference pass confirms that sections 6 to 13 cite the decision IDs and section 14 question numbers they depend on, use D10's names table for every crate, limit field, generation and error-code block, and contradict none of these records.

Acceptance criteria

• DIP PR open in dashpay/dips under an alias filename with editor and two core reviews.
• D1 to D8 and D12 to D17 accepted with reversibility stated; D9 to D11 recorded.
• The fee-version registry PR and the docs PR merged.
• Section 6 starts with no open question owned here, D14's Tenderdash evidence included, since 6.4 gates on it.

Risks

• Reversal after Phase 3 freezes the ABI costs one protocol version per surface; mitigated by the reversibility field and the due dates above.
• Editor latency does not block: the alias filename carries the work.
• D5 is a product decision that can stall engineering; default if undecided: allowlisted deployment from Phase 2 (sections 07 and 14.4), open deployment at a later PV.
• D15 and D16 can stop the plan rather than delay it; default if undecided at the Phase 3 PV-opening PR: ship Phases 1 and 2 and stop.
• README wording is public and dash.org already disagrees (v5.0 versus v4.0); align with the roadmap owner first.
• The fee-version registry PR is not fee-neutral by inspection. FEE_VERSION1 and FEE_VERSION2 differ in data_contract_registration (v1's nine fields are all zero, fee/data_contract_registration/v1.rs:5-14; v2 carries the PV9 registration fees, v2.rs:5-15), so registering FEE_VERSION2 changes what as_static() resolves for every PlatformVersion from PV9 on (v9.rs:62, v14.rs:225). It is safe today only because as_static() has exactly one caller, a test (block_processing_end_events/tests.rs:866): the PR must assert that caller inventory and the index invariant rather than table identity, and renumbering additionally flips the == 1 refund branch at op.rs:280 for every PV from 9 on, which is why D3 makes the None audit part of the gate.

---

---

Continued in part 6 of 14 below.

[QuantumExplorer]

Part 6 of 14 of the plan (continued from part 5 above).

6. Phase 1: VM-independent infrastructure

Work useful without an engine. This section is two tracks, decided after review so that value-moving scope never holds the VM phases. Phase 1, PV15, is what Phases 2 to 5 consume: the block budget (6.1), code blobs (6.2), range proofs (6.3) and the settlement queue of 6.5 (which 6.2's staging cleanup needs and 10.2.6 reuses). Phase 1b is oracle feeds (6.4) and the escrow, allowance and auction primitives (6.5): it moves value, carries an external audit and the 11.2.9 assessment, activates in its own protocol version (PV15 beside Phase 1 if ready, otherwise the next free PV), and nothing in sections 07 to 10 waits for it (14.2). Conventions: activation at PV15 (opened like PR #4267 opened v14); caps as Option<T> fields in a new SYSTEM_LIMITS_V5; new block events as OptionalFeatureVersion; new trees created at genesis and in a transition_to_version_15 arm of packages/rs-drive-abci/src/execution/platform_events/protocol_upgrade/perform_events_on_first_block_of_protocol_change/v0/mod.rs:67-123. Three new wire ids appended to StateTransitionType (packages/rs-dpp/src/state_transition/state_transition_types.rs:23-43, last value 20): CodeBlob 21 at PV15, with 22 (OracleFeedObservation) and 23 (IdentityAllowance) reserved for Phase 1b and appended when it activates, each gated by a *_INITIAL_PROTOCOL_VERSION constant (packages/rs-platform-version/src/version/feature_initial_protocol_versions.rs) through the has_is_allowed_validation/validate_is_allowed arms in packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/is_allowed.rs:26-50 and :52-101. Three new root trees; RootTree (packages/rs-drive/src/drive/mod.rs:190-231) has 17 byte values taken and the layout at :172-185 leaves the slots beneath 72, 88 and 104 open, so the proposed discriminants are CodeBlobs 68, OracleFeeds 84, SettlementQueue 100.

Rule for every block-start path added here: bounded by a SYSTEM_LIMITS_V5 cap derived from the 6.1 budget, every byte it writes prepaid and refund-attributed, and every credit it moves accumulated into the block's BlockFees through the 6.5 accumulator, without which a block event destroys credits and halts the node. Consensus errors for the three transition types take one fresh 41200-41299 code block (highest in tree is 40904, packages/rs-dpp/src/errors/consensus/codes.rs:401), leaving section 08's 41000-41099 for Phase 3 and section 10's 41100-41199 for Phase 5 untouched and 41300-41399 for the Phase 2 guard errors section 07 asks for without naming a range; the allocation of all four blocks belongs in section 12's error-code paragraph, which already reasons about the 40500 and 40900 boundaries. Build order: Phase 1 is 6.1, 6.3, the 6.5 queue (6.2 needs it), then 6.2; Phase 1b is 6.4, then the rest of 6.5.

6.1 (a) Consensus-visible per-block compute budget

Reasoning

Blocks are bounded by max_tx_bytes (packages/rs-drive-abci/src/abci/handler/prepare_proposal.rs:97-114), by Tenderdash's reaper over gas_wanted, and by the proposer-only wall clock proposer_tx_processing_time_limit (abci/config.rs:37-39; process_proposal.rs:235-241 passes None). Validators re-execute any block unbounded.

Design

Metric: metered work, not billed fee. Per transition the budget consumes the processing_fee of FeeResult (packages/rs-dpp/src/fee/fee_result/mod.rs:55-64) as derived from OperationCost and the ValidationOperations, taken before apply_user_fee_increase and before additional_fixed_fee_cost is added (execute_event/v0/mod.rs:73-79), so neither a user fee increase nor the contract registration flat fee can fill the budget with credits instead of work; from Phase 3, fuel converted at a fee-table constant adds to the same number. Credits are a proxy for time, not a measurement: the 8M credits/ms figure at drive_abci_validation_versions/v10.rs:338-343 is the only place that rate is written down and it prices compute alone, while database work comes from fixed constants (storage_seek_cost 2000, storage_load_credit_per_byte 20, non_storage_load_credit_per_byte 10, packages/rs-platform-version/src/version/fee/storage/v1.rs:8-10) that bill a cold seek and a page-cache hit identically. A transition type whose fee under-prices its CPU bypasses the budget by the shortfall ratio; the budget is exactly as good as fee calibration, so section 12 sets the value from measured validator wall time per consumed budget, exported as a metric with the existing drive-abci metrics.

Rule: before executing transition i, if the metered sum over 0..i-1 (a new accumulator beside StateTransitionsProcessingResult::aggregated_fees(), platform_types/state_transitions_processing_result/mod.rs:192) has reached max_block_processing_credits, transition i and all later ones get NotExecuted(NotExecutedReason::BlockProcessingBudgetExhausted); a sum landing exactly on the budget at i still executes i. The proposer maps it to TxAction::Delayed like the timer (prepare_proposal.rs:235-236); validators count NotExecuted in failed_count and the unexpected_execution_results gate rejects the block (process_proposal.rs:278-308). The crossing transition stays in, so a costly one is never starved, and the overshoot is one transition; since Phase 3 fuel lets one transition approach the budget, two calibration-independent backstops join it in SYSTEM_LIMITS_V5: max_state_transition_processing_credits per transition, enforced in check_tx through validate_fees_of_event (packages/rs-drive-abci/src/execution/check_tx/v0/mod.rs:180) and at execution as a paid consensus error, and max_state_transitions_per_type_per_block. Overshoot is then at most budget plus the per-transition cap, which section 12 folds into calibration. None keeps PV14. Rejected: Tenderdash max_gas (reap-time only).

Metered now, declared later. At PV15 nothing declares a bound, so the accumulator is purely metered. From the first hook-bearing protocol version (PV17, section 08.2.6) it takes the declared bound instead: a hook-bearing transition contributes B (08.2.6's formula over instantiation, translation, memory pages, context bytes and budget * credits_per_fuel) before the guest runs, in prepare_proposal and process_proposal alike, so an over-budget proposal is rejected without any guest executing, the property that bounds validator work; transitions with no hook keep contributing their metered processing_fee after execution. Both quantities are credits against the same max_block_processing_credits, and the mixed sum stays deterministic because B is a function of the decoded transition and the contract's ValidationModuleRef while the metered part is a fold of the same operations on every node. Phase 5 adds its max_fee reservation to the same accumulator (10.2.4) and the block-event drains add theirs before the first transition (10.2.6).

Value: derived, not chosen here. max_block_processing_credits is the fraction of the block interval reserved for transition execution on the reference evonode profile the DIP fixes (11.2.3; this repository publishes no minimum spec), minus measured propagation and non-execution block work, converted at the measured credits-per-millisecond rate; the interval input is block_spacing_ms 5000 (packages/rs-drive-abci/src/config.rs:725). Two cross-checks bound it: a full budget executes in under one fifth of Tenderdash timeout.propose (50 s in the dashmate genesis, packages/dashmate/configs/defaults/getBaseConfigFactory.js:448), the rule 11.2.3 calibrates and section 13's criterion repeats, and the value stays at or below the block max_gas dashmate ships (57631392000, :436). 40e9 credits, 5 s at 8M credits/ms, is the whole minimum block interval: an upper bound used to size the derived caps in 6.2, 6.4 and 6.5 while the measurement is outstanding, provisional and not a proposal. Gate: PV15 does not signal until the wall-time-per-budget metric is recorded on the reference profile on arm64 and amd64 and a test recomputes the constant from the committed measurement, the reproducibility rule section 12 applies to credits_per_fuel.

Block events are capped separately, as shares of the same budget. Every block-event workload the plan adds, with its cap and why it cannot return Err:

Block event	PV	Cap	Err-freedom
Oracle slot open and close (6.4)	1b	max_active_oracle_feeds committee writes at open; max_active_oracle_feeds writes and max_active_oracle_feeds * k reads at close	validity never depends on the value; an unaffordable committee or slot write is skipped, not failed
Settlement drain, 6.2 cleanup included (6.5)	15 for the queue and 6.2 cleanup; 1b for escrow, allowance and auction entries	max_settlements_per_block, at most a tenth of the budget	outcomes are documents or the fixed-size fallback, prepaid at scheduling
Scheduled contract calls (10.2.6)	19	max_scheduled_calls_per_block, a sub-cap inside max_settlements_per_block	fired, rejected or dropped outcomes, bounded by the prepaid balance

Sum constraint: those caps plus max_block_processing_credits are what a validator re-executes in one block, so every cap is a share of the budget and none is chosen independently of it. A block-event Err halts the node (11.2.2), which is why each row carries an argument, not only a test.

Tasks

• Add max_block_processing_credits, max_state_transition_processing_credits, max_state_transitions_per_type_per_block as Option fields to SystemLimits (packages/rs-platform-version/src/version/system_limits/mod.rs) and SYSTEM_LIMITS_V5; extend mocks.
• Add the metered accumulator and the check in process_raw_state_transitions/v0/mod.rs independent of proposing_state_transitions; add NotExecutedReason::BlockProcessingBudgetExhausted (the enum carries one variant today, platform_types/state_transitions_processing_result/mod.rs:13-16) and verify that the existing exhaustive NotExecuted(_) savepoint arm (process_raw_state_transitions/v0/mod.rs:252-262) and the TxAction classification in prepare_proposal (:206-236) agree on it, as that arm's comment requires; per-transition cap in check_tx and execution; per-type counter; wall-time-per-budget metric.
• Record the wall-time-per-budget measurement on the reference profile on arm64 and amd64, set max_block_processing_credits from it, and add the test that recomputes the constant from the committed measurement. PV15 signalling waits on this task.

Tests

• Strategy test with independent_process_proposal_verification: true: maximal-cost blocks are truncated at the budget and accepted with equal app hashes; a hand-built over-budget block is rejected at PV15 and accepted under PV14.
• A transition at the per-transition cap placed last: accepted, overshoot at most the cap; one over the cap fails paid in check_tx and execution; a block spanning an epoch change where previous_fee_versions reprices mid-block sums identically on both sides; a sum exactly equal to the budget at i executes i and marks i+1 NotExecuted.

Acceptance

Over-budget blocks are rejected at PV15, no single transition exceeds the per-transition cap, and the budget constant is reproducible from a committed measurement. Consumed by Phases 3, 4, 5, 6.4 and 6.5; from PV17 the same accumulator carries declared bounds ahead of execution (08.2.6).

6.2 (b) Chunked, hash-addressed code-blob storage

Reasoning

Code cannot ride in DataContractCreate: a transition must fit 20480 bytes (decode_raw_state_transitions/v0/mod.rs:53-72, equal to Tenderdash max-tx-bytes) and a stored contract 65000 (packages/rs-drive/src/drive/contract/insert/insert_contract/v1/mod.rs:58-65). Raising the cap couples to gossip and the 2 MiB block.

Design

Layout under RootTree::CodeBlobs: complete blobs at [root, 0, hash] with [.., 0] metadata (length, chunk count, storage owner) and [.., 1] chunks keyed by big-endian u32 index, so a 6.3 range proof fetches a blob; staging at [root, 1, uploader_id, hash] with the same shape. Every chunk write checks uploader_id against the signer, so nobody can squat a public hash: a stranger can only stage their own copy. Transition CodeBlob (wire id 21) with bodies Chunk { hash, total_len, index, bytes }, Abandon { hash }, Delete { hash }. Chunks arrive in any order; a chunk for a hash already complete at [root, 0, hash] is a paid consensus error (dedup is by referencing, never by uploading). Completion: the chunk that fills the last index makes state validation fetch every staged chunk (billed as storage loads; an absent or short chunk is a consensus error, never Err), hash them at a new per-byte constant in FeeProcessingVersion (packages/rs-platform-version/src/version/fee/processing/mod.rs:7, a v2 table), and produce one of two actions: on match, a promote action moving the staging subtree to [root, 0, hash] and stamping the owner; on mismatch, CodeBlobStagingCleanupAction, whose operations delete the staging subtree (chunk elements carry StorageFlags for the uploader's epoch, so the deletes refund) and whose result is UnsuccessfulPaidExecution with a new error code. The split at validation time is forced by the engine, which applies the action's operations and only then attaches consensus errors (execute_event/v0/mod.rs:89-99); a mismatch found in conversion or Drive could only surface as Err, which validators classify as internal and reject the block. Two uploaders on one hash: first completer wins, the second's completion is the same paid cleanup. Deadline: the first chunk schedules a cleanup entry in the 6.5 queue with a prepaid cleanup fee, so abandoned staging is deleted and refunded when it fires; Abandon does the same early. Reference count: an explicit code_blob_references field in DataContractConfig (packages/rs-dpp/src/data_contract/config/, new config version) maintained by the DataContractCreate/DataContractUpdate action conversions (packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/), incrementing on add and decrementing on removal including update-to-empty. It does not ride on keywords: update_contract/v1/mod.rs:272 skips the keyword update for an empty set and leaves the old documents in place (system_limits/mod.rs:42-48). Delete is callable by the storage owner at count zero and refunds the storage. Fees: 27000 credits per stored byte plus a flat fee (section 12). Caps in SYSTEM_LIMITS_V5: blob 256 KiB, chunk 16 KiB, incomplete blobs per identity. Rejected: per-contract copies (no dedup); staging keyed by hash alone (squatting).

Tasks

• rs-drive: RootTree::CodeBlobs, a new packages/rs-drive/src/drive/code_blobs/ module (stage, promote, cleanup, delete, fetch), action and DriveOperation conversions under state_transition_action/action_convert_to_operations/, code_blob_references maintenance in the contract conversions, genesis creation and the transition_to_version_15 arm.
• rs-dpp: StateTransitionType::CodeBlob = 21 and the transition bodies, a code_blob_state_transition: Option<FeatureVersionBounds> slot in DPPStateTransitionSerializationVersions (packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_serialization_versions/mod.rs:8-43, the Option idiom of :30), CODE_BLOBS_INITIAL_PROTOCOL_VERSION = 15, the config field, consensus errors under packages/rs-dpp/src/errors/consensus/state/ taking codes from the 41200-41299 block.
• rs-drive-abci: has_is_allowed_validation/validate_is_allowed arms, structure and state validation with a DRIVE_ABCI_VALIDATION_VERSIONS_V11 slot, ExecutionEvent::Paid mapping (execution_event/mod.rs:30-45), check_tx arm.
• Proofs: a StateTransitionProofResult variant with arms in verify_state_transition_was_executed_with_proof/v0 and prove_state_transition; rs-sdk helper; wasm-dpp2 match sites.

Tests

• rs-drive: out-of-order completion; mismatch on the last chunk leaves no staging state and refunds the earlier chunks; a chunk for a complete hash fails paid; a stranger cannot write into another uploader's staging; two uploaders on one hash, the second completion fails paid and refunds; delete blocked at nonzero count; update-to-empty decrements the count; abandon and deadline cleanup refund.
• drive-abci: a 256 KiB blob over 16 blocks verifies whole via 6.3.

Acceptance

A client uploads, proves, and references a code blob by hash on a PV15 devnet; no transition exceeds 20480 bytes; no staging entry outlives its deadline. Consumed by Phases 2, 3, 5.

6.3 (c) Range prove_elements and Element projection

Reasoning

GetPathElements proves point reads only (Query::insert_keys, packages/rs-drive/src/prove/prove_elements/v0/mod.rs:29-42). 6.2, 6.4, 6.5 and Phase 4 need ordered ranges. The wasm-drive-verify stub (packages/wasm-drive-verify/src/system/verify_elements.rs:47-58) is stale: rs-drive's verify feature exposes Element and wasm-sdk already projects every variant (packages/wasm-sdk/src/queries/system.rs:478-530, :858-1003).

Design

prove_elements v1 and verify_elements v1 (slots at drive_versions/mod.rs:114 and drive_verify_method_versions/mod.rs:157) take RangeSpec { start_after, end_inclusive, limit, ascending } and build the same PathQuery on both sides with the insert_range_* family (grovedb-query/src/insert.rs:49-131). Limits: max_returned_elements (100, drive_abci_query_versions/mod.rs:10) caps the count as today, and because a range over 16 KiB chunks at limit 100 would return about 1.6 MiB of proof per unpaid query (today's bounds are a key count, a 64 KiB request and 255-byte keys, path_elements/v0/mod.rs:19-34, over small elements), v1 adds max_returned_element_bytes (256 KiB, one full blob) beside it. The prover walks the range and stops at the last element that keeps the running byte total within the cap, proving with that effective limit limit_eff <= limit; the response carries limit_eff; the verifier rejects limit_eff > limit, rebuilds the query with limit_eff, and treats the range as exhausted only when the result count is below limit_eff and limit_eff == limit; otherwise the client pages from the last key. Queries stay unpaid; the byte cap bounds prover CPU and response size per request, and the design assumes DAPI's existing per-client rate limiting and adds none. Wire: GetPathElementsRequestV1 per the build.rs recipe (packages/dapi-grpc/build.rs:228-239), bumping path_elements (drive_abci_query_versions/mod.rs:149). Projection: the Element projection moves from wasm-sdk into rs-drive behind the verify feature (the feature wasm-drive-verify already links, packages/wasm-drive-verify/Cargo.toml:13-15) as a new module beside verify (packages/rs-drive/src/lib.rs:63-65): element_type_name (system.rs:921), element_value_bytes (:858), element_sum (:869), element_reference_target (:897) and the three wrapper-variant name helpers (:954, :989, :1003) leave wasm-sdk, and both wasm crates call the shared functions. Rejected: a separate workspace crate for seven functions.

Tasks

• rs-drive prove_elements/v1, verify_elements/v1, DRIVE_VERSION_V10 slots; max_returned_element_bytes in DriveAbciQueryVersions; dapi-grpc GetPathElementsRequestV1; drive-abci query_path_elements_v1; rs-dapi drive_method!; grpc-coverage entry.
• rs-drive verify-gated element projection module with wasm-sdk switched to it; wasm-drive-verify verifyElements implemented over it with the v1 range shape; rs-sdk range query for Elements, proof-verifier FromProof arm, wasm-sdk binding.

Tests

• Round trips for both directions, paging, empty range, limit at cap; byte cap hit mid-range yields limit_eff < limit, the verifier accepts and does not report exhaustion; a proof whose limit_eff exceeds the request is rejected; projection parity: for every Element variant, verifyElements and wasm-sdk getPathElements return the same projected shape over the wasm-sdk vectors.

Acceptance

A JS client without rs-sdk verifies a range proof of blob chunks; one unpaid query returns at most max_returned_element_bytes of elements. Consumed by 6.2, 6.4, 6.5, Phase 4.

6.4 (d) Phase 1b: oracle feeds, on-chain median, LLMQ signing gated on Phase 0

Reasoning

Lending, stable assets, and conditional settlement need data before computation. Two transports exist: an on-chain median of masternode observations, and a validator-quorum threshold signature through vote extensions (withdrawals use VoteExtensionType::ThresholdRecoverRaw, platform_types/withdrawal/unsigned_withdrawal_txs/v0/mod.rs:162-169). The second cannot be made safe with what this repository controls. verify_vote_extension rejects any precommit whose extension set differs from the local expectation (abci/handler/verify_vote_extension.rs:70-85), so a value-dependent extension splits precommits along exchange prices, drops them past one third, and times the round out every height while prices move; verify_and_match_with_vote_extensions returns None when the commit's extension count differs from the withdrawal count (unsigned_withdrawal_txs/v0/mod.rs:59-61), so a commit carrying a feed extension fails finalize with VoteExtensionMismatchReceived (execution/engine/finalize_block_proposal/v0/mod.rs:143-155); and whether Tenderdash recovers a threshold signature from a strict subset of precommits, and commits the block when it cannot, is not verifiable here (no Tenderdash Go source is vendored, and the pinned rs-tenderdash-abci checkout carries only generated ABCI bindings, Cargo.lock:7543). The median is the design; the signed transport is an upgrade behind a hard gate.

Design

Registry: a system contract in a new packages/oracle-feeds-contract package (the shape of packages/dpns-contract) with a feed document type: feedId, decimals, hardMin/hardMax, slotBlocks, k (eligible observers per slot), m (minimum observations), stalenessBlocks. Registration is a document create from any identity that deposits a minimum balance into the feed's prefunded balance at [40, feeds, feedId] (beside the voting subtree, packages/rs-drive/src/drive/prefunded_specialized_balances/mod.rs:36); anyone may top it up; only the registrant ($ownerId) may replace bounds and staleness or retire the feed, effective at the next slot open (bounds are the publisher's claim; consumers choose feeds). max_active_oracle_feeds in SYSTEM_LIMITS_V5 rejects registration past the cap; a feed at zero balance stops updating and, past staleness, reads as absent. Values: RootTree::OracleFeeds holds [root, feed_id, be_u64(slot_height)] = FeedValue { value: i64, height, core_height } (fixed size), key 0 latest, provable via 6.3.

Observations: OracleFeedObservation (wire id 22), masternode-signed like MasternodeVote, carrying (feed_id, slot_index, value). Eligibility is deterministic, narrow and frozen per slot. At the slot-open block-start event (the first block at or after the slot's first height) the k masternodes whose pro_tx_hash has the smallest XOR distance to sha256(feed_id || be_u64(s)) in full_masternode_list() of the state committed at that height (platform_state/accessors.rs:105), the target salted per option (a) below if Phase 0 adopts it, are written as the slot's committee element [RootTree::OracleFeeds, feed_id, 1] = SlotCommittee { slot, members: [pro_tx_hash; k] } (key 0 is the latest value), replaced in place each slot so it never grows, its storage prepaid from the feed balance; a feed that cannot pay skips the open and that slot accepts nothing. Freezing the committee is what makes the at-most-k bound hold: the masternode list changes within a slot (a ProRegTx lands, a node is banned), and a live derivation against the latest committed list would select a different k-set at different heights of one slot, admitting more than k distinct observers. An observation is accepted only from a committee member that is also still in the current list, once per member per slot, with uniqueness checked against the block transaction (which includes committed state), so the second observation from one member in one block sees the first. check_tx and execution reject everything else as an unpaid consensus error: a non-member, an unknown or retired feed, a slot with no committee, a closed slot, a value outside hard bounds, a member whose observation for the slot is already committed, a feed balance below the observation fee. Pending observations are a separate rule, since check_tx cannot see other pending transactions: at most one per member reaches state per slot by the rule above; RecheckTx evicts a pending observation whose member's slot observation has committed; two differently signed observations from one member that are both pending are ordered by the proposer, the first is accepted and the second is a free in-block rejection the proposer removes (TxAction::Removed), bounded per block by max_state_transitions_per_type_per_block (6.1) so validators never re-execute an unbounded run of them. Equivocation therefore costs a member nothing beyond its seat and is recorded in the D11 register as accepted for Phase 1b, with a per-member observation ban as the revisit. The mempool therefore holds at most k accepted observations per feed per slot, plus equivocations bounded per block. An accepted observation executes as PaidFixedCost (the MasternodeVote arm, execution_event/mod.rs:293-302) whose operations deduct a fixed observation fee from the feed balance (deduct_from_prefunded_specialized_balance_operations) into the pools; the constant covers validation plus 1/m of the slot entry's storage; the signer pays nothing. Slot close: a block-start event (DriveAbciBlockStartMethodVersions, drive_abci_method_versions/mod.rs:129) at the first block after the slot's last height reads the at most k observations and, if at least m exist, writes the lower median (sort ascending, index (n-1)/2) as the slot value, deducting the entry's storage from the feed balance (skip the write, never Err, when the balance cannot cover it), then deletes the observations. Every credit the close moves lands in the 6.5 block-event accumulator. Block validity never depends on the value. Bound: max_active_oracle_feeds * k reads and max_active_oracle_feeds writes per block at close, plus max_active_oracle_feeds committee writes at open (each an O(n log n) selection over the masternode list, metered into the same row), derived from the 6.1 budget like the 6.5 drain.

Reads: guard access to feeds is reserved and undefined at PV16. feed is a reserved word in section 07 with no Phase 2 definition, so it has no resolution rule, static type, staleness semantics, error class, cost row or read-cap accounting yet, and oracle-aware guards do not ship with Phase 2. The first consumers are 6.5 escrow conditions in Phase 1b, carrying (feed_id, op, threshold) and resolved against the latest slot value at drain, and Phase 4 footprint reads at PV18 (09.2.2's OracleFeed { feed_id } entry, a point read of [RootTree::OracleFeeds, feed_id, 0]). A feed past stalenessBlocks reads as absent to both, and an escrow whose condition names an absent feed does not release: it holds to expiry and refunds, so a stalled feed delays a settlement but never redirects one.

Gated upgrade: only if Phase 0 shows that Tenderdash recovers a ThresholdRecoverRaw signature from a strict subset of precommits and commits the block when recovery fails may a second extension family attest the slot value. Then extend_vote attaches it only within node-local tolerance; verify_vote_extension accepts a feed extension only if its bytes equal the value committed in block H (a deterministic state read) and accepts its absence unconditionally; verify_and_match_with_vote_extensions partitions the commit's extensions by sign_request_id prefix (withdrawals use plwdtx, unsigned_withdrawal_txs/v0/mod.rs:180) before comparing the withdrawal subset; the ingest at H+1 reads only the block's canonical commit (proposed_last_commit and local_last_commit, both ignored today at block_proposal/v0.rs:160 and :89), verifies with validator_sets()[quorum_hash].threshold_public_key from the last committed state (accessors.rs:96), runs before update_core_info rotates the sets (run_block_proposal/v0/mod.rs:246), and treats an unknown quorum as no update, never Err. The signature is an attestation over the median; the median stays the value. Rejected: Core-side signing sessions (Core changes outside this repository); unbounded observation transitions (k bounds them); value-dependent vote extensions without the gate.

Manipulation and incentives

Feeds are the only external-data mechanism in the plan and the lending and stable-asset cases rest on them, so the failure modes are stated rather than assumed. No protocol rule makes a feed value correct: hardMin/hardMax, k and m are the only enforced bounds.

Collusion. With n observations accepted in a slot (m <= n <= k) and t of them adversarial, the lower median at index (n-1)/2 stays between the honest order statistics t positions either side of the honest median: honest-bounded while t < n/2, chosen outright by the adversary inside hard bounds once t reaches floor(n/2) + 1. So a registrant sets k odd and comfortably above m, and hard bounds are the only backstop a consumer gets: a feed with wide bounds is worth what its observer set is worth.

Eligibility grinding. The target sha256(feed_id || be_u64(s)) is computable for every future slot the moment a feed is registered, and pro_tx_hash is a transaction hash a registrant can grind off-chain, so seats in a chosen slot of a chosen feed cost one masternode collateral each instead of a share of the whole list. Two answers, decided in Phase 0 with the D11 threat register: (a) salt the target with last_committed_block_id_hash() (platform_types/platform_state/accessors.rs:181) at the height the previous slot closed, so eligibility for slot s is unknowable until slot s-1 closes and a grinder must land a ProRegTx in the masternode list inside one slot, while every node still derives the same salt from committed state in check_tx and execution; (b) keep the pure hash and rely on k, m and hard bounds. Recommended: (a), whose only cost is that a masternode learns its eligibility one slot ahead, which the k-per-slot mempool bound already assumes.

Liveness. Any k - m + 1 members of an eligible set stall a slot by not reporting, and ordinary downtime does the same, so m sits well below k. A stalled feed keeps its last value until stalenessBlocks and then reads as absent, the safe direction: consumers fail closed, and no block ever depends on a slot closing.

Incentives. Feeds are unincentivized at the protocol level in Phase 1b by decision: the observation fee moves from the feed's prefunded balance to the pools, so an observer is neither paid nor charged, and nothing in consensus makes a masternode run a price observer. A registrant that wants liveness recruits observers off-chain (its own masternodes, or an agreement with operators) and funds the feed balance for the slot writes. Rejected for Phase 1b: a flat per-observation reward from the feed balance, which pays for reporting anything inside hard bounds and is farmable exactly where the value is least checked. An accuracy-conditioned reward (paying observations within a band of the accepted median) is the option to revisit once feeds have consumers, and since it pays a colluding majority too it is no fix for the collusion bound.

Tasks

• Contract and types: packages/oracle-feeds-contract, SystemDataContract::OracleFeeds (packages/data-contracts/src/lib.rs:36), oracle_feeds in SystemDataContractVersions as SYSTEM_DATA_CONTRACT_VERSIONS_V4 (system_data_contract_versions/mod.rs:8-17; v14.rs:224 is at V3); StateTransitionType::OracleFeedObservation = 22, its serialization slot, ORACLE_FEEDS_INITIAL_PROTOCOL_VERSION = 15, consensus errors under errors/consensus/state/ taking codes from the 41200-41299 block.
• rs-drive: RootTree::OracleFeeds, feed value and observation operations, the [40, feeds] balance path; genesis and transition_to_version_15 create the contract (load_system_data_contract, as at perform_events_on_first_block_of_protocol_change/v0/mod.rs:231) and the tree.
• rs-drive-abci: is_allowed arms, the slot-open event writing the committee element, validation by committee membership plus current-list presence (salted or unsalted per the Phase 0 decision above) with uniqueness against the block transaction and the RecheckTx eviction, PaidFixedCost mapping, slot-close event feeding the 6.5 block-event accumulator, max_active_oracle_feeds and the k bound in SYSTEM_LIMITS_V5, getOracleFeed and history queries with SDK bindings.
• Phase 0 evidence, owned here because the section 05 decision register does not carry it: establish from dashpay/tenderdash whether a threshold signature is recovered from a strict subset of precommits and what a node does when recovery fails. The answer opens or closes the signed transport; the median ships either way.
• Gated on that outcome: the extension family, the verify_and_match_with_vote_extensions partition, the ingest event, and mimic carrying proposed_last_commit and local_last_commit (both None today, packages/rs-drive-abci/src/mimic/mod.rs:150 and :284).

Tests

• Ineligible masternode, unknown feed, closed slot, out-of-bounds, duplicate and unfunded feed fail unpaid in check_tx and execution; a masternode that joins the list mid-slot is ineligible for that slot and eligible for the next, and k+1 distinct observers never appear in one slot under a mid-slot list change; two observations from one member in one block accept the first and reject the second, and RecheckTx evicts the pending duplicate after commit; a strategy test with mocked observations writes the median at slot close, skips below m, deducts storage from the feed balance and stops when it is exhausted; block-start cost at the feed cap stays under the derived bound.
• Adversarial: a majority of an eligible set reports an outlier and the outlier is written, bounded only by hard bounds, pinning that the protocol claims no correctness; an eligible set abstains for many consecutive slots and the feed goes stale then absent while blocks continue and an escrow naming it holds and refunds at expiry; under the salted option (a), eligibility for slot s+1 is not computable before slot s closes.
• Gated: a commit carrying withdrawals plus a feed extension finalizes; prepare_proposal and process_proposal fed different commit infos produce identical app hashes.

Acceptance

A devnet feed updates every slot with provable history; observations from ineligible masternodes never enter the mempool; feed liveness never touches block liveness. Gate: no vote-extension work starts without the Phase 0 Tenderdash evidence. Consumed by 6.5 and Phase 4 (09.2.2's OracleFeed footprint entry); Phase 2 reserves the word feed without defining it (section 07).

6.5 (e) Native primitives: the settlement queue (Phase 1), escrow, subscriptions and auctions (Phase 1b)

Reasoning

Custody, recurring payment, and price discovery have settled mechanisms. AMM and lending are excluded: XRPL's native AMM launched in March 2024, a routing bug surfaced in days, and the fix (fixAMMOverflowOffer, shipped in rippled 2.1.1) needed an 80 percent amendment majority held for two weeks before activation. Platform is slower (67 percent lock-in at an epoch boundary, activation the next 9.125-day epoch, no expedited path); those wait for Phase 5, where a fix is a contract update.

Design

Shared timed settlement queue: RootTree::SettlementQueue keyed by big-endian u64 fire time then entry id. Prepay at scheduling: the creating transition escrows, into the entry's own prefunded balance at [40, settlements, entry_id] beside the escrowed amount, a maximum settlement fee (the estimated storage of the outcome document plus a fixed processing charge from the fee tables). The drain, a block-start event in a new DriveAbciSettlementMethodVersions, reads RangeToInclusive(..=block_info.time_ms) under max_settlements_per_block (the vote-poll pattern, check_for_ended_vote_polls/v0/mod.rs:66-85, whose maximum_vote_polls_to_process is 2 at v10.rs:333) and per entry deducts the actual cost into the pools, refunds the remainder to the payer, and writes the outcome document under StorageFlags::new_single_epoch(epoch.index, Some(payer)) (as document_create_transition.rs:60) so its storage refund attributes to the payer; if the prepaid amount no longer covers the cost (fee tables changed at an epoch boundary), the escrowed amount settles without a document and a fixed-size outcome element records it. Outcomes are never Err.

Block-event accounting ships with the drain, not later. Every credit it moves accumulates into a block_event_fees FeeResult merged into the block's BlockFees (BlockFeesV0 { processing_fee, storage_fee, refunds_per_epoch }, execution/types/block_fees/v0/mod.rs:8-14) before process_block_fees_and_validate_sum_trees, which today is handed only aggregated_fees() (execution/engine/run_block_proposal/v0/mod.rs:393-396); without that merge a drained entry destroys credits and CorruptedCreditsNotBalanced (process_block_fees_and_validate_sum_trees/v0/mod.rs:183) halts the node. The 6.4 slot close uses the same accumulator; 10.2.6's scheduled calls extend it rather than adding a second.

Bound: max_settlements_per_block * max_settlement_operations per block, with max_settlements_per_block = floor(0.1 * max_block_processing_credits / max_settlement_processing_credits), so the drain never exceeds a tenth of the 6.1 budget; 6.2 staging cleanup rides the same queue. Escrow: credits locked in the entry's [40] balance, a term of the conservation equation (calculate_total_credits_balance/v2/mod.rs:19-80); release by deadline, group approval (GroupActionEvent gains EscrowEvent), or a 6.4 feed condition evaluated at drain; expiry refunds via the queue. Minimum-size escrow spam grows state only by bytes the creator paid at 27000 per byte with refunds attributed to the creator, the same terms as any document.

Subscriptions: a pull-model allowance under the identity subtree (new IdentityRootStructure key, packages/rs-drive/src/drive/identity/mod.rs:337-350) with (payee, amount_per_period, period_ms, cap, expiry, last_claim_ms, claimed); IdentityAllowance {Set, Claim, Revoke} (wire id 23) moves credits [96] to [96]; no cron. Claim is signed and paid by the payee, so a payee can never spend the payer's balance on fees. amount = min(cap - claimed, floor((now - last_claim_ms) / period_ms) * amount_per_period), all arithmetic checked or saturating u64; zero elapsed periods, expiry passed, or a payer balance below amount (including a payer carrying IdentityTreeNegativeCredit, identity/mod.rs:347) is a paid consensus error with no transfer, never Err, never partial; on success last_claim_ms advances by whole periods only. A payer who stays empty costs the payee one failed claim per attempt and nothing else.

Auctions: TradeMode::Auction fills the commented slot at packages/rs-dpp/src/nft/mod.rs:8-13 (English or Dutch; reserve, floor, start price, decay window T, deadline). A bid escrows into the auction's [40] balance and, in the same transition, refunds the previous high bidder (paid by the new bidder), so the escrow holds exactly one live bid and settlement is O(1); max_bids_per_auction stays as a defensive cap. Dutch price at block time t: start - u64((u128(start - floor) * u128(min(t - t0, T)) / u128(T))), floor division on block_info.time_ms, checked or saturating u64 like the integer arms of DistributionFunction::evaluate (token_perpetual_distribution/distribution_function/evaluate.rs:45-87) and never like its f64 arms (evaluate.rs:208-417), which are the divergence hazard. Settlement runs from the drain as a dedicated operation set (document owner change plus payout; reserve unmet refunds the single live bid), invoked without a signer and therefore bypassing nonce, revision and signature checks by construction; the owner-signed purchase path is not reused.

Proposer exposure. Section 11.2.9 gates every value-moving capability grant on an MEV assessment and names Phase 5 as the first; Phase 1b moves value first, so the assessment applies here and its outcome gates Phase 1b signalling. Two exposures. (1) The Dutch price is a function of block_info.time_ms, and Drive validates only height and core height for a proposal (next_block_to, execution/types/block_state_info/v0/mod.rs:119-126), so the proposed time is bounded by Tenderdash synchrony (message_delay 70 s, precision 1 s in the dashmate genesis, getBaseConfigFactory.js:454-455) and by nothing here: a proposer can advance the clock inside that window and buy at the lower price in its own block. Mitigation in Phase 1b: min_auction_decay_window_ms in SYSTEM_LIMITS_V5 rejects a decay window short enough for that skew to matter, bounding the reachable move to (start - floor) * skew / T. (2) In an English auction the proposer orders bids inside the final block and can leave a competing bid out of the block it builds (prepare_proposal picks the transaction set and truncates only the tail, prepare_proposal.rs:97-114), so it bids last at one increment above what it sees. Accepted for Phase 1b, reason recorded rather than mitigated: no ordering rule constrains the party building the block, settlement is already off the bid path (it runs from the drain over committed state), and commit-reveal is Phase 5's answer (10.2.7). The auction documentation carries the exposure so authors set deadlines longer than one proposer's turn.

Tasks

• Phase 1 (PV15): queue root tree, drain event, max_settlements_per_block, max_settlement_processing_credits in SYSTEM_LIMITS_V5; the block_event_fees accumulator merged into BlockFees before process_block_fees_and_validate_sum_trees; prepaid fee escrow in every scheduling transition (6.2 cleanup included); fixed-size outcome fallback.
• Phase 1b: escrow create, release, cancel as batched transitions over the prefunded specialized balance operations; EscrowEvent; allowance tree, IdentityAllowance transition, getIdentityAllowances query.
• Phase 1b: TradeMode::Auction in meta-schema v4 and parser generation 4 under CONTRACT_VERSIONS_V7 (14.2's renumbering rule applies if Phase 1b lands after PV16), bid transition with in-line refund, settlement operation set, the section 07 and 08.2.2 rule that an auction type declares neither guards nor a validationModule stated in the auction chapter, min_auction_decay_window_ms in SYSTEM_LIMITS_V5; the 11.2.9 assessment recorded in the DIP before PV15 signalling; SDK parity manifest entries.

Tests

• Conservation holds under verify_sum_trees including prepaid refunds; a drained entry's credits appear in BlockFees and the block-end conservation check passes, including in a block carrying no state transitions; strategy runs add escrow, auction, and allowance OperationType variants; backlog above the cap drains deterministically; settlement under a fee-table change falls back to the fixed-size outcome; a minimum-size escrow spam run grows state only by paid bytes attributed to the creator.
• Allowance: zero elapsed periods, cap reached, expiry passed, payer at zero balance, payer in negative credit, whole-period advance. Auction: no bids, reserve unmet, outbid refund inside the bid, bidder drained, Dutch price at t0, mid-window and past T with identical integers on both architectures; a Dutch auction at the min_auction_decay_window_ms floor prices within the stated bound across the extreme block times a proposer can set.

Acceptance

All three run on a devnet with proofs for every read; every block-start write is prepaid and refund-attributed and every block-event credit is in BlockFees; the drain stays under the derived cap. The queue is Phase 1 (PV15), precedes 6.2 and is what 10.2.6 reuses; escrow, allowance and auctions are Phase 1b, depend on 6.1 and 6.4 (escrow conditions), gate on the 11.2.9 assessment and the external audit (14.2), and nothing on the path to Phase 5 waits for them.

6.6 (f) Events and receipts: explicit punt

Decision: no general event log in Phase 1. The receipt is the affected-state proof (StateTransitionProofOutcome) plus ExecTxResult { code, info, gas_used } (abci/app/execution_result.rs:10-50), committed under the header results_hash but not bound by state proofs (StateId, packages/rs-drive-proof-verifier/src/verify.rs, binds app hash and block metadata, not results). A provable log needs an append-only tree and a fee per emitted byte; grovedb at the pin ships MmrTree and BulkAppendTree. D4 requires a punt to reserve an ABI slot and name a revisit phase: the reservation is a capabilities vector value held for a future log grant (the vector is empty at abi 0, section 08 rule 4, and section 09's read grant takes the first admissible value), so no HookContextV0 or HookContextV1 field is spent on it. Revisit in Phase 5, which answers with a proof-result variant rather than an emit-and-index path.

• State in the DIP that results_hash is not bound by state proofs and ExecTxResult.info is not proven, and record the reserved capabilities value in the D10 names table.

6.7 Phase risks

• Budget: metered credits are a proxy for time; a fee under-estimate is a budget bypass, and the per-transition and per-type caps are the floor beneath calibration; adjust per PV. The constant itself is provisional until measured, and every derived cap in 6.2, 6.4 and 6.5 moves with it.
• Feed values: no protocol rule makes them correct. A colluding majority of an eligible set sets the value inside hard bounds, an abstaining minority stalls the slot, and feeds are unincentivized, so observer liveness is the registrant's problem; the bounds are k, m, hard bounds and the recommended per-slot salt. Belongs in the section 14 risk register and the D11 threat register.
• Proposer extraction starts with Phase 1b, not Phase 5: the Dutch price reads a proposer-chosen clock and the final block of an English auction is proposer-ordered and proposer-filtered (6.5).
• Every primitive bugfix is a PV; keep parameters, not curves, in consensus.
• Three new transition types touch every exhaustive match in rs-dpp, rs-drive, drive-abci, wasm-dpp2; one PR each.
• Feed transport: the Phase 0 Tenderdash evidence decides whether signing exists; the median is built regardless.

---

---

Continued in part 7 of 14 below.

[QuantumExplorer]

Part 7 of 14 of the plan (continued from part 6 above).

7. Phase 2: bounded expression guards

Gate: PV16. Section 6 (PV15) opens SYSTEM_LIMITS_V5, DRIVE_ABCI_VALIDATION_VERSIONS_V11 and CONTRACT_VERSIONS_V7 (meta-schema v4, parser generation 4, DocumentTypeV3) over the PV14 baseline CONTRACT_VERSIONS_V6 (packages/rs-platform-version/src/version/v14.rs:215); section 14.2 binds meta-schema v5, parser generation 5 and CONTRACT_VERSIONS_V8 to this row, so this phase opens those plus SYSTEM_LIMITS_V6, DPP_VALIDATION_VERSIONS_V6, DRIVE_ABCI_VALIDATION_VERSIONS_V12, DocumentTypeV4 and DOCUMENT_VERSIONS_V5 (document serialization format 4, for the $createdAtContractVersion stamp below). Unpathed identifiers are proposals. Shorthand: batch/ = packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch, document_type/ = packages/rs-dpp/src/data_contract/document_type, try_from_schema/ = document_type/class_methods/try_from_schema, actions/ = packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition, strategy_tests/ = packages/rs-drive-abci/tests/strategy_tests/test_cases; other short paths are unique within the crate named beside them (rs-drive-abci abci/ and execution/; rs-platform-version fee/, system_limits/, mocks/).

Reasoning

A guard is an author-written predicate on a document type (who may act; what must hold between old and new document). Today that is a Rust data trigger only Dash can extend (batch/data_triggers/executor.rs:38-52). A total, terminating expression layer hands it to authors without a VM, and comes before Phase 3 because:

1. Cost is static for free: every property is bounded (document_type/property/mod.rs:157-180; max_field_value_size 5120, system_limits/v4.rs:19), so worst-case cost is fixed at registration, as the Kubernetes API server rejects CEL rules whose worst-case estimated running time is too high (kubernetes.io/docs/reference/using-api/cel/, Estimated cost limits).
2. It builds what section 8 reuses: a fee channel for compute, a read cap, evaluator generations, old-document plumbing, failures as consensus errors.
3. Author formulas already run in consensus with checked math (the linear arm of DistributionFunction::evaluate, packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/evaluate.rs:134-147); guards use checked arithmetic only, with no wrapping or saturating operator in the grammar.

The ceiling is known (Firestore security rules: 10 get/exists calls per single-document request, recursion not permitted; firebase.google.com/docs/firestore/security/rules-structure); Phase 3 is the off-ramp.

Design

Evaluator choice

cedar-policy 4.12.0 (Apache-2.0, MSRV 1.89) has a Lean specification artifact for the Cedar language itself (cedar-spec), which says nothing about our embedding or about a cost bound, and it has no division operator (docs.cedarpolicy.com/policies/syntax-operators.html), so arithmetic would need a second grammar; a fork of cel 0.14.4 (MIT, MSRV 1.86) carries floats, dynamic typing, no cost metering and 1150 of 2343 cel-spec cases marked expected-failure. Decision: a new node-internal crate at packages/rs-platform-guards (no_std plus alloc, no I/O), CEL-subset syntax so the cel-spec generator applies, Cedar's permit/forbid combination; both crates become dev-dependency oracles, never consensus code.

Grammar and scope

Bindings: new (the action's resulting document with system fields, so $ownerId after transfer; every action but delete), old (the stored document; every action but create), owner, action, block.{timeMs,height,coreHeight,epoch}. Member access: bare new.p only when p matches [A-Za-z_][A-Za-z0-9_]*; any other admitted name (^[a-zA-Z0-9-_]{1,64}$, packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json:10 and :20-22, so max-bid and 2fa are legal) is written new["max-bid"]; the lexer never folds - or a leading digit into a name, and a guard naming an unreachable property fails registration. deref(new.p) is legal only when p is IdentifierWithReference(PermanentDocument{..}) (property/mod.rs:90-121,179); Identity, Contract, Token and IdentityPublicKey targets are type errors. Allowed: comparisons of equal types; &&, ||, !, ?:; + - * / %; in over literal lists; has(); size(); startsWith. Not allowed: number (F64), u128 and i128 in arithmetic, regex, concatenation, iteration (bounded all/exists deferred), user functions, recursion, other reads. feed (oracle read, section 6.4) and lookup (keyed unique-index read) are reserved words with no Phase 2 definition: each ships with its own resolution rule, snapshot, static type, error class, cost row and read-cap accounting, or not at all. Guards only narrow what existing checks accept. Per action: any true forbid rejects; if any permit exists one must hold; every require must hold.

Trigger coverage (batch/data_triggers/triggers): dashpay contact request (owner != new.toUserId, dashpay/v1/mod.rs:54; recipient existence becomes the refersTo: identity read, batch/action_validation/document/document_reference_validation/v0/mod.rs:150-156), withdrawal delete (old.status == 3, COMPLETE at packages/withdrawals-contract/src/lib.rs:43; withdrawals/v1/mod.rs:119-128) and reject (forbid true) are expressible. DPNS create is not and stays native (dpns/v1/mod.rs:48-400: homograph normalization at :122 and :135-136, label split and join at :200, parent query with no reference to the parent at :211-265, salted preorder hash lookup at :327-381); the profile leading-byte check (profile_v0/mod.rs:66) waits for byte indexing.

Evaluation semantics (normative, DIP appendix)

Both bindings decode through the schema's DocumentPropertyType, never by platform_value::Value tag, so old (storage) and new (payload) cannot disagree on representation. Arithmetic is checked i128; / and % truncate toward zero; i128::MIN / -1 and division by zero are evaluation errors. size() on strings is UTF-8 bytes, the measure validate_document uses (packages/rs-dpp/src/data_contract/methods/validate_document/v0/mod.rs:76); on arrays it is the element count. An absent optional property is a typed null, unequal to everything and an error under arithmetic, size() and startsWith; the type checker requires has() to dominate such uses on old, so no replace or delete guard can brick documents that predate a property. Referenced property types resolve at evaluation time against the referenced contract's current version; schema compatibility forbids removal or retyping there, so presence is the only drift. Nothing traps: every failure is GuardEvaluationError.

Generations and stack bounds

Stored contracts are re-parsed from raw document_schemas on every cache miss (DataContract::versioned_deserialize, packages/rs-drive/src/drive/contract/get_fetch/fetch_contract/v0/mod.rs:81,138) under the current PV's generation, not the admitting one. A stored guard that fails a later grammar is ProtocolError, so Err on every transition and query touching the contract, on every node: a permanent liveness failure for that contract, or the chain if it is a system contract. Rule: grammar, type rules, unit table and evaluator are generations inside rs-platform-guards, selected by a guards field beside try_from_schema in DPPContractVersions (dpp_contract_versions/v6.rs:14-20 states the discipline); generation N+1 must parse everything generation N accepted into an identical typed AST (builtins and reserved words only extend), pinned by a stored-guard corpus replayed through every later generation. A guard-load failure on a stored contract is a consensus-halting bug class and a fault-injection criterion.

Stack: on the check_tx (gossip) path validate_basic_structure runs before signature verification (packages/rs-drive-abci/src/execution/validation/state_transition/check_tx_verification/v0/mod.rs:163 under CheckTxLevel::FirstTimeCheck at :85, with validate_identity_signed_state_transition only at :195); in block execution the order is reversed (processor/v0/mod.rs:60, then :150). So an unsigned 20 KiB contract (max_state_transition_size, system_limits/v4.rs:23) with ~10,000 nested ( or unary levels would be parsed by every node that gossips it, and overflow aborts, invisible to catch_unwind and error classification. The lexer counts paren and unary depth before any recursive call and rejects above max_guard_expression_depth (64, SYSTEM_LIMITS_V6); type checker, cost pass and evaluator are iterative over a flattened AST; parser tests run under a deliberately small thread stack.

Static cost, read cap, fees

Registration type-checks each guard and sums a per-node unit table, rejecting above max_guard_static_units (1024), max_guard_ast_nodes (256), max_guards_per_document_type (4), max_guard_document_reads (Some(10), Firestore's number) and max_guard_expression_depth (64). The read cap counts deref evaluations only, the grammar's single read form at PV16; it exists so that the reserved feed and lookup extensions inherit an accounted budget instead of opening a new one. Every fallback bound is a row in a guards sub-table on FeeVersion (FeeGuardVersion, section 12; the struct is at fee/mod.rs:35-48): string_fallback_bytes (5120), array_fallback_items, unit_price, guard_read_reservation; maxLength is Option<u16> (property/mod.rs:73-76) and max_field_value_size is PV-keyed, so a SystemLimits fallback would tie units to PV and change gas_used on replay. Per node: a string costs min(4 x maxLength, string_fallback_bytes); in costs list length times the element bound; size() and startsWith cost the operand bound. Execution charges the static count via ValidationOperation::GuardEvaluation(units) (execution_operation/mod.rs:74-87) at unit_price (1000 credits; a 30-node guard is about three fetch_identity_balance_processing_cost lookups, fee/processing/v1.rs:4); deref bills actual GroveDB cost via PrecalculatedOperation (dpns/v1/mod.rs:265-279 pattern). Registration bills a per-guard fee plus a ProtocolValidationOperation variant (rs-dpp validation/operations.rs:5-9), paid again on update (execution_event/mod.rs:328-334). Rejected: a runtime meter, which ties fees to short-circuit order.

check_tx: CheckTx and RecheckTx skip batch state validation (batch/mod.rs:45-55), where guards run, so read costs would never reach gas_wanted (total_base_fee, abci/handler/check_tx.rs:66-70). An identity funded to the compute estimate would pass check_tx, cause ten 5 KiB reads plus contract fetches at block time, then fail validate_fees_of_event (validate_fees_of_event/v0/mod.rs:145-160) into an unpaid drop: the PV11 free-read shape the _v1 triggers closed. Rule, one push site per mode: the transformer runs in every mode with the outer execution context and receives validation_mode (transform_into_action_v1 today, batch/mod.rs:86-92), and pushes GuardEvaluation(units) for the guards firing on each action plus guard_read_reservation (a full-size document read plus a contract fetch) times their deref count only where should_validate_batch_valid_against_state is false (batch/mod.rs:45-55: CheckTx, RecheckTx, NoValidation); in Validator mode it pushes neither and the state generation pushes that unit count plus the actual read costs. No guard is charged twice; units reach gas_wanted and gas_used alike, gas_wanted >= gas_used always, equal for read-free guards.

Execution-time gate, the PV16 instance of 11.2.3's one bound per phase. check_tx prices each transition against the last committed balance with no mempool-level decrement (execution/check_tx/v0/mod.rs:179-186), so several transitions from one identity pass it against the same balance, and the post-validation check (validate_fees_of_event/v0/mod.rs:145-160, reached from execute_event/v0/mod.rs:101-104) runs after the guards have been evaluated and the reads done: an identity funded for the first transition alone would have the rest evaluated for free and dropped unpaid, the shape 08.2.6 closes for hooks one PV later. So validate_state_v1 receives the signer's PartialIdentity (loaded at processor/v0/mod.rs:55 and already handed to validate_advanced_structure_from_state at :296-300; the plumbing 08.2.6 needs at PV17, done once here) and, immediately before the first guard runs, requires balance - accrued >= G. G is the transition's guard bound: the sum over its document actions of the static units of the guards firing times unit_price plus the deref count times guard_read_reservation, plus the metered cost of the nonce-bump action, computed from the parsed DocumentTypeV4 with no guard evaluated; accrued is the fold of the execution context's operations so far; both sides after apply_user_fee_increase, in the order validate_fees_of_event applies (v0/mod.rs:136-139). A shortfall is InsufficientBalanceForGuardEvaluation (a StateError in the Phase 2 code block), pushed with BumpIdentityDataContractNonce and charged the affordable minimum, no guard evaluated and no read performed; the unpaid path stays reachable only for a balance that cannot cover the bump itself, which the minimum-balance pre-check (processor/v0/mod.rs:170-185) leaves to same-block drain. G is the D10 name for this bound; 08.2.6's B and 10.2.4's max_fee are its successors.

Per-block bound: 4 x 1024 units per transition at <= 50 ns per unit on the reference validator (calibration test) is 0.2 ms, below one signature verification. A 2 MiB block (max_bytes 2,097,152, packages/dashmate/configs/defaults/getBaseConfigFactory.js:435) holds ~8,000 batch transitions at an assumed 256-byte floor (owner id, contract id, document id and entropy are 128 bytes of that, before signature and nonces), so ~1.6 s worst case; the tree pins no floor, so the calibration test measures the smallest guard-bearing batch transition and the bound is recomputed from it. proposer_tx_processing_time_limit (abci/config.rs:39) is proposer-local, and Drive never reads the Tenderdash block max_gas (:436; its only occurrence in packages/rs-drive-abci is a captured InitChain request at replay/log_ingest.rs:1109), so nothing in this repository bounds validator work per block. Section 6's max_block_processing_credits is therefore a declared prerequisite: the static bound alone is not sufficient.

Fee registry precondition, owned by section 12: FEE_VERSIONS is &[FEE_VERSION1] (fee/mod.rs:32) while FEE_VERSION2 (PV9 through 14) declares number 1 (fee/v2.rs:13), FeeVersion::get indexes FEE_VERSIONS[number - 1] (fee/mod.rs:53-55), and previous_fee_versions persists numbers only (EpochIndexFeeVersionsForStorage, packages/rs-dpp/src/fee/default_costs/mod.rs:16). Guards cannot be priced until a second fee version is registered and resolvable, so section 12's repair is a merge gate here, and whichever numbering it settles must leave refunds for stored epochs provably unchanged: v1 and v2 differ only in data_contract_registration and refunds read StorageDiskUsageCreditPerByte (rs-dpp fee_result/refunds.rs:60), identical in both, but packages/rs-drive/src/fees/op.rs:280 branches on fee_version_number == 1 and its other arm takes CorruptedCodeExecution when previous_fee_versions is None, an Err on a consensus path. Field additions are invisible to persisted state because only the number is stored. Per section 14.2 the guards sub-table lands on the PV16 fee generation, FEE_VERSION4, its number following section 12's single decision.

Placement

guards is a document-type keyword, [{name, kind: permit|forbid|require, on: [actions], since?, expr}], admitted by a new meta-schema v5 (v4 is closed to new top-level keys and freezes once the release carrying PV15 ships, the discipline the v3 schema states at document-meta.json:4 and enforces at :969), which closes the kind and on enums, requires a non-empty on and unique names per document type; a create guard naming old or a delete guard naming new is a registration BasicError. v5 keeps the v1 $id verbatim: enrich_with_base_schema injects it as every PV12+ document schema's $schema (document_type/schema/enrich_with_base_schema/v1/mod.rs:6-7), so a /v5/ id would be wire-visible; v5 gets the same $id equality assertion and enrich_with_base_schema is not versioned here. Generation 5 reads the keyword before parse_document_type_core (the try_from_schema/v3/mod.rs:242-246 pattern) into DocumentTypeV4. Keyword, not a new typed field on a DataContractInSerializationFormatV2 (V1 is current, packages/rs-dpp/src/data_contract/serialized_version/v1/mod.rs:27) or a DataContractConfig flag: document types are re-parsed from raw JSON on every load (packages/rs-dpp/src/data_contract/v1/serialization/mod.rs:155-167; v0/serialization/mod.rs:92,138) and every SDK already sees document_schemas.

Admissible guarded type, the rule section 08.2.2 rule 6 states for modules and this phase states first: a document type may declare guards only if every write to its documents reaches the batch seam where guards run. Two features put a write elsewhere, and each is a registration BasicError on a type declaring guards: a contested index (Index.contested_index, document_type/index/mod.rs:442), whose winning document is inserted by award_document_to_winner from the check_for_ended_vote_polls block event (execution/platform_events/voting/check_for_ended_vote_polls/v0/mod.rs:279; award_document_to_winner/v0/mod.rs:18), and tradeMode: Auction (6.5), whose settlement changes the document's owner and pays out from the 6.5 drain, a block event with no transition to charge and no nonce to bump. In both the write lands where no guard runs and any Err halts the node (11.2.2), and a guard enforced at registration and never at the write that lands is worse than no guard; an admitted transfer guard on an auction type would constrain every transfer except the one settlement performs. Lifting the auction exclusion later is feasible because guard cost is static (a settlement could prepay the guard units at scheduling and run the guards in the drain), but it needs a defined outcome for a settlement the guards reject, so it is deferred and the auction chapter states the exclusion. Two more registration rules. An indexOnly type has no stored document, so nothing binds old and no stamp exists to compare since against: it admits create guards only, and an on: [delete] guard on it is a BasicError at PV16 (08.2.4 (c) defines a delete context for modules; guards may adopt it in a later generation). No system data contract carries guards: they have no user update path and their rules stay native triggers, so the 6.4 and 6.5 system contracts, DPNS and withdrawals are untouched by this phase and by any freeze of it.

Governance reads (11.2.6 owns the registry): from PV16 a contract create or update whose document types carry guards reads the deployer allowlist in ContractGovernance, the system contract created by transition_to_version_16; an identity absent from the allowlist is a StateError rejection (GuardDeployerNotAllowedError) with the point read billed as PrecalculatedOperation, so the rejection is paid. The read is state-dependent, so it lands in a new data_contract_create/state/v2 and data_contract_update/state/v2 behind contract_create_state_transition.state: 2 and contract_update_state_transition.state: 2 (both are 1 today, drive_abci_validation_versions/v10.rs:102, :110). Evaluation reads the same registry once per transition touching a guard-bearing document type, on 11.2.6's per-run model: a frozenGuard document for that contract id, or an unexpired globalFreeze, rejects every action that any guard of that document type names in on, paid (GuardFrozenError, nonce bumped, no guard evaluated and no read performed), while actions no guard names proceed. A freeze rejects rather than suppresses, for three reasons. A guard is an application invariant (a balance field that may only decrease, a claim that may happen once), so a write admitted while the guard is switched off leaves state the guard would have rejected, and that state survives the unfreeze; restoring native validation restores no such invariant. Under suppression a stolen freeze key would switch off every guard on the network for the freeze's duration, an extraction tool, where under rejection it is the self-expiring denial of service 11.2.6 already accepts. And the case suppression was drafted for, a guard that wrongly rejects everything, needs no freeze at all: the contract owner removes the guard by DataContractUpdate (removal is always admitted, below) and the writes proceed by the owner's explicit decision. The freeze is therefore the evaluator's kill switch, not the application's, its cost is that guarded writes pause until the unfreeze, and its recovery authority is exactly two paths: unfreeze under 11.2.6's thresholds, or guard removal by the contract owner. Deletes are not exempted: a delete restriction is the guard most worth holding during an incident (deleting the record that says a claim happened re-enables the claim), the freeze is reversible by design (globalFreeze expires, frozenGuard is a document), and a contract whose owner is gone and whose guard stays frozen strands its documents exactly as forbid true on delete would, which the since rule below already confines to documents created under that guard. Section 08.2.5 applies the same rule to a frozen module.

Updates (validate_update v2, v1's freezes kept): documentsMutable, canBeDeleted, creationRestrictionMode and tradeMode are frozen (document_type/methods/validate_update/common/mod.rs:92-226) so an owner cannot change the rights of documents other identities own; a freely editable on: [delete] guard would bypass that (forbid true: every document undeletable, prepaid storage never refunded). Rule: a create guard is freely editable (future documents only); a guard on an existing-document action (replace, delete, transfer, updatePrice, purchase) carries since, no lower than the contract version installing it (lower is a registration BasicError, so no guard reaches back) and defaulting to that version, applies only to documents whose $createdAtContractVersion is at or after it, and may be removed but not edited (an edit is a removal plus a new name with a fresh since). The stamp is new, immutable, and not $contractVersion. That stamp records the contract version a document's bytes last conformed to, so the replace conversion re-stamps it with the current version (actions/document_replace_transition_action/v1/mod.rs:45-49, as requiredSince needs), and keying since on it would let an ordinary replace under version 2 pull a version-1 document under version 2's delete prohibition. $createdAtContractVersion is written once by the PV16 create conversion (generation 2 of actions/document_create_transition_action, beside v1's $contractVersion stamp), copied verbatim from the fetched original by the PV16 replace conversion, and carried unchanged by transfer, updatePrice and purchase, whose actions keep the stored document and re-stamp nothing today. It rides document serialization format 4 (DOCUMENT_VERSIONS_V5 raising document_serialization_version to 4, opened at PV16 as format 3 was at PV14, packages/rs-platform-version/src/version/v14.rs:216), one varint after the $contractVersion stamp, 0 meaning absent; format 3 and older documents decode as absent, stay absent when a PV16 write re-serializes them, and an absent stamp never satisfies since. That is exact, not merely conservative: every document created before PV16 predates every guard, so no since guard may ever apply to it. Bug fixes stay possible; existing documents keep their rights and are never re-validated. Rejected: keying since on $contractVersion; freezing all guards; ChangeControlRules governance (Phase 3).

Seam, errors, SDKs

batch_state_transition.state has one arm (0 => validate_state_v0, batch/mod.rs:227-258); batch/state/v1/mod.rs is the PV12 transformer variant (transform_into_action_v1, selected by transform_into_action, batch/mod.rs:71-99), not a state version. So state bumps 0 to 1 in DRIVE_ABCI_VALIDATION_VERSIONS_V12, arm 1 => validate_state_v1 lives in a new batch/state/validate_state_v1/mod.rs, and state/mod.rs documents the naming. It runs guards after per-action validate_state and data triggers (batch/state/v0/mod.rs:317-322), never behind execution.use_document_triggers (:279); rejection pushes BumpIdentityDataContractNonce (:333-340), so the transition stays paid.

old per action: replace and the transfer family take the original from the transformer (batch/transformer/v0/mod.rs:797, :882, already billed). The replace action drops it (actions/document_replace_transition_action/v0/mod.rs:16-45) and gains original_document; transfer, updatePrice and purchase actions already carry document: Document built from that original (document_transfer_transition_action/transformer.rs:16-35), from which new derives. Delete fetches nothing in the transformer (:849-858; the action is base only, document_delete_transition_action/v0/mod.rs:8-10); its original is fetched inside validate_state (batch/action_validation/document/document_delete_transition_action/state_v0/mod.rs:74, fetch_document_with_id, billed as PrecalculatedOperation on transform 1+, batch/state/v0/fetch_documents.rs:225-260) and discarded. Delete's state_v1 hands that document to the guard runner instead of moving the fetch (no billing change); a missing document short-circuits with the existing consensus error before any guard runs.

Errors: StateError::GuardRejectedError, GuardEvaluationError, GuardDeployerNotAllowedError, GuardFrozenError and InsufficientBalanceForGuardEvaluation, appended (rs-dpp errors/consensus/state/state_error.rs:77-81, whose variant order is frozen by test) with codes drawn from the Phase 2 block in section 12's single allocation of the four phase code ranges; registration failures are BasicError variants; no path returns Err, which is InternalError and rejects the block (process_proposal.rs:285-308).

Type-checking is split: local structure (grammar, member access, unit sum, same-contract deref targets) lives in rs-dpp under validation, so DataContract::from_value(.., full_validation, ..) (packages/wasm-dpp2/src/data_contract/model.rs:257) and rs-sdk reject bad guards client-side; cross-contract deref targets resolve in drive-abci for contract create and update inside validate_data_contract_references (data_contract_common/data_contract_reference_validation/v0/mod.rs:59-153, one billed fetch per foreign contract), a missing or non-permanent target being a BasicError. Mobile sends schema JSON through one FFI entry (platform_wallet_create_data_contract_with_signer, packages/rs-platform-wallet-ffi/src/data_contract.rs:22), so no FFI change (section 13).

Tasks

Evaluator crate

• Create packages/rs-platform-guards (new, no_std plus alloc): depth-counting lexer, parser, flattened typed AST, iterative type checker, cost pass and evaluator as generation 1; no non-workspace consensus dependencies; wasm32 build in CI.
• Publish grammar (member-access forms, the meta-schema property-name space including nested object keys, per-action binding availability, reserved words feed and lookup), semantics and unit table as a normative DIP appendix (section 5), pinned by crate tests and a differential harness (cel-spec v0.25.1 generator, cedar-policy oracle; dev-dependencies only).

rs-dpp (PV16)

• Add a new meta-schema document/v5/document-meta.json admitting guards, v1 $id verbatim; arm 5 in select_document_meta_schema (try_from_schema/common/mod.rs:284-301).
• Add a new try_from_schema/v5 generation and dispatcher arm 5 (try_from_schema/mod.rs:47-113), DocumentTypeV4 with getters and DocumentTypeRef arms, the guards generation field in DPPContractVersions.
• Add document serialization format 4: serialize_v4 and its decoder beside packages/rs-dpp/src/document/v0/serialize/v3.rs carrying $createdAtContractVersion after the $contractVersion stamp, the created_at_contract_version: Option<u32> field and accessors on DocumentV0, DOCUMENT_VERSIONS_V5 with document_serialization_version max 4; every consumer that decodes document bytes from proofs (rs-drive verify, wasm-dpp2, the mobile FFI) follows the format 3 precedent.
• Add validate_update/v2 with the since rule (no lower than the installing version, keyed on $createdAtContractVersion), the contested-index and tradeMode: Auction exclusions, the indexOnly create-only rule, registration_cost/v2, ProtocolValidationOperation::DocumentTypeGuardValidation, and the StateError and BasicError variants with codes.

Version tables (PV16)

• CONTRACT_VERSIONS_V8 (document_type_schema: 5, try_from_schema: 5, guards: 1, validate_update: 2, registration_cost: 2) and DPP_VALIDATION_VERSIONS_V6, wired from a new v16.rs together with DOCUMENT_VERSIONS_V5; SYSTEM_LIMITS_V6 with the five guard limits.
• Fee registry repair (section 12) as a merge gate, then FEE_VERSION4 with the guards sub-table, registration v3, validation v2.
• DRIVE_ABCI_VALIDATION_VERSIONS_V12: batch_state_transition.state: 1, batch_state_transition.transform_into_action: 2, contract_create_state_transition.state: 2, contract_update_state_transition.state: 2 and new document action versions; extend TEST_PLATFORM_V2 and TEST_PLATFORM_V3 (mocks/v2_test.rs:61, mocks/v3_test.rs:45).

rs-drive, drive-abci, SDKs (PV16)

• Create and replace conversions at generation 2 (stamping $createdAtContractVersion on create, copying it from original_document on replace, selected by the PV16 table beside format 4); replace action with original_document, delete state_v1 returning the fetched document; add arm 2 => transform_into_action_v2 in batch/mod.rs:71-99 with the body in a new batch/state/v2/mod.rs (bodies for 0 and 1 are at batch/state/v0/mod.rs:57 and batch/state/v1/mod.rs:25), pushing GuardEvaluation(units) and the read reservation from the per-transition helpers in batch/transformer/v0/mod.rs (try_into_action_v0 :203, transform_document_transition_v0 :737) only when batch state validation is skipped; validate_state_v1 receiving the signer's PartialIdentity, with the G gate before the first guard, the unit push, PrecalculatedOperation reads and bump-nonce rejection.
• Cross-contract deref resolution in validate_data_contract_references for create and update; the deployer allowlist read in the new contract create and update state generations, with frozenGuard and globalFreeze rejecting every guarded action before evaluation (11.2.6).
• Map the new codes in packages/wasm-dpp2/src/consensus_error.rs, rs-sdk and packages/js-evo-sdk, so a TypeScript consumer sees the guard rejection code rather than a generic error, and add the row to docs/sdk/sdk-parity-manifest.json.
• Mobile: a contract with guards round-trips through Swift persistence (packages/swift-sdk/Sources/SwiftDashSDK/Core/Utils/DataContractParser.swift reads only properties, indices and required) and the Kotlin Room entity (packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/entities/DataContractEntity.kt:55, schemaData passthrough) with the array intact, and both create paths (packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift:3386 documentSchemasJSON, packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/IdentityNative.kt:242 documentsSchemaJson) submit it unchanged.
• New book chapter book/src/data-model/guards.md, linked from book/src/SUMMARY.md:52: grammar, unit table, limits and the activation PV, reviewed against the DIP appendix.

Tests

• rs-platform-guards proptest: never panics, runs under a small thread stack, evaluated units <= static units, oracle agreement, print/parse round trip over names generated from the meta-schema regex; deep-nesting corpus in the cargo-fuzz target (section 11's nightly workflow) and in a new batch/tests/document/guards.rs; stored-guard corpus replayed through every later generation.
• Golden cost and result vectors per fee version in a new packages/rs-platform-guards/tests/vectors/, run natively in tests-rs-workspace.yml (self-hosted rust-ci, :28), under wasm-bindgen-test, and in a new ubuntu-24.04 plus ubuntu-24.04-arm matrix job copied from release-docker-image.yml:44-47; unit calibration test, including the minimal guard-bearing batch transition size the per-block bound assumes.
• batch/tests/document/guards.rs: permit, forbid, require, overflow, absent field with and without has(), bracket member access, deref per target kind, read cap, gas_used includes units, paid rejection with nonce bumped, identity funded exactly to the compute estimate rejected in check_tx, contract update cannot make another identity's document undeletable, rejection at PV15; exactly one GuardEvaluation operation per firing guard per mode across CheckTx, RecheckTx, Validator and NoValidation; registration rejection for old on create, new on delete, empty or unknown on, duplicate names, and guards on a document type with a contested index; a guard-bearing create from an identity absent from deployer rejected and paid, a frozenGuard document rejecting every guarded action of that contract, delete included, paid with the guard counter at zero, while an action no guard names proceeds, the same for an unexpired globalFreeze, and the owner's update removing the guard restoring the write; create at contract version 1, an update installing a since: 2 delete guard, a replace, then a delete that succeeds ($createdAtContractVersion stays 1 while $contractVersion becomes 2) beside a version-2 create whose delete is rejected, and a format-3 document from a PV15 fixture replaced at PV16 whose delete succeeds; since below the installing version rejected at registration; K transitions from one identity funded for one: the first pays, the rest are InsufficientBalanceForGuardEvaluation at the gate with the guard counter at zero and none Unpaid; on: [delete] on an indexOnly type and guards on a tradeMode: Auction type rejected at registration; contact-request and withdrawal-delete parity fixtures.
• Strategy test with verify_state_transition_results, independent_process_proposal_verification and a golden root hash (strategy_tests/identity_and_document_tests.rs:427-440); PV15 to PV16 upgrade test modelled on strategy_tests/upgrade_fork_tests.rs:559; section 12's fee registry and refund tests green at the PV16 pin (14.2).

Acceptance criteria

• Identical contract bytes with guards: rejected at PV15, accepted at PV16; generation 0 to 4 parsers byte-identical; every parser entry point bounded in stack use independent of input; no evaluator or guard-load failure class yields InternalError under fault injection, a stored guard loaded under a later generation included.
• Static units are a pure function of (schema, guard, fee version); vectors match on amd64, arm64 and wasm32; gas_wanted >= gas_used for every guard batch, equal for read-free guards, with exactly one push site per mode.
• The contact-request and withdrawal-delete rules as guards pass their trigger corpora within 2x the native processing fee; DPNS stays native.
• No action rewrites $createdAtContractVersion; no guard is evaluated for an identity that cannot pay G; a freeze admits no guarded write.

Risks

• Grammar creep: each builtin is consensus surface with a cost row and a generation; contained by the superset rule.
• Static charging over-prices short-circuited guards (accepted for determinism); parse-on-load cost multiplies with contract fetches, bound by max_guard_ast_nodes, measured before activation.
• Format 4 is the second document serialization change in three protocol versions; every decoder follows the format 3 precedent, and the PV15 to PV16 upgrade test covers a format-3 document rewritten in format 4.
• Firestore-style contortion signals Phase 3, not failure; section 12's fee registry repair and section 6's max_block_processing_credits are hard prerequisites.

---

---

Continued in part 8 of 14 below.

[QuantumExplorer]

Part 8 of 14 of the plan (continued from part 7 above).

8. Phase 3: WASM validation predicates

Gate: PV17 in the section 14 schedule (Phase 1 PV15, Phase 2 PV16). Generation numbers come from 14.2: SystemLimits V7, validation V13, contract versions V9 (meta-schema v6, parser generation 6, DocumentTypeV5), FEE_VERSION5 with fee_version_number 5 under section 12's numbering, DriveVersion V11. Names without a repository path are proposals and follow the D10 names table shared with sections 09, 13 and 14: the new crates live at packages/rs-contract-runtime, -abi, -sdk, -sdk-macros, -testutils and -cli, and the published names among them are dash-contract-abi, dash-contract-sdk, dash-contract-sdk-macros, dash-contract-testutils and the CLI dash-contract; host namespace dash_v1 (section 04.7); fee sub-table FeeWasmVersion (section 12).

8.1 Reasoning

Phase 3 is the first stage that runs author-supplied code in consensus: a document type names a module; the module sees one document transition and answers accept or reject(code). No reads, no writes, never in the mempool; a wrong answer misclassifies one transition and cannot diverge state. The seam and billing channel already exist for system data triggers (batch/state/v0/mod.rs:317-340 and batch/data_triggers/triggers/dpns/v1/mod.rs:265-278 under packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions).

Engine: wasmi 2.x at an exact pin (section 04), not the 1.x the research synthesis named: 2.0.0 meters fuel per input Wasm operator (issue #1088, closed by PR #2013) and exposes the table through Config::operator_cost and Config::fuel_cost(CustomFuelCosts) (PR #2025); 1.x ended at 1.1.0 with 1.0.0 and 1.0.1 yanked (CVE-2025-66627); MSRV 1.86 (wasmi v2.0.0 workspace Cargo.toml). Every bump is a consensus event (fuel is only "relatively stable" across versions). Not foreclosed: footprint reads and the check_tx policy (section 09), entry points (section 10).

8.2 Design

8.2.1 Engine integration

• Crate packages/rs-contract-runtime (new) wraps every activated engine behind a HookEngine trait dispatched on wasm_engine_version; rs-dpp never depends on it.
• Pin and coexistence: wasmi 2.0.x from a dashpay fork at an exact revision, default-features = false, features std, validate, deterministic and one explicit dispatch feature (portable-dispatch). The crate's defaults are stable, std, wat, validate, memory64 and auto-dispatch (wasmi v2.0.0 crates/wasmi/Cargo.toml:38); wat, memory64 and auto-dispatch are dropped deliberately, and stable is left off because it is an empty marker feature gating no code (stable = [], :58). Every activated revision stays linked under its own package name (the soroban-wasmi pattern; sections 01 goal 7, 03.11, 11.2.5), because Cargo links one copy per semver-compatible range (=2.0.3 and =2.0.4 cannot coexist) and a node syncing from genesis would otherwise compute different fuel_used, fees and app hashes for PV17 blocks. wasm_engine_version: Option<u16> sits beside grove_version on DriveVersion (packages/rs-platform-version/src/version/drive_versions/mod.rs:40-46) and selects the package, its operator table and its parser pin; a PV18 binary executes PV17 blocks on the PV17 package. Fallback if the section 03.11 corpus shows patch-level drift: install-time instrumentation (a Platform-owned per-basic-block fuel counter injected at prepare, engine fuel kept only as a trap), which makes fuel engine-independent (section 01).
• Consensus Config, every toggle explicit because the defaults enable tail calls, extended const, multi-memory, floats, start functions and lazy translation (wasmi v2.0.0 crates/wasmi/src/engine/config.rs): consume_fuel(true); operator_cost(OperatorCost) (one u8 per operator) and fuel_cost(CustomFuelCosts) from FeeWasmVersion; compilation_mode(CompilationMode::Eager); floats(false), wasm_saturating_float_to_int(false), wasm_tail_call(false), wasm_extended_const(false), wasm_multi_memory(false), wasm_simd(false), wasm_memory64(false); wasm_bulk_memory, wasm_reference_types, wasm_multi_value, wasm_sign_extension and wasm_mutable_global true (8.2.2 rule 1); allow_start_fn(false); enforced_limits(EnforcedLimits::strict()) as a floor only, since 2.0.0 exposes no per-field setters (crates/wasmi/src/engine/limits/engine.rs); set_min_stack_height equal to set_max_stack_height so the value stack is allocated once, before guest entry; set_max_recursion_depth from SystemLimits; StoreLimitsBuilder::memory_size(max_hook_memory_pages * 65536) (bytes, not pages), memories(1), tables(1), table_elements(max_hook_table_elements), trap_on_grow_failure(true). The limiter compares counters against constants and never consults host memory.
• Fixed footprint: prepare requires min == max on the memory and on the table (8.2.2 rule 2), so instantiation allocates everything before guest entry and memory.grow or table.grow never allocate: a positive delta fails against the declared maximum on every node. Allocation failure before guest entry is HostFault (8.2.7).
• Resumable calls (TypedFunc::call_resumable) stay out of consensus: fuel is set to the budget, the call returns or traps, fuel_used = budget - remaining.

8.2.2 Registration-time prepare pass

rs-contract-runtime::prepare runs inside the rs-drive-abci state validation of DataContractCreate and DataContractUpdate (new state generations; validate_data_contract_references at data_contract_create/state/v1/mod.rs:63-70 and data_contract_update/state/v1/mod.rs:65 is the pattern) for each document type naming a module. Not in rs-dpp: full contract validation runs only in Validator mode (data_contract_create/mod.rs:42-49). Order per module: (1) the section 11.2.6 governance reads, deployer allowlist and frozenModule by code hash, billed as in 8.2.5; (2) the 8.2.6 gate with the prepare bound hook_prepare_credit_per_byte * length over the blob length in the section 06 metadata, so an under-funded contract create never reaches translation; (3) fetch the blob, apply the rules, bill the bound as a precalculated operation. Failures are paid StateErrors: ValidationModuleError { kind: PrepareFailed { rule } } returned with BumpIdentityNonceAction, the data_contract_create/state/v1/mod.rs:73-79 convention. The state phase can return a BasicError (data_contract_update/state/v0/mod.rs:142 returns DataContractNotPresentError beside a bump action), but 11.2.3's rule holds: anything that needs wasm validation to classify is a paid, named StateError, never a BasicError.

The rules run over a wasmparser pass exact-pinned in rs-contract-runtime at the version wasmi 2.0.0's 0.228.0 workspace requirement resolves to (a second copy beside the tree's 0.244.0, Cargo.lock:8899-8900), with wasmi's toggles set to the same allowlist so pass and engine agree; the parser pin joins the golden suite and moves only with a PV. The custom section is decoded by rs-contract-abi's own decoder.

1. Feature set: MVP plus sign-extension, mutable-globals, bulk-memory, reference-types and multi-value. The last three are on by default for wasm32-unknown-unknown in rustc 1.92 (rustc --print cfg; the prebuilt core and alloc carry them, and a hello-world hook lowers copy_nonoverlapping to memory.copy), so an MVP-only rule is unreachable from the stable toolchain. All three are deterministic; bulk copies are metered per byte through CustomFuelCosts::bytes_copied_per_fuel, the operators through OperatorCost. Reject floats (nontrapping-fptoint is moot without them), SIMD, threads, multi-memory, memory64, tail calls, extended const, exceptions, GC, and custom sections other than dash-contract-abi and name.
2. One memory, defined not imported, min == max <= max_hook_memory_pages (proposal 16); at most one table, min == max, elements <= max_hook_table_elements; code <= max_hook_code_size (proposal 256 KiB, at most the section 06 blob cap of 256 KiB); caps on functions, locals, globals, data and element segments, imports, exports and types from SystemLimits.
3. Imports only from the PV allowlist of dash_v<n> namespaces (section 04.7); PV17 grants exactly dash_v1.context_len and dash_v1.context_read. Exports: exactly memory and validate: () -> i32; no start. Verified on rustc 1.92: a release cdylib for wasm32-unknown-unknown exports exactly those two names, with or without --strip-all and equal memory link args, and the linker's own globals stay internal, so the rule needs no allowance for them.
4. Custom section dash-contract-abi = bincode (abi_version: u16, target_protocol_version: u32, capabilities: Vec<u16>); accepted iff abi_version is in the PV's accepted set and equals the keyword's abiVersion (8.2.3), target_protocol_version <= active PV (Soroban's contractenvmetav0 rule) and capabilities is empty in v0.
5. Eager translation under the consensus Config succeeds; the artifact is discarded.
6. Admissible hooked type: a module is accepted only on a document type whose every write reaches the seam. Rejected, each under its own rule id and each a paid PrepareFailed { rule } with a unit test: a contested index (contested_index on Index), whose winning document is written by the vote-poll block event (packages/rs-drive-abci/src/execution/platform_events/voting/award_document_to_winner/) and not by a DocumentAction; documents_keep_history, whose retained revisions are outside the v0 context; trade_mode: TradeMode::Auction (Phase 1, section 06.5), settled from the block-event drain; non-empty token_costs, whose token debit is settled outside the seam. Admitted: TradeMode::None and TradeMode::DirectPurchase, so purchase and price updates still reach the seam through their own transitions, and index_only types, whose delete context 8.2.4 (c) defines. System data contracts are excluded by construction: no validationModule, no user update path.

8.2.3 Module storage and document-type reference

• Bytes live in the section 06 hash-addressed blob store under RootTree::CodeBlobs: fetched and proved through the section 06 prove_elements v1 range proof (GetPathElementsRequestV1), the storage owner recorded in the metadata element and chunk elements carrying the uploader's StorageFlags, immutable, shared by hash, reference-counted through code_blob_references in DataContractConfig (a referenced blob cannot be deleted).
• Reference: document-type keyword validationModule: { "codeHash": <32 bytes>, "abiVersion": 0, "maxFuel": <u64> }, admitted by meta-schema v6 and parsed by try_from_schema generation 6 into DocumentTypeV5 (generation rule at dpp_contract_versions/v6.rs:14-20). The parser rejects maxFuel == 0 and maxFuel > max_hook_fuel_per_call through the DataContractError channel that surfaces as BasicError::ContractError (packages/rs-dpp/src/errors/consensus/basic/basic_error.rs:136) and stores the effective budget in ValidationModuleRef { code_hash, abi_version, budget }; the keyword's abi_version is authoritative at run time (the seam already holds the contract) and selects the context type, HookContextV0 for 0. Rejected: a run-time clamp, under which a u64::MAX keyword saturates in the check_tx estimate while the block path clamps, so mempool and block disagree on affordability for a whole document type.
• Update policy: validationModule and the property schema of a module-bearing type are frozen like trade_mode and index_only (document_type/methods/validate_update/common/mod.rs:107-115, :357-365), since the module was compiled against that schema; an update may attach a module only to a type it adds. DataContractUpdate re-runs 8.2.2 for every module-bearing type, added or not (blob present, ABI accepted, prepare under the current engine package), so a module retired by a later PV fails at update, not at run time. The freeze is the PV17 rule sections 04.7 and 13 restate: in-place replacement, Delete { hash } on replacement and ChangeControlRules governance belong to the PV19 entry_module and its change_rules (10.2.8). Author-facing consequence and recovery recipe: 8.6.
• Fee: document_type_validation_module_fee in the next FeeDataContractRegistrationVersion (fee/data_contract_registration/mod.rs:10-16), charged per module-bearing type on create and on every update, which re-prepares each of them.

8.2.4 ABI v0

Shared crate packages/rs-contract-abi (new; published as dash-contract-abi, no_std + alloc), compiled by host and guest, bincode 2 under the platform-serialization configuration (standard, big-endian) over section 13's platform-value-core split (Value without Float).

// packages/rs-contract-abi/src/v0.rs  (proposed names and shapes)
#[derive(Encode, Decode)]
pub struct HookContextV0 {
    pub abi_version: u16,
    pub op: DocumentOp,                     // seven document kinds
    pub owner_id: [u8; 32],
    pub contract_id: [u8; 32],
    pub document_type: String,
    pub document_id: [u8; 32],
    pub old_document: Option<DocumentWire>,
    pub new_document: Option<DocumentWire>,
    pub op_data: OpData,                    // recipient or price
    pub block: BlockRef,                    // last committed block: height, time_ms, core_height, epoch
    pub capabilities: Vec<u16>,             // empty in v0; Phase 4 channel
}
// DocumentWire: owner_id, revision, timestamps, properties: BTreeMap<String, Value>
// (an F64 property travels as Value::Bytes of f64::to_bits, big-endian; see (g))

// Guest side: two imports in namespace dash_v1, one export.
extern "C" { fn context_len() -> i32; fn context_read(dst: i32, cap: i32) -> i32; }
#[no_mangle] extern "C" fn validate() -> i32 { /* 0 accept, 1..=65535 reject code */ }

(a) Pull, one shot: the guest calls context_len, sizes a buffer, and calls context_read exactly once with cap >= context_len; a second call or a short cap is InvalidResult, a destination outside memory traps (8.2.7). No exported allocator to trust, and the copy is priced once per context byte (8.2.6), so no import can be looped for uncharged host work; section 09 prices its own imports per call. (b) block is last_block_info() on the seam's PlatformStateRef (platform_types/platform_state/accessors.rs:114), not the block_info being processed, so any future check_tx path sees the same view (check_tx/v0/mod.rs:180); new_document timestamps carry the current block's time, a one-block lag the SDK documents. (c) old_document is None for Create and for IndexOnlyDelete (index-only types store no document; the action's index values, DocumentIndexOnlyDeleteTransitionActionV0::data at packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_index_only_delete_transition_action/v0/mod.rs:14, travel in op_data), present for the other five kinds; section 07's action versions retain it. (d) One i32 result: 0 accept, 1..=65535 an author code carried verbatim in the consensus error, anything else InvalidResult. (e) No emit or log import: state is the event log (section 06). (f) abi_version first; new fields only as HookContextV1 under a later PV; capabilities is the Phase 4 channel. (g) Floats: DocumentPropertyType::F64 exists (packages/rs-dpp/src/data_contract/document_type/property/mod.rs:170) and Value::Float(f64) with it (packages/rs-platform-value/src/lib.rs:136). DocumentWire carries such a property as the eight big-endian bytes of f64::to_bits, an infallible integer conversion, so no host-side conversion can fail and no field is dropped; the guest sees opaque bytes (sections 09.2.2, 11.2.1) and section 13's codegen refuses to type them. Rejected: refusing modules on types with an F64 property, which section 09's reads of other types would reopen. A golden vector covers every DocumentPropertyType.

8.2.5 Invocation seam and check_tx

Seam: the next batch/state generation, selected by batch_state_transition.state in validation V13, plus a new hook_execution: OptionalFeatureVersion on DriveAbciDocumentsStateTransitionValidationVersions (drive_abci_validation_versions/mod.rs:186-191; the OptionalFeatureVersion fields of DriveAbciStateTransitionValidationVersion at :107-114 are the pattern), Some(0) at PV17. None maps every hook-bearing transition to ModuleUnavailable { DisabledByProtocolVersion }, paid: section 11.2.6 layer 1. The generation runs after the trigger loop, for every action still present as a DocumentAction of the seven document kinds whose type names a module (an action a trigger or guard already rewrote to BumpIdentityDataContractNonceAction is skipped); token actions are out of scope. Rejected: seven per-action seams. Never gated on node config: execution.use_document_triggers (packages/rs-drive-abci/src/config.rs:92-93) is the anti-pattern. Per run, in order:

1. Governance reads (section 11.2.6 layer 2): frozenModule by code hash, frozenContract by contract id, globalFreeze, as point reads on the ContractGovernance contract through the block transaction (tx at the seam), so a freeze committed earlier in the same block binds the next transition; no cross-transition cache; billed as a PrecalculatedOperation at the query's own cost, the dpns v1 shape (data_triggers/triggers/dpns/v1/mod.rs:265-278). A hit is ModuleUnavailable { Frozen }. 11.2.6 owns this read model and 8.4's kill-switch test asserts it; 04.2's load-once-per-block cache is superseded, since a cache filled at block start cannot see a freeze landed earlier in the same block.
2. The 8.2.6 gate against the signer's balance; failure is InsufficientBalanceForHookExecution (the 11.2.3 variant, in this section's code block) pushed with BumpIdentityDataContractNonce, charged the affordable minimum, and never instantiates the engine.
3. Blob fetch with its section 06 metadata. Absence is Err(ExecutionError::DriveIncoherence) (packages/rs-drive-abci/src/error/execution.rs:89): a referenced blob cannot be deleted, so absence is corruption, not a user condition. A failed_under engine marker (8.2.7) is ModuleUnavailable { TranslationFailed } without touching the engine.
4. run_hook through the node-local cache: a bounded LRU keyed by code hash and wasm_engine_version, measured in translated bytes with a documented default (proposal 64 MiB); a hit or miss changes neither result nor charge, only time.

Unavailability fails closed, with one exemption keyed to permanence. A frozen module (frozenModule, frozenContract or globalFreeze) rejects all seven kinds paid, deletes included: a freeze is the incident switch and is reversible by design, so it must not open a window in which the module's delete restriction (the record that says a claim happened, the escrow marker) is unenforced while the invariant it protects is exactly what the incident concerns; section 07 states the same rule for frozenGuard and the reasons behind it. For the permanent reasons (a failed_under translation failure, ABI retired, hook_execution: None), Delete and IndexOnlyDelete proceed without invoking the module, so prepaid storage stays recoverable and no document is stranded: those are protocol-version events announced in advance, not incidents, and stranding storage forever is the worse outcome there. The other five kinds are rejected paid under every reason: transfer, purchase and price updates go with the writes, because they are the rights a module exists to constrain. Cost, stated rather than hidden: under a permanent unavailability a module's own delete restriction is unenforced, and under a freeze the type's documents cannot be deleted until the unfreeze.

check_tx: batch validate_state never runs in the mempool, so hooks stay out of it. validates_full_state_on_check_tx() is false by default (packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/state.rs:53-55) with masternode_vote its only override (state_transitions/masternode_vote/mod.rs:90), and check_tx calls validate_state only for transitions that override it (check_tx_verification/v0/mod.rs:320-329); ValidationMode::should_validate_batch_valid_against_state (batch/mod.rs:45-55) is a second, narrower guard, passed as the full_validation argument to try_into_action_v0 (batch/state/v0/mod.rs:374, batch/state/v1/mod.rs:76), so the mempool transformer does not validate actions against state either. Mechanism: the next batch transform_into_action generation (slot at drive_abci_validation_versions/mod.rs:191, arms 0 and 1 at batch/mod.rs:71-98) pushes ValidationOperation::HookExecution { fuel_used: budget, code_len, pages, context_len } for every document action whose type names a module, in CheckTx and RecheckTx mode only (Validator records the actual run at the seam), so the dry-run fold (execution/check_tx/v0/mod.rs:179-186) prices the bound B of 8.2.6 into affordability and gas_wanted; budget is ValidationModuleRef.budget, already capped at parse time (8.2.3). Priority is user_fee_increase times a multiplier (check_tx/v0/mod.rs:151-152), unaffected.

// packages/rs-contract-runtime/src/hook.rs  (proposed)
pub enum HookOutcome { Accept, Reject(u16), Trapped(TrapKind), OutOfFuel, InvalidResult, Unavailable(UnavailableReason) }
pub struct HookRun { pub outcome: HookOutcome, pub fuel_used: u64 }
pub fn run_hook(engine: &HookEngine, module: &PreparedModule, ctx: &HookContextV0,
                budget: u64, limits: &HookLimits) -> Result<HookRun, HostFault>;
// HostFault: allocation failure before guest entry and engine-internal invariants only (8.2.7);
// it maps to InternalError on purpose and nothing a module or its author does can reach it.

8.2.6 Fees, bounds and the block budget

• Rates in FeeWasmVersion (section 12) on FeeVersion (packages/rs-platform-version/src/version/fee/mod.rs:34-47), in the PV17 fee generation FEE_VERSION5 with fee_version_number: 5 appended to FEE_VERSIONS (mod.rs:32): credits_per_fuel; OperatorCost and CustomFuelCosts; hook_instantiate_base, hook_translate_credit_per_code_byte, hook_memory_credit_per_page; hook_context_credit_per_byte; hook_prepare_credit_per_byte. Section 12 owns the numbering and regenerates its constants table from 14.2 (task in 8.3); the number is load-bearing: refunds branch on fee_version_number == 1 and otherwise take CorruptedCodeExecution when previous_fee_versions is None (packages/rs-drive/src/fees/op.rs:280-292), a halt inside a block event.
• Bound per run, known before instantiation from the blob metadata, the module header and the encoded context: B = hook_instantiate_base + hook_translate_credit_per_code_byte * code_len + hook_memory_credit_per_page * pages + hook_context_credit_per_byte * context_len + budget * credits_per_fuel, budget being ValidationModuleRef.budget; every multiply is checked_mul into ExecutionError::Overflow, the add_many_to_fee_result pattern (execution_operation/mod.rs:97-200). B is the D10 name for this quantity at PV17 and PV18; 11.2.3's floor(tx) is the same thing under the other name. Rejected: a flat instantiation fee, under-priced exactly for the largest modules (eager translation of 256 KiB on a cache miss, zeroing 1 MiB of memory).
• Bound check then charge actuals (section 12; section 01 rule (b)). The affordability check after validation (validate_fees_of_event/v0/mod.rs:115-160) is too late for a hook: an unaffordable event executes as UnpaidConsensusExecutionError (execute_event/v0/mod.rs:101-103), no charge and no nonce bump, and check_tx prices each transition against the last committed balance (check_tx/v0/mod.rs:179-186), so one balance admits N sequential-nonce transitions of which N-1 would run to budget for free. So (1) the seam receives the signer's PartialIdentity (balance loaded at processor/v0/mod.rs:55, handed over as validate_advanced_structure_from_state already receives it, :296-300) and requires balance - accrued >= B + nonce-bump cost, both sides after apply_user_fee_increase as in validate_fees_of_event (validate_fees_of_event/v0/mod.rs:136-139), accrued being the fold of the execution context's operations so far; (2) once the engine is entered the run is charged whatever the rest of the transition does: the PV17 execute_event generation (slot at drive_abci_method_versions/mod.rs:183) charges the recorded HookExecution and the bump and returns UnsuccessfulPaidExecution when the post-validation check fails, which the gate has made affordable. Charged, before user_fee_increase: fuel_used * credits_per_fuel plus the instantiation and context terms, never above B, never zero after entry; out-of-fuel charges the full budget; a non-zero increase scales the whole processing fee by the same percentage (UserFeeIncrease is a percentage, packages/rs-dpp/src/lib.rs:135-137, applied at execute_event/v0/mod.rs:73), which the gate covered. No literal debit and credit-back: this is the bound-check-then-charge-actuals model section 12 specifies, and 05 D3's literal escrow is superseded by it. Rejected: affordability checked once after validation, false on the under-funded path.
• Block budget (sections 01 goal 4, 06.1): each hook-bearing transition contributes B, computed from the decoded transition and the contract's ValidationModuleRef (cached contract fetch), to the pre-execution sum against max_block_processing_credits in prepare_proposal and process_proposal, so an over-budget proposal is rejected before any guest runs; validators otherwise re-execute with no timer (proposer_tx_processing_time_limit is consulted only when proposing, process_raw_state_transitions/v0/mod.rs:149-158). max_hook_fuel_per_call is derived, not chosen: max_block_processing_credits / N_min credits at credits_per_fuel, where N_min is the number of minimal hook-bearing batches (max_transitions_in_documents_batch: 1, system_limits/v4.rs:26) that fit the 2 MiB block (Tenderdash max_bytes: '2097152', packages/dashmate/configs/defaults/getBaseConfigFactory.js:435); with section 06's initial 40e9 credits and, for illustration only, 300-byte batches, that is under 6M credits, under one millisecond at the fee model's roughly 8M credits per ms (drive_abci_validation_versions/v10.rs:338-343).
• Two per-transition ceilings exist, so their relation is stated rather than implied: B evaluated at the caps (every fixed term at its maximum plus max_hook_fuel_per_call * credits_per_fuel, plus the nonce-bump cost) is at or below section 06.1's max_state_transition_processing_credits, which is itself strictly below max_block_processing_credits, so every hook-bearing transition is includable. Both inequalities are asserted in a unit test beside 04.6's test deriving Tenderdash max_gas and the budget from one constant. The calibration is a section 12 table entry.
• Charging: ValidationOperation::HookExecution { fuel_used, code_len, pages, context_len } priced from fee_version at fold time (execution_operation/mod.rs:74-87, :97-200), so user_fee_increase applies; this variant is the one fold sections 09 and 12 build on and supersedes section 12's bare PrecalculatedOperation wording.

8.2.7 Error classification

Two matches, one per engine error type. TrapCode has twelve variants and is not #[non_exhaustive] (wasmi 2.0.0 crates/core/src/trap.rs:274-346), so its arm list carries no wildcard. ErrorKind is #[non_exhaustive] with 20 variants, 19 with the wat feature off as it is here (crates/wasmi/src/error.rs:156-213), so its arms cover every variant of the consensus build and end in an explicit wildcard resolving to HostFault: a variant added by a later patch must not silently become a paid rejection. ErrorKind::Wat is absent, being #[cfg(feature = "wat")] (:211-212) with the feature off (8.2.1); ResumableHostTrap and ResumableOutOfFuel are #[doc(hidden)] internals of the resumable-call path 8.2.1 excludes and take the HostFault row. A test instantiates each row. Fuel exhausted exactly at a host-call boundary is pinned by a golden vector rather than assumed, so a change in that behaviour is a golden-file change and hence a PV event.

Condition	StateError::ValidationModuleError kind	Class	Paid
return 0	none; transition proceeds	accept	n/a
return 1..=65535	Rejected { code }	bump nonce	yes
TrapCode::{UnreachableCodeReached, MemoryOutOfBounds, TableOutOfBounds, IndirectCallToNull, IntegerDivisionByZero, IntegerOverflow, BadConversionToInteger, StackOverflow, BadSignature, GrowthOperationLimited} (the limiter is counter-based, so deterministic)	Trapped { kind }	bump nonce	yes
TrapCode::OutOfFuel	OutOfFuel { budget }, full budget charged	bump nonce	yes
result outside 0..=65535; second context_read; cap < context_len (ErrorKind::Host downcast to the runtime's own error)	InvalidResult	bump nonce	yes
context_read with dst or cap (as u32) outside memory: the host checks the bounds itself and raises TrapCode::MemoryOutOfBounds, so no ErrorKind::Memory can arise from a host copy	Trapped { MemoryOutOfBounds }	bump nonce	yes
run-time ErrorKind::{Translation, Wasm, UserLimits, ImplementationLimits, Instantiation, Linker, Memory, Table, Global} on a stored module, or its failed_under marker	ModuleUnavailable { TranslationFailed }, writes only (8.2.5)	bump nonce	yes
ABI retired, hook_execution: None at registration	ModuleUnavailable { AbiRetired | DisabledByProtocolVersion }, writes only (8.2.5)	bump nonce	yes
governance frozen (frozenModule, frozenContract, globalFreeze)	ModuleUnavailable { Frozen }, all seven kinds (8.2.5)	bump nonce	yes
balance below B at the 8.2.6 gate	InsufficientBalanceForHookExecution (11.2.3), charged the affordable minimum, engine never entered	bump nonce	yes
prepare rule failed (8.2.2)	PrepareFailed { rule }	bump identity nonce	yes
TrapCode::OutOfSystemMemory; ErrorKind::{Message, I32ExitStatus, Fuel, Func, Read, Ir, ResumableHostTrap, ResumableOutOfFuel}, a foreign Host error or the wildcard arm; allocation failure before guest entry	HostFault, Err	InternalError, block rejected (process_proposal.rs:285-307)	no
blob absent at run time	Err(ExecutionError::DriveIncoherence)	InternalError	no
host allocation failure (Rust aborts the process)	no result	node aborts; Tenderdash proceeds without it	no

Engine bumps: the golden suite covers a corpus, not the modules registered on mainnet, and a stored module can fail translation under a later package while every node agrees. Re-preparation is therefore lazy and charged, never a first-block sweep: the first transition at or after the bump PV that needs a module re-prepares it under the new package at that transition's expense and writes prepared_under or failed_under: wasm_engine_version into the section 06 metadata, so every later run reads the marker and the paid row fires without touching the engine. That is 04.7's lazy rule, it keeps the work inside max_block_processing_credits, and it is the form the in-chain sweep of 11.2.5's engine-swap runbook takes. An eager first-block pass over every registered blob is rejected: its cost grows with adoption rather than with any measured bound, nothing charges it against the block budget, and an Err in a block event halts the node (11.2.2). Per-block translation is bounded by max_distinct_modules_instantiated_per_block on SYSTEM_LIMITS_V7 (11.2.7), which counts re-preparations. The candidate package is still run against the full on-chain module set before the PV is cut (11.2.5, 8.5), so a rejection is known before signalling rather than discovered on chain.

StateError is append-only (state_error.rs:77-81); payload (contract_id, document_type, document_id: Option, kind); codes in a fresh block 41000-41099 after the 40900 shielded block (errors/consensus/codes.rs:396-401), covering InsufficientBalanceForHookExecution as well.

8.2.8 Host functions in v0

Namespace dash_v1: context_len() -> i32 and context_read(dst, cap) -> i32 (bytes written; one shot). Nothing else: no log (a covert channel), no abort (unreachable traps), no clock, randomness or emit.

8.2.9 Guest SDK, native harness, CLI

• packages/rs-contract-sdk (new; published as dash-contract-sdk, no_std + alloc) re-exports dash-contract-abi; #[hook(predicate)] from dash-contract-sdk-macros (packages/rs-contract-sdk-macros, new) generates validate, the one-shot context pull, decoding, panic-to-unreachable and the dash-contract-abi section as a #[link_section] static, which survives --strip-all (verified on rustc 1.92). The dash-contract types generator (section 13) shares the same crates.
• dash-contract-testutils (packages/rs-contract-testutils, new) runs the hook body natively and, in the same test, through rs-contract-runtime with the consensus Config, reporting fuel. CLI dash-contract at packages/rs-contract-cli (new; section 13 lists the full command set): build is a release wasm32-unknown-unknown cdylib with panic = "abort" and link args --strip-all and equal --initial-memory and --max-memory (min == max). Verified on rustc 1.92: --strip-all drops the name, producers and target_features sections the toolchain otherwise emits while keeping dash-contract-abi, the module carries one funcref table with min == max, and the output exports exactly memory and validate and passes rules 1 to 6. check is the exact consensus prepare pass; CI runs a hello-world hook through build then check.

8.2.10 PV gating

Everything activates at PV17 through the generations above, including hook_execution: Some(0). No new state transition, so no is_allowed arm. First-block migration: ContractGovernance is created one PV earlier, in transition_to_version_16 (section 11.2.6), with deployer, frozenGuard and globalFreeze; section 11's transition_to_version_17 extends it with the frozenModule and frozenContract document types 8.2.2 and 8.2.5 read, and section 11's task list carries that extension as its own migration step. Phase 3 adds no tree of its own, and engine-bump PVs add no first-block pass: re-preparation is lazy and charged (8.2.7).

8.3 Tasks

Engine crate

• Create packages/rs-contract-runtime (new): one package per activated engine revision, HookEngine dispatch on wasm_engine_version, consensus Config builder, StoreLimits, stack preallocation, bounded LRU cache, wasmparser exact pin, deny lints per section 01 principle 6.
• Add wasm_engine_version: Option<u16> beside grove_version in DriveVersion (rs-platform-version drive_versions), Some from DriveVersion V11 at PV17; extend TEST_PLATFORM_V2/V3 mocks.

Prepare pass

• Implement rs-contract-runtime::prepare with rules 1 to 6 and PrepareError; call it from new rs-drive-abci data_contract_create and data_contract_update state generations after the governance reads and the gate, billing hook_prepare_credit_per_byte; failures as PrepareFailed with BumpIdentityNonceAction; gate PV17.
• Add max_hook_code_size, max_hook_memory_pages, max_hook_table_elements, max_hook_fuel_per_call (derived per 8.2.6), recursion depth, stack height and the structural caps to SYSTEM_LIMITS_V7 as Option<T>, beside 11.2.7's max_distinct_modules_instantiated_per_block.

Document-type reference (rs-dpp)

• Add meta-schema v6 admitting validationModule, try_from_schema generation 6 with the maxFuel range check and the rule 6 admissible-type check, DocumentTypeV5 with validation_module: Option<ValidationModuleRef> and every DocumentTypeRef arm (document_type/mod.rs:132).
• Freeze the field in a new document_type/methods/validate_update generation; add document_type_validation_module_fee to the next FeeDataContractRegistrationVersion and registration_cost.

ABI crate

• Create packages/rs-contract-abi (new, no_std, published as dash-contract-abi) with HookContextV0, DocumentWire (F64 as bits), OpData, BlockRef, DocumentOp, the custom-section codec and result-code rules; golden vectors against rs-dpp Document conversions covering every DocumentPropertyType and the IndexOnlyDelete context.

Seam, errors, fees (rs-drive-abci, rs-platform-version)

• Add the next batch/state generation (governance reads, gate, blob fetch, run_hook) after triggers and guards, with the delete-and-index-only-delete exemption from ModuleUnavailable of 8.2.5; add hook_execution: OptionalFeatureVersion to DriveAbciDocumentsStateTransitionValidationVersions, Some(0) in validation V13; pass the signer's PartialIdentity into validate_state.
• Add the PV17 execute_event generation charging a recorded HookExecution and the nonce bump on an unaffordable remainder; add B per hook-bearing transition to the section 06.1 pre-execution block-budget sum in prepare_proposal and process_proposal and to the check_tx dry-run estimate; assert the 8.2.6 ceiling relation in a unit test.
• Append StateError::ValidationModuleError (rs-dpp errors/consensus/state) with the 8.2.7 kinds, InsufficientBalanceForHookExecution and codes 41000-41099, ErrorWithCode arms, wasm-dpp2 and rs-sdk decoding.
• Add FeeWasmVersion to FeeVersion in FEE_VERSION5 and ValidationOperation::HookExecution priced from it with checked arithmetic.
• Regenerate section 12's "New constants" table from the 14.2 allocation (owner: section 12), so the generations an implementer reads there are FEE_VERSION5, SYSTEM_LIMITS_V7 and validation V13, not the pre-14.2 numbers.
• Implement lazy re-preparation and the prepared_under/failed_under metadata field now, charged to the first transition that needs the module after an engine bump and counted against max_distinct_modules_instantiated_per_block; the first engine-bump PV exercises it.

Guest SDK, harness, CLI

• Create packages/rs-contract-sdk (new, no_std + alloc, published as dash-contract-sdk, re-exporting dash-contract-abi); criterion: the three example hooks build with dash-contract build and pass dash-contract check.
• Create packages/rs-contract-sdk-macros (new); criterion: #[hook(predicate)] output exports exactly memory and validate and carries the dash-contract-abi section, asserted by running the prepare pass in a test.
• Add the types generator to packages/rs-contract-cli with the section 13 build.rs helper; criterion: generated structs round-trip the fixture contracts' documents through DocumentWire.
• Create packages/rs-contract-testutils (new); criterion: native and wasm runs of each example hook agree on outcome and report fuel.
• Create packages/rs-contract-cli (new, the dash-contract binary) with the 8.2.9 build flags and check; CI: hello-world build then check.
• Ship three example hooks (monotonic counter, transfer allowlist, purchase price floor) in packages/rs-contract-examples (new), reused as fixtures under packages/rs-drive-abci/tests/supporting_files/contract/.

Determinism CI and security

• Add an engine vector suite under packages/rs-contract-runtime/tests/vectors/ (new): *.wat inputs (integer wrap, growth at cap, recursion limit, fuel exhaustion including exhaustion at a host-call boundary, every trap kind, every ErrorKind row) and a golden.json of (fuel, outcome) per engine package and parser pin, regenerated only with a PV bump; a test fails when the pinned wasmi or wasmparser version changes without a regenerated golden file.
• Add packages/rs-drive-abci/tests/strategy_tests/test_cases/wasm_hook_tests.rs (new) with verify_state_transition_results: true, independent_process_proposal_verification: true (strategy.rs:351-354) and a pinned root hash; the tests run in the push and nightly strategy phase (tests-rs-workspace.yml:383), plus one smoke test named run_chain_comprehensive_mixed_operations_with_wasm_hooks so the PR-path filter at tests-rs-workspace.yml:355 admits it; include the block-fill and cold-versus-warm-cache cases of 8.4.
• Add a matrix job on ubuntu-24.04 and ubuntu-24.04-arm running the hook corpus and comparing root hashes; a replay job re-executing a recorded PV17 fixture chain under the next binary through drive-abci replay (feature replay; packages/rs-drive-abci/src/replay/runner.rs:226 extracts the expected app hash and :266-275 compares it against the committed one); cargo-fuzz targets for prepare and the ABI decoder (section 11 nightly).
• Security checklist, code: the 8.2.7 map is one match with no wildcard arm over every TrapCode variant, plus one match over ErrorKind covering every variant of the consensus build and ending in an explicit wildcard that resolves to HostFault because the enum is #[non_exhaustive], both enforced by the test that instantiates each row; a CI grep proves no f32 or f64 token in rs-contract-runtime; every Store is built through one consensus_store() constructor applying the 8.2.1 Config and StoreLimits; no clock, environment or filesystem access; no panic path from guest input (catch_unwind as defense in depth, section 01 principle 6).
• Security checklist, operational (owner: the Platform release lead): subscribe the security alias to wasmi-labs/wasmi advisories and RustSec; record the external audit vendor and report date in section 11 before signalling PV17.

Activation and docs

• Wire every generation above into version/v17.rs with the v14.rs:249-405 test pattern; write book/src/data-model/validation-modules.md (new) opening with the activation PV and carrying the 8.6 recovery recipe.

8.4 Tests

• Unit: one test per prepare rule, including one per rejected document-type feature of rule 6; per-op hook tests under rs-drive-abci batch/tests/document/ asserting the StateTransitionExecutionResult class for every row of 8.2.7, including a forced host fault (test_fault_injection pattern, process_raw_state_transitions/v0/mod.rs:26-51); an under-funded signer with a hook-bearing transition produces no engine invocation (fault-injection counter on the engine) and InsufficientBalanceForHookExecution at the affordable minimum; a gate pass with an unaffordable remainder charges the run and bumps the nonce; a frozenModule document lands and the next hook-bearing transition in the same block is ModuleUnavailable, a Delete of a document of that type in the same block is rejected paid, and after the unfreeze the same delete succeeds with its storage refund on the StorageFlags owner, while a failed_under module lets the delete proceed; maxFuel of 0 or above the cap fails parsing; an IndexOnlyDelete context carries old_document: None and the index values in op_data; an overflowing bound is ExecutionError::Overflow, never a saturation.
• Activation and fees: the keyword rejected by the PV16 parser; an upgrade strategy test modelled on run_chain_v12_to_v13_locks_in_before_activation (packages/rs-drive-abci/tests/strategy_tests/test_cases/upgrade_fork_tests.rs:559); golden fuel per engine package; out-of-fuel charges exactly the budget; gas_used equals the charged amount; check_tx gas_wanted >= gas_used for accept, reject and out-of-fuel runs; worst-case B at the caps stays under max_state_transition_processing_credits, which stays under max_block_processing_credits.
• Block budget: a block filled with minimal hook-bearing transitions at budget is accepted at the budget and an over-budget proposal is rejected with the engine counter at zero; process_proposal time stays under the Tenderdash timeout on the reference hardware.
• Determinism: repeat-run and cross-architecture root-hash equality; more registered modules than the cache holds with root-hash equality between a cold and a warm node; replay of a PV17 fixture chain under the PV18 binary, including a lazy re-preparation charged to the first transition needing it after the bump.

8.5 Acceptance criteria

• A contract with validationModule on one document type registers at PV17; all seven document transition kinds are accepted or rejected exactly as the module dictates; a hello-world hook from dash-contract build passes dash-contract check in CI.
• Every row of 8.2.7 is exercised and only the host-fault and blob-absent rows yield InternalError; root hashes and golden fuel are identical on amd64 and arm64; a PV17 fixture chain replays under the next binary.
• The hook component of the processing fee equals fuel_used * credits_per_fuel plus the instantiation and context terms before user_fee_increase on every node, never above B (a non-zero increase scales it by the same percentage as every other processing fee), and no engine runs without an affordable bound; the PV17 block budget includes hook bounds and the per-call cap is strictly below both the per-transition ceiling and the budget; the PV16-to-PV17 upgrade test shows hooks executing from the first PV17 block.
• Testnet exit, engine bumps: the PV-opening PR re-prepares the full on-chain module set of testnet and mainnet under the candidate package and lists every module the new engine rejects (11.2.5 engine swap), before the PV is cut.

8.6 Risks

• Fuel drift inside the pinned line: the exact pin and the golden suite detect it. A security patch that changes fuel or a result is a new engine package and a new PV with a documented divergence height (section 01 goal 7), never an in-place bump, which would break replay from genesis; a patch that changes neither ships as a non-consensus hotfix (the 11.2.5 runbook). Cost: every activated package stays linked and patched.
• wasmi sponsorship ends October 2026: decide fork-and-freeze or co-sponsorship before PV17 (section 11).
• A live module fails under a new package: the pre-cut differential run and the 8.5 exit criterion bound it; on chain the lazy marker turns it into a paid ModuleUnavailable { TranslationFailed } for writes while deletes still succeed.
• Buggy hooks and the absence of an in-place upgrade path: at PV17 a module and its type's property schema are frozen (8.2.3), so a fix is a new document type. Recovery recipe, in the book and the SDK docs: attach the fixed module to a new document type in a DataContractUpdate, have clients re-create the affected documents there, then delete the old ones for the storage refund, which the 8.2.5 delete exemption keeps available even when the old module is frozen or un-preparable. In-place replacement arrives with the PV19 entry_module and its change_rules (10.2.8).
• Cache sizing: the LRU default must fit the smallest evonode; a smaller cache costs time on misses, never results.

---

---

Continued in part 9 of 14 below.

[QuantumExplorer]

Part 9 of 14 of the plan (continued from part 8 above).

9. Phase 4: declared-footprint reads

Gate: PV18, one protocol version after Phase 3 (section 08, PV17); generations per section 14.2 (SystemLimits V8, DRIVE_ABCI_VALIDATION_VERSIONS_V14, FEE_VERSION6 with fee_version_number 6 under section 12's numbering; BatchTransitionV2 gated by serialization bounds, no contract-version change). No DPP validation generation: state transition basic structure dispatches from DriveAbciDocumentsStateTransitionValidationVersions::basic_structure (drive_abci_validation_versions/mod.rs:187, batch/mod.rs:108-114), while DPPValidationVersions covers only schema, contract, document-type and voting validation (dpp_validation_versions/mod.rs:10-16), so the footprint rules land in V14 and rs-dpp gains types and errors only. Names without a repository path are proposals and follow sections 08 and 13 as recorded in D10: the new crates packages/rs-contract-abi (published as dash-contract-abi) and packages/rs-contract-runtime; the published dash-contract-sdk and dash-contract-testutils; CLI dash-contract (check, simulate, types); fee sub-table FeeWasmVersion.

9.1 Reasoning

Predicates see one transition; hooks such as holder allowlists, feed-based price floors or per-block-lagged quotas need state the transition does not carry. Phase 4 adds it under the constraints of sections 04 and 08: reads bounded and priced before the guest runs (affordability is one dry run, validate_fees_of_event/v0/mod.rs:102-163), reads provable, and no GroveDB access from the guest, so Err (hence InternalError) stays unreachable from user code. The precedent is Soroban's footprint (Stellar docs, transaction simulation page): every transaction carries the set of ledger keys it may read or write, an access outside it is a deterministic failure, and simulateTransaction records the footprint against a snapshot; the fee page prices the non-refundable part (instructions, bytes read and written) from the declared resources.

Enforceable class, stated precisely: invariants over state as of the previous block boundary. A cumulative constraint ("at most k documents per owner per day" via IndexQuery) admits as many transitions as one block holds, since none sees the others; allowlist revocation has the same one-block window; no native quota exists to fall back on. Real quotas need a declarative per-type per-owner rate-limit primitive with no reads, deferred to section 14; the two-transitions-in-one-block test (9.4) is documented behaviour in the book.

9.2 Design

9.2.1 Declared, host-resolved, snapshot reads

BatchTransitionV2 adds read_footprint: Vec<FootprintEntry> to the signed bytes (V0 and V1 exist, packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/mod.rs:84-91); one footprint per batch, since max_transitions_in_documents_batch is 1 at every PV (system_limits/v4.rs:26). The host resolves every entry through existing Drive read paths before instantiating the module; the guest reads the results through imports (9.2.3).

1. Snapshot: reads use transaction: None, the last committed state, the view HookContextV0.block reports (section 08 decision (b)) and the view check_tx's dry run uses (execution/check_tx/v0/mod.rs:180-186). Gains: exact provability, mempool parity, order-independence within a block. Cost: a hook does not see earlier transitions of the same block while old_document and new_document are in-flight (9.1). Phase 5's in-flight reads (section 10) are a different entry kind with their own bound and provability; no Phase 4 guarantee transfers.
2. Contract version: the footprint is validated and resolved against the contract committed at N-1, fetched with transaction: None, never the contract the transformer holds: in Validator mode that one comes through the block transaction (transform_document_transitions_within_contract_v0 passes transaction to get_contract_with_fetch_info_and_fee, batch/transformer/v0/mod.rs:419-426), so a contract update earlier in block N is visible there and absent at N-1. An entry naming a type, index or token position absent at N-1 is a paid FootprintViolation { NotInCommittedContract } in Validator mode and a BasicError in check_tx, whose transformer already sees committed state (it runs with transaction: None, check_tx_verification/v0/mod.rs:57-63, reached from check_tx_v0, check_tx/v0/mod.rs:158-164). Every read goes through one resolver function that maps PathKeyNotFound, PathNotFound and PathParentLayerNotFound to None or empty, as execute_raw_results_no_proof_internal and execute_no_proof_internal do (packages/rs-drive/src/query/mod.rs:2704-2714, :2748-2758); grove_get_path_query itself propagates them (grove_get_path_query/v0/mod.rs:31) and is never called bare.
3. Every declared entry is resolved and charged whether used or not (Soroban's rule), so read cost never depends on guest control flow; no GroveDB access while the guest runs, so mid-execution failures are guest traps only. Error classes: 9.2.7.

Rejected: lazy reads during execution (Drive re-entered from inside wasmi, Err reachable mid-call); results copied into the context (index results bloat the mandatory copy and cost fuel to decode); registration-time footprint templates (a template language in consensus the SDK can compute client-side).

9.2.2 Entries and their GroveDB path queries

Entry (sketch)	Scope	Resolves to
Document { document_type, id }	type of the hook's own contract, not indexOnly (no primary-tree body), W_max(type) at or below max_document_wire_bytes (9.2.4)	DriveDocumentQuery on $id (is_for_primary_key, packages/rs-drive/src/query/mod.rs:1166), path [64, cid, 1, type, 0] (contract_document_type_path plus the primary-key &[0], packages/rs-drive/src/drive/document/paths.rs:17-26 and :45-56)
IndexQuery { document_type, index_name, equal: Vec<PropertyValue>, range: Option<RangeClause>, ascending, limit }	same, the wire cap included; index_name must exist; 1 <= limit <= max_hook_index_query_limit	DriveDocumentQuery with limit: Some(limit), no offset, start_at or block_time_ms (query/mod.rs:1057-1075), via construct_path_query (query/mod.rs:1963) into PathQuery { path, SizedQuery { query, limit, offset } } (grovedb/src/query/mod.rs:51-83 at the pin)
TokenBalance { token_position, identity_id }	position in the hook contract's tokens, id via calculate_token_id (packages/rs-dpp/src/tokens/mod.rs:27)	fetch_identity_token_balance_with_costs (packages/rs-drive/src/drive/tokens/balance/fetch_identity_token_balance/mod.rs:58) with apply: true and transaction: None in every mode, preflight included: the stateful path returns None for an absent balance where the estimator path returns Some(0) (fetch_identity_token_balance/v0/mod.rs:62-76); wire result Option<u64>; path [16, 128, token_id] (token_balances_path, tokens/paths.rs:495-501)
OracleFeed { feed_id }	Phase 1b active (otherwise the entry kind is a BasicError); feed document present in the section 06.4 registry contract at N-1	point read of [RootTree::OracleFeeds, feed_id, 0] (latest FeedValue, section 06.4) through grove_get_raw (packages/rs-drive/src/util/grove_operations/grove_get_raw/mod.rs:30), the element family section 06.3's prove_elements v1 proves; absent past the feed's stalenessBlocks

Grammar rules for determinism: the index is named, never chosen by find_best_index (query/mod.rs:2213); at PV18 only plain indexes qualify, so basic structure rejects an IndexQuery on an index carrying preallocated, rankedCountable, rankedSummable, rankedAverageable, timeRange or skipIfAbsent (constants at packages/rs-dpp/src/data_contract/document_type/index/mod.rs:41-113), contested, or on an indexOnly type, because their traversal is not bounded by limit (9.2.4), and a Document entry on an indexOnly type; range only on the last indexed property, equal on every earlier one; no cursors, offsets or time-range clauses; order is index order then document id; keepsHistory types return the current version; contested types, other contracts' documents and identity credit balances are out of scope. Values: equal and range bounds are a PropertyValue typed by the indexed property's DocumentPropertyType and encoded by the property-typed encoding the query path uses, never raw Value (whose integer variants give one logical value several encodings). PropertyValue has no float variant, so a clause on a DocumentPropertyType::F64 property (Value::Float in platform-value, lib.rs:136) fails basic structure; in results DocumentWire carries such a property as the eight big-endian bytes of f64::to_bits, section 08 decision (g), opaque to the guest. Results are DocumentWire (section 08). Caps as Option<T> in SystemLimits V8: max_hook_footprint_entries (proposal 8), max_hook_index_query_limit (16), max_hook_read_bytes (256 KiB), max_hook_host_calls (256). Entries resolve in declared order; when cumulative resolved bytes exceed max_hook_read_bytes, resolution stops and the transition fails with a paid FootprintViolation { ReadBytesExceeded } charged the actual cost so far. Because the credit bound is enforced at resolution (9.2.4), the byte cap is not a cost guard: its job is to bound the universe read_copy can address and the context the harness must reproduce.

One function, three callers: footprint_entry_to_query(entry, contract, document_type) -> Result<DriveDocumentQuery, FootprintBasicError> builds the query and calls construct_path_query with starts_at_document: None (no Drive access); any Err (Error::Query(QuerySyntaxError), packages/rs-drive/src/error/mod.rs:37, or Error::Protocol from property-value encoding: a mistyped equal, a range on a non-comparable type, limit: 0) is the BasicError. CheckTx, Validator basic structure and the state-path resolver run exactly this function, so a footprint that passed basic structure cannot fail construction at resolution. Canonical form: basic structure re-encodes the decoded footprint and rejects the transition unless the bytes equal the signed bytes.

9.2.3 Capability imports and host-function versioning

Namespace dash_v2 (section 04's additive dash_v<n> grammar; PV17's context imports are dash_v1.context_len and dash_v1.context_read, section 08 prepare rule 3) joins the PV18 import allowlist; the read capability id becomes the first admissible value of the capabilities vector rule 4 requires empty in v0, so the grant rides the vector, not the namespace name. The guest names what it wants; the host serves only declared entries:

// SKETCH: guest imports in namespace dash_v2; pointers and lengths in linear memory
fn read_request(entry_ptr: i32, entry_len: i32) -> i32; // wire bytes of a FootprintEntry -> handle; traps FootprintViolation if undeclared
fn read_count(handle: i32) -> i32;                       // resolved items
fn read_len(handle: i32, n: i32) -> i32;                 // bytes of item n, -1 if absent
fn read_copy(handle: i32, n: i32, ptr: i32, cap: i32) -> i32; // bytes copied; negative status past the item's length, never a trap

Matching is byte equality against the signed wire bytes (canonical by 9.2.2), so a data-dependent read is served only if declared and generated constructors give client and guest the same bytes. entry_len is capped at the largest declared entry's wire length (longer traps FootprintViolation) and read_request is charged per byte compared. HookContextV1 (abi 1) echoes the footprint and fills capabilities with the granted entry kinds; a module importing dash_v2 declares abi 1 in its custom section, checked in prepare. A granted namespace is frozen: a semantic change is a function in a later dash_v<n>, removal is a PV table change that retires the ABI (section 11's outcome table, ModuleUnavailable { AbiRetired }); a new entry kind is a new FootprintEntry variant under a later abi_version value (section 08 rule 4 has no minor), added to the accepted set in the PV that grants it; an ungranted variant fails basic structure. Rejected: per-capability namespace names such as dash_cap_read_v1, because section 04's grammar is one number per grant and section 10's emit import then takes dash_v3; the D10 names table therefore carries the mapping once, dash_v1 to abi 0 at PV17, dash_v2 to abi 1 at PV18, dash_v3 to abi 2 at PV19, and section 13's abi-v1 feature line names dash_v2. Also rejected: the component model, a second surface (canonical ABI, interface types) to freeze per protocol version and validate in prepare, for a capability the core import grammar already expresses.

9.2.4 Costs

Actual cost is the CalculatedCostOperations the resolution reads push (grove_get_path_query/v0/mod.rs:30), priced by ephemeral_cost (packages/rs-drive/src/fees/op.rs:1598-1639; storage_seek_cost 2000, storage_load_credit_per_byte 20, fee/storage/v1.rs:8-10), plus hook_host_call_fee per import call and hook_host_copy_credit_per_byte per byte compared or copied, folded through the same ValidationOperation fold as fuel (section 08's HookExecution); reads only, so no storage fee, refund or attribution question.

The declared bound is a sum of grovedb's own worst-case primitives, not a closed form over depth and limit. Three facts about the pinned grovedb (6fc7e1e8) fix the terms. Every storage read is one seek plus the bytes loaded (storage/src/rocksdb_storage/storage_context/context_tx.rs:310-320). Opening a merk at a path reads the immediate parent element only (open_merk, grovedb/src/util/compat.rs:30-80, parent element at :45-53); add_worst_case_get_merk_at_path charges two seeks (grovedb/src/estimated_costs/worst_case_costs.rs:50), one node at the path key's worst size (:54-58) and the prefix hash-node calls get_storage_context_cost adds (:61, blake3 blocks over the prefix body, storage/src/rocksdb_storage/storage.rs:1220-1228), which ephemeral_cost prices at blake3_base + blake3_per_block each (op.rs:1626-1629). A point get is a direct key lookup, never a descent (get_node_direct_fn, merk/src/merk/get.rs:290-308; the cached path at :311-352 falls back to it at the first unloaded link); add_worst_case_get_merk_node charges one seek plus worst_case_encoded_tree_size(key_len, element_size, node_type) (merk/src/estimated_costs/worst_case_costs.rs:74-90). A range walk fetches every node it touches at that price (MerkSource::fetch, merk/src/merk/source.rs:39-58), and the nodes touched grow with the merk's population, which no contract bounds. With open (two seeks, one worst-case node and those blake3 hash-node calls), get(key, size) and walk(n, size) as the three terms, H = hook_read_worst_case_tree_height (proposal 92, MAX_PROOF_TREE_HEIGHT at merk/src/proofs/tree.rs:655, the height of an AVL tree with 2^64 entries) in FeeWasmVersion bounding a walk's two boundary paths, and D_max the document bound:

• Document: open + get(id, D_max); keepsHistory moves the read to [.., id] key 0 (query/mod.rs:1721-1732) and changes no term;
• IndexQuery with p properties and limit L on a plain index: open of the last property-name level; walk(2H + L, value node) over that level, where a plain index keeps a value key only while its terminal holds a reference (drained groups are pruned, remove_reference_for_index_level_for_contract_operations/v1/mod.rs:33-36), so at most L value keys are visited; per visited key open + walk(2H + 1, reference node) of its 0 terminal; per result one reference follow (grovedb/src/operations/get/query.rs:98-107) costing open + get(id, D_max). Keys are max_field_value_size (5120) at value levels and 32 at id levels;
• TokenBalance: open + get(identity_id, 8); OracleFeed: open + get(0, FeedValue);
• host calls: max_hook_host_calls * (hook_host_call_fee + max_item_len * hook_host_copy_credit_per_byte), max_item_len the largest W_max over the declared entries (the guest-encoding bound below, never D_max), since read_copy may be replayed on the largest item up to the call cap.

D_max = min(DocumentType::max_size, max_state_transition_size) when every property has a finite max_byte_size, else max_state_transition_size (20480, the largest document any batch can have written): max_size_v0 skips properties whose max_byte_size is None (versioned_methods.rs:627-645), which Array and VariableTypeArray return (property/mod.rs:367-368), so it undercounts them. PV19 keeps the bound: a proposed create or replace whose serialized document would exceed max_state_transition_size less a growth headroom is rejected before apply (10.2.3), so no document exceeds D_max whichever path wrote it and whatever later rewrites add.

D_max bounds stored bytes and prices the storage terms (seeks and loaded bytes). The host copy is priced on the guest encoding, which is larger: DocumentWire (08.2.4) carries every property name and a per-value encoding overhead that the stored layout omits, since storage writes values in schema order without names. So 32 properties of 600-byte values with 40-byte names fit under D_max in storage and pass it on the wire, and a copy bound derived from D_max would under-price every read_copy of such a document. A second bound, W_max, prices every byte the host copies into the guest. Per type it is computable at registration from the schema alone: W_max(type) = D_max(type) + sum over the type's properties, nested paths included, of (name length + value encoding overhead) + the fixed DocumentWire fields (owner id, revision, timestamps), where a name is at most 64 bytes and an object has at most 100 properties (document-meta.json:21-24), and the encoding overhead per value is a length prefix of at most 9 bytes plus a variant tag. No contract-free form follows from those limits, because the 100-property limit is per object and documentSchema recurses with no depth bound (document-meta.json:7-14): two nested objects of 80 properties with 50-byte names satisfy every limit and carry 9,600 bytes of leaf overhead on their own, and a deeper tree carries more, so a formula over the top level alone can fall below W_max(type). The pre-check therefore reserves against an explicitly enforced cap: max_document_wire_bytes (SYSTEM_LIMITS_V8, proposal 40960, twice max_state_transition_size). At PV18 a contract attaching an abi 1 module fails registration (a BasicError naming the type) if any of its document types has W_max(type) above the cap, since a footprint may name any type of the hook's own contract; PV19 applies the same rule to a contract attaching an entry_module. The chain max_document_wire_bytes >= W_max(type) >= encoded DocumentWire then holds for every document a footprint can copy, and the pre-check's contract-free copy term is max_document_wire_bytes. The Document entry's copy, each IndexQuery result's copy and every read_copy replay are priced at W_max; the storage terms keep D_max; and 08.2.6's hook_context_credit_per_byte already prices the actual encoded context, so Phase 3 needs no change. Enforcement at resolution: after each entry resolves its ephemeral_cost is added; when the running actual exceeds the declared bound, resolution stops, the bound is charged, and the transition fails with a paid FootprintViolation { BoundExceeded }. That is the mechanism behind the 9.5 criterion; the index-kind restriction keeps it unreachable for honest footprints (preallocated never prunes empty subtrees, so a range over 100000 empty buckets under limit: 1 would open 100000 terminals at two seeks each against a bound of a few hundred seeks). Charging actual rather than declared cost departs from Soroban's non-refundable rule because the estimator makes it free and every other pipeline read is billed that way.

Insertion points. Pre-check: the batch validate_estimated_fee (packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/state_transition_estimated_fee_validation.rs:30-84) sees only the identity balance and the platform version, and calculate_min_required_fee (:18-28) only the platform version, so it adds a contract-free worst case (entries times the formula at D_max = 20480, max_document_wire_bytes for copies, L = max_hook_index_query_limit) computable from FeeVersion and SystemLimits alone, keeping the trait signature. Dry run: the CheckTx transformer appends ValidationOperation::FootprintRead { bound }, a sibling of section 08's HookExecution in the same enum and priced at fold time (execution_operation/mod.rs:74-87), to the execution event's operations, so validate_fees_of_event (check_tx/v0/mod.rs:180-186) prices it into gas_wanted; the Validator path replaces it with the actual CalculatedCostOperations and the host-call charge. The two variants together supersede section 12's bare PrecalculatedOperation wording, and both feed the Phase 1 block budget.

9.2.5 check_tx policy

ERC-7562 rule (Draft)	PV18 mechanism
OP-011: no ORIGIN, GASPRICE, TIMESTAMP, NUMBER, PREVRANDAO, BASEFEE and kin	no clock, randomness or environment imports (section 08); block is the last committed block in mempool and in block
STO-010, STO-021: own and associated storage only	footprint scope: own documents, own tokens, the system oracle feed
OP-020: out-of-gas is never caught	out-of-fuel is a trap the guest cannot catch; entry, limit, byte and host-call caps bound host work
STO-031 to STO-033: staked entities read more	not adopted: a rejected hook transition is paid (bump nonce), which is the stake; cross-contract reads deferred
"Running the validation rules": validate again before inclusion	always: validators run the hook; a mempool verdict is never trusted

Decision: at PV18 check_tx runs footprint_entry_to_query plus the scope, cap and canonical-form checks against the committed contract and prices the declared bound into gas_wanted; it neither resolves reads nor runs the guest (should_validate_batch_valid_against_state stays false for CheckTx and RecheckTx, batch/mod.rs:47-54). Mempool compute is unpriced, there is no reputation layer (ERC-7562's GREP and UREP rules), and RecheckTx runs every block only because dashmate enables Tenderdash recheck_tx (packages/dashmate/configs/defaults/getBaseConfigFactory.js:458), node configuration: a node with it off keeps stale estimates and changes no consensus outcome. The rows above are ABI invariants, so enabling execution later is a mempool-policy change; section 14 carries it as a testnet exit criterion.

UX substitute: a non-consensus preflight query on the Drive query service (name per D10) that runs the module against committed state, records reads and returns verdict, fuel, read cost and footprint (Soroban's simulateTransaction, which returns the recorded footprint and minResourceFee). Section 13's decision against client-side pre-validation rules out a second engine pin inside wasm-sdk and both mobile frameworks; a server-side endpoint ships none, so that decision restates as no in-client engine, server-side preflight instead, and section 13's Phase 4 task list carries the endpoint's client bindings. It is the first DAPI endpoint executing user code, and "fuel-capped like any query" is not enough: existing queries are bounded by grovedb work on committed state, fuel bounds one call, and nothing bounds concurrency, so an unauthenticated client could pin every evonode's query threads for free. Its own limits: in SystemLimits V8, max_preflight_fuel (at most max_hook_fuel_per_call, so a verdict under the cap equals the consensus verdict) and per-request module and footprint size caps; in PlatformConfig (packages/rs-drive-abci/src/config.rs:130), since they are node resources, a concurrency cap with immediate rejection when exhausted, an isolated thread pool so preflight never starves proof queries, and an operator disable switch, admissible only because the endpoint is off consensus. Because that half is per node, two evonodes can answer differently or not at all, so the client contract is stated: the node status query (get_status, packages/rs-drive-abci/src/query/service.rs:601-604) advertises preflight availability and the effective max_preflight_fuel and size caps; an SDK routes to a node with enough headroom, and where none has it falls back to dash-contract simulate on a local node (section 13's path) and submits with no preflight verdict, accepting the 9.6 paid-violation risk. A load test is a testnet exit criterion (section 14).

9.2.6 Proof story

The footprint is in the signed transition, so the read set is known without receipts. Each entry is provable against the app hash of block N-1, carried in block N's header: documents and index queries through the getDocuments proof path with identical clauses and limit (prover and verifier build byte-identical PathQuerys, the section 06 invariant), token balances through prove_identity_token_balances, feed values through section 06's prove_elements v1. Reads are of committed N-1 state and the guest is deterministic, so a client holding proofs captured at N-1 before N committed re-executes the module and reproduces the verdict.

A client arriving after N commits gets proofs at N: it can re-execute only when every entry is unchanged between N-1 and N, and it can never reconstruct an in-flight old_document (9.2.1). The full claim therefore needs proofs at a past height, which Drive does not serve and grovedb cannot express today (prove_query takes a PathQuery and no height, grovedb/src/operations/proof/generate.rs:73-78 at the pin; every proof is against the current root). Phase 4 defers it explicitly rather than leave a headline property unowned: a record in section 05's register (Drive lead, due before the Phase 4 design review) chooses between serving proofs at a retained height and declining, names the grovedb work either choice needs, and states reversibility; until it lands, the 9.5 criterion claims only what proofs captured at N-1 support. What ships regardless is a receipt: ExecTxResult carries a hash of the resolved read bytes plus the context beside code, info and gas_used (abci/app/execution_result.rs:10-50), under results_hash, not bound by state proofs (section 06.6). A late client can therefore check that its re-execution matches what the network executed against, without proving those inputs were the committed state; the book states that boundary.

9.2.7 Errors and SDK surface

FootprintViolation { entry, kind }, kinds Undeclared, NotInCommittedContract, BoundExceeded and ReadBytesExceeded, joins section 08's ValidationModuleError detail (codes 41000-41099): paid via bump nonce, read cost charged (the bound on BoundExceeded, the actual so far on ReadBytesExceeded). Malformed footprints (scope, caps, unknown index, disallowed index kind, ungranted kind, non-canonical bytes, query construction failure) are a new BasicError variant: unpaid, rejected in check_tx, removed by the proposer (prepare_proposal.rs:215-223), never in a block. Resolver errors are classified, never propagated with ?: today every ? on a Drive error becomes StateTransitionExecutionResult::InternalError (process_raw_state_transitions/v0/mod.rs:360), the honest proposer strips it (prepare_proposal.rs:226), and a malicious proposer who includes it makes every validator reject the block. So Error::Query and Error::Protocol out of the resolver are a paid FootprintViolation; InternalError is reserved for Error::GroveDB and Error::Drive corruption variants, the policy today for transformer fetches.

SDKs: rs-sdk batch builders take a footprint and a preflight helper fetches entries with proofs and runs the module through rs-contract-runtime; wasm-sdk and the mobile SDKs call the preflight query instead, on section 13's decision against a second engine pin in clients (9.2.5); wasm-dpp2 gains BatchTransitionV2 at its two exhaustive matches (packages/wasm-dpp2/src/state_transitions/base/state_transition.rs:379-380 and :506-514) and the V1 constructor (packages/wasm-dpp2/src/state_transitions/batch/batch_transition.rs:103); the six document write entry points in packages/rs-platform-wallet-ffi/src/document.rs (platform_wallet_*) and packages/rs-unified-sdk-jni/src/transactions.rs (TransactionsNative.document*) gain an optional footprint argument, an FFI change unlike config JSON; dash-contract-testutils gets read fixtures and reports read cost; dash-contract types emits typed PropertyValue and entry constructors from the schema.

9.3 Tasks

rs-dpp, ABI crate and version tables (PV18)

• Add FootprintEntry, PropertyValue, RangeClause and HookContextV1 to packages/rs-contract-abi (new) over platform-value-core, re-exported by rs-dpp, with canonical golden vectors and the re-encode-equals-wire check.
• Add BatchTransitionV2 with read_footprint under packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition, max_version: 2 in the next DPPStateTransitionSerializationVersions generation (tokens precedent, dpp_state_transition_serialization_versions/v2.rs:68-72), accessors and signable fields.
• Append the footprint BasicError variant and the FootprintViolation detail with its four kinds and codes; decode in wasm-dpp2 and rs-sdk.
• Add the contract-free worst case to calculate_min_required_fee (state_transition_estimated_fee_validation.rs:18-28) from FeeWasmVersion rates and SystemLimits caps, keeping the trait signature; test that it never undercuts the dry-run bound.
• Add max_document_wire_bytes to SYSTEM_LIMITS_V8 and the registration check in the PV18 contract create and update state generations: W_max(type) computed from the parsed document type, nested properties included, for every type of a contract attaching an abi 1 module (and, at PV19, an entry_module), rejected above the cap with a BasicError naming the type.
• Add the four read caps, max_preflight_fuel and the preflight size caps to SystemLimits V8 (None earlier); host-call rates, hook_read_worst_case_tree_height and the bound formula version to FeeWasmVersion in FEE_VERSION6; abi 1 and dash_v2 to the engine sub-table grants; extend TEST_PLATFORM_V2/V3.

rs-drive, rs-contract-runtime, drive-abci

• Add footprint_entry_to_query and the resolver in a new packages/rs-drive/src/drive/hooks/read_footprint module: contract fetched with transaction: None, not-found mapped to None or empty, token balances on the apply: true path, LowLevelDriveOperations collected, max_hook_read_bytes enforced with ReadBytesExceeded and the running bound with BoundExceeded; the declared-bound function beside it.
• Implement dash_v2 over the resolved set: wire-byte match with the entry_len cap, FootprintViolation trap, per-byte and per-call fees, read_copy status codes, max_hook_host_calls.
• Add the next batch/state generation resolving the footprint before run_hook and classifying resolver errors per 9.2.7; bump batch_state_transition.state in DRIVE_ABCI_VALIDATION_VERSIONS_V14.
• Add footprint basic structure (CheckTx and Validator) calling footprint_entry_to_query, and ValidationOperation::FootprintRead in the CheckTx transformer.
• Add the preflight query (proto, next DriveAbciQueryVersions generation, rs-dapi drive_method!, grpc-coverage entry) with its fuel and size caps and the PlatformConfig concurrency cap, pool and disable switch; advertise availability and the effective caps in the get_status response so an SDK can route or degrade deterministically.
• Record the past-height proof decision (9.2.6) in section 05's register before the Phase 4 design review; if it resolves to serving them, the grovedb work and the query surface are that record's tasks, not Phase 4's.

SDKs and tooling

• rs-sdk: with_read_footprint(Vec<FootprintEntry>) on the six document transition builders under packages/rs-sdk/src/platform/documents/transitions/ (create, replace, delete, transfer, purchase, set_price) and the PutDocument, PurchaseDocument and TransferDocument traits under packages/rs-sdk/src/platform/transition/; a preflight helper under packages/rs-sdk/src/platform/ that fetches each entry with proof and runs the module through rs-contract-runtime behind a feature; offline vectors under packages/rs-sdk/tests/vectors. Acceptance: a mock-mode test reproduces a recorded verdict.
• wasm-sdk: the same argument on the six document_* builders in packages/wasm-sdk/src/state_transitions/document.rs and a preflight call to the query; evo-sdk TypeScript surface over both.
• rs-platform-wallet-ffi and rs-unified-sdk-jni: optional footprint bytes on the document write entry points named in 9.2.7; Swift and Kotlin wrappers; rows in docs/sdk/sdk-parity-manifest.json and packages/kotlin-sdk/PARITY.md.
• packages/rs-contract-sdk: typed entry constructors and a Reads accessor with a golden encoding test against the rs-dpp vectors; packages/rs-contract-cli: dash-contract types emits PropertyValue and entry constructors from the schema.
• packages/rs-contract-testutils: read fixtures, a block-boundary simulation, and a fuel plus read-cost report asserted in tests; dash-contract check rejects a module importing dash_v2 without abi 1 and the capability entry.
• Book: a new book/src/data-model/footprint-reads.md beside section 08's validation-modules.md, opening with PV18, stating the staleness rule and the enforceable-invariant class (9.1), and stating what a client can and cannot verify about one execution (9.2.6).

9.4 Tests

• Unit (packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/): undeclared read is PaidConsensusError with nonce bumped and read cost charged; ungranted kind, foreign contract type, unknown index, disallowed index kind, Document on an indexOnly type, an F64 clause, non-canonical bytes and over-cap footprints fail check_tx and basic structure unpaid; absent document yields None; an identity with no balance entry yields None with identical bytes in preflight and consensus; unused entries are charged; accepted and rejected runs charge equal read cost; ReadBytesExceeded charges the actual cost so far; 256 read_copy calls on a maximal item stay under the bound; read_request above the entry_len cap traps; check_tx gas_wanted >= block gas_used.
• Same-block contract: a DataContractUpdate adding an index plus a footprint naming it in one block yields NotInCommittedContract, never InternalError; a contract registered and read in one block resolves empty.
• Determinism: resolved bytes and root hash identical under independent_process_proposal_verification and in the section 14.3 nightly cross-arch workflow (ubuntu-24.04 plus ubuntu-24.04-arm); shuffled transition order yields identical verdicts; two transitions in one block show the second hook reading the pre-block value (the 9.1 rule); read-cost golden vectors (footprint fixture to CalculatedCostOperation bytes) pinned per grovedb pin.
• Proof: extend packages/rs-drive-abci/tests/strategy_tests/verify_state_transitions.rs (verify_state_transitions_were_or_were_not_executed, :258) with footprint entries; footprint_verdict_reproduces_from_n_minus_1_proofs captures proofs at N-1, runs the batch in block N, re-executes through the dash-contract-testutils harness and asserts the verdict equals ExecTxResult; a tampered proof fails; the read-bytes hash matches.
• Strategy: a new tests/strategy_tests/test_cases/hook_read_tests.rs with footprint-bearing batches and a golden root; upgrade test from PV17 showing BatchTransitionV2 rejected by serialization bounds before activation.
• Bound: adversarial fixtures rather than random footprints: 2^20 documents in one type, keepsHistory, a deep AVL, preallocated empties on a sibling index of the same type; actual never exceeds the bound, and BoundExceeded is reachable only through a forced fee-table mismatch.
• Guest-encoding bound, on nested fixtures (a flat type of 32 properties with 40-byte names and 600-byte values; a type of two objects with 80 properties each and 50-byte names; a three-level tree): max_document_wire_bytes >= W_max(type) >= encoded DocumentWire holds for every fixture document; the flat and two-object fixtures sit under D_max in storage and over it on the wire, and each copied max_hook_host_calls times charges within its declared bound and within the pre-check's reservation; a contract attaching an abi 1 module whose type exceeds the cap fails registration naming the type, and the same contract without the module registers.
• Fuzz: cargo-fuzz targets in the section 14.3 fuzz/ crate, footprint_decode, footprint_to_query and footprint_match (14.3 lists the matcher; the other two join it), oracle "the resolver never returns Err for a footprint that passed basic structure"; a signing test in rs-dpp asserting a maximal footprint batch with signature fits max_state_transition_size (20480).

9.5 Acceptance criteria

• A PV18 hook reading an owner profile, an index query, a token balance and an oracle feed accepts and rejects on a local network exactly as the harness predicted, with identical gas_used on every node.
• No footprint outcome yields InternalError, including query construction, same-block contract changes and resolver errors; violations are paid; malformed footprints never enter a block; every strategy-run verdict is reproduced by the harness from proofs captured at N-1 before N commits, and a client arriving after N reproduces the read-bytes hash in ExecTxResult (proof-backed reproduction after N is the deferred decision of 9.2.6, not a Phase 4 deliverable).
• Charged read credits never exceed the declared bound, enforced by BoundExceeded; gas_wanted covers reads, host calls and fuel; the preflight load test passes; PV17 nodes reject BatchTransitionV2 and the upgrade test shows footprints active from the first PV18 block.

9.6 Risks

• Declaration ergonomics: data-dependent point reads break when state changes between preflight and inclusion (a paid violation); non-canonical client encodings would too, which the canonical-form rule and PropertyValue prevent. Mitigation: generated constructors, preflight, and preferring declared index queries over derived ids; if testnet violation rates are high, a later PV can allow undeclared reads under a declared credit ceiling.
• Cost estimation drift: D_max and H = 92 over-reserve balance for small types and shallow trees; actual is charged, so users pay correctly but need headroom. Track bound-to-actual ratios and revise per fee version; the index-kind restriction is the price of a sound bound and lifts only with a per-kind formula.
• Engine drift: read cost enters fees and the app hash, and the storage-layer seek and byte accounting carries no GroveVersion gate, so a grovedb bump that changes merk read accounting is consensus-breaking for PV18 replay and must be PV-gated like fuel drift (section 11); the per-pin golden vectors in 9.4 detect it.
• Snapshot staleness misread as a bug, and cumulative invariants assumed to hold within a block (9.1); the harness simulates the block boundary and the book states both rules.
• Wire size: footprint bytes count against 20480; the entry cap and the size test bound it. Preflight is off-consensus user code on DAPI nodes: the caps, the advertised availability and the disable switch are the mitigation, not a proof.
• ABI 1 modules are new modules: frozen PV17 modules keep abi 0 and cannot gain reads without a new document type, the section 08 freeze policy.

---

---

Continued in part 10 of 14 below.

[QuantumExplorer]

Part 10 of 14 of the plan (continued from part 9 above).

10. Phase 5: constrained entry points

Gate: PV19 (section 14.2: wire id 24, SYSTEM_LIMITS_V9, DRIVE_ABCI_VALIDATION_VERSIONS_V15, DPP validation V8, CONTRACT_VERSIONS_V10, FEE_VERSION7 numbered 7, DriveVersion V12). Rule: user code proposes, Drive disposes (section 04).

10.1 Reasoning

Phases 3 and 4 only veto; auctions settle, subscriptions charge and escrows release, so author code must move state. Guest writes through host imports would put GroveDB Err (hence InternalError and a rejected block, process_proposal.rs:285-308) on the guest's path and need nested rollback and reentrancy rules. Instead the guest returns a bounded list of proposed operations, each an existing document, token or credit action; the batch pipeline validates, prices, applies and proves them with the code user batches already use, so every consensus rule applies unchanged.

10.2 Design

10.2.1 Transition and entry module

ContractCall (wire id 24 appended to StateTransitionType, whose last value is 20 today, packages/rs-dpp/src/state_transition/state_transition_types.rs:23-43): contract id, method index, bincode args, section 09's read_footprint, max_fuel, max_fee, identity contract nonce, user_fee_increase, signature; gated like section 06's transitions (is_allowed.rs:52-100).

Section 12's "Declared caps and the pre-VM reservation" bounds a Phase 5 call with max_fuel plus max_storage_bytes. Phase 5 replaces max_storage_bytes with a single required max_fee, the ceiling on the whole call's fee across both payers (10.2.2), because two declared bounds over one transition split the affordability check into two that can disagree. Section 12 is amended to match: its reservation formula drops the max_storage_bytes term for ContractCall and reads max_fee, affordability is balance >= max_fee, gas_wanted = max_fee bounds gas_used (10.2.4), and its "Failure charging" list gains the over-max-fee row of 10.2.9. Section 11.2.3's floor(tx) keeps its compute terms and takes its storage part from max_fee minus those terms rather than from an output-bytes cap, so one declared quantity is the storage bound here. Phase 3 batches declare no fuel field at all: their bound is the per-document-type maxFuel keyword (section 08.2.3), so max_fuel on the wire first exists here.

max_fee is bounded above as well as below (10.2.4 step 1), and the upper bound includes max_state_transition_processing_credits (SYSTEM_LIMITS_V5, section 06.1), which check_tx already enforces per transition. Without it one call reserves an arbitrary share of max_block_processing_credits, and since Tenderdash's reap loop breaks rather than skips once a candidate's gas_wanted would exceed the block max_gas (section 12, "Block budget and gas_wanted"), a call whose max_fee approaches max_gas is never reapable and blocks every lower-priority transaction behind it. max_fuel_per_entry_point * credits_per_fuel plus the largest admissible storage term therefore stays under the per-transition cap, which section 12 keeps a small fraction of the configured max_gas.

Signing authority is static per method. MethodDecl { name, max_fuel, max_operations, capabilities } declares debits_caller, writes_as_caller and token_transfers_from_caller; the transition's purpose_requirement and security_level_requirement derive from the called method's set: TRANSFER at CRITICAL whenever the method may debit the caller (the IdentityCreditTransfer rule, packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/identity_signed.rs:15-21), otherwise AUTHENTICATION at CRITICAL | HIGH | MEDIUM (the batch rule, batch_transition/v1/identity_signed.rs:17-40). The key check runs in check_tx and in-block before the guest, so an app-scoped authentication key can never move the caller's balance; a guest emitting a caller debit from a method without debits_caller gets ProposedOperationRejected.

The module is contract-level: DataContractInSerializationFormatV2 and DataContractV2 gain entry_module: Option<EntryModule { code_hash, abi_version: 2, methods: Vec<MethodDecl>, change_rules, pause_rules: ChangeControlRules, paused: bool }>. abi_version is section 08 rule 4's zero-based field (0 predicates, 1 reads, 2 entry points); section 13's Cargo features abi-v0, abi-v1, abi-v2 already carry the same numbers, and its Phases 4 and 5 task should name abi-v1 after dash_v2 rather than the rejected dash_cap_read_v1. Bytes come from the section 06 blob store through the section 08 prepare pass: exports memory and call: () -> i32; imports only from section 04.7's additive dash_v<n> grammar: dash_v1 (section 08 context), dash_v2 (section 09 reads) and the PV19 namespace dash_v3 holding emit(ptr, len) (capped by max_call_output_bytes). The grant rides the capabilities vector, not the namespace name (section 09 rejects per-capability names). A contract attaching an entry_module also passes 09.2.4's wire cap: every document type's W_max(type) at or below max_document_wire_bytes, since the call's footprint may name any of them.

10.2.2 Principal and payers

D1's keyless identity (section 04.4): id equals the contract id, balance a sum item under [96, id]. Section 04.4's lazy rule (the first transition attaching a module creates the principal, paid by its signer) extends to entry_module at PV19: the PV19 generations of insert_contract (v0 and v1 exist under packages/rs-drive/src/drive/contract/insert/insert_contract) and update_contract create it when entry_module is present and no principal exists; transition_to_version_19 creates none. That is the lazy-creation resolution section 14 records for the principals question (section 14, "Resolved here rather than left open"); section 14 should restate it in [96, id] terms, not [64, contract_id, 2]. An identity already at that id is a paid ContractPrincipalIdCollision (10.2.9), never an overwrite. Anyone funds it with IdentityCreditTransfer (the recipient balance must exist, identity_credit_transfer/state/v0/mod.rs:61-71).

Each proposed operation names its acting owner, Caller or Principal. Attribution rule, owned here and cited rather than restated elsewhere: the acting owner is both the per-action validator's owner_id and the StorageFlags owner of storage the operation creates (document_create_transition.rs:59-60 pattern), the caller pays processing (fuel, reads, validation, the nonce bump) plus storage of Caller operations, and the principal pays storage of Principal operations, so a deletion refunds whoever paid. Section 12's "Storage refund attribution" deferred this hybrid to Phase 5 and is amended to that sentence; section 03.3 rule 4's "the payer is always the signer" is section 04.5's one-payer PV15 rule and holds only until the two-payer event lands here. The new execute_event generation splits the FeeResult by owner and writes two balances; both are checked in the dry run and after apply (10.2.4). A caller never funds principal-owned bytes, so a contract cannot harvest a caller's storage fee by writing and deleting. Authority is ordinary: a mint as Principal passes only if manual_minting_rules (token_configuration/v0/mod.rs:84-90) names it, through the mint validator's check (token_mint_transition_action/state_v0/mod.rs:60-72); the module is the principal's signature. Groups: deferred (per-member signatures).

10.2.3 Proposed operations

Each names its acting owner: create, replace, delete and transfer documents in the contract's own types (guards, predicates and data triggers still run; DocumentTransfer goes through document_transfer_transition_action and the batch transformer's ownership check, batch/transformer/v0/mod.rs:1111-1117); transfer, mint and burn its own tokens (no group or emergency actions); CreditTransfer (Principal to anyone, Caller to Principal only) as the RemoveFromIdentityBalance plus AddToIdentityBalance pair (identity_credit_transfer_transition.rs:30-43); Schedule, Cancel and, where Phase 1b is active, ClaimAllowance (10.2.6), Principal only, so no caller can lock the principal's credits in the queue or consume its drain cap. Nothing in this list debits an identity other than the caller or the principal: a subscriber's balance moves only under the subscriber's own signature (a Caller to Principal transfer) or through Phase 1b's allowance, which the subscriber signed once; no document can authorize a debit by itself. Authority rule: a proposed operation has exactly the batch validator's authority for its acting owner; principal code has no elevated power over caller-owned documents. An auction therefore keeps its item (transferred to the principal by the listing call, as Caller) and its bid records principal-owned; settlement transfers the item to the winner and deletes the principal's own bids. Caps in SYSTEM_LIMITS_V9, proposed initial values: 16 operations and 8 document operations per call, 64 KiB output, 4 KiB args, plus fuel per call, scheduled calls per block, max_pending_scheduled_calls_per_contract and max_fee_multiplier; section 12 calibrates each against the block budget before PV19 signalling. One more cap is a correctness rule rather than a calibration: the serialized document a proposed create or replace would write is capped at max_state_transition_size - document_growth_headroom (20480 minus a SYSTEM_LIMITS_V9 constant, proposal 64 bytes; system_limits/v4.rs:23 for the 20480), checked in the basic-structure stage as ProposedOperationRejected { DocumentTooLarge }. Today every stored document is below 20480 by construction, because it arrived inside a signed transition of at most that size whose signature, nonces and ids leave more headroom than any later rewrite can consume, and 09.2.4's read pricing relies on that as D_max; max_field_value_size (5120) bounds one field, not a document, so a proposed create with eight such fields inside a 64 KiB output would otherwise write a document near 40 KiB that every later footprint read is priced to be half the size of. The headroom is what makes the cap hold on every rewrite path and not only on the two it checks: a document is rewritten by every later action, and ordinary transitions add bytes without re-supplying the document, so a document accepted at exactly 20480 would grow past it when updatePrice adds the eight price bytes (serialize/v3.rs:206-214) or a transfer sets the three $transferredAt fields (:104-110, :151-157, :198-204), and the $revision varint grows with every replace (:74-78). document_growth_headroom therefore exceeds the summed maximum growth of every optional system field the serialization format in force can add after creation (revision varint 9 bytes, price 8, the six $transferredAt and $updatedAt timestamps and heights 40, well under 64), pinned by a unit test that enumerates the serializer's post-creation fields and fails when a format change adds one the constant no longer covers. The cap keeps D_max valid at PV19 without touching the read formula; the guest-encoding bound W_max that 09.2.4 prices host copies with is per type from the schema, held under max_document_wire_bytes at registration for module-bearing contracts, and is not what this cap protects.

Sequential rule: operations transform, validate and apply one at a time in list order, each against the state after its predecessors, inside the block transaction under one savepoint per call (10.2.4). Validating against pre-call state would let two creates that both pass uniqueness (document_create_transition_action/state_v1/mod.rs:174-177) collide at apply as DriveError::CorruptedContractIndexes (add_reference_for_index_level_for_contract_operations/v0/mod.rs:341), an Err and a rejected block on every validator. This section owns the choice: section 11.2.2's Atomicity bullet is amended to it (apply is atomic by rollback to the per-call savepoint, not by validating the whole list before any conversion) and section 14.2's Phase 5 prerequisite records the savepoint as chosen, not validate-all-then-apply as an equal alternative. Every decoded ProposedOp gets the three stages a signed batch gets: basic structure (schema, sizes, max_field_value_size, system_limits/mod.rs:9; validate_basic_structure/v0, priced as processing), advanced structure (document_create_transition_action/advanced_structure_v1) and state, all against the block transaction; the decoder rejects Value::Float and any non-canonical encoding as ContractCallError { kind: BadOutput }. One operation per apply_drive_operations group, because max_transitions_in_documents_batch stays 1 at every PV to keep two document operations out of one GroveDB batch (system_limits/mod.rs:57, :109-112).

10.2.4 Execution flow, fees, mempool, atomicity

1. Pre-check (processor/v0/mod.rs:170-185, check_tx and in-block; the in-block run reads the live balance in the block transaction, which is what makes step 4 sound): floor = B_entry + read bound + min_call_fee. B_entry is the entry module's run bound, 08.2.6's formula with the call's budget: hook_instantiate_base + hook_translate_credit_per_code_byte * code_len + hook_memory_credit_per_page * pages + hook_context_credit_per_byte * context_len + max_fuel * credits_per_fuel, with code_len and pages from the blob metadata the contract's entry_module names and context_len the encoded CallContextV0 length (args, footprint, principal balance). min_call_fee is a new FEE_VERSION7 constant covering the fixed work every call does whatever the guest returns: decode and method lookup, the savepoint, the metered cost of the BumpIdentityDataContractNonce action (packages/rs-drive/src/state_transition_action/system/bump_identity_data_contract_nonce_action), the 10.2.5 receipt write at its fixed size and the empty callEffects write (storage at the storage-table price for a first write, replaced bytes thereafter, the larger of the two). floor <= max_fee <= min(floor * max_fee_multiplier, max_state_transition_processing_credits) (10.2.1); caller balance >= max_fee. Two of B_entry's terms need the contract, which the pre-check never has (section 12), so the check is split: check_tx and the in-block pre-check enforce balance >= max_fee and max_fee >= floor with the code and memory terms at zero, everything else being on the wire; step 2, contract in hand, recomputes floor with the module's real code_len and pages and rejects max_fee < floor as ContractCallOverMaxFee before instantiation, paid from the fixed terms. An SDK computes the full floor from the contract it fetches for the method declaration anyway (10.3). floor does not cover the proposed operations: their validation, dry-run and application costs are reserved per unit inside step 3 against max_fee, so a caller declaring only floor can afford a call that emits nothing, whatever the module's size, and a call that emits more degrades before the first unit it cannot pay for. Compute is collectable before the guest runs, and a caller reserves at most max_fee_multiplier times its work in block gas. Recheck re-validates identity nonces (check_tx_verification/v0/mod.rs:447-463) and address balances (:423-445) but not identity balances today: has_identity_minimum_balance_pre_check_validation occurs once in that file, in the FirstTimeCheck arm at :230-241, with no counterpart in the Recheck arm (:397-511). The ContractCall recheck arm adds balance >= max_fee, so a call whose balance fell is evicted.
2. Transform: the 10.2.8 checks; a savepoint before any write (set_savepoint, as the proposer does per transition at process_raw_state_transitions/v0/mod.rs:186-187; validators set none today, :117-127, so this is PV19-gated under DriveVersion V12); footprint resolved against the block transaction, not Phase 4's snapshot (a bid must see the bid before it); the full floor check of step 1; then, as the first unit under step 3's reservation rule, B_entry is reserved against max_fee and the guest runs at min(max_fuel, method max_fuel, cap); output decoded. The instantiation, translation, memory and context terms are thus reserved before the engine is entered, and a maximal module that returns an empty list is paid for by floor alone.
3. Per operation, in order, under one accounting rule with two running sums. reserved is the sum of the worst-case bounds of every unit started (B_entry, the read bound, the fixed terms, then each operation unit below); accrued is the actual metered cost of every unit completed, where out of fuel counts the whole budget (08.2.7). Before a unit runs its bound is added to reserved and reserved <= max_fee is required; a unit that would breach it never runs and the call degrades as ContractCallOverMaxFee. The charge is always accrued, never reserved: bounds gate work and actuals are billed, the model section 12 states, and accrued <= reserved <= max_fee holds throughout. The units and their bounds: the three stages with the acting owner_id, bounded by max_proposed_operation_processing_credits (SYSTEM_LIMITS_V9, sized from max_field_value_size, the per-type index caps and the validator constants of FeeProcessingVersion); guards at their static units (07); target-type predicates at their B (08.2.6), computed from the target type's ValidationModuleRef before instantiation; data triggers at their PV's declared cost; then a dry run (apply_drive_operations with apply = false, one operation per batch, so the phantom-group defect of 10.2.3 cannot enter the estimate), whose own processing is bounded by the same constant, added to running per-payer estimates; a total over max_fee, or a payer estimate over its balance after the call's own debits, is ContractCallOverMaxFee; then apply, under the step-2 savepoint that makes the sequence atomic; after the last operation the callEffects write (10.2.5), bounded by max_call_output_bytes at the storage-table price, is reserved and applied the same way. Any stage failure, and any apply-time Err from the closed list (unique index conflict, CorruptedContractIndexes above; insufficient balance, IdentityError::IdentityInsufficientBalance, remove_from_identity_balance/v0/mod.rs:109; token supply or balance overflow; missing document), is ProposedOperationRejected { index, code }: the operation's index and the inner error's u32 code() (codes.rs:11), flat rather than a nested ConsensusError, so clients dispatch on the outer code and the layout is fixed. The list is an enumerated From in the converter with a test per variant; anything outside it stays InternalError.
4. Charge: the actual FeeResult is known after apply and before the debit (execute_event/v0/mod.rs:53-87). If the actual total exceeds max_fee, or a payer's share exceeds its balance after the call's own debits, the call is rolled back and degraded; otherwise both balances are written once. Degrade, on any failure from step 2 on: rollback_to_savepoint, then BumpIdentityDataContractNonce with the error and fuel_used, plus the 10.2.5 receipt recording the failure, so compute plus the receipt's fixed bytes, paid by the caller (never Unpaid, execute_event/v0/mod.rs:101-104). The bound, derived rather than asserted: the degraded fee is accrued at the point of failure; every unit that contributed to it had its bound added to reserved and checked against max_fee before it ran (the entry run by B_entry, reads by the declared bound, each operation unit by step 3's rule, the fixed terms by min_call_fee), and each actual is at most its bound, so accrued <= reserved <= max_fee; step 1 checked max_fee against the live pre-call balance in the block transaction, which the rollback restores; therefore the degraded fee is affordable, required_removed_balance (the storage part, fee_result/mod.rs:223, here only the receipt's fixed bytes) never exceeds the balance, and the debt path (apply_balance_change_from_fee_to_identity/v0/mod.rs:87-135) is unreachable. The earlier claim that the degraded fee stays under floor is withdrawn: instantiating predicates for several proposed operations, their translation and context charges, and the native estimation of each operation are not covered by floor, and need not be, because the invariant that matters is accrued <= max_fee <= pre-call balance. gas_used <= gas_wanted holds because gas_wanted = max_fee and gas_used = accrued, not because the estimate is exact.

Savepoint discipline: the call's savepoint is consumed by the rollback on every non-success path and left inert on success, as the proposer's kept-transition savepoints are (:225-262; residue is inert at non-genesis heights); at genesis_height a call is ContractCallUnavailable, preserving the init_chain single-savepoint rule (:128-135). No submessages: the guest never sees its operations' outcome, hence no reentrancy. check_tx runs step 1 plus the 10.2.8 checks, sets gas_wanted = max_fee (check_tx.rs:66-70), never runs the guest (D8); priority stays user_fee_increase * 100.

10.2.5 Events and the call receipt

Section 06.6's punt on a general event log stands; Phase 5 adds a receipt, because the nonce alone proves less than the earlier draft claimed. A proof carrying the identity contract nonce shows that the nonce was consumed, not that this call's operations were applied: 10.2.4 advances the nonce on a rolled-back failure too, and two differently signed calls can compete for one nonce, so the existing verifier's distinction between ExecutionProved and AffectedState (verify_state_transition_was_executed_with_proof/v0/mod.rs:2097-2108, whose classifier is an exhaustive match with DataContractUpdate => false for exactly this reason) applies. So every executed call, success or paid failure, writes two documents in the ContractCalls system contract 10.2.6 creates, both at the slot id hash(contract_id || caller_id), one slot per caller per contract, created by the first call and replaced in place by every later one (replaced bytes, no growth), owned by the caller with the caller's StorageFlags. callReceipt, fixed size, its storage part of min_call_fee (10.2.4 step 1): contractId; callHash, sha256 of the signed transition bytes; nonce, the identity contract nonce consumed; outcome, 0 for success, else the 10.2.9 code of the failure; effectsHash, sha256 of the canonical encoding of the applied operation list (the validated ProposedOps in order, the empty-list hash on failure); height. callEffects, that list itself as bytes, at most max_call_output_bytes, reserved and charged as the last unit of 10.2.4 step 3 on success and written empty on failure (the empty write is in min_call_fee). The list is stored rather than only hashed because the affected-state maps cannot reconstruct it: two opposite transfers leave the balances where they started, and several replacements of one document expose only the last. On failure both documents are written beside the nonce bump and the fee debit, outside the rolled-back savepoint (10.2.4 step 4).

Native-only write rule, stated because a system contract confers no protection by itself: the tree protects withdrawal and rewardShare documents with explicit reject_data_trigger bindings (batch/data_triggers/bindings/list/v0/mod.rs:70-101), and the comment there records why the mutability flag was not used instead (the documents would lose their revision). callReceipt and callEffects follow that pattern: Create, Replace, Transfer, UpdatePrice and Purchase on either type carry reject_data_trigger bindings, the schema sets transferable: never and tradeMode: none as a second line, and the only batch action admitted is Delete, owner-checked as every delete is (document_delete_transition_action/state_v0/mod.rs:97-103), so the caller can reclaim the storage and nobody, the caller included, can rewrite the slot. Both documents are written only by the call's execute path and the drain, which emit DriveOperations directly and never pass the batch triggers, exactly as the withdrawal status events write withdrawal documents. Without this rule a caller could Replace its own receipt with outcome: 0 and a chosen callHash, and a state proof would then vouch for a success that never happened; the forgery test in 10.4 pins it.

VerifiedContractCallEffects, a new StateTransitionProofResult variant (proof_result.rs:23), carries the receipt, the effects list and the affected documents, credit and token balance maps from one multi-root proof. Two authentications, kept separate because they answer different questions: the receipt and the effects list prove what this call did, while the affected-state maps show those targets as of the proof height, informational, since later transactions may have moved them without invalidating the receipt. The verifier classifies from the receipt, the one arm of state_transition_proof_binds_execution whose answer depends on proof content, documented at the match: ExecutionProved iff the proven receipt's callHash equals the hash of the transition being verified and sha256 of the proven callEffects bytes equals its effectsHash, in which case outcome and the ordered operation list are authenticated; a receipt that is absent or names another call (a later call from the same caller replaced the slot, or a competing call consumed the nonce) yields AffectedState, with the receipt handed to the SDK so it can see what did execute at that slot. Retention is the slot's: the pair lives until the caller's next call to that contract overwrites it or the caller deletes it, so a client that needs the record archives the proof, as it would any receipt. Scheduled calls have callOutcome (10.2.6), which gains effectsHash and an effects field under the same write rule. An event stream is an event document type the contract writes: priced, provable by index queries. A host log import is rejected: unpriced, unproven.

10.2.6 Scheduled execution

Schedule { method, args, read_footprint, fire_at_ms, prepaid_credits } adds an entry to the section 06.5 settlement queue under its key (big-endian fire time, then entry id), with entry id contract_id || sequence_be from a per-contract u64 counter element beside the queue (bumped per Schedule; a sibling pending count enforces max_pending_scheduled_calls_per_contract), so equal fire times drain by contract id then sequence. The entry is stored under StorageFlags::new_single_epoch(epoch, principal) and moves prepaid_credits into the entry's prefunded balance under [40] (drive_op_batch/prefunded_specialized_balance.rs:14-28), a conservation term. read_footprint is section 09's grammar with the scope of the scheduling contract, validated at scheduling exactly as a signed call's footprint is in basic structure (canonical form, caps, named indexes; a malformed one is ProposedOperationRejected), stored in the entry with its bytes prepaid like the rest of it, and at fire re-priced under the fee version then in force and resolved against the block transaction as step 2 does; an undeclared read is a FootprintViolation outcome. Arbitrary args cannot tell the host which queries to build, so the stored footprint is the only source of a scheduled read. Bound at scheduling and again at fire: prepaid_credits >= B_entry(method max_fuel) + read bound + min_scheduled_call_fee (a second new FEE_VERSION7 constant covering drain overhead plus the outcome write), the step-1 floor for a payer with no identity balance; an entry that no longer covers it is dropped. Step 3's per-unit rule then runs against the prepaid remainder in place of max_fee: a unit whose bound would exceed the remainder never runs and the entry drains as rejected, charged accrued, so a fired entry's charge never exceeds its prepaid balance and the drain never reaches an unaffordable debit. No transition deletes a contract (state_transition_types.rs:23-43 has none), so an entry leaves the queue only by fire, drop or Cancel, each refunding to the principal.

Payer path: the drain is the PV19 generation of the 06.5 settlement drain, not a second one: one block-start event in DriveAbciSettlementMethodVersions (new, section 06.5) as an OptionalFeatureVersion, run in the run_dao_platform_events slot (run_block_proposal/v0/mod.rs:310), one RangeToInclusive read in key order regardless of kind, entry kind dispatched per entry, with max_scheduled_calls_per_block a per-kind sub-cap inside max_settlements_per_block. It is not an ExecutionEvent: every variant is built by ExecutionEvent::create_from_state_transition_action from a StateTransitionAction (execution_event/mod.rs:178), and a block event has no transition, no nonce and no signer to build one from. PaidFixedCost is the nearest existing payer shape and is still a signed transition: the MasternodeVote arm (execution_event/mod.rs:293-304) pays a fixed cost from a prefunded specialized balance (DeductFromPrefundedBalance of contested_document_single_vote_cost, masternode_vote_transition.rs:49-57) while fees_to_add_to_pool books the same amount into the pools (execute_event/v0/mod.rs:529-551). The drain reuses that payer shape without the transition. Per entry it runs steps 2 to 4 as the principal with the entry id as payer: no nonce, no signature, fee from the same per-operation dry runs and actuals with fuel and reads as PrecalculatedOperations, capped by the prepaid balance, deducted with deduct_from_prefunded_specialized_balance_operations (packages/rs-drive/src/drive/prefunded_specialized_balances/deduct_from_prefunded_specialized_balance_operations/mod.rs:31); degrade is rollback to the entry's savepoint, delete the entry, write a rejected outcome.

That savepoint is set and consumed on both proposal paths under the PV19 gate (DriveVersion V12): rollback_to_savepoint runs only while proposing_state_transitions is true today (process_raw_state_transitions/v0/mod.rs:136-137, section 02.1.9), so rolling back inside a block event on every node is new consensus behaviour. Section 14.2's Phase 5 prerequisite therefore extends from proposed operations inside a transition to block events, section 11.3's fault-injection task gains the block-event case (an injected failure at operation k of a drained call leaves every touched subtree equal to its pre-entry state on proposer and validator alike, with only the queue entry, the prepaid balance, the fee pools and the callOutcome differing), and section 02.1.9 item 3, whether grovedb's in-transaction Merk and root-hash caches observe a savepoint rollback, becomes a Phase 5 prerequisite rather than an unowned open item.

Used credits go to a block_event_fees accumulator merged into BlockFees (BlockFeesV0 { processing_fee, storage_fee, refunds_per_epoch }, block_fees/v0/mod.rs:8-14) before process_block_fees_and_validate_sum_trees, which today sees only aggregated_fees() (run_block_proposal/v0/mod.rs:393-396); without it every fired call destroys credits and CorruptedCreditsNotBalanced halts the node. The remainder returns to the principal (Cancel early).

Budget: within the shared scan, scheduled entries stop at max_scheduled_calls_per_block = floor(0.1 * max_block_processing_credits / (max_fuel_per_entry_point * credits_per_fuel + max scheduled operation cost)), the 06.5 derivation with the guest run in the per-entry term, and the drain's metered credits, both kinds, are added to the 06.1 accumulator before the first transition, so validators re-execute at most a tenth of the budget in scheduled guest runs and the block budget bounds the sum. Outcomes are documents in callOutcome, a type of a new SystemDataContract::ContractCalls entry (packages/data-contracts/src/lib.rs:36-49, created in transition_to_version_19): fired, rejected, or dropped; owned by the principal, storage paid from the prepaid balance with StorageFlags owned by the principal (the 06.5 fixed-size fallback covers a fee-table change), deletable by the principal through a proposed DocumentDelete (the one foreign-type case) for the refund. No outcome is free and none is Err (a block-event Err halts the node). A host fault in the drain is therefore the one halt no in-chain or proposer-side switch reaches: the drain runs before the transactions of every block, empty blocks included, so a freeze document cannot land and the proposer denylist (11.2.6 layer 2) filters nothing; recovery is D6's coordinated binary behind a network-keyed activation height (11.2.5, 11.2.8), whose fix drops the faulting entry as a dropped outcome or disables the drain, rehearsed on a devnet with an injected faulting entry before PV19 (11.3). That is why the drain's guest-reachable outcome set is closed and fuzzed rather than merely enumerated. Pause (10.2.8) leaves no dormant entries: due entries of a paused contract drain as rejected outcomes with refund, so they cannot pin the head of the queue and starve other contracts. Rows 1 to 4 of 10.2.9 map to outcome kinds; rows 5 to 7 have no scheduled analogue except the host-fault Err. Auctions settle at the deadline from a scheduled method whose footprint names the bid index. Subscriptions come in two shapes, and only one needs Phase 1b. A pull subscription, where the subscriber's balance is debited each period without a fresh signature, exists only through Phase 1b's allowance: the scheduled method emits ClaimAllowance { payer } over the 06.5 allowance the subscriber signed once, and where Phase 1b has not activated the operation is a BasicError. A prepaid subscription needs nothing from Phase 1b: the subscriber funds the principal under its own signature (a ContractCall whose Caller to Principal CreditTransfer records a principal-owned subscription document with the prepaid balance, or a plain IdentityCreditTransfer to the principal id), and each period the scheduled method decrements that document and pays the payee from the principal balance, Principal to anyone. No subscriber is ever debited on the strength of a document, which 10.2.3's credit rule forbids and a scheduled run, having no subscriber signature, could not do. The PV19 example and acceptance runs use the prepaid shape, with the pull shape added where Phase 1b is active.

10.2.7 MEV and ordering

Drive executes request.txs in Tenderdash's reaped order and only drops or delays (prepare_proposal.rs:97-114), so the proposer may put its own calls first. PV19 ships no ordering protocol (section 14.7 question 6) and reduces the incentive: settlement through 10.2.6 (bids in block N settle at N+1 in document-id order, a uniform-price batch), commit-reveal as two calls, the 10.2.5 receipt making reordering auditable. Every capability grant passes the section 11.2.9 MEV assessment; user_fee_increase is priority, not ordering.

10.2.8 Permissioning

Code replacement is a DataContractUpdate admitted by change_rules.can_make_change (change_control_rules/v0/mod.rs:30-44). At PV19 change_rules and pause_rules accept only ContractOwner and NoOne (authorized_action_takers.rs:26-33): updates stay owner-signed under validate_update_ownership_and_version (packages/rs-dpp/src/data_contract/methods/validate_update/common/mod.rs:44-51), NoOne freezes code forever, and the other three of the five variants (Identity, MainGroup, Group) fail basic structure until a later PV adds a non-owner signer rule (group approval has no contract-update path, the reason 11.2.6 rejects group writes). paused flips under pause_rules (TokenEmergencyAction::Pause shape, packages/rs-dpp/src/tokens/emergency_action.rs:13-17): calls fail paid, due scheduled entries drain rejected (10.2.6). Exactly two disables exist: the OptionalFeatureVersion slot being None for the PV, and the section 11.2.6 registry documents (deployer allowlist at registration, frozenContract and globalFreeze per call) read in consensus and billed to the call, both mapping calls to ContractCallUnavailable. No ExecutionConfig field may be read on the ContractCall path (the use_document_triggers anti-pattern, section 04.6); the 11.3 config audit covers the new code.

10.2.9 Determinism and error classification

Codes 41100-41199 appended to StateError (after section 08's 41000-41099; the last block allocated today is 40900-40999, codes.rs:396-401). Only the last row is an Err.

Condition	Class	Paid
nonzero return, trap, out of fuel (full budget), bad or non-canonical output	ContractCallError { kind }	yes
operation fails a stage, the authority rule or an undeclared capability, or applies to a listed Err	ProposedOperationRejected { index, code }	yes
max_fee below the full floor at step 2; a unit's reservation, an estimate or an actual over max_fee or a payer balance (10.2.4)	ContractCallOverMaxFee	yes
paused, frozen, unlisted deployer, no such method, module absent, genesis height	ContractCallUnavailable { reason }	yes
identity exists at the contract id on insert or update	ContractPrincipalIdCollision	yes
args, footprint or max_fee outside its bounds, key purpose or level below the method's, unknown contract	BasicError or signature error, rejected in check_tx	no
node-local host fault, Err outside the closed list	Err, InternalError, block rejected	no

10.3 Tasks

rs-dpp, ABI, version tables (PV19)

• Add ContractCall (wire id 24) with method-derived purpose_requirement and security_level_requirement; EntryModule and MethodDecl capabilities on DataContractInSerializationFormatV2 and DataContractV2 (CONTRACT_VERSIONS_V10) with validate_update restricted to ContractOwner and NoOne; ProposedOp and CallContextV0 (abi 2) in the proposed packages/rs-contract-abi crate that section 13 creates, with a canonical decoder; the 10.2.9 variants; contract_serialization_version.max_version raised to 2 in CONTRACT_VERSIONS_V10 (1 today, dpp_contract_versions/v6.rs:37-41), so PV18 nodes reject format V2 by bounds; the 10.2.3 caps, max_proposed_operation_processing_credits and max_fee_multiplier in SYSTEM_LIMITS_V9; the new min_call_fee and min_scheduled_call_fee constants in FEE_VERSION7. Accepted when a HIGH authentication key cannot sign a caller-debiting call, the decoder rejects Float, and a V2 contract fails deserialization under CONTRACT_VERSIONS_V9.

rs-contract-runtime

• Implement dash_v3.emit, the call export and run_call, HostFault the only Err. Accepted when every runtime error variant maps to a 10.2.9 row.

rs-drive

• ContractCallTransitionAction under packages/rs-drive/src/state_transition_action plus converter with the enumerated Err list. Accepted when a test asserts the emitted DriveOperations are only IdentityOperation, DocumentOperation, TokenOperation and PrefundedSpecializedBalanceOperation and net to zero credits.
• insert_contract v2 and the update_contract counterpart, both gated by DriveVersion V12, creating the principal sum item under [96, id] and rejecting an existing identity. Accepted when the balance proves and the collision test passes.
• VerifiedContractCallEffects prove and verify arms with the receipt-keyed ExecutionProved classification (10.2.5); the scheduled-call entry kind; the ContractCalls system contract with callOutcome, callReceipt and callEffects and their reject_data_trigger bindings (10.2.5); the receipt and effects writes in the call's execute path on success and on paid failure, outside the rolled-back savepoint. Accepted when the proof verifies under rs-drive's verify feature, a paid failure's receipt verifies with its code, and an ordinary DocumentReplace of a receipt is rejected.

rs-drive-abci

• ContractCall processor impls: step 1 with the multiplier, the max_state_transition_processing_credits bound and the recheck balance check, the full floor and the B_entry reservation before instantiation in transform, guest run under the call savepoint (DriveVersion V12 on both proposal paths), per-operation units under the step 3 reservation rule (reserved gates, accrued is charged), and the two-payer execute_event generation with the post-apply check and degrade. Accepted when the 10.2.9 unit rows and the estimator-miss test pass.
• Scheduled-call drain as an OptionalFeatureVersion block event with the prefunded payer path, its own per-entry savepoint on both proposal paths, block_event_fees in BlockFees, the stored footprint re-priced and resolved at fire, the budget-derived cap and, where Phase 1b is active, ClaimAllowance. Accepted when a golden-hash strategy test with verify_sum_trees passes through fire, drop, cancel and pause.

SDKs, DAPI, tooling

• rs-sdk ContractCall builder, affected-state wait, preflight and vectors; wasm-sdk and evo-sdk contractCall; wasm-dpp2 match sites and proof converter; no proto change (opaque bytes; state via existing queries). Accepted when an rs-sdk test broadcasts a ContractCall against a local network and waits for VerifiedContractCallEffects, and the wasm-sdk and evo-sdk vectors round-trip the same bytes.
• rs-sdk-ffi and packages/rs-unified-sdk-jni contract_call carrying the consensus code (today string-matched to ProtocolError, packages/rs-sdk-ffi/src/error.rs:159-160, no code carried). Accepted when a Swift and a Kotlin test observe the 10.2.9 code of a ContractCallOverMaxFee call instead of ProtocolError.
• Section 13 deliverables (its Phases 4 and 5 checkboxes): #[hook(entry_point)] in dash-contract-sdk, dash-contract simulate over a call fixture and dash-contract deploy for ContractCall, emit capture in dash-contract-testutils, the "first entry point" tutorial. Accepted when simulate over the auction fixture reproduces the devnet fee within the estimator bound and the tutorial contract passes the 10.5 devnet run.

10.4 Tests

• Unit (drive-abci): each 10.2.9 row yields its class with nonce bumped and fuel_used charged; a credit op to a third party, a foreign-contract document, an unauthorized principal mint and a caller debit from a method without debits_caller are rejected; two creates colliding on a unique index yield ProposedOperationRejected, never InternalError, with no partial writes; a HIGH authentication key cannot sign a caller-debiting call; an entry-module update signed by a non-owner is DataContractUpdatePermissionError; a maximal write into a deep index that misses the estimate degrades to compute only, never the debt path; deleting a principal-owned document written in a caller's call refunds the principal; gas_used <= gas_wanted for a maximal call; a cold-cache call of a module at max_hook_code_size and max_hook_memory_pages returning an empty list, from a caller funded exactly to max_fee = floor, succeeds paid with accrued <= reserved <= max_fee and the balance at or above zero; a call whose max_fee covers the wire floor but not the module terms is ContractCallOverMaxFee before instantiation with the engine counter at zero; forgery: an ordinary DocumentReplace of the caller's own callReceipt with outcome: 0, a DocumentCreate at the slot id and a DocumentTransfer of the receipt are each rejected, an owner DocumentDelete succeeds with the refund and the next call recreates the slot; a proposed create whose serialized document would exceed max_state_transition_size - document_growth_headroom (eight fields at max_field_value_size) is ProposedOperationRejected { DocumentTooLarge } with nothing written, one exactly at the cap is accepted, then priced by updatePrice, transferred and replaced at a two-byte revision, and its serialized size stays at or below max_state_transition_size after each; the headroom unit test enumerates the serializer's post-creation system fields and asserts their summed maximum growth is below document_growth_headroom; a footprint reading that document max_hook_host_calls times charges within its declared bound; a maximal call whose every operation fails still degrades as paid with the caller's balance exactly at max_fee; a caller funded exactly to max_fee = floor submitting the maximal predicate-bearing operation list that fails at the last operation is charged accrued <= max_fee, never enters the debt path, and its receipt records the failure, and the same call with max_fee one credit below the last unit's bound degrades before that unit with the engine and estimator counters unchanged for it; receipts: success and paid failure each verify as ExecutionProved with outcome and a callEffects list matching effectsHash, a later call from the same caller turns the earlier call's proof into AffectedState, a receipt with a tampered callHash fails verification, and effects bytes that do not hash to the receipt's effectsHash fail it too; a max_fee above max_state_transition_processing_credits fails paid in check_tx and at execution, the section 06.1 per-transition cap test extended to this type.
• Strategy: OperationType::ContractCall (packages/strategy-tests/src/operations.rs:781-856) and packages/rs-drive-abci/tests/strategy_tests/test_cases/contract_call_tests.rs (new) running an auction and a prepaid subscription contract (the pull variant through ClaimAllowance where Phase 1b is active), the auction settling and the subscription charging from scheduled methods whose stored footprints name the bid index and the subscription document, to golden root hashes under verify_state_transition_results, independent_process_proposal_verification and verify_sum_trees, through fire, drop, cancel and pause; a fault injected at operation k of a drained scheduled call leaves every subtree the call's operations touched equal to its pre-entry state, for every k, on proposer and validator alike, with only the queue entry, the prepaid balance, the fee pools and the callOutcome document differing (the 11.3 paid-rejection snapshot); summed per-operation estimates at or above summed actuals over the corpus; a full queue of dropped entries grows state only by paid bytes; cross-arch matrix (section 14); PV18 to PV19 upgrade test: a format V2 DataContractCreate and DataContractUpdate and a ContractCall are rejected before activation and accepted from the first PV19 block.
• Proof and fuzz: VerifiedContractCallEffects verifies in rs-sdk and wasm-sdk; cargo-fuzz targets fuzz/fuzz_targets/proposed_op_decoder.rs (new) and fuzz/fuzz_targets/proposed_op_three_stages.rs (new, arbitrary decoded documents through the three stages) in section 14's proposed workspace-excluded fuzz/ crate, run from .github/workflows/tests-rs-nightly-long-running.yml for eight hours each per night with zero Err and zero panics on the corpus; wasm-dpp2 decodes every 10.2.9 variant, ProposedOperationRejected included, from its ExecTxResult.info bytes; a maximal call fits 20480 bytes.

10.5 Acceptance criteria

• An auction (principal-owned item and bids, item transferred to the winner by a scheduled settlement that reads the bids through its stored footprint) and a prepaid subscription contract run end to end on a PV19 devnet with every read and effect proven from mobile SDKs; no outcome is InternalError or Unpaid.
• No call leaves compute unpaid; every executed call leaves a callReceipt and callEffects pair that verifies, and no batch transition can write either; proposals over max_fee cost accrued only; gas_used <= gas_wanted by the 10.2.4 degrade; scheduled calls fire within one block under the block budget; CorruptedCreditsNotBalanced never fires.
• Code replacement, pause, freeze and allowlist changes need no protocol version; PV18 nodes reject ContractCall through is_allowed and format V2 contracts through the serialization bounds.

10.6 Risks

• Operations apply sequentially but the guest never sees their outcome, so a read-modify-write across its own output stays two calls; a later ABI minor may add in-call state tracking.
• Sequential application, the per-call savepoint on validators, the per-entry savepoint in a block event and the two-payer charge are new consensus-critical execute_event paths; they reuse apply_drive_operations unchanged and land first with the golden-hash suite.
• The closed Err list is hand-maintained; a Drive change adding a guest-reachable Err outside it is a liveness bug the fuzz target must catch.
• In-flight footprints mean N-1 proofs do not reproduce a call; the receipt is the evidence. Proposer extraction becomes real once value flows (10.2.7).

10.7 Beyond Phase 5 (deferred)

• Contract-to-contract calls: need a read overlay for speculative sub-calls and a pop-savepoint primitive (grovedb has RocksDB savepoints, storage/src/rocksdb_storage/storage.rs:328-347, but no pop and no overlay), nested error classification and cross-principal fee attribution (section 03); demand-gated, section 14.7 question 5 (b).
• Performance tier: wasmtime 36 LTS (MSRV 1.86; the 48 LTS line needs Rust 1.95, above the tree's 1.92) with Cranelift, or Pulley once it leaves Tier 2, plus install-time instrumentation (finite-wasm) under a protocol version, after the section 11 fuel-equivalence evidence.
• zk-predicates: per-document-type verifying key over the shielded verification plumbing (section 03); design study from Phase 3.
• CosmWasm ABI compatibility: Storage, Querier and submessages mapped onto footprints and proposed operations, only on an ecosystem argument.

---

---

Continued in part 11 of 14 below.

[QuantumExplorer]

Part 11 of 14 of the plan (continued from part 10 above).

11. Cross-cutting: determinism, security, and engine governance

Phases 1 to 5 (PV15 to PV19, section 14); paths under packages/rs-drive-abci/src unless noted.

11.1 Reasoning

User code has four ways to hurt the chain. (1) A result that differs across nodes. (2) An identical result in the wrong class: any Err in the transition loop becomes InternalError (execution/platform_events/state_transition_processing/process_raw_state_transitions/v0/mod.rs:212-219); the proposer strips it unpaid (abci/handler/prepare_proposal.rs:226-233, TxAction::Removed) and validators reject a block that carries one (abci/handler/process_proposal.rs:285-308). (3) A node-local switch on a consensus path: use_document_triggers (execution/validation/state_transition/state_transitions/batch/state/v0/mod.rs:82, :279), verify_sum_trees (execution/platform_events/block_processing_end_events/process_block_fees_and_validate_sum_trees/v0/mod.rs:174) and verify_token_sum_trees (execution/platform_events/tokens/validate_token_aggregated_balance/v0/mod.rs:15); a node with sum-tree verification off keeps running where the rest halt. (4) Work that is never paid for: the proposer's only time bound is proposer_tx_processing_time_limit (abci/config.rs:39, None by default at :60, which the read at process_raw_state_transitions/v0/mod.rs:150-158 turns into u16::MAX ms), node-local and tested only between transitions, so one transition overshoots it freely; validators re-execute with no timer (process_proposal.rs:235-241 runs the proposal with the proposing flag false) under the 50 s propose timeout (packages/dashmate/configs/defaults/getBaseConfigFactory.js:448). Cost bounds are therefore a liveness property, and every bound must be computable from bytes and committed state before a guest runs.

11.2 Design

11.2.1 Determinism bug classes

Class	Mitigation (owning section)
NaN, floats	Prepare pass rejects float and SIMD opcodes (08); wasmi deterministic feature; guards integer-only (07); F64 reaches a guest as opaque bytes (09)
Stack depth	Config::set_max_recursion_depth and set_max_stack_height from SystemLimits, set_min_stack_height equal to the maximum so the value stack is allocated before guest entry (08.2.1); no reentry from host functions (04.2); a JIT tier needs finite-wasm instrumentation (10.7)
Fuel drift	Upstream promises only "relatively stable" fuel, so every bump, patch included, is a consensus event: one immutable vendored engine per wasm_engine_version (11.2.5); golden fuel vectors regenerated only in PV-opening PRs
Compile bombs, module-limit gaps, cold caches	CompilationMode::Eager at registration, billed per byte (12); caps on code bytes, functions, locals, globals, tables and br_table targets; proposal allowlist frozen per PV; one consensus_config(platform_version) for prepare and run; the rs-contract-runtime translated-module LRU keyed by code hash and wasm_engine_version (section 08, run_hook; node-local, liveness only, never correctness) plus max_distinct_modules_instantiated_per_block (new) on SystemLimits, so cold-cache translation after a restart or rolling upgrade is bounded per block
Host impurity, node-local switches	No clock, environment, randomness, filesystem or network in host functions; BTreeMap only in guest-visible data; HookContextV0.block is last_block_info() (08 decision (b)), the block whose committed state the snapshot reads come from (09), not the BlockInfo being processed; both are consensus data and both carry a proposer-chosen time (one block earlier for the committed one), so a time-conditioned guest is proposer-influenceable (11.2.9); no ExecutionConfig or AbciConfig field read on any hook or contract-call path

11.2.2 Error classification

Everything a guest or author can cause is a paid ConsensusError; Err is reserved for HostFault. Three invariants make "paid" achievable:

• Stage: every guard or guest evaluation runs in state validation, after identity, balance and nonce are loaded. The batch path bumps the per-contract nonce there (BumpIdentityDataContractNonce, execution/validation/state_transition/state_transitions/batch/state/v0/mod.rs:270-278), and two other state validators in the same directory already fall back to StateTransitionAction::BumpIdentityNonceAction on a paid rejection (data_contract_create/state/v1/mod.rs:75-76, identity_update/state/v0/mod.rs:64-65), so ContractCall (10) takes its bump action from that existing pattern (packages/rs-drive/src/state_transition_action/system/bump_identity_nonce_action). Structure and basic validation evaluate nothing user-supplied beyond size and shape.
• Atomicity: proposed operations are validated, priced and applied one at a time in list order, each against the state its predecessors left, under one savepoint per call (10.2.3, 10.2.4); any failure rolls back to that savepoint, so a paid rejection leaves exactly the permitted failure effects in state: the fee debit, the nonce bump and the 10.2.5 receipt, and for a drained scheduled call the queue entry, the prepaid balance and the callOutcome document. Validating the whole list against pre-call state was rejected there (two creates can both pass uniqueness and collide at apply as an Err).
• HostFault is a closed enum: grovedb storage errors, version-table lookup failures and protocol errors that cannot depend on guest input. The host-function trait returns Result<T, HostFault> with no From<drive::Error> or From<dpp::Error> impls, so ? on a drive error inside a host function does not compile; every other failure (undecodable document, missing identity or contract, bad argument) is converted at the call site to a guest-visible error code or a named paid ConsensusError. Any InternalError on a hook-bearing transition emits a metric and a log line.

Outcome	Variant (section)	Class
Guard forbids, overflows, exceeds budget	GuardRejectedError, GuardEvaluationError (07)	paid, bump nonce
Predicate rejects, traps, out of fuel, bad result	ValidationModuleError (08)	paid, bump nonce
Undeclared read	FootprintViolation (09)	paid, bump nonce
Proposed operation invalid or conflicting; call over its declared max_fee	ProposedOperationRejected { index, code }, ContractCallOverMaxFee (10)	paid, bump nonce; raised at the ABI boundary (11.2.3)
Balance below the pre-execution bound	IdentityInsufficientBalanceError, the existing variant 08.2.5 uses (packages/rs-dpp/src/errors/consensus/state/state_error.rs:175), so no new variant and no new 8.2.7 row	paid at the affordable minimum, bump nonce; guest never instantiated
Frozen, ABI retired, hooks disabled, paused, module rejected by a new engine	ModuleUnavailable (08), ContractCallUnavailable (10)	paid at the minimum transition fee, bump nonce
Oversized or structurally malformed transition (size and shape only, bounded by max_state_transition_size)	BasicError	unpaid, rejected in check_tx
Module fails the prepare pass or wasm validation	ValidationModuleError::PrepareFailed { rule } (08)	paid, bump nonce; only ever raised inside a block
HostFault	Err	InternalError; proposer strips, validators reject

Scheduled execution (10.2.6) runs in a block event (the settlement drain in the run_dao_platform_events slot, execution/engine/run_block_proposal/v0/mod.rs:310): no transition to pay, no nonce to bump, and a block-event Err halts the node (the sum-tree check returns Err(CorruptedCreditsNotBalanced) at execution/platform_events/block_processing_end_events/process_block_fees_and_validate_sum_trees/v0/mod.rs:181-191, and error_into_exception turns any handler Err into a ResponseException to Tenderdash, abci/app/consensus.rs:202, :209, :216). Rules: prepaid_credits moves into the entry's prefunded balance at scheduling (10.2.6), so a run can never be unaffordable; every run writes a callOutcome document in the ContractCalls system contract (fired; rejected with its 10.2.9 row as reason; dropped when the prepaid balance no longer covers the bound); no guest-reachable condition is Err; the run is charged from the prepaid balance and the remainder refunded to the principal; entries drain by fire time then entry id, capped by max_scheduled_calls_per_block and counted against max_block_processing_credits before the first transition; the block-event path is in the fault-injection corpus (11.3).

11.2.3 Pre-execution bounds and the block budget

One pre-execution bound per phase, defined once in its owning section and only cited here: G for guard-bearing batches at PV16 (section 07, static guard units plus read reservations plus the nonce bump), B for hook-bearing batches at PV17 and PV18 (8.2.6, extended at PV18 by section 09's declared read bound as a FootprintRead operation) and max_fee for ContractCall at PV19 (10.2.4 step 1); section 12 calls the same quantity the reservation. Two rules are this section's: every term is computable from the transition bytes and committed state before any guest runs, and the arithmetic follows the order validate_fees_of_event applies, fee increase first and fixed cost after (execution/platform_events/state_transition_processing/validate_fees_of_event/v0/mod.rs:136-143; additional_fixed_fee_cost at execution/types/execution_event/mod.rs:42).

• Balance gate, an execution-time consensus check: immediately before the guest (or the first guard) runs, with the identity already fetched, require live balance minus processing debt already recorded this block to cover the bound plus the nonce-bump cost (section 07 for guards, 8.2.6 for hooks, 10.2.4 step 1 for ContractCall); otherwise the phase's insufficient-balance variant (InsufficientBalanceForGuardEvaluation at PV16, InsufficientBalanceForHookExecution at PV17 and PV18, each in its phase's code block; ContractCall fails its pre-check instead), charging the affordable minimum transition fee, bumping the nonce and never evaluating a guard or instantiating the guest. Without it, K transitions each declaring a bound close to the whole balance pass check_tx independently (the dry run at execution/check_tx/v0/mod.rs:180-186 compares one transition's estimate against the last-committed balance, validate_fees_of_event/v0/mod.rs:145, with no mempool-level decrement); the first pays and the other K-1 run to the bound as processing debt the pools never receive (packages/rs-dpp/src/fee/fee_result/mod.rs:159-166). Hence no per-identity outstanding-reservation ledger in the mempool: check_tx stays a cheap prefilter and the gate is enforced in the block.
• Storage: storage is the one fee class whose shortfall is an Err today (required_removed_balance > previous_balance at packages/rs-drive/src/drive/identity/update/methods/apply_balance_change_from_fee_to_identity/v0/mod.rs:91-99, which the loop turns into InternalError), and in Phase 5 the guest chooses the documents it emits. max_fee is what bounds it: max_call_output_bytes caps the emit payload, not the storage the proposed operations create, so nothing is priced from the output cap. Each validated operation's exact storage cost comes from apply_drive_operations(apply = false) at the ABI boundary into running per-payer estimates; a total over max_fee, or a payer estimate over its balance, is ContractCallOverMaxFee (10.2.9), paid, and the degraded outcome is affordable because 10.2.4 keeps accrued <= max_fee, which step 1 checked against the live pre-call balance. Invariant: the apply path of a hook transition is never reached with required_removed_balance > balance.
• Block budget on declared bounds: the proposer sums the bound over the block before any guest runs and stops including hook-bearing transitions when the sum would exceed max_block_processing_credits, marking the rest NotExecuted (TxAction::Delayed, prepare_proposal.rs:236); validators compute the same sum first and reject the proposal before executing anything, so validator work is bounded by the budget plus one transition. gas_wanted is in credits (total_base_fee, abci/handler/check_tx.rs:66-70) and carries exactly that bound: B for hook-bearing batches, max_fee for ContractCall. max_block_processing_credits stays at or below the Tenderdash block max_gas dashmate ships (57,631,392,000 at getBaseConfigFactory.js:436), enforced by a dashmate config test, because an operator can edit max_gas but not SystemLimits.
• Block events are the second execution surface and share the same budget. One table, one sum constraint:

Block event (phase)	Cap	Share	Why no Err
Oracle slot open and close (06.4, Phase 1b)	max_active_oracle_feeds committee writes at open, max_active_oracle_feeds * k reads and max_active_oracle_feeds writes at close	derived from the 06.1 budget	the write is skipped, never failed, when the feed balance cannot cover it
Settlement drain (06.5 queue at PV15; escrow, allowance and auction entries with Phase 1b)	max_settlements_per_block = floor(0.1 * max_block_processing_credits / max_settlement_processing_credits)	one tenth	fixed-size outcome fallback when the prepaid amount no longer covers the cost
Scheduled calls (10.2.6, PV19)	max_scheduled_calls_per_block, a per-kind sub-cap inside max_settlements_per_block	inside the settlement tenth	prepaid at scheduling; every guest-reachable outcome is a callOutcome document

Each row's metered credits join the 06.1 accumulator before the first transition, so max_block_processing_credits bounds block events plus transitions rather than transitions alone. A block-event workload added later without a cap and a row here is a review defect.

• Calibration: the fuel price per credit is set so that a full budget executes in under one fifth of timeout.propose on the reference evonode hardware profile the DIP fixes (no minimum evonode spec is published in docs/ or the dashmate README today), measured on arm64 and amd64 and re-measured in every PV-opening PR. If more than one third of validators exceed timeout.propose on a budget-conformant block, the same transactions are re-proposed every round with no invalid block anywhere: the budget is a liveness parameter, not a fee parameter.
• check_tx cost bound: only size and shape checks bounded by max_state_transition_size run in check_tx (free to the sender and repeated under recheck_tx: true, getBaseConfigFactory.js:458); full wasm validation runs only at paid assembly or registration inside a block; anything that needs wasm validation to classify is a paid consensus error, never a BasicError.

11.2.4 Security review

An external audit closes before signalling on each PV that widens the user-code surface (scopes: section 14.2), the guard audit before PV16 signalling, because PV16's only in-chain controls are the deployer allowlist, frozenGuard and globalFreeze (11.2.6), with no frozenModule yet. Standing: embargoed disclosure with the wasmi maintainer (CVE-2025-66627, GHSA-g4v2-cjqp-rfmq, a use-after-free in linear memory; the fix, #1722, shipped in 1.0.1 and the 0.41.2, 0.47.1 and 0.51.3 backports, 1.0.0 and 1.0.1 are yanked on crates.io, and 1.0.2 is the first live 1.0 release), the nightly rustsec job (.github/workflows/security-audit-rust.yml) and a SECURITY.md (none exists).

In-process execution is a decision, not an omission. The guest runs inside drive-abci, which holds the Core RPC credentials (config.rs:29-33, :59-63) and the GroveDB state, so an engine memory-safety bug is node compromise. Out-of-process execution (a sandbox helper holding guest memory) was evaluated and rejected for PV17 to PV19: every footprint read and proposed operation is a host call (09, 10), so a process boundary puts a serialization round trip on each call of a path priced in fuel; and a helper crash (out-of-memory kill, signal, IPC timeout) is not attributable to guest versus host, so it could only be HostFault, a rejected proposal, which hands a guest that can crash the helper a per-round liveness lever instead of a paid rejection. Containment is the interpreter tier (wasmi translates to its own IR and interprets it; a JIT tier is 10.7's open item), the pin and closure hash (11.2.5), the audits and the advisory contact; the decision is revisited with a JIT tier, where the measured per-call cost of the boundary is weighed against the tier's speedup.

11.2.5 Engine upgrade governance

• One engine per activated pin: wasm_engine_version N maps to one immutable vendored crate whose source is the exact pin activated at that PV. The requirement this plan places on replay is that height h executes under the engine of the PV in force at h; the tool that checks it is the log-driven ABCI replay subcommand, which replays requests extracted from a drive-abci JSON log against a supplied GroveDB path (packages/rs-drive-abci/src/replay/cli.rs:11-33) and compares app_hash per block (replay/runner.rs:226-275). Vendoring per major would replay PV17 heights under a later patch's fuel and fail that comparison. The grovedb single-engine model needs a fork Dash controls (section 14's open question on engine stewardship).
• Closure pinning: every crate in the engine's dependency closure (above all the wasm parser, which implements validation and the proposal allowlist and is resolved by Cargo.lock, not by the wasmi line) is pinned with = versions in the vendored crate; a CI test hashes that crate's resolved subgraph from Cargo.lock (names, versions, features) against a committed value only a PV-opening PR may change; no consumer may enable a feature on the vendored crate beyond the ones it declares.
• Pinned major: wasmi 2.0.0 shipped on 2026-09-01; the 1.x line last saw 1.1.0 (2026-06-12). PV17 pins 2.x unless the maintainer gives a written 1.x LTS commitment; a CVE fixed only on the next major is a PV, never a hotfix.
• No expedited vote exists. Precedents: PR fix!: emergency hard fork to fix masternode voting #2397 rewrote PV7's validation table in place (packages/rs-platform-version/src/version/v7.rs:40, DRIVE_ABCI_VALIDATION_VERSIONS_V4 to V5, no new PV); execution/platform_events/protocol_upgrade/check_for_desired_protocol_upgrade/v0/mod.rs:17-31 hard-codes a 51 percent minimum for one version on each network; the only epoch-index gate is testnet-only (execution/platform_events/protocol_upgrade/upgrade_protocol_version/v0/mod.rs:62, epoch 1430). No mainnet flag day exists in the code.
• Runbook (D6): a misbehaving module on a live chain is frozen through 11.2.6, no PV. An engine security fix is applied as a source patch to the vendored crate only when the diff touches no translation, fuel-metering or trap-producing path (a diff-scope rule, reviewed as such), gated by a differential run over every module stored on mainnet and testnet plus a wasm-smith fuzz campaign comparing fuel, output and trap for old versus patched; anything else is a normal PV with pre-coordinated signalling. A halted chain has two steps, in order: day zero is the layer 2 denylist of 11.2.6, whose propagation model (how many proposers must adopt it before rounds stop burning, and how the list reaches them) the runbook states; then, if the fix is in the binary rather than the contract, a coordinated binary behind a network-keyed activation height, for which the tree has no mechanism today (the testnet epoch gate above is the closest thing), so that table and its rehearsal are part of the runbook. A halt from inside the scheduled drain (10.2.6) skips the first step: the drain runs before the transactions of every block, empty blocks included, so the denylist reaches nothing and the freeze write cannot land, and the coordinated binary is day zero; the runbook's rehearsal therefore includes a faulting queue entry on a devnet, and the fix it rehearses drops that entry as a dropped outcome or disables the drain behind the activation height.
• Engine swap: the PV-opening PR replays every module stored on mainnet and testnet through the new engine's validator; a module the new engine rejects maps to ModuleUnavailable (paid) and is listed in the PR. There is no in-chain sweep: re-preparation is lazy and charged to the first transition needing each module after activation (08.2.7), and the PR's replay is how every outcome is known before signalling.

11.2.6 Permissioning and kill switches

Four layers. This subsection owns the registry's documents, its creation PV, its read model and what it gates at each PV; other sections cite it rather than restating any of the four.

1. Per-PV disable, the slowest: hook and call execution slots are OptionalFeatureVersion; None maps every hook-bearing transition to ModuleUnavailable, paid at the minimum transition fee.
2. Operator-side proposer denylist (D5 layer 1, shipped with Phase 3): a node-local list of contract ids consulted only when proposing, so the transition is skipped as TxAction::Removed (prepare_proposal.rs:222-233) and no validator consults it, which is why it cannot diverge state and is the one admitted exception to the 11.3 rule against node config on execution paths. It restores liveness within one release cycle without a vote, and it is the only layer that works in the circular case: a contract that stops blocks committing also stops the freeze write of layer 3.
3. Registry without a PV: a ContractGovernance system contract appended to SystemDataContract (packages/data-contracts/src/lib.rs:36-49), created in transition_to_version_16 at PV16 (pattern: transition_to_version_14, execution/platform_events/protocol_upgrade/perform_events_on_first_block_of_protocol_change/v0/mod.rs:698) with deployer, frozenGuard (by contract id) and globalFreeze; PV17 extends the same contract with frozenModule (by code hash) and frozenContract. Read model: point reads per run and at registration through the block transaction, no cross-transition and no cross-block cache, so a freeze committed earlier in a block binds the next transition of that block; billed to the transition. Freezes are documents, so provable and reversible. A freeze has one meaning at every layer and phase: the frozen guard, module or contract rejects the actions it governs, paid, and never suppresses them (section 07; 08.2.5), so an incident switch can never become a bypass. Authority is asymmetric: freeze at a low threshold (fast); unfreeze and globalFreeze removal at a higher threshold or after a time lock; globalFreeze expires after a fixed number of blocks unless renewed; freeze and unfreeze keys sit at different security levels; a frozen-module rejection is charged only the minimum transition fee. Key holder set, thresholds and rotation go in the DIP. Latency: a freeze is an ordinary transition a malicious proposer can decline for its own rounds, so inclusion latency is bounded by the run of dishonest proposers, not by consensus; forced inclusion was rejected because mempool contents are not consensus-visible. Also rejected: group writes (no document group-action path) and a masternode vote (too slow for incidents).
4. Deployer allowlist in the same contract, preventive rather than reactive: checked at guard-bearing contract create and update from PV16 (section 07, GuardDeployerNotAllowedError), at hook-bearing create and update from PV17 and at ContractCall time (10). Deployment is allowlisted from PV16, not open (14.4); frozenGuard and globalFreeze are PV16's reactive switches beside it. Open deployment is a later PV (D5, 14.4).

11.2.7 Resource limits

All caps are Option<T> on SystemLimits, None before their PV, never consts or node config: per transition (fuel, context bytes, footprint entries, read bytes, host calls, args, output, proposed operations), per block (max_block_processing_credits and max_settlements_per_block from 06, max_scheduled_calls_per_block from 10, max_distinct_modules_instantiated_per_block new here) and per contract (code bytes, memory pages, structural counts, methods, incomplete blobs) (sections 06, 08 to 12). There is no separate hook sub-budget field: hook compute is counted against max_block_processing_credits in the same accumulator as every other transition (06.1), which is what makes the 11.2.3 table a sum constraint.

11.2.8 Threat model (D11 register)

Threat	Mitigation
Contract halts the chain	11.2.1, 11.2.2 and the pre-execution budget (11.2.3) prevent it; once halted, the freeze registry cannot land, so the recovery depends on where the fault sits: a host fault inside a signed call is skipped by the operator denylist (11.2.6 layer 2) until the D6 coordinated binary (11.2.5) lands, while a host fault inside the scheduled drain (10.2.6), which runs before the transactions of every block, empty blocks included, is reached by no denylist and no freeze, so the coordinated binary behind a network-keyed activation height is day zero, dropping the faulting entry or disabling the drain, rehearsed with a faulting queue entry (11.3); contract value only under summed roots (section 12, Credit conservation)
Contract misbehaves on a live chain	Freeze registry (11.2.6 layer 3); latency bounded by the honest-proposer fraction
Mempool and validator DoS via expensive hooks	Guests never run in check_tx and check_tx work is bounded by size (11.2.3); gas_wanted carries the declared bound; budget on declared bounds before execution; balance gate; distinct-module cap
Fee under-estimation (section 12, Client estimation), unrefunded storage growth	Balance gate and the per-operation dry runs against max_fee (11.2.3), estimator audit; owner on every StorageFlags, Identifier::default() rejected, blob refcount refunds
Engine vulnerability; governance key compromise	Pin, closure hash, rustsec, advisory contact, D6 runbook, in-process containment (11.2.4); a stolen freeze key can freeze, not alter, globalFreeze self-expires and unfreeze needs the higher threshold

11.2.9 MEV

prepare_proposal.rs iterates request.txs in Tenderdash's order and only truncates the tail at max_tx_bytes (abci/handler/prepare_proposal.rs:97-114); no sort or reprioritization exists in the handler, and user_fee_increase * 100 is the only priority lever (execution/check_tx/v0/mod.rs:32, :151-152). Policy: the DIP "Security Considerations" section carries an "MEV exposure" subsection stating the exposure (masternodes are ProTx-registered, so extraction is attributable; the proposer chooses block time, which a guest observes through HookContextV0.block one block later and through new_document timestamps in the current block, 08 decision (b)); an MEV assessment against that subsection gates every value-moving capability grant. The first subject is not Phase 5: section 06.5 ships escrow, auctions and settlement at PV15, where the proposer controls both ordering and, through block_info.time_ms, the Dutch price, so 06.5 is assessed and the outcome recorded there before PV15 signalling; Phase 5 capability grants (10.2.7) follow. Batch settlement and commit-reveal (10.2.6, 10.2.7) are preferred over ordering machinery (section 14's open question on ordering).

11.3 Tasks

Determinism

• When packages/rs-contract-runtime, packages/rs-contract-abi and packages/rs-platform-guards are created (sections 07 and 08, PV16 and PV17), add a per-crate clippy.toml listing method paths in disallowed-methods (std::time::Instant::now, std::time::SystemTime::now, std::env::var, std::fs::read, rand::random) and fully qualified type paths in disallowed-types (std::collections::HashMap, std::collections::HashSet), since an entry that does not resolve is itself an error, plus #![deny(clippy::disallowed_methods, clippy::disallowed_types)] in each crate root; the float ban stays on the section 08 prepare pass, primitive paths being unreliable in clippy configuration. Acceptance: cargo clippy -p <crate> --all-targets fails on a std::collections::HashMap or SystemTime::now use in the crate.
• Add the engine vector suite as packages/rs-drive-abci/tests/engine_vectors.rs (new; committed fuel and output hashes per wasm_engine_version over the section 03 corpus) and the closure-hash test of 11.2.5 beside it; acceptance: changing any committed fuel or output hash, or any name, version or feature in the vendored engine's Cargo.lock subgraph, fails cargo test -p drive-abci unless the committed hash file is updated in the same PR (PV17).
• Enumerate every config.* read under execution/ and abci/handler (grep self.config. and platform.config., about 110 sites including tests) and classify each as (a) network constant fixed per chain (network, chain_id, genesis_height, core_subsidy_halving_interval, quorum types), (b) node-local switch on a consensus path (use_document_triggers, verify_sum_trees, verify_token_sum_trees, proposer_tx_processing_time_limit), or (c) tunable that must become a version-table or SystemLimits field. Deliverable: the classification as a comment on ExecutionConfig (config.rs:90). Acceptance: the classification is committed and no ExecutionConfig or AbciConfig field is read on any hook or contract-call path added later, the 11.2.6 layer 2 denylist being the one admitted exception because it is consulted only when proposing (lands with Phase 1, PV15).
• Measure the per-block cost of always-on sum-tree verification (calculate_total_credits_balance and calculate_total_tokens_balance at mainnet state size, both architectures) and record it in the PV15 PR body; then delete the (b) booleans verify_sum_trees, verify_token_sum_trees and use_document_triggers, with tests reaching the same effect through a cfg(test) platform builder, and amend section 12's credit-conservation reasoning, which today argues from verify_sum_trees being node config, in the same PR (PV15).
• Retire proposer_tx_processing_time_limit in favour of the 11.2.3 budget only after the budget has soaked on testnet for the Phase 3 soak window (14.4): remove the code path and its dashmate wiring (packages/dashmate/docker-compose.yml:97 passes PLATFORM_DRIVE_ABCI_PROPOSER_TX_PROCESSING_TIME_LIMIT) in one PR, with an entry in packages/dashmate/configs/getConfigFileMigrationsFactory.js and a release note naming the dropped variable (PV17 at the earliest).

Error classification

• Define HostFault and the host-function trait signature of 11.2.2 in rs-contract-runtime with the wildcard-free wasmi error mapping and a compile-time list of host functions; add the drive-abci test enumerating every wasmi error variant and every host function's non-storage failure against 11.2.2, and the metric and log line for InternalError on hook-bearing transitions (PV17, extended at PV18 and PV19).
• Add the hook fault-injection surface: an injectable failure at every host function and every wasmi error variant (trap kinds, out of fuel, stack, memory), driven on both the prepare_proposal and process_proposal paths and on the scheduled-execution block event, asserting per case on the transaction paths that the proposer strips with the root restored to the savepoint, the validator rejects with the root unchanged, and no other StateTransitionExecutionResult variant (platform_types/state_transitions_processing_result/mod.rs:24-57) appears, and on the drain that every guest-reachable fault drains as a rejected outcome and only the injected host fault is Err, the case the D6 drain-halt rehearsal covers; the existing test_fault_injection (process_raw_state_transitions/v0/mod.rs:25-57) stays as the post-apply model only. Add StateTransitionNotActiveError tests per new gate constant.
• Add the paid-rejection snapshot test as packages/rs-drive-abci/tests/strategy_tests/test_cases/paid_rejection_tests.rs (new): root before a paid rejection, assert only the permitted failure effects changed (the identity balance and nonce subtrees and the fee pools; at PV19 also the callReceipt document, and for a drained scheduled call the queue entry, the prepaid balance and the callOutcome document), for guard rejection and GuardFrozenError (PV16), predicate rejection (PV17), FootprintViolation (PV18), ProposedOperationRejected and ContractCallOverMaxFee (PV19) and the InsufficientBalanceForGuardEvaluation and InsufficientBalanceForHookExecution gate rejections, on both proposal paths.

Fees and budget

• One bound function per phase, implemented in that phase: the section 07 gate against G in the PV16 validate_state_v1 before the first guard, the 8.2.6 gate against B in the PV17 batch/state generation (execution/validation/state_transition/state_transitions/batch/state/, before run_hook) and 10.2.4 step 1 against max_fee in the ContractCall state module, both applying the 11.2.3 ordering rule beside validate_fees_of_event (execution/platform_events/state_transition_processing/validate_fees_of_event/). Cross-phase property test owned here: for every corpus module and every declared bound the actual FeeResult stays at or below the bound (PV17, extended at PV18 and PV19).
• Implement the per-operation storage check in the ContractCall state module after the rs-contract-abi ProposedOp decoder (10.2.3), wrapping apply_drive_operations(apply = false) (packages/rs-drive/src/util/batch/drive_op_batch/drive_methods/apply_drive_operations/mod.rs:35) cumulatively over the operation list against max_fee and each payer's balance; strategy test driving balances to the exact boundary for every proposed-operation kind (PV19).
• Implement the declared-bound block budget in prepare_proposal and process_proposal, set gas_wanted to the phase's bound, add the dashmate config test (max_block_processing_credits at or below max_gas, under packages/dashmate/test/unit/config) and the check_tx benchmark (largest permitted hook-bearing transition within a fixed multiple of a plain document create) (PV17).
• Add every 11.2.3 block-event row to the same budget accumulator before the first transition, with a test per row asserting its cap and that the budget bounds events plus transitions (PV15 for the 06.5 queue row, Phase 1b for the 06.4 row and the settlement entries, PV19 for scheduled calls).
• Write the 11.2.3 calibration procedure into the PROTOCOL_VERSION_CHECKLIST section of packages/rs-contract-abi/README.md (new, section 13), linked from .github/PULL_REQUEST_TEMPLATE.md; the DIP fixes the reference hardware profile and names its owner before the first calibration run, and each PV-opening PR records the full-budget wall-clock on arm64 and amd64 for that profile, the resulting fuel price per credit and the timeout.propose it was checked against (PV17).
• Add max_distinct_modules_instantiated_per_block: Option<u16> to SYSTEM_LIMITS_V7 and count instantiations in the section 08 run_hook LRU (rs-contract-runtime); acceptance: the proposer marks the transition that would instantiate module cap + 1 NotExecuted, a proposal carrying cap + 1 distinct modules is rejected, and a cold-cache restart translates at most cap modules in one block (PV17).

Security review and engine governance

• Contract the audits scoped in 14.2 (Phase 1b's external scope for 6.4 and 6.5, plus one per PV from PV16 to PV19), the guard audit closing before PV16 signalling; each closes with the report link and remediation status in the PV-opening PR body under the "audit closed" gate (14.4); establish the wasmi maintainer advisory contact and a peer channel with the other consensus embedders of wasmi (the soroban-wasmi fork, 08.2.1), and add SECURITY.md at the repository root (new) before the PV17 dependency lands.
• Write the D6 runbook (the layer 2 denylist propagation model included, and the drain-halt path that skips it), the diff-scope rule, the in-process decision (11.2.4) and the pinned-major decision into the DIP "Security Considerations" section; rehearse the runbook on a devnet before PV17, and again before PV19 with a faulting queue entry that the coordinated binary drops behind a network-keyed activation height.
• Vendor each activated pin as an immutable package wasmi-engine-v<N> (new) under packages/rs-contract-runtime/engines/, at the exact revision section 08.2.1 pins (a Dash-controlled fork if section 14's engine-stewardship question resolves that way, the upstream revision otherwise), every closure crate at an = version; acceptance: the closure-hash test above.
• Build drive-abci engine-diff (new subcommand beside Replay, packages/rs-drive-abci/src/main.rs:68-71): runs every module stored in a mainnet or testnet state snapshot under two engine packages and reports fuel, output and trap deltas, exiting non-zero on any delta; every source patch to a vendored crate and every engine-swap PV-opening PR attaches its run, and the PR body lists any module the new engine rejects, since no in-chain sweep exists (08.2.7).
• Add an engine-differential job (new) to .github/workflows/tests-rs-nightly-long-running.yml: wasm-smith modules generated from a committed seed list (fuzz/seeds/engine_differential.txt, new, fixed count) run through old versus patched engine comparing fuel, output and trap; zero deltas is the gate for a source patch (11.2.5).

Permissioning and limits

• Add ContractGovernance as packages/contract-governance-contract (new, the shape of packages/dpns-contract) behind its own feature in packages/data-contracts, with a new SystemDataContract discriminant, created in transition_to_version_16 with deployer, frozenGuard and globalFreeze (thresholds, time lock and expiry per 11.2.6), extended at PV17 with frozenModule and frozenContract; host lookup yielding ModuleUnavailable; allowlist check at guard-bearing contract create and update from PV16 (section 07) and at hook-bearing create and update from PV17; freeze reads rejecting, never suppressing, at both.
• Add the layer 2 denylist as a proposer-only list read in prepare_proposal with its runbook entry; acceptance: a denylisted contract's transitions are TxAction::Removed on the proposer path only, a validator holding the same list validates the same block identically, and two nodes disagreeing on the list produce identical roots for that block (PV17).
• Add each 11.2.7 cap to the SystemLimits generation of its phase with a test asserting None on every earlier PV; extend TEST_PLATFORM_V2/V3.
• Test the 10.2.6 drain (the run_dao_platform_events slot, execution/engine/run_block_proposal/v0/mod.rs:310; implementation in 10.3) against 11.2.2 in packages/rs-drive-abci/tests/strategy_tests/test_cases/scheduled_call_tests.rs (new): the prepaid balance under [40] is debited at scheduling and the remainder refunded to the principal on a fired outcome; injected trap, out of fuel, module unavailable and paused or frozen cases each write a rejected callOutcome document with that reason; two entries with the same fire time drain by entry id on both proposal paths with equal roots; a block-event Err is reachable only from an injected HostFault (PV19).
• Add the "MEV exposure" subsection to the DIP "Security Considerations" section (attributable extraction, user_fee_increase as the only lever, proposer-chosen block time) with an assessment template; the section 06.5 assessment is completed and linked before Phase 1b signalling, and every Phase 5 capability grant PR (10.2.7) links a completed assessment in its body.

11.4 Tests

Golden fuel and output vectors per engine version; closure hash; amd64 and arm64 root-hash equality (14.3); classification exhaustiveness under hook fault injection on both proposal paths and the block event; bound and storage property and boundary tests; budget overflow rejected before execution; each block-event row at its cap; distinct-module cap at its boundary and one past it; scheduled drain outcomes and ordering on both proposal paths; frozenGuard rejection at PV16; frozenModule, frozenContract and allowlist rejections at PV17; globalFreeze expiry; denylist divergence-freedom; every cap at its boundary and one past it.

11.5 Acceptance criteria

• No guest-reachable condition yields InternalError, UnpaidConsensusError or a node halt in the Phase 2 to 5 suites, in transitions or in block events; the apply path is never reached with required_removed_balance > balance; fuel and root hashes match on amd64 and arm64; a pin or closure change without a PV fails CI.
• Validator work per rejected proposal is bounded by the budget plus one transition; check_tx work is bounded by transition size; cold-cache translation per block is bounded by the distinct-module cap; block events consume no more than their tabled share of the budget.
• Each surface-widening PV has a closed audit before signalling; a module can be frozen and unfrozen without a protocol version, with proofs, under the asymmetric thresholds.

11.6 Risks

• "Relatively stable" fuel makes every bump a consensus event; per-pin vendoring and the differential tool contain it at the price of slow patching, and a CVE fixed only on the next major forces a PV.
• PV16 guards ship behind the deployer allowlist with frozenGuard and globalFreeze as their only reactive switches, before frozenModule exists; the guard audit and the static-cost registration rule (14.5) are the gate.
• Governance key custody is operational risk outside consensus; the asymmetric thresholds bound a stolen freeze key to a self-expiring denial of service.
• In-process execution makes an engine memory-safety bug node compromise (11.2.4); the interpreter tier, pin, closure hash and audits are the containment, and a JIT tier reopens the decision.
• Calibration is per-hardware; a budget tuned on faster hardware than the slowest third of validators is a liveness stall, not an invalid block.
• Engines accumulate without a retirement rule: packages/rs-drive-abci/src/abci/ implements no state-sync handler, so a new node replays history and every activated pin stays linked and executed forever. Bounding that (a cap on retained pins, or a snapshot-based bootstrap) is unscheduled and belongs with the section 14 risk register.
• The layer 2 denylist is bounded by release and configuration propagation rather than by consensus; the runbook's propagation model and its rehearsal are the mitigation.
• Cross-architecture test CI is net-new: release images build for linux/arm64 (.github/workflows/release-docker-image.yml:47) but no Rust test job runs on arm64; amd64 plus replay is the fallback.

---

---

Continued in part 12 of 14 below.

[QuantumExplorer]

Part 12 of 14 of the plan (continued from part 11 above).

12. Cross-cutting: fees and economics

Reasoning

Two live mechanisms decide every choice here. Fees are computed once after validation from metered GroveDB costs plus ValidationOperation entries folded into processing_fee, behind one affordability pre-check against an average-case estimate (packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v0/mod.rs:55-87; validate_fees_of_event/v0/mod.rs:102-163). Fee constants are consensus data cached per epoch, but fee_version_number keys refund pricing rather than the constant set: FEE_VERSION1 (packages/rs-platform-version/src/version/fee/v1.rs:12) and FEE_VERSION2 (fee/v2.rs:12-13) both carry number 1, only the first is registered in FEE_VERSIONS (fee/mod.rs:32), and refunds branch on that number (packages/rs-drive/src/fees/op.rs:280-301), so the registry has to be repaired before any new fee constant can be priced. Under-pricing compute is a liveness risk because validators re-execute with no timer; over-pricing is a UX cost; ties break conservative.

Design

Fee-version numbering

This section owns the numbering; sections 04.5, 05 D3, 07, 08.2.6, 09 and 14.2 cite it and restate nothing. Decision: FEE_VERSION2 is registered with fee_version_number: 2 and every later table takes the next number, so FEE_VERSIONS[i].fee_version_number == i + 1 holds and section 14.2's schedule (FEE_VERSION3 numbered 3 through FEE_VERSION7 numbered 7) is the allocation. The invariant is not cosmetic: FeeVersion::get indexes FEE_VERSIONS[number - 1] (fee/mod.rs:53-63), persisted state stores numbers only, and rehydration is get(number).expect(..), so a number unequal to its index resolves to another table's constants or panics at node start. Rejected: leaving FEE_VERSION2 at 1 and starting FEE_VERSION3 at 2, under which two registered tables share number 1, get and as_static (fee/mod.rs:50-52) are ambiguous by construction, and the index invariant test every other section's gate list assumes fails on the first entry.

Renumbering reprices PV9 to PV14 epochs on replay, so the registry PR carries three consequences explicitly:

• as_static() on a PV9 to PV14 FeeVersion resolves to FEE_VERSION1 today and to FEE_VERSION2 afterwards. The tables differ only in data_contract_registration (v1's fields are zero, fee/data_contract_registration/v1.rs:6-14; v2 carries the PV9 fees, v2.rs:6-14), and there is one caller in tree, a test (packages/rs-drive-abci/src/execution/platform_events/block_processing_end_events/tests.rs:866), so the PR pins that caller inventory rather than asserting table identity.
• The fee_version_number == 1 branch at op.rs:280 stops being taken for PV9 to PV14 epochs, so every SectionedStorageRemoval takes the other arm, where a None previous_fee_versions is CorruptedCodeExecution (op.rs:291). Inside a block event that is a node halt, not a rejected proposal, which is why the None audit below is part of the gate rather than a follow-up.
• The epoch cache gains an entry only when the number differs from the last one at an epoch change (protocol_upgrade/upgrade_protocol_version/v0/mod.rs:96-115), so a node replaying from genesis records a PV9 entry a continuously running node never had. Both maps must price refunds identically, and they do: FEE_VERSION1 and FEE_VERSION2 both carry FEE_STORAGE_VERSION1 and refunds read only StorageDiskUsageCreditPerByte (packages/rs-dpp/src/fee/fee_result/refunds.rs:60). A replay-versus-upgrade refund test asserts it.

Fuel to credits

credits = fuel * credits_per_fuel, one checked u64 multiply; fuel comes from the pinned wasmi 2.0.x engine's Config::operator_cost table, itself consensus data (section 08). Calibration: a criterion bench in the proposed packages/rs-contract-runtime/benches runs the committed corpus, takes the slowest module's p99 nanoseconds per fuel unit, applies a 2x factor and converts at the roughly 8M credits per ms of CPU the PV14 shielded fee comment derives from (drive_abci_versions/drive_abci_validation_versions/v10.rs:338-343). No constant encodes that rate today, so FeeWasmVersion is its first consensus home. The reference machine is the evonode profile the DIP fixes, a Phase 0 deliverable and not an assumption here (11.2.3; this repository publishes no minimum spec); the raw measurement CSV is committed beside the corpus and a test recomputes credits_per_fuel from it, so the constant is reproducible rather than asserted.

Engine identity is a fee input: fuel per module is a function of the exact revision and its Config, so recalibration is a new fee version in a new PV and an engine bump is a fee change plus a module-validity change. wasm_engine_version selects the revision, each stored module records the version it was validated and priced under, and every activated revision stays linked for replay (section 08). Cargo.lock has no wasmi entry today; the 2.0 line is this plan's selection (section 03), not a tree fact. Rejected: Soroban-style cost parameters changeable by validator vote without a protocol version (CAP-0046-10); Platform has no consensus-parameter channel besides PV voting.

Processing versus storage

Guard evaluation, hook fuel, host-call base costs and the module prepare pass are processing_fee. Bytes a hook writes, and code blob bytes, are storage_fee at storage_disk_usage_credit_per_byte (fee/storage/v1.rs:6) with StorageFlags, so the 50-era refund applies unchanged. user_fee_increase multiplies processing only (packages/rs-dpp/src/fee/fee_result/mod.rs:198-209), so priority bidding covers fuel with no new field; fuel is folded before the multiplier is applied (execute_event/v0/mod.rs:67-73), which the bounds below must account for. Rejected: a third compute fee class, a sixth conservation term for no economic difference.

Declared bounds and where affordability is enforced

Pipeline order fixes where a bound can be enforced: basic structure, then the identity minimum-balance pre-check (packages/rs-drive-abci/src/execution/validation/state_transition/processor/v0/mod.rs:169-185, dispatched at processor/traits/identity_balance.rs:24-27), then state validation, where hooks run beside the data triggers (batch/state/v0/mod.rs:309-322), then execute_event, whose first step is validate_fees_of_event (execute_event/v0/mod.rs:384-396). The VM has already run by the time fee validation executes, so a bound checked there gates nothing.

The pre-check is the only pre-VM gate on the mempool path, and its signature is the whole constraint: validate_identity_minimum_balance_pre_check receives a PartialIdentity and a PlatformVersion and nothing else, dispatching to validate_estimated_fee(balance, platform_version) on the transition itself (identity_balance.rs:38-59, Batch at :57-59). It can read the transition's own declared fields and the version tables, never a contract. That splits the design by phase:

• PV16 adds no field either. The guard bound G (section 07) is static: the units of the guards firing on the transition's actions times unit_price, plus their deref count times guard_read_reservation, plus the nonce bump, all known from the parsed document type. The CheckTx transformer pushes it as GuardEvaluation and reservation operations so gas_wanted carries it, and validate_state_v1 gates on balance - accrued >= G with the signer's PartialIdentity before the first guard runs, the shape of PV17's seam gate one phase earlier.
• PV17 and PV18 add no field to the batch transition. The per-run bound is B, defined once at 08.2.6 over instantiation, translation, memory pages, context bytes and budget * credits_per_fuel, where budget is the document type's validationModule.maxFuel keyword, bounded at parse time by max_hook_fuel_per_call and never clamped at run time so mempool and block cannot disagree (08.2.3); PV18 adds section 09's read bound to the same quantity. Because the contract is in hand in the transformer and not in the pre-check, the bound reaches the mempool as a priced operation rather than a wire field: the CheckTx transformer pushes ValidationOperation::HookExecution and FootprintRead, the check_tx dry run prices them (check_tx/v0/mod.rs:179-186), and gas_wanted carries B although no guest runs. The affordability gate is at the seam, with the signer's PartialIdentity: balance - accrued >= B + nonce-bump cost (08.2.6). The pre-check keeps a contract-free floor computable from FeeVersion and SystemLimits alone, the shape section 09 uses for footprint entries. B is the D10 name for this quantity at PV17 and PV18; 11.2.3's floor(tx) is the same thing.
• PV19 declares max_fuel and max_fee on the ContractCall wire, so the pre-check enforces them from the transition alone: balance >= max_fee in check_tx and in block, gas_wanted = max_fee (10.2.4). max_fee is the single declared ceiling over the whole call across both payers and supersedes the max_storage_bytes term this section previously proposed (10.2.1), because two declared bounds over one transition split affordability into two checks that can disagree. 10.2.4 splits floor between what the wire carries (fuel, reads, min_call_fee, checked in check_tx) and the entry module's instantiation terms (checked in block before the engine is entered), and keeps two sums: reserved, the bounds that gate each unit of work, and accrued, the actuals that are billed. So the reservation model there and the actual-cost billing below are one rule, not two.

Bound check then charge actuals, never escrow. No balance moves before execution: used fuel is folded into processing_fee before apply_user_fee_increase (:67-73), additional_fixed_fee_cost is added after it (:75-79), and the balance is written once (:81-87), so the remainder is never debited and "refund" needs no code. 05 D3's literal debit and credit-back is superseded by this model, as 08.2.6 also records. Rejected: a system-wide fuel cap as the bound, which prices every trivial predicate as the worst case; resolving the budget from state inside the pre-check, which needs a PlatformRef there and a contract load per check_tx.

Emitted operations are chosen by guest code, so their storage cost is unknowable before the VM runs. At PV19 each proposed operation is dry-run (apply = false) after the guest returns and before any apply, into per-payer running estimates; a total over max_fee, or a payer estimate over its balance after the call's own debits, is ContractCallOverMaxFee (10.2.4). That branch must never be reached by accident: apply_balance_change_from_fee_to_identity returns IdentityInsufficientBalance when required_removed_balance > previous_balance (packages/rs-drive/src/drive/identity/update/methods/apply_balance_change_from_fee_to_identity/v0/mod.rs:94-100), execute_event propagates it, process_raw_state_transitions maps it to InternalError (v0/mod.rs:360), and process_proposal rejects the block (abci/handler/process_proposal.rs:285-308).

The debt path stays reachable and is not claimed otherwise: fuel is capped, but non-fuel processing (index seeks, identity fetches) is still an average-case estimate, so desired_removed_balance > previous_balance can hold and the negative-credit branch (:102-109) is taken exactly as for documents today. The invariant claimed is "never Err", not "never debt". The refund TODO at validate_fees_of_event/v0/mod.rs:138 stays: ignoring refunds in affordability is conservative.

Failure charging

Fuel exhaustion is the small part of the error surface. Every host call touching Drive returns Result<_, Error>, and grovedb failures on guest-named paths (missing parent layer, wrong element type, unknown document type in a foreign contract) are Err today, which inside a hook becomes InternalError. Rule: a closed, versioned guest-visible error enum with a total mapping from every host-call failure into it; any rs-drive Err reaching the hook seam converts to a paid consensus error carrying the fuel consumed so far; the residual Err set is enumerated and fuzzed, and is HostFault alone (08.2.7). Out-of-fuel, trap, explicit reject and footprint violation are new StateError variants giving PaidConsensusError with actual_fees and gas_used (packages/rs-drive-abci/src/abci/app/execution_result.rs:32-39): fuel to the trap plus the metered bump.

Four consensus error-code blocks, allocated here so the earlier phases cannot collide with the later ones: 41000-41099 for Phase 3 (ValidationModuleError and InsufficientBalanceForHookExecution, 08.2.7), 41100-41199 for Phase 5 (ProposedOperationRejected, ContractCallOverMaxFee, 10.2.9), 41200-41299 for the section 06 transition types (Phase 1 and Phase 1b), 41300-41399 for the Phase 2 guard errors (section 07). The highest code in tree is 40904 (packages/rs-dpp/src/errors/consensus/codes.rs:401), and the 40500-40699 data-trigger block (codes.rs:356) already holds address errors at 40600, so a wasm failure reported there would reach clients labelled a data-trigger error.

The mempool does not self-correct: should_validate_batch_valid_against_state is false for CheckTx and RecheckTx (batch/mod.rs:47-54), so a transition failing only in state validation is never rejected there. A call that produced InternalError is stripped from the block and removed from the proposing node's mempool (TxAction::Removed, abci/handler/prepare_proposal.rs:226-233, the same action taken for UnpaidConsensusError at :215-223; Tenderdash removes REMOVED records through TxMempool.RemoveTxByKey), but every other node still holds it, so each of them re-executes it to its cap for free the first time it proposes. Recheck (CheckTxLevel::Recheck, execution/check_tx/mod.rs:17-20) drops any transaction whose last proposal outcome was InternalError, keyed until that identity contract nonce advances, which reduces the repeat from once per remaining proposer to once per node that has not rechecked.

BumpIdentityDataContractNonce is a BatchedTransitionAction produced inside batch state validation (batch/state/v0/mod.rs:325-340), so it covers PV17 and PV18 hooks but not ContractCall, a new transition type: that transition gets its own bump action against the identity contract nonce of the called contract, charged with consumed fuel (10.2.4 step 4). At PV19 every proposed operation validates and applies in list order under the call's savepoint, so a failure rolls back rather than surfacing as an Err after apply_drive_operations(apply = true), the partial-state class the fault-injection hook documents (process_raw_state_transitions/v0/mod.rs:25-29). Charging on failure: actual metered fuel is charged on every outcome, and out-of-fuel by definition consumed the whole budget, so its charge is the budget (08.2.7). What is rejected is charging the declared cap for traps and rejects that stopped early; the DoS bound is the cap, not a penalty.

Block budget and gas_wanted

gas_wanted is the dry run's total_base_fee (abci/handler/check_tx.rs:66-70) and carries the declared bound for hook-bearing transitions (B through PV18, max_fee at PV19); priority is unchanged. It is not a free field: Tenderdash reaps by it, adding each candidate's gas_wanted and breaking out of the loop once the running sum exceeds Block.MaxGas (dashpay/tenderdash TxMempool.ReapMaxBytesMaxGas), and dashmate sets max_gas to 57631392000 (packages/dashmate/configs/defaults/getBaseConfigFactory.js:436, defaults/getTestnetConfigFactory.js:159). A call whose bound approaches max_gas is therefore never reapable and, because the loop breaks rather than skips, blocks every lower-priority transaction behind it; and bounds, not usage, consume the budget. max_hook_fuel_per_call * credits_per_fuel and the PV19 per-call caps are bounded to a small fraction of max_gas (08.2.6, 10.2.3).

The validator side has no equivalent: proposer_tx_processing_time_limit is node config, proposer only, default None (packages/rs-drive-abci/src/abci/config.rs:37-39, :60), so a validator re-executing a proposal would otherwise run every included call to its cap unbounded. Section 06.1's accumulator is the answer: process_proposal sums declared bounds and metered processing credits per transition and rejects once the running sum exceeds max_block_processing_credits (it already aggregates fees, process_proposal.rs:282-283), bounding worst-case validator work at the budget plus one transition. Block events are shares of the same budget, tabulated once at 06.1 with each one's cap and its Err-freedom argument; this section's calibration takes that table as its sum constraint. NotExecuted(ProposerRanOutOfTime) is unchanged for contract calls: proposer-local, never in a validated block.

Code blob storage fees and refunds

Module bytes are storage in the hash-addressed blob store under RootTree::CodeBlobs (section 06.2), never part of the serialized contract element: chunk elements carry the uploader's StorageFlags, the blob is shared by hash across contracts, reference-counted through code_blob_references in DataContractConfig, and Delete { hash } at count zero refunds the storage owner. Inside the contract element they would inherit the contract's flags, None when the contract is readonly and non-deletable (packages/rs-drive/src/drive/contract/insert/insert_contract/v1/mod.rs:46-53), so "always owned" would be impossible; and every contract update re-inserts the whole element with fresh current-epoch owned flags (contract/update/update_contract/v1/mod.rs:72-75), so an unrelated schema change would refund and re-pay every module byte. The separate root tree removes both: a contract update that does not touch the module neither re-flags nor re-charges its bytes.

Two costs, charged where the work happens. Blob completion pays per-byte hashing at a new FeeProcessingVersion constant over the assembled chunks (06.2), the only per-byte work that transition does. Wasm validation is not charged there: the prepare pass runs at DataContractCreate and DataContractUpdate, billed hook_prepare_credit_per_byte to the registrant per module-bearing type on create and on every update, since an update re-prepares each of them (08.2.2, 08.2.3), alongside document_type_validation_module_fee in the FEE_VERSION5 FeeDataContractRegistrationVersion generation, riding additional_fixed_fee_cost (execution/types/execution_event/mod.rs:319, :344, the path the existing registration fee takes). Bytes are priced as bytes; a module is priced where it is bound to a schema. Chunked upload follows from max_state_transition_size 20480 bytes (packages/rs-platform-version/src/version/system_limits/v4.rs:23), so no single transition pays for the whole artifact, and abandoned staging needs no expiry constant: the first chunk schedules a prepaid cleanup entry in the 06.5 settlement queue whose deadline deletes the staging subtree and refunds the uploader's chunk bytes through their epoch flags, with Abandon doing the same early, keeping cleanup inside a capped prepaid block event rather than an unpriced lifecycle sweep.

Refund-rate invariant: refunds are priced at the current epoch's StorageDiskUsageCreditPerByte, not the rate paid at write time (refunds.rs:59-60), and the pool subtraction uses checked_sub_unsigned on signed per-epoch credits (packages/rs-dpp/src/fee/epoch/distribution.rs:112-118), so an epoch pool can go negative without error. Blobs are the largest owned element the chain will hold, so a later fee version raising the disk rate would let a deletion refund more than was paid: conservation still balances while those epochs' proposer payouts drain. Either storage_disk_usage_credit_per_byte never increases while refund pricing is write-epoch-agnostic, enforced by a test over FEE_VERSIONS, or refund pricing moves to the write epoch's rate using the cache this section already threads.

Storage refund attribution

Through PV18 there is one payer and one owner: the StorageFlags owner is the identity the pipeline debits for the transition, the document rule today (state_transition_action/action_convert_to_operations/batch/document/document_create_transition.rs:59-60), which is section 04.5's one-payer rule and the reading 03.3 rule 4 states. At PV19 the hybrid this section previously left open is adopted from 10.2.2, which owns it: the acting owner named on a proposed operation, Caller or Principal, is both the per-action validator's owner_id and the StorageFlags owner of storage that operation creates; the caller pays processing (fuel, reads, validation, the nonce bump) plus storage of its Caller operations, the principal pays storage of its Principal operations. A deletion therefore refunds whoever paid, and a caller never funds principal-owned bytes, so a contract cannot harvest a caller's storage fee by writing and deleting. The strategy test for the rule (A creates, B grows, the contract deletes) stays in 03.3 and is re-run under the two-payer event. A contract deleting state a departed user paid for refunds that user: the flags carry the original owner and other_refunds already credits third parties.

Scheduled calls have no transition and no debited identity, so the transition rule does not reach them: bytes a drained entry writes carry StorageFlags::new_single_epoch(epoch, principal), storage is paid from the entry's prepaid balance under [40], and refunds credit the principal (10.2.6). An entry that no longer covers its floor is a deterministic recorded outcome, dropped or rejected with refund, never an Err at a block event. Rejected: system-owned bytes, since Identifier::default() routes to removed_bytes_from_system with no refund (op.rs:277-279), so no host function or operation converter may build flags with it.

Credit conservation

The principal is an identity, so its balance is a sum item under [96, id] (10.2.2). Prepaid balances for queue entries go under [40] beside PREFUNDED_BALANCES_FOR_VOTING (packages/rs-drive/src/drive/prefunded_specialized_balances/mod.rs:26-33), already a term of the conservation equation (drive/balances/calculate_total_credits_balance/v2/mod.rs:20-92). Forbidden by construction: credit-denominated values held as document properties, since the document subtree sits under the NormalTree [64] and is invisible to the sum check, and in-contract token ledgers, which bypass the Misc["T"] check; host functions and proposed operations move credits and tokens only through existing DriveOperation kinds. The per-contract key [64, contract_id, 2] stays uncreated and unreserved (section 04.3): code blobs live in their own root tree, so there is no opaque scratch area to police. verify_sum_trees is node config (packages/rs-drive-abci/src/config.rs:95-97, :613-615), so the invariant cannot rely on it.

Withdrawal limit

The PV14 daily base is daily_withdrawal_limit_percent (15) of the total credits recorded a day ago, floored at one maximal withdrawal (500 Dash) and capped at max_daily_withdrawal_amount (4000 Dash), with inflows since the snapshot added on top of the capped base (packages/rs-dpp/src/withdrawal/daily_withdrawal_limit/v2/mod.rs:22-66, selected by DPP_METHOD_VERSIONS_V3 at packages/rs-platform-version/src/version/v14.rs:221, values at packages/rs-platform-version/src/version/system_limits/v4.rs:29-31; packages/rs-drive/src/drive/identity/withdrawals/calculate_current_withdrawal_limit/v1/mod.rs:107-116). The reference is that recorded snapshot, whose live counterpart is the system total under Misc at key b"D" (drive/balances/mod.rs:27, :34-40). Contract-held credits are identity balances and enter the snapshot like any other; no change. Principals are keyless and entry points may not emit withdrawals, so contracts cannot consume the shared daily budget directly.

Client estimation

Two numbers, not one function. calculate_min_required_fee (packages/rs-dpp/src/state_transition/traits/state_transition_estimated_fee_validation.rs:14-31) stays an admission floor below the actual fee: document_batch_sub_transition is 100000 credits (fee/state_transition_min_fees/v1.rs:8) while the disk rate alone is 27000 credits per byte, so a 500-byte document create costs orders of magnitude more than the floor. The declared bound (B through PV18, max_fee at PV19) is the upper bound, is what gas_wanted reports, and is what a client quotes. Both are single rs-dpp functions re-exported through rs-sdk, wasm-sdk and the platform-wallet FFI estimators, so admission, quote and charge cannot drift. Clients have no state-aware quote today: static formulas at sdk.version() (packages/rs-platform-wallet-ffi/src/shielded_send.rs:208-225), the min-balance pre-check, and the actual fee afterwards from gas_used. A state-aware quote for hooks exists only as section 09's non-consensus preflight endpoint, which is advisory and never the charge. Rejected: a dry-run estimateFee RPC on the consensus path, unprovable and unequal to the charge.

New constants

An index, not a second source of truth: values, validation and tests belong to the owning section, and the generations are section 14.2's allocation.

Constant	Proposed home	PV (generation)	Owner
blob per-byte hashing cost	FeeProcessingVersion v2	15 (FEE_VERSION3)	06.2
guard unit_price and fallback bounds	FeeGuardVersion, the guards sub-table on FeeVersion	16 (FEE_VERSION4)	07
credits_per_fuel, operator and custom fuel costs, instantiate, translate, memory-page, context-byte and prepare rates	FeeWasmVersion on FeeVersion	17 (FEE_VERSION5)	08.2.6
document_type_validation_module_fee	next FeeDataContractRegistrationVersion generation	17 (FEE_VERSION5)	08.2.3
host-call rates, hook_read_worst_case_tree_height, bound formula version	FeeWasmVersion	18 (FEE_VERSION6)	09.3
min_call_fee, min_scheduled_call_fee	new FeeVersion constants	19 (FEE_VERSION7)	10.2.4, 10.2.6
max_block_processing_credits, max_state_transition_processing_credits, max_state_transitions_per_type_per_block; blob, chunk and incomplete-upload caps; max_settlements_per_block, max_settlement_processing_credits; scheduled-entry prepaid balance key under [40]	SYSTEM_LIMITS_V5, prefunded_specialized_balances	15	06.1, 06.2, 06.5
max_guard_static_units, max_guard_ast_nodes, max_guards_per_document_type, max_guard_document_reads, max_guard_expression_depth	SYSTEM_LIMITS_V6	16	07
max_hook_code_size, max_hook_memory_pages, max_hook_table_elements, max_hook_fuel_per_call, max_distinct_modules_instantiated_per_block	SYSTEM_LIMITS_V7	17	08.3, 11.2.7
max_hook_footprint_entries, max_hook_index_query_limit, max_hook_read_bytes, max_hook_host_calls, max_preflight_fuel, max_document_wire_bytes	SYSTEM_LIMITS_V8	18	09.3, 09.2.4
per-call operation caps, max_proposed_operation_processing_credits, document_growth_headroom, max_call_output_bytes, max_fee_multiplier, max_pending_scheduled_calls_per_contract, max_scheduled_calls_per_block	SYSTEM_LIMITS_V9	19	10.2.3, 10.2.4

Tasks

Fee registry prerequisite (merge gate before Phase 1)

• rs-platform-version: register FEE_VERSION2 with fee_version_number: 2 as the second FEE_VERSIONS entry (fee/mod.rs:32) and give each later table the next number, so FeeVersion::get (fee/mod.rs:53-63) resolves every registered number.
• rs-platform-version: assert FEE_VERSIONS[i].fee_version_number == i + 1 for every entry, that every PLATFORM_VERSIONS entry's fee_version resolves through FeeVersion::get, and that each renumbered table's storage sub-table is byte-equal to FEE_STORAGE_VERSION1; pin the as_static() caller inventory as known and permitted (one caller, block_processing_end_events/tests.rs:866).
• rs-drive: make previous_fee_versions a required parameter of Drive::calculate_fee, so the compiler audits the 124 Drive::calculate_fee call sites under packages/rs-drive/src (most pass None today) instead of a manual sweep; block-lifecycle callers (vote poll cleanup, withdrawal document deletes) are the dangerous ones, since CorruptedCodeExecution from op.rs:291 halts the node there rather than rejecting a proposal.
• rs-drive-abci: replay-from-genesis versus saved-state refund equivalence across the PV9 and PV15 epoch boundaries, plus a test that every block event runs with Some(previous_fee_versions).
• Record the numbering and its three consequences in the DIP, so an implementer reads one answer rather than reconstructing it from the refund branch.

Fuel pricing

• rs-platform-version: add FeeWasmVersion to FeeVersion and populate it in FEE_VERSION5 with credits_per_fuel, the operator and custom fuel cost tables and the instantiate, translate, memory-page, context-byte and prepare rates (08.2.6); FEE_VERSION6 adds section 09's read and host-call rates.
• packages/rs-contract-runtime/benches (proposed): criterion bench over the corpus at packages/rs-contract-runtime/tests/corpus (proposed, section 03), the reference profile named in the crate README, raw measurement CSV committed beside the corpus. Acceptance: a test recomputes credits_per_fuel from that CSV and asserts equality with the constant in FEE_VERSION5, and CI runs the bench on the named hardware class and records the p99.
• Phase 0 deliverable: publish the reference and minimum evonode hardware profile in the DIP, since credits_per_fuel, max_block_processing_credits (06.1), the preflight caps (09) and every wall-clock acceptance criterion take it as input and this repository publishes no such spec (11.2.3).
• rs-drive-abci: fold fuel into processing_fee through ValidationOperation::HookExecution (08.2.6), a sibling of PrecalculatedOperation (execution/types/execution_operation/mod.rs:86) priced at fold time, at the hook seam section 08 places in packages/rs-contract-runtime (proposed), following the DPNS trigger pattern (batch/data_triggers/triggers/dpns/v1/mod.rs:272-278). Acceptance: for every corpus call, the executed event's processing_fee minus its storage-derived processing equals used_fuel * credits_per_fuel.
• rs-drive-abci: hook execution must not be gated by execution.use_document_triggers (packages/rs-drive-abci/src/config.rs:91-93, :621-623), which loads no trigger bindings when false (batch/state/v0/mod.rs:82-86) and would skip every hook and every fuel charge on a node with the flag off, giving a different app hash; make it cfg(test)-only or replace it with a consensus gate, and assert in the strategy suite that it cannot change block results once hooks are active.

Declared bounds, mempool, failure

• rs-drive-abci: one named insertion point per phase, cited identically by 04.5, 08.2.6, 11.2.3 and this section. PV16: the validate_state_v1 gate on balance - accrued >= G with the signer's PartialIdentity before the first guard (section 07). PV17 and PV18: the seam gate on balance - accrued >= B + nonce-bump cost with the signer's PartialIdentity, the CheckTx transformer pushing the priced bound so gas_wanted carries it, and the minimum-balance pre-check keeping only a contract-free floor. PV19: max_fuel and max_fee on the ContractCall wire, balance >= max_fee in the pre-check, gas_wanted = max_fee.
• rs-drive-abci: a test asserting the largest permitted bound (max_hook_fuel_per_call * credits_per_fuel plus the fixed terms at PV17, max_fee at its ceiling at PV19) stays under a stated fraction of the configured max_gas.
• rs-drive-abci: process_proposal rejects a proposal once the 06.1 accumulator exceeds max_block_processing_credits; the same accumulator bounds prepare_proposal and the block events tabulated at 06.1.
• rs-drive-abci: recheck drops a transaction whose last proposal outcome was InternalError, keyed until that identity contract nonce advances, so a node re-executes it at most once.
• rs-dpp: the four consensus code blocks allocated above (41000-41099, 41100-41199, 41200-41299, 41300-41399) reserved in one PR, each phase's variants landing in its own; a bump action for ContractCall charged with consumed fuel.
• packages/rs-contract-runtime (proposed): total mapping from every host-call failure into the guest-visible outcome enum, a property test that no guest input, path or key produces Err at the seam, and the residual HostFault set enumerated in the module docs.
• rs-drive-abci: PV19 proposed operations validate and apply in list order under the call's savepoint (10.2.3), so no Err surfaces post-apply.

Storage, attribution, conservation

• rs-drive: blob bytes charged as storage under RootTree::CodeBlobs with the uploader's StorageFlags, refunded on Delete at reference count zero; the completion transition charged per-byte hashing; contract create and update charged the prepare bound plus the fixed module fee per module-bearing type; abandoned staging refunded by its queued deadline entry rather than by a block-lifecycle sweep.
• rs-platform-version: a test over FEE_VERSIONS that storage_disk_usage_credit_per_byte never increases, or the move of refund pricing to the write epoch's rate in the PV that introduces blob storage.
• rs-drive: hook-emitted operations carry the acting owner's flags per 10.2.2, scheduled-call writes carry the principal, and no host function or converter may build flags with Identifier::default().
• rs-drive: prepaid queue-entry balances under [40]; a check at the emit seam that no proposed operation creates a sum item outside the trees the conservation equation reads; an underfunded queue entry records a dropped or rejected outcome with refund instead of returning an insufficient-balance error.

Clients

• rs-dpp: keep calculate_min_required_fee a floor and add the declared-bound function beside it, both extended for hook-bearing transitions; re-export both through rs-sdk, wasm-sdk and the platform-wallet FFI estimators. Acceptance: the client quote equals the rs-dpp bound for every corpus transition, checked in a wasm-sdk test and a platform-wallet-ffi test.

Tests

• Fuel corpus fees bit-identical across the CI matrix (section 11); per-module fees pinned by golden values that change only with the fee generation or the pinned engine version.
• Strategy test with verify_sum_trees on: calls, scheduled drains and blob deletion across an epoch change never trip CorruptedCreditsNotBalanced.
• Out-of-fuel at 0, cap minus 1 and cap yields PaidConsensusError with gas_used equal to the metered fee, never InternalError; a balance driven to exactly the declared bound never reaches the required_removed_balance > previous_balance branch; a departed identity is credited when a contract deletes its state.
• Floor and bound tested separately: calculate_min_required_fee at or below the actual fee, and the actual fee at or below the declared bound, which equals gas_wanted, for every corpus transition.

Acceptance criteria

• No fee constant is read outside FeeVersion or SystemLimits; no Err path exists from fuel exhaustion, a host call, or a PV19 proposed operation.
• required_removed_balance > previous_balance is unreachable for hook-bearing transitions; every stored blob element carries owned StorageFlags.

Risks

• Calibration on the wrong hardware class under-prices compute; mitigated by the 2x factor, the committed CSV, the published reference profile and the per-block credit budget above. Until that profile exists, every wall-clock criterion in the plan is unfalsifiable.
• Renumbering the fee versions reprices PV9 to PV14 epochs on replay and makes previous_fee_versions load-bearing on every refund path; a missed block-lifecycle None halts the node rather than rejecting a proposal.
• The debt path stays reachable through under-estimated non-fuel processing, as it is for documents today; only Err is excluded, not debt.
• Any client reimplementing the fee formula instead of calling the FFI or wasm binding drifts from rs-dpp; the Swift estimators already delegate to Rust (packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift:492, PlatformWalletManagerAddressFunding.swift:31), and section 13 must keep TS and Kotlin on the same path.

---

---

Continued in part 13 of 14 below.

[QuantumExplorer]

Part 13 of 14 of the plan (continued from part 12 above).

13. Developer experience, SDK, and tooling plan

Reasoning

Developers will judge this work by the guest crate, the test loop, the CLI and the docs, not by the engine. The cautionary tale is ink!: its README now says "Since January 2026, we are unfortunately unable to actively maintain or develop ink! further"; wasmi's own sponsorship ends in October 2026 (both in the external-engines facts). The SDK is therefore a product with a release line, shipped in the same PR stack as each consensus phase, never after it.

Three facts from the tree fix the shape:

1. platform-value uses std unconditionally (BTreeMap from std at packages/rs-platform-value/src/lib.rs:31, thread_local! at :54), carries a Float(f64) variant (:136), and pulls rand into Identifier (types/identifier.rs:4-7,190-194). It already declares an std feature (Cargo.toml:28-32) that only forwards serde/std and gates nothing in the source (no feature = "std" cfg exists under src/), which is why a flag is rejected in favour of a split. platform-serialization declares mod impl_std unconditionally (packages/rs-platform-serialization/src/features/mod.rs:2) and impl_std.rs:12-20 imports std::ffi, std::net, std::path, std::sync and std::time; the guest bypasses it and encodes with bincode 2 directly. platform-version stays out of the guest: ABI constants live in dash-contract-abi and the CLI resolves protocol versions on the host, so its std use (OnceLock only under mock-versions, packages/rs-platform-version/src/version/protocol_version.rs:14,66-68; RangeInclusive at version/mod.rs:5; format! in fee/mod.rs:53-60, so no_std would also need alloc) is not on the path, and whether its dependencies versioned-feature-core and grovedb-version (Cargo.toml:13-14) build without std is unverified.
2. Hand-written client mirrors drift. Swift DataContractConfig (packages/swift-sdk/Sources/SwiftDashSDK/DPP/DPPDataContract.swift:305-309) has five stored properties: three match Rust, documentsKeepRevisionLogForPassedTimeMs has no Rust counterpart, documentsMutableContractDefaultStored matches documents_mutable_contract_default only by intent, and four DataContractConfigV0 fields (documents_keep_history_contract_default, documents_can_be_deleted_contract_default, requires_identity_encryption_bounded_key, requires_identity_decryption_bounded_key; packages/rs-dpp/src/data_contract/config/v0/mod.rs:21-46) plus V1's sized_integer_types (config/mod.rs:282) are absent. The TS interface (packages/wasm-dpp2/src/data_contract/model.rs:102-111) omits only sizedIntegerTypes. Kotlin has no config type; its persistence entity copies six config columns by hand (packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/entities/DataContractEntity.kt:64-70). Validation-module configuration must not become another hand mirror.
3. Any Err that escapes the hook executor becomes StateTransitionExecutionResult::InternalError (packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/process_raw_state_transitions/v0/mod.rs:360; HandlerErrorCode::Internal = 13, packages/rs-drive-abci/src/abci/handler/error/mod.rs:97) and validators reject the block. The trigger seam the executor inherits does exactly that: data_trigger_binding.execute(...)? (packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/executor.rs:47). Tooling that cannot reproduce every outcome the chain can produce gives false confidence, so the CLI, the harness and the node share crates and engine pins.

Design

Guest SDK

Four new workspace crates, named as D10 records and sections 08, 09 and 10 use: directory packages/rs-* like the core crates (rs-dpp, rs-drive, rs-platform-value; members such as wasm-dpp2 and strategy-tests drop the prefix, Cargo.toml:6-52), Cargo package name without the prefix, which is what an author writes in a manifest. They are packages/rs-platform-value-core (platform-value-core: Value without Float, Identifier, bincode 2 alloc big-endian encoding; platform-value re-exports it), packages/rs-contract-abi (dash-contract-abi, #![no_std]: context structs, Reject, the ABI section constants shared by host and guest; section 08.2.4 places HookContextV0 here and section 10 CallContextV0), packages/rs-contract-sdk (dash-contract-sdk, guest import path dash_contract_sdk) and packages/rs-contract-sdk-macros (dash-contract-sdk-macros), the last two #![no_std] plus alloc for wasm32-unknown-unknown, which rust-toolchain.toml installs with channel 1.92. Examples follow the same convention in packages/rs-contract-examples (new, never published). Rejected: gating std inside platform-value, and hand-copying the encoding into the guest (a shared crate cannot drift).

Encoding contract. Value has a hand-written Decode with explicit variant indices (lib.rs:242-264: 16 Identifier, 17 Float, 18 Text, 19 Bool, 20 Null). platform-value-core owns that index table; index 17 is reserved, its Decode rejects it with a typed error, and platform-value layers Float on top at 17, so host and guest bytes are identical for every other variant and a derived encoding that renumbers Text cannot appear. Identifier::random and random_with_rng sit behind a random feature, off by default, that the guest never enables. Floats never reach guest arithmetic, and no module is refused for a float in its schema: section 08.2.4 (g) carries an F64 property (packages/rs-dpp/src/data_contract/document_type/property/mod.rs:170) across the ABI as the eight big-endian bytes of f64::to_bits, so index 17 is never emitted and the guest sees opaque bytes that the generator refuses to type. The context carries only schema-validated typed documents, never the raw transition value map. The generated decoder returns the reserved result -1 on a malformed context, which the host classifies as InvalidResult (section 08.2.7, paid, nonce bumped), distinguishable from an author code and from a trap; it can only arise from a host encoding bug, which the index-table golden vectors guard.

Typed documents: a generator maps document_schemas to Rust structs through DocumentPropertyType (property/mod.rs:158-179, @append_only at :157): Object becomes a nested struct, Array a Vec, Identifier and IdentifierWithReference the core Identifier, F64 a hard error. The generator fails closed on any variant it does not model explicitly, and the snapshot test enumerates all twenty current variants so appending one breaks the build instead of falling through to a default mapping. Documents cross the ABI in section 08.2.4's DocumentWire, whose properties are a self-describing map keyed by property name, the BTreeMap<String, Value> that Document::properties already holds (packages/rs-dpp/src/document/v0/accessors.rs:28), not a positional record: a module generated against contract version 1 that receives a version 2 document with an added property still reads every field it knows, and the context size is bounded by DocumentType::max_size. The schema is the IDL, so there is no second interface file to keep in sync; it is exposed as dash-contract types and a build.rs helper. Hand-written structs are rejected: they drift.

Entry points and the ABI section

#[hook(predicate)] (Phase 3) and #[hook(entry_point)] (Phase 5) generate the export, the context decode and section 08's dash-contract-abi custom section, amended with two fields: generated-against contract version and build-profile version. Cargo features abi-v0, abi-v1, abi-v2 (section 08.2.4's ABI v0, section 09's reads, section 10's entry points; the zero-based numbering of the abi_version field, one behind the host namespace) are a compile-time convenience, so a module built against a later ABI fails to compile instead of trapping; the consensus rule is the registration check, stated here because a feature gates nobody who writes imports by hand: exactly one custom section of that name, decoded under a fixed length bound (the whole section sits under max_hook_code_size, section 08.2.2, and capabilities is capped), abi_version at most the maximum the active protocol version admits, target_protocol_version at most the active PV, generated-against version as below, import set a subset of that ABI version's allowlist; anything else, including two sections of that name, is a fixed paid consensus error at registration (ValidationModuleError { PrepareFailed { rule } }, section 08.2.2, because section 11.2.3 holds that anything needing wasm validation to classify is paid, never a BasicError).

Generated-against version, aligned with the update policy that owns it: a newly attached module names the contract version the transition installs, 1 at create. A module already attached keeps its registered value and is never re-checked against a later contract version, because section 08.2.3 freezes validationModule and the property schema of a module-bearing type and lets an update attach a module only to a type it adds, so the schema a stored module was generated against cannot change under it. At PV17 a corrected predicate is therefore a new document type, not a replacement, and the SDK, the CLI and the book say so in those words; the one in-place path is PV19's contract-level entry_module update admitted by change_rules (section 10.2.8), whose replacement names the contract version that update installs.

Replay fixes the maintenance rule: a module registered under abi-v0 at PV17 (Phase 3; the phase-to-protocol-version mapping opens the Tasks below) must execute identically at every later PV, so imports are append-only per ABI version, the semantics of an existing import are versioned by protocol version inside the host and never changed in place, and a host-import bug fix is itself a PV-gated version of that import. Whether a post-processing tool preserves a custom section it does not know is a property of that tool and its version, not something to assume: packages/wasm-sdk/Cargo.toml:114 already sets wasm-opt = false, with no reason recorded in the file or in PR #2690, which introduced the line. Section preservation is this design's own requirement: build pins the tool version and its section-keeping configuration, and a test asserts the section survives the release profile.

Hook outcomes and reject codes

A predicate returns Result<(), Reject> with a contract-defined Reject(u16), encoded as the i32 result of section 08's validate export (0 accept, 1..=65535 the code). Every hook outcome maps to exactly one ConsensusError, section 08.2.7's StateError::ValidationModuleError kinds; the developer-visible mapping the SDK, simulate and fuel report (registration verdicts are the same error type's PrepareFailed { rule }, which check mirrors offline):

Outcome	Kind	Paid, nonce bumped
return code 1..=65535	Rejected { code }	yes
trap: unreachable, out-of-bounds, division by zero, stack or memory cap, arithmetic overflow under the build profile	Trapped { kind }	yes
fuel exhausted	OutOfFuel { budget }	yes
result outside 0..=65535, reserved -1, context_read misuse, entry-point output that does not decode	InvalidResult	yes
translation failure on a stored module (a failed_under marker from lazy re-preparation, 08.2.7), ABI retired, governance freeze	ModuleUnavailable { reason }	yes
GroveDB read failure, a blob absent at run time (ExecutionError::DriveIncoherence), or a stored blob whose bytes no longer hash to the registered code hash	Err (node-local corruption class)	no; InternalError

Codes: the state-error space is taken through 40999 (data triggers own 40500-40699 with AddressDoesNotExistError at 40600, packages/rs-dpp/src/errors/consensus/codes.rs:356-360; tokens, groups and shielded hold 40700-40999, :365,389,396; the highest assigned code is 40904 at :401), so the kinds take a new block at 41000-41099. The error carries section 08.2.7's payload, (contract_id, document_type, document_id: Option<Identifier>, kind), with the author's number inside Rejected { code } and nothing variable-length. Clients receive it as info: base64 of a CBOR map {"data": {"serializedError": <platform-versioned ConsensusError bytes>}} (packages/rs-drive-abci/src/abci/handler/error/consensus.rs:21-35), with gas_used from total_base_fee() (packages/rs-drive-abci/src/abci/app/execution_result.rs:23,37). A rejected hook bumps the identity data contract nonce exactly as a data-trigger failure does (batch/state/v0/mod.rs:325-330), and the fee on every non-success row includes fuel consumed to that point. Free-form strings are rejected: variable size makes fees unpredictable.

Test harness

dash-contract-testutils (packages/rs-contract-testutils) runs a hook under the pinned wasmi by default, so cargo test exercises the engine, fuel and traps the chain uses. Native execution of guest code is not the chain's semantics: usize is 32 bits on wasm32 and 64 on the host, integer overflow panics under debug and wraps under release, and a dependency can pull f64 in unnoticed, so plain-Rust mode is opt-in for breakpoints and coverage, never the default. The wasm build profile turns overflow-checks on, so arithmetic overflow is a deterministic trap; the guest lint denies usize and isize in any ABI-visible type, panics in predicates and unbounded loops; the float check is an opcode scan of the compiled module, which check needs anyway because section 08.2.1's consensus Config sets floats(false), so dependencies are covered transitively. Heavier tiers: TestPlatformBuilder (packages/rs-drive-abci/src/test/helpers/setup.rs:23-66) for consensus-path tests and strategy tests for chains (section 14).

CLI

dash-contract (packages/rs-contract-cli) links packages/rs-contract-runtime (section 11) and the version crates; every command that touches the engine takes --protocol-version and selects the vendored engine pin that PV activates.

• build: a versioned build profile owned by the CLI, not "deterministic flags": toolchain 1.92 and wasm32-unknown-unknown from rust-toolchain.toml, --locked against a committed Cargo.lock, --remap-path-prefix so no absolute path reaches debug info or panic strings, codegen-units = 1, lto = "fat", panic = "abort", overflow-checks = true, symbol stripping that keeps the ABI section, and the post-processing tool pinned by version. The profile version is written into the ABI section so check reports which profile an on-chain module claims; CI builds every example on two hosts and asserts hash equality, which is the audit baseline.
• check: section 08.2.2's registration checks (module and memory caps, import allowlist, exports, ABI section, eager translation) under the SystemLimits fields section 08.3 adds in SYSTEM_LIMITS_V7 (max_hook_code_size, max_hook_memory_pages, max_hook_table_elements, max_hook_fuel_per_call) and the engine pin of the given PV; refuses a module whose corpus fuel exceeds its declared maxFuel.
• size: against max_hook_code_size and section 06.2's blob caps (blob 256 KiB, chunk 16 KiB). Chunk count is the ceiling of length over 16 KiB, never length over 20480: 20480 is max_state_transition_size for the whole signed transition (packages/rs-platform-version/src/version/system_limits/v4.rs:23), and the Phase 3 task list below adds a dpp signing-size test pinning that a full 16 KiB Chunk fits it, as seed_pool_batch_fits_max_state_transition_size does for shielded actions (v4.rs:41).
• fuel: runs the corpus under the engine pin of --protocol-version and prices it with --fee-version. FeeVersion (packages/rs-platform-version/src/version/fee/mod.rs:35-47) has no fuel field today; the constants arrive as section 12's FeeWasmVersion sub-table in FEE_VERSION5, the PV17 fee generation in section 14.2's schedule (section 12's constants table still names FEE_VERSION3; section 08.2.6 already uses the 14.2 numbering). Pricing an old epoch is not possible today: FEE_VERSIONS is &[FEE_VERSION1] (fee/mod.rs:32), FEE_VERSION2 carries fee_version_number: 1 (fee/v2.rs:13, the number v1.rs:12 already uses), and the per-epoch cache persists only the number (packages/rs-drive-abci/src/platform_types/platform_state/platform_state_for_saving/v1/mod.rs:100-103) and resolves it through FeeVersion::get on load (:145), so a persisted 1 always yields FEE_VERSION1. --fee-version is therefore meaningful only once section 12's fee-registry repair lands, which section 14.2 makes a Phase 1 merge gate and section 05 records as D3, and fuel refuses a number FeeVersion::get cannot resolve. Prints declared maxFuel, corpus maximum, credits for both, and wall-clock on the reference machine class from the nanoseconds-per-fuel calibration section 12 records with the fee version, because fuel bounds work, not time.
• simulate: testutils over a JSON fixture, running the developer's own module under wasmi and reporting fuel.
• deploy: section 06.2 CodeBlob chunks, then DataContractCreate or Update through rs-sdk PutContract (packages/rs-sdk/src/platform/transition/put_contract.rs:21), generalising packages/rs-scripts/src/bin/register_contract.rs. Resumable and idempotent by code hash (reads the staging subtree through section 06.3 and sends only missing indices), and refuses to stage past the incomplete-blobs-per-identity cap. It offers no PV17 replacement path because none exists: under section 08.2.3 a corrected predicate is a new document type, which deploy reports instead of attempting an update. At PV19 an entry_module update admitted by change_rules (section 10.2.8) is a replacement, and deploy then issues Delete { hash } once the old blob's code_blob_references reaches zero, which section 06.2 allows the storage owner at count zero, so the storage refund lands. Abandoned staging is deleted and refunded by section 06.2's queued deadline; there is no contract-delete transition (21 variants, packages/rs-dpp/src/state_transition/mod.rs:462), so blob lifetime is the reference count, not the contract's.

A JS-first CLI is rejected: check and fuel are only trustworthy if they share the node's crates.

Mempool admission

Hooks stay out of check_tx today only by an inherited default: validates_full_state_on_check_tx is false unless a transition overrides it (packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/state.rs:53-55; only MasternodeVote does), so packages/rs-drive-abci/src/execution/validation/state_transition/check_tx_verification/v0/mod.rs:320-329 skips validate_state for batches and the data-trigger seam at batch/state/v0/mod.rs:318 that the hook executor inherits is never reached; should_validate_batch_valid_against_state (batch/mod.rs:45-55) gates a different step (batch/state/v0/mod.rs:374; batch/state/v1/mod.rs:76). Flipping that default for mempool accuracy would run the engine in check_tx, so Phase 3 adds an explicit gate: the hook executor runs only under ValidationMode::Validator, with a test that CheckTx and RecheckTx never instantiate the engine.

The admission model this section depends on, stated rather than cited: each validation module declares maxFuel at registration (section 08's keyword, bounded by max_hook_fuel_per_call), and the check_tx estimate (validate_fees_of_event, packages/rs-drive-abci/src/execution/check_tx/v0/mod.rs:179-186) adds section 08.2.6's whole bound B per hook-bearing action (instantiation base, translation per code byte, memory per page, context per byte and budget * credits_per_fuel), not the fuel term alone, because a flat instantiation charge is under-priced exactly for the largest modules. The balance check uses that sum. Without it: an attacker registers a hook that burns its budget and rejects, funds N identities to the base fee and floods the mempool; check_tx admits everything, the proposer burns proposer_tx_processing_time_limit (process_raw_state_transitions/v0/mod.rs:155) executing each to its cap, the fee exceeds each balance, and throughput collapses at the price of identity creation: the fee-under-estimate class behind the mainnet halts, moved to the mempool. Test: an identity funded to the base fee but not to B is rejected in check_tx and never reaches a block.

Engine pins across protocol versions

Engine drift is not a CLI-versus-node problem; the hazard is stored modules versus a bumped engine. A module accepted under wasmi pin A executes under pin B after activation; if B's validator rejects the stored bytes, the failure would surface as Err through the inherited ? at executor.rs:47 and every block carrying a transition on that contract would fail every round: a deterministic liveness halt from one PV bump. Rules: (1) the node links every engine pin that was ever active, vendored per section 11 and selected by wasm_engine_version (section 08.2.1, beside grove_version on DriveVersion), and executes a module with the engine of the PV the block runs under; check and fuel select the same pin from --protocol-version; replay from genesis therefore runs PV17 blocks on the PV17 engine, and since no retirement rule exists the linked set only grows, a cost section 11.2.5 owns. (2) On activation of any PV that changes the pin no sweep runs: each stored module is re-prepared lazily by the first transition that needs it, at that transition's expense, and one the new engine rejects is marked failed_under (08.2.7), so a transition that hits it gets ModuleUnavailable, paid, never Err; the PV-opening PR's off-chain replay (11.2.5) lists those modules before signalling. (3) The check verdict corpus runs under every vendored pin, not only the current one. (4) Validators have no wall-clock budget (NotExecuted(ProposerRanOutOfTime), packages/rs-drive-abci/src/platform_types/state_transitions_processing_result/mod.rs:15, is proposer-only), so max_block_processing_credits (section 06.1, SYSTEM_LIMITS_V5) is the consensus-visible bound and fuel's wall-clock column is calibrated against it.

Local network, docs, examples

dashmate's local preset already runs a full network (packages/dashmate/src/commands/setup.js:84; yarn start), and no genesis default needs changing. init_chain reads the genesis app_version out of the ABCI consensus params and treats 0 as "start at the desired version" (PlatformVersion::desired(), packages/rs-drive-abci/src/execution/engine/initialization/init_chain/mod.rs:44-51), and DESIRED_PLATFORM_VERSION is LATEST_PLATFORM_VERSION (packages/rs-platform-version/src/version/protocol_version.rs:72-74). dashmate's base genesis template sets no version.app_version (packages/dashmate/configs/defaults/getBaseConfigFactory.js:432-460), unlike the testnet and mainnet factories, which pin app_version: '1' (getTestnetConfigFactory.js:172, getMainnetConfigFactory.js:76); drive-abci's own initial_protocol_version is dead code (packages/rs-drive-abci/src/config.rs:231-234, // TODO: Is not using). A node built from the hook PV's tree therefore starts a local network at that PV with hooks active, while testnet and mainnet still activate by signalling. Book chapters go under book/src/contracts/ (new), opening with "Introduced in protocol version N" as book/src/fees/shielded-fees.md:3 does; tutorials "first guard" (Phase 2), "first predicate" (Phase 3) and "first entry point" (Phase 5) sit beside the evo-sdk tutorials in book/src/SUMMARY.md. Examples in packages/rs-contract-examples/ double as strategy fixtures, the fuel corpus and the differential-test corpus.

Client SDKs

Schema-keyword module declarations reach consensus from mobile unchanged through platform_wallet_create_data_contract_with_signer (packages/rs-platform-wallet-ffi/src/data_contract.rs:22), but a declaration references a code hash whose bytes must already be committed, so every client follows one ordering: stage the CodeBlob chunks, wait for inclusion and a section 06.3 proof of the complete blob, then send the create or update; otherwise the contract transition fails with a paid consensus error and the user pays twice. The opt-in FFI/JNI functions return the code hash so the second step is bound to the first, and docs/sdk/sdk-parity-manifest.json records the sequencing beside the capability. The CodeBlob transition needs exposure in rs-sdk (packages/rs-sdk/src/platform/transition/), wasm-sdk (packages/wasm-sdk/src/state_transitions/contract.rs) and evo-sdk ContractsFacade (packages/js-evo-sdk/src/contracts/facade.ts). Contract calls follow the client checklist in section 10. rs-sdk-ffi has no structured consensus-error field: DashSDKError (packages/rs-sdk-ffi/src/error.rs:38-45) carries a DashSDKErrorCode and a message, and although the enum distinguishes DriveInternalError = 10 (error.rs:32), From<FFIError> assigns the code by substring matching on the Display string (ProtocolError only when the text contains "protocol", error.rs:159), so a hook rejection would surface as ProtocolError, NotFound or InternalError depending on wording. It gains consensus_code: u32 (the code Tenderdash returns), error_bytes (the data.serializedError payload, after base64 and CBOR decoding of info) and reject_code: Option<u16>, the last filled best-effort from dash_sdk::Error's typed consensus variant before the substring fallback; a mobile build on an older dpp still surfaces the code and the bytes after a protocol upgrade. Mirrored in the Swift and Kotlin wrappers.

Decision: no engine pin inside wasm-sdk or either mobile framework, in this release or after Phase 4 without binary-size numbers. The boundary, stated once so the task lists agree: native rs-sdk may link packages/rs-contract-runtime behind an off-by-default feature (section 09.3's preflight helper over proofs); wasm-sdk, Swift and Kotlin call section 09.2.5's non-consensus preflight query, a PV18 endpoint with its own SystemLimits and PlatformConfig caps whose load test is a testnet exit criterion (section 14.5). Until PV18 the pre-flight path is dash-contract simulate and a local node; without state reads a client-side verdict would not be authoritative anyway.

Audit tooling and language breadth

check, fuel and the two-host reproducible build are the audit baseline; the ABI is frozen in a DIP so auditors have a normative reference, either inside the single Standard DIP or in the second Standard DIP section 05 tasks for the point where section 08 freezes the guest interface. No static analyser of the Slither class exists for this ABI, and none is promised.

Rust first. AssemblyScript, TinyGo and C target the same imports once the ABI spec exists; each needs a determinism audit of its runtime (allocator, GC, float use) before it is listed as supported. Solidity through a Solang-class compiler is a time-boxed experiment after Phase 5, not a commitment: the EVM storage model does not map onto document-shaped state.

Decisions

• SDK owner: named in the Phase 3 PV-opening PR; the crates.io publish job below has no owner account until then. Due before the PV17 stack opens.
• wasmi funding (co-sponsor or fork-and-freeze): due before the first hook PV opens, not merely before October 2026, because a frozen engine with a validator bug has only section 11's D6 runbook (freeze, non-consensus hotfix, or a normal PV with pre-coordinated signalling; no expedited vote exists). Recorded in section 11.

Tasks

Phase-to-protocol-version mapping used below: Phase 1 PV15 and Phase 1b its own PV (section 06), Phase 2 PV16 (section 07), Phase 3 PV17 (section 08), Phase 4 PV18 (section 09), Phase 5 PV19 (section 10).

Groundwork (Phases 0 and 1, no protocol-version gate)

• Split packages/rs-platform-value-core (new) out of packages/rs-platform-value (workspace member; random feature off by default), re-export it, and add cargo check --target wasm32-unknown-unknown for it beside the wasm32 dependency-tree checks in .github/workflows/tests-rs-workspace.yml:219-226; add the index-table golden vectors (one per variant, plus a rejected-17 vector). Record a cargo check -p platform-version --target wasm32-unknown-unknown probe result (whether versioned-feature-core and grovedb-version build without std); it is not on the guest path.
• Create packages/rs-contract-abi (new; dash-contract-abi, #![no_std]; custom-section constant and codec, Reject) behind abi-v0, built in the same CI step; section 08.3's task fills the same crate with HookContextV0 and DocumentWire at Phase 3, section 10's with CallContextV0 at Phase 5.
• Land section 12's fee-registry repair before Phase 1 merges (section 05's D3; the gate is section 14.2's): every registered FeeVersion carries a distinct fee_version_number and sits at that index in FEE_VERSIONS, which today holds &[FEE_VERSION1] alone (packages/rs-platform-version/src/version/fee/mod.rs:32). Acceptance: the persisted-number round trip (platform_state_for_saving/v1/mod.rs:100-103, resolved through FeeVersion::get at :145) resolves every number a PlatformVersion names, and dash-contract fuel --fee-version refuses one it cannot.
• Generate the DataContractConfig mirrors from DataContractConfigV0 and V1: a build step in packages/wasm-dpp2 emitting the typescript_custom_section block at packages/wasm-dpp2/src/data_contract/model.rs:57 from the rs-dpp struct, a script beside packages/swift-sdk/build_ios.sh writing the Swift struct, and the Kotlin entity's config columns; each mirror carries exactly the Rust field set. Acceptance: a snapshot test diffs the generated field names against rs-dpp.
• Docs corrections with target wording: README.md:49-50 and book/src/platform-comparison.md:48-49 ("planned for Platform v4.0 (targeted for mainnet in 2027)") become "planned in five phases gated on protocol versions 15 to 19; see the smart-contracts plan issue"; README.md:63 and platform-comparison.md:38-39 table cells become "Planned (staged, PV15 to PV19)" and "No VM today (data contracts); wasmi-executed hooks planned"; book/src/sdk-support.md:12-13,27-31 state that packages/swift-sdk and packages/kotlin-sdk ship today; book/src/state-transitions/lifecycle.md:250-261 says 21 variants. Acceptance: grep -rn "Platform v4.0\|Coming in v4.0\|planned for v4.0" README.md book/src/platform-comparison.md and grep -n "Coming in v3" book/src/sdk-support.md both return nothing, lifecycle.md's count equals the enum's, and the 45 v4.0-dev GitHub permalinks under book/src/drive/ are untouched.

Phase 2 (guards)

• Create packages/rs-contract-cli (new) in this phase with check for guard expressions (parse, static cost against section 07's max_guard_static_units) and tutorial "first guard" with a packages/rs-contract-examples/bounded-transfer fixture. Acceptance: check verdicts equal the consensus guard validator's on a fixture corpus of accepted and rejected guards.

Phase 3 (predicates, first hook protocol version)

• packages/rs-contract-sdk and packages/rs-contract-sdk-macros (both new): #[hook(predicate)], ABI section emission, Reject(u16), the reserved -1 decode failure, the typed-document generator failing closed with a twenty-variant snapshot test over packages/rs-drive-abci/tests/supporting_files/contract/. Acceptance: wasm32 #![no_std] build green in tests-rs-workspace.yml; every packages/rs-contract-examples module builds.
• packages/rs-contract-testutils (new): wasmi default, native opt-in, read stubs reserved for Phase 4. Acceptance: the wasmi-versus-native differential (verdict and fuel) green on every packages/rs-contract-examples fixture.
• Extend packages/rs-contract-cli with the build profile, module check, size, fuel, simulate, deploy. Acceptance: two-host hash equality on every example; check verdicts equal registration verdicts on a rejected-module corpus under every vendored pin; fuel credits equal a local network's charge at the given fee version.
• rs-platform-version: section 12's FeeWasmVersion sub-table lands on FeeVersion in FEE_VERSION5, the PV17 table in section 14.2's schedule. Acceptance: fuel --fee-version prices the corpus against it and refuses a number FeeVersion::get cannot resolve.
• rs-drive-abci: the ValidationMode::Validator gate at the hook seam with the never-instantiate test for CheckTx and RecheckTx; section 08.2.6's bound B in the check_tx estimate with the underfunded-identity test asserting the whole bound, not the fuel term; the lazy re-preparation path writing prepared_under or failed_under on the first use after an engine bump (08.2.7, no first-block arm); the fault-injection assertion (section 11's corpus) that only a GroveDB read failure, an absent blob or a code-hash mismatch escapes the executor as Err.
• rs-dpp: the 41000-41099 code block with section 08.2.7's Rejected payload shape; the Chunk signing-size test.
• Expose CodeBlob in rs-sdk, wasm-sdk, evo-sdk ContractsFacade, rs-sdk-ffi and rs-unified-sdk-jni with the stage, wait, create sequencing and the returned code hash; record capability and sequencing in docs/sdk/sdk-parity-manifest.json.
• Add consensus_code, error_bytes and reject_code to DashSDKError in packages/rs-sdk-ffi/src/error.rs, populated before the substring fallback, and to the Swift and Kotlin wrappers.
• Write book/src/contracts/ (overview, ABI, fees, testing, and the fix-a-bug recipe: under section 08.2.3 a corrected predicate is a new document type, so the chapter states the client-side re-creation path and its storage-refund consequences) and tutorial "first predicate" with an escrow example; no dashmate change (local genesis leaves app_version unset, so init_chain starts at the node's desired version). Acceptance: yarn start local network accepts the tutorial predicate in the scripted run below.

Phases 4 and 5

• abi-v1 (section 09's dash_v2 reads) and abi-v2 (section 10's dash_v3 emit) features in packages/rs-contract-sdk, read stubs in packages/rs-contract-testutils, #[hook(entry_point)]. Acceptance: a v0-only module registers and executes unchanged in the PV19 suite.
• Bind section 09.2.5's preflight query where section 09.3 does not: rs-sdk-ffi, rs-unified-sdk-jni and the Swift and Kotlin wrappers, plus the evo-sdk surface over wasm-sdk's call; record the capability and its caps in docs/sdk/sdk-parity-manifest.json. Acceptance: a Swift and a Kotlin test read verdict, fuel and read cost for a rejecting module, and the concurrency-cap load test section 14.5 gates runs against dashmate local.
• Expose the contract-call ST and its proof result in rs-sdk, wasm-sdk, js-evo-sdk, rs-sdk-ffi and rs-unified-sdk-jni per section 10's checklist; tutorial "first entry point" with an auction example. Acceptance: docs/sdk/sdk-parity-manifest.json lists the call ST for both mobile SDKs and both example apps execute it against dashmate local.

Maintenance

• Add a crates.io publish job to .github/workflows/release.yml, which today publishes npm packages, Docker images and the mobile SDKs and runs no cargo publish (none exists under .github, scripts or package.json), for platform-value-core, dash-contract-abi, dash-contract-sdk, dash-contract-sdk-macros, dash-contract-testutils and dash-contract, gated on the release tag and publishing under the owner account the Decisions entry names. Acceptance: cargo install dash-contract --version <tag> succeeds the day the GitHub release is published.
• Add a PROTOCOL_VERSION_CHECKLIST section to packages/rs-contract-abi/README.md (new imports only behind a new abi-vN; never remove or alter an existing import, version its semantics inside the host by PV; testutils updated; fuel vectors regenerated; check corpus run under the new pin; book chapter amended) and link it from .github/PULL_REQUEST_TEMPLATE.md.

Tests

• Guest crates build for wasm32-unknown-unknown with #![no_std] in CI; index-table golden vectors encode identically on host and guest, and index 17 is rejected; the three config mirrors' field-name snapshot equals rs-dpp.
• Generator snapshot over all twenty variants; wasmi-versus-native differential on every example; check verdicts equal registration verdicts under every vendored pin, including a module with two ABI sections and one whose section was stripped by post-processing; fuel credits equal the local-network charge at the given fee version and fuel refuses an unregistered fee-version number; two-host build hash equality; CheckTx and RecheckTx never instantiate the engine; an identity funded below section 08.2.6's bound B is rejected in check_tx; only a GroveDB read failure, an absent blob or a code-hash mismatch escapes the executor as Err; book examples compile as doc tests.

Acceptance criteria

• A developer with only the book goes from cargo new to a predicate accepted on dashmate local in under one hour, measured by a scripted CI run.
• Every example builds and passes in the workspace job; crates and CLI are installable from crates.io the day the release ships; the parity manifest lists contract capabilities, with their sequencing, for both mobile SDKs.
• A block at max_block_processing_credits executes in under one fifth of timeout.propose on the reference evonode hardware profile the DIP fixes (section 11.2.3; this repository publishes no minimum spec today), on arm64 and amd64, the bound section 11.2.3 calibrates and section 12 records with the fee version; fuel's wall-clock column reports against the same measurement.

Risks

• The SDK becomes a byproduct and stalls (ink!): mitigated by the owner decision, the release gate and the per-version checklist.
• Stored modules versus a bumped engine: every activated pin stays linked, lazy re-preparation marks what the new pin rejects as failed_under (08.2.7), and the fuel-equality and per-pin check tests fail on divergence.
• Generated types diverge from consensus parsing: the generator lives beside try_from_schema in rs-dpp, is tested against it, and fails closed on unknown variants.
• No in-place fix for a deployed predicate (section 08.2.3): the book carries the new-document-type recipe from the first release, so the constraint is a documented cost, not a support surprise.
• Demand for client-side pre-validation in wasm and mobile, or for extra languages, outruns capacity: the PV18 preflight query serves the first and neither is promised beyond it; both gate on measurements after Phase 4.

---

---

Continued in part 14 of 14 below.

[QuantumExplorer]

Part 14 of 14 of the plan (continued from part 13 above).

14. Delivery: sequencing, testing, rollout, success criteria, risks, open questions

14.1 Reasoning

One protocol version per phase: activation is the only consensus switch (lock-in when 67 percent of active HPMNs signal at an epoch boundary, protocol_version_upgrade_percentage_needed, drive_abci_method_versions/v10.rs:58; active the next epoch). Withholding a failed phase means not shipping the release, not signalling a lower number: info answers with DESIRED_PLATFORM_VERSION.protocol_version (packages/rs-drive-abci/src/abci/handler/info.rs:69), a compile-time alias of LATEST_PLATFORM_VERSION (packages/rs-platform-version/src/version/protocol_version.rs:72-74) that reaches the header as proposed_app_version (execution/engine/run_block_proposal/v0/mod.rs:126, :257), and no node setting caps it (nothing in packages/rs-drive-abci/src/config.rs). A failed soak therefore blocks every unrelated fix in the same release, so Phase 1 either adds an operator setting capping the signalled version below the binary's or the release manager owns that coupling in writing (D9). PV numbers are relative, not reserved: any other consensus change landing first shifts every row below it, so the tables mean "the next free PV after Phase n". Each PV follows the shielded-pool delivery: a behaviour-free PV-opening PR (#4267, commit 2d324d8, opened v14 in three files), then a crate-by-crate stack (#3177 to #3228) with // changed: notes. Rejected: an umbrella PR per phase, and merging Phases 1 and 2 into PV15 (section 12's fee registry repair comes first).

14.2 Sequencing

Phase (section)	PV	Depends on	Main crates	Size	Audit (11.2.4)
0 decisions, DIP (05)	none	nothing	dashpay/dips, README, book	S	no
1 VM prerequisites (06: 6.1, 6.2, 6.3, the 6.5 queue)	15	D1, D2, D3, D7, D12, D13, D17; section 12 fee registry repair	platform-version, dpp, drive, drive-abci, dapi-grpc, SDKs	L	internal
1b value-moving primitives (06: 6.4, 6.5 escrow, allowance, auctions)	its own PV: 15 beside Phase 1 if ready, else the next free PV	Phase 1 (6.1, the queue), D14, the 11.2.9 assessment, the external audit; nothing on the path to Phases 2 to 5 depends on it	dpp, drive, drive-abci, packages/oracle-feeds-contract (new), SDKs	XL	external
2 guards (07)	16	6.1 (Phase 1); section 12 fee registry repair; nothing in Phase 1b	packages/rs-platform-guards (new), dpp, drive-abci	L	yes
3 predicates (08)	17	6.2, Phase 2, packages/rs-platform-value-core (new, section 13), D4 to D6, D8, D15, D16, 11.2.5, section 12 fuel pricing	packages/rs-contract-runtime, -abi and -sdk (all new), dpp, drive-abci	XL	yes
4 footprint reads (09)	18	Phase 3, 6.3; 6.4 only for the OracleFeed entry kind, admitted once Phase 1b is active	packages/rs-contract-abi, dpp, drive, drive-abci, FFI, JNI	L	yes
5 entry points (10)	19	Phase 4, 6.1, the 6.5 queue (Phase 1), D1, D5, the per-call savepoint below; ClaimAllowance only where Phase 1b is active	dpp, drive, drive-abci, packages/rs-contract-runtime, SDKs	XL	yes

Audit scope, settled here: Phase 1b moves value (auction settlement, escrow, allowances) and makes feed medians consensus data, so 6.4 and 6.5 are externally audited before Phase 1b signalling; Phase 1 opens permanent storage (code blobs) and the block budget and is audited internally. Phase 1b is its own protocol version so that its audit, the 11.2.9 assessment and the D14 Tenderdash evidence can never hold the guard and predicate phases: if it is ready with Phase 1 it rides PV15 beside it, otherwise it takes the next free PV after whichever phase is ready first, and nothing in sections 07 to 10 waits for it.

Phases 2 and 3 depend on nothing in Phase 1b: section 07 reserves feed without defining it and 6.4's acceptance records the reservation; section 07 excludes tradeMode: Auction types from guards and 08.2.2 from modules, so neither needs the auction to exist. Phase 4 admits the OracleFeed footprint entry only where Phase 1b is active (09.2.2), and Phase 5's scheduled calls use the settlement queue, which is Phase 1's (the first 6.5 task), with ClaimAllowance conditional on Phase 1b (10.2.6).

Phase 5 prerequisite, atomic proposed-op application. Proposed operations run through the existing pipeline, which has no nested rollback: execution can write into the shared block transaction before failing, and the validator path is deliberately left un-rolled-back because changing it is a consensus change (process_raw_state_transitions/v0/mod.rs:108-135). If op k of n fails (principal balance, unique index collision, guard rejection), ops 1 to k-1 are already written, which is the partial-state leak of the 415652 and 415661 halts. PV19 therefore ships the validator-path savepoint under DriveVersion V12, with operations transformed, validated and applied one at a time in list order (10.2.3, 10.2.4). Validate-all-against-pre-call-state is rejected there on correctness grounds, not preference: two creates that both pass uniqueness against pre-call state collide at apply as an Err. Section 10.2.6 extends the same savepoint to block events, where rollback_to_savepoint runs only while proposing today (process_raw_state_transitions/v0/mod.rs:136-137); 14.5 gates both with a per-k root-hash test.

Generation allocation, binding. Sections 06 and 07 were both drafted against meta-schema v4, parser generation 4 and CONTRACT_VERSIONS_V7: 06 keeps that set at PV15, and 07 takes CONTRACT_VERSIONS_V8, meta-schema v5 and parser generation 5 at PV16. DriveVersion V10 at PV15, V11 at PV17 (wasm_engine_version Some), V12 at PV19 (principal creation in insert_contract, the savepoint); wire id 21 at PV15, 22 and 23 reserved for Phase 1b and appended when it activates, 24 at PV19. PV16 also opens document serialization format 4 (DOCUMENT_VERSIONS_V5) for section 07's $createdAtContractVersion stamp, the second document format change after PV14's format 3. The contract-versions numbers below assume Phase 1b activates with Phase 1 at PV15, since TradeMode::Auction is what opens meta-schema v4, parser generation 4, DocumentTypeV3 and CONTRACT_VERSIONS_V7 there; if Phase 1b lands after PV16, PV16 takes that set for guards and every later contract-versions, meta-schema and DocumentType number in this document drops by one, a single edit to this table at the PV-opening PR. TradeMode::Auction takes discriminant 4; 2 and 3 stay reserved for the commented PublicOffer and PrivateOffer (packages/rs-dpp/src/nft/mod.rs:8-13). Two validation tables exist and only one is in the table below: DRIVE_ABCI_VALIDATION_VERSIONS_V10 sits at PV14 (packages/rs-platform-version/src/version/v14.rs:203), so V11 opens PV15. DPP validation is separate (DPP_VALIDATION_VERSIONS_V5 at PV14, v14.rs:210) and advances only where a phase adds basic-structure rules: V6 at PV16 (guards), V7 at PV17 (modules), V8 at PV19 (ContractCall).

PV	SystemLimits	DriveAbci validation	Contract versions (meta-schema, parser, DocumentType)	FeeVersion
15	V5	V11	V7 (v4, 4, DocumentTypeV3; TradeMode::Auction)	FEE_VERSION3 (3)
16	V6	V12	V8 (v5, 5, DocumentTypeV4 guards)	FEE_VERSION4 (4)
17	V7	V13	V9 (v6, 6, DocumentTypeV5 validationModule)	FEE_VERSION5 (5)
18	V8	V14	unchanged (BatchTransitionV2 by bounds)	FEE_VERSION6 (6)
19	V9	V15	V10 (serialization format V2, DataContractV2)	FEE_VERSION7 (7)

DocumentType has V0 to V2 today (packages/rs-dpp/src/data_contract/document_type/mod.rs:147-151; DocumentTypeV2 at document_type/v2/mod.rs:30), so sections 06, 07 and 08 name V3, V4 and V5 for the new generations. The three are independent: parser generations 2 and 3 both build DocumentTypeV2 (try_from_schema/mod.rs:81-107). PV15 takes meta-schema v4 because v3 pins tradeMode to enum [0, 1] (packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json:773-780) and parser generation 4 pairs with it (the discipline at dpp_contract_versions/v6.rs:14-20); DocumentTypeV3 holds 6.5's parsed auction state and stays bound to that row even if it lands as a pass-through, because 07 and 08 are written against V4 and V5.

The fee numbers are not free either: FEE_VERSIONS holds one entry (packages/rs-platform-version/src/version/fee/mod.rs:32), FeeVersion::get indexes FEE_VERSIONS[n-1] (:53-63), FEE_VERSION2 carries fee_version_number: 1 and is unregistered (fee/v2.rs:13), and persisted state stores only the numbers, rehydrating with get(number).expect(...): a number absent from the array panics at node start, including on a rollback to an older binary. Binding, so the rest of the plan cites one answer: FEE_VERSION2 is registered as number 2 and FEE_VERSION3 to FEE_VERSION7 take 3 to 7, holding FEE_VERSIONS[i].fee_version_number == i + 1; section 12 owns the registration mechanism and its registry PR, a Phase 1 merge gate under D3, implements it. The PV15 stack carries an assertion of that invariant and of every PLATFORM_VERSIONS entry's fee_version resolving, a test that each renumbered version's storage table is byte-equal to FEE_STORAGE_VERSION1, and a refund test comparing an in-place-upgraded node with one replayed from genesis, since previous_fee_versions is appended only when the number changes at an epoch boundary and refunds price historical bytes through it (packages/rs-drive/src/fees/op.rs:280-301).

14.3 Testing strategy

Layer	Per phase
Unit	tests.rs per new validation module; one test per row of tables 8.2.7 and 10.2.9; a table test over every engine trap code and host error asserting the mapped consensus error, from an exhaustive match with no wildcard arm; a forced host fault is the only InternalError; StateTransitionNotActiveError tests per gate constant.
Fees	Cold-versus-warm: the same hook run twice in one process must produce a byte-equal FeeResult, so no compiled-module cache can leak into a fee or budget term.
strategy-tests	OperationType variants; test_cases/<phase>_tests.rs with proofs, independent process_proposal re-run and a pinned root hash; each phase joins comprehensive_mixed_operations (strategy_tests/test_cases/comprehensive_tests.rs:67), the only PR-path simulation.
platform-test-suite	One evo-sdk spec per phase on dashmate local; the evidence source is the nightly tests.yml run (cron 23:00, .github/workflows/tests.yml:15-16), which calls the reusable tests-test-suite.yml. NIGHTLY_STATUS.md (repository root, manually maintained, still describing the v4.1-dev nightly) records the long-standing flakiness: evidence, not the gate.
Cross-arch	Net-new: nightly ubuntu-24.04 plus ubuntu-24.04-arm matrix comparing root hashes and golden fuel, from PV16. From PV17 an amd64 ABCI request log is replayed on arm64 with drive-abci replay (packages/rs-drive-abci/src/main.rs:68-71, needs --features replay, outside the default set at Cargo.toml:129; the comment at :142 still names the old abci-server binary). It ingests TRACE-level drive-abci JSON logs of received ABCI request entries (replay/cli.rs:13, log_ingest.rs:111), which only a running node emits, so the log comes from a nightly amd64 dashmate local-network run, not from a strategy test, whose mimic harness drives the handlers in process.
Engine generations	Golden fuel and output vectors committed per wasm_engine_version (11.3) and re-run against every generation on each engine bump; a replay test executes a PV17-era block on the PV17 engine after the PV18 engine is linked into the same binary. No ABCI state-sync handler exists (state_sync: None, query/system/status/v0/mod.rs:69), so a new node bootstraps by replaying history and runs every hook-bearing block under the engine of the PV in force at that height: this row also measures replay throughput and binary size per linked engine.
Fuzzing	None today. Nightly cargo-fuzz in a workspace-excluded fuzz/ directory (new): guard parser (PV16), prepare pass and HookContextV0 decoder (PV17), footprint matcher (PV18), ProposedOp decoder (PV19).
Upgrade	Per PV via the protocol-upgrade-test skill: idempotent transition_to_version_N, genesis-versus-upgrade equivalence, a lock-in test copied from run_chain_v12_to_v13_locks_in_before_activation (packages/rs-drive-abci/tests/strategy_tests/test_cases/upgrade_fork_tests.rs:559), TEST_PLATFORM_V2/V3 mocks extended, a dashmate rolling-upgrade rehearsal.

CI infrastructure (before PV16)

• Add the ubuntu-24.04 plus ubuntu-24.04-arm matrix and root-hash and golden-fuel artifact comparison to .github/workflows/tests-rs-nightly-long-running.yml, together with an amd64 dashmate local-network job capturing a TRACE request log and an arm64 drive-abci replay job built with --features replay. Acceptance: the comparison job is green on v4.2-dev and fails when a deliberately altered root hash artifact is injected.
• Add a nightly fuzz workflow over a new fuzz/ directory excluded from the workspace (root Cargo.toml exclude, so clippy --workspace --all-features and cargo machete do not see it), one target per Fuzzing row above, a committed seed corpus and a fixed per-target run time. Acceptance: the workflow is green and a seeded crash input is reproduced by cargo fuzz run.
• Extend the nextest filter at .github/workflows/tests-rs-workspace.yml:355 so each phase's PR simulation fits the 90 minute job timeout (:34); add one un-ignored upgrade test per PV.

14.4 Rollout

Per PV: PV-opening PR; crate stack; audit closed; devnet acceptance against 14.5; testnet release, signalling, activation, soak; mainnet signalling only after the soak report, activation one to two 9.125-day epochs later (788400 s, packages/dashmate/configs/defaults/getBaseConfigFactory.js:358). Testnet epochs are 3600 s (getTestnetConfigFactory.js:85): activation takes hours and epoch-boundary code runs hundreds of times; the soak is 14 days minimum, counted in days.

Permissioning: deployment is allowlisted from PV16, not open. Layer 3 of the 11.2.6 ContractGovernance registry checks the deployer allowlist at guard-bearing contract create and update from PV16, module-bearing from PV17 and ContractCall from PV19; editing the list needs no PV. That allowlist and frozenGuard, with globalFreeze above them, are PV16's only in-chain kill switches, which is why the guard audit closes before PV16 signalling (11.2.4). Open deployment is a later PV (D5) after two allowlisted soaks with zero halts, the Phase 4 violation criterion met, and both freeze drills below.

Rollout gates

• Add a PV-opening PR heading to .github/PULL_REQUEST_TEMPLATE.md carrying the four gate checkboxes: audit closed, devnet criteria met, soak report attached, SDK, CLI and book tagged (section 13 release line). Acceptance: the boxes render on a new PR and the PV-opening reviewer named in D9 blocks merge while any is unticked.
• Open one tracking issue per PV in dashpay/platform; each soak report is a comment carrying hook transitions per day, result classes, fuel per engine version, TxAction::Delayed counts, violation counts and the replay-throughput figure from 14.3. Acceptance: the report is linked from the PV-opening PR before mainnet signalling.
• Seed the testnet allowlist by writing deployer documents to the 11.2.6 ContractGovernance system contract with the dash-contract CLI (section 13), signed by the key holders the DIP names: the guard-bearing team contracts at PV16, the section 08 example modules at PV17, the auction and subscription contracts at PV19. Acceptance: a proved getDocuments query on the allowlist type returns the seeded contract ids on testnet.
• Run the freeze drills on testnet before open deployment: a frozenGuard write at PV16, a per-contract frozenContract write at PV17, and a globalFreeze write at each, timed from transition to the first block rejecting a guarded write or a call. Acceptance: guarded writes and calls return the fixed consensus error charged at the minimum transition fee with no guard evaluated and no engine entered, deletes on the frozen type are rejected too, RecheckTx evicts queued calls, and due scheduled entries drain as rejected with refund.

14.5 Success criteria

Phase	Measurable
0	DIP PR open under an alias filename; D1 to D8 and D12 to D17 accepted, D9 to D11 recorded; docs PR merged.
1	Budget: a strategy test overfills a block and asserts the proposer emits TxAction::Delayed for the tail (abci/handler/prepare_proposal.rs:236), a hand-built over-budget proposal is rejected by process_proposal at PV15 and accepted at PV14, and the tail commits in the next block; a transition above max_state_transition_processing_credits is rejected at check_tx, so no transition can be undeliverable forever. Blobs: a 256 KiB blob uploads in chunks under the 20480-byte transition cap and verifies in JS; abandoned staging is deleted and refunded by its deadline entry. Conservation never fails and per-block identity plus pool deltas net to zero. 14 day soak, zero halts.
1b	Feeds: a feed updates at every slot close with proofs, the committee element admits at most k observers per slot under a mid-slot masternode list change, and two nodes whose Core RPC differs in height write identical slot values. Primitives: escrow, allowance and auction run on a devnet with proofs, the 11.2.9 assessment is linked from the PV-opening PR, and conservation never fails through settlement, refund and drop. 14 day soak, zero halts.
2	Guard vectors byte-equal on amd64, arm64, wasm32; registration rejects a guard whose static cost is not derivable from schema bounds (unbounded string or array, regex over an unbounded input, any comprehension), one unit test per rejection class; gas_wanted == gas_used for read-free guard batches; the dashpay contact-request and withdrawal-delete rules, as guards, within 2x the native processing fee on their trigger corpora, with DPNS create staying native (07); $createdAtContractVersion survives replace, transfer, price update and purchase unchanged, a since guard never applies to a pre-PV16 document, and a frozen guard admits no guarded write.
3	Seven document kinds follow the module; charged credits equal module bytes times the FeeVersion translation rate, plus fuel_used * credits_per_fuel under a checked multiply, plus 8.2.6's instantiation, memory-page, context-byte and preparation terms, with no cache term, proven by the cold-versus-warm test; gas_wanted >= gas_used on every hook batch and no UnpaidConsensusError from one; the allowlist entry binds contract id to code hash, so an update retargeting the blob needs re-listing; replay of a hook-bearing testnet range under the PV17 engine reports blocks per second and binary size per linked engine in the soak report; the soak corpus is the section 08 examples, the team contracts and an adversarial corpus (fuzzer-derived modules that trap, exhaust fuel and read outside the footprint), not a contract count; zero halts, zero fuel drift.
4	Every strategy verdict reproduced by the harness from proofs captured at N-1 before N commits (client-side reproduction after N waits on past-height proof serving, 9.2.6); every declared footprint entry resolved and charged whether the guest reads it or not, billed through add_operation as data triggers bill queries today (batch/data_triggers/triggers/dpns/v1/mod.rs:272), so read cost never depends on guest control flow; a block with two transitions on one footprint proves same-block writes are invisible to hooks (the 9.1 snapshot rule); undeclared-read violations under 5 percent, else the 9.6 declared-ceiling variant precedes PV19.
5	Auction and prepaid subscription contracts run from Swift and Kotlin (the pull subscription where Phase 1b is active), every read and effect proven, the receipt and effects pair verifying for every call; a fault injected at proposed op k of n leaves every subtree the operations touched equal to its pre-call state, for every k, on proposer and validator paths, with the caller balance, the identity contract nonce, the fee pools and the callReceipt differing from the pre-call root exactly by the paid-failure effects (asserted against a reference run applying only those effects, the 11.3 paid-rejection snapshot), and a fault at operation k of a drained scheduled call likewise, with the queue entry, the prepaid balance and the callOutcome as its permitted effects, while a host fault leaves the root unchanged on the validator and restored to the savepoint on the proposer; a scheduled call fires in the first block whose scheduled sub-budget admits it, the queue never exceeds its cap, and overflow drops refund; no UnpaidConsensusError and no InternalError; sum trees balance through cancel and drop.

14.6 Risk register

Risk	L	I	Mitigation	Owner
Guest outcome filed as InternalError	M	H	process_proposal rejects any block carrying one (abci/handler/process_proposal.rs:285-308), so a resource-dependent classification makes some validators reject what the proposer accepted and burns rounds: every guest-consumable resource (fuel, memory pages, table size, stack and call depth, module bytes) is capped at deployment and enforced by the engine, so no host allocation can fail mid-execution; every trap maps one-to-one in an exhaustive match; the only Err is a Drive read or write failure; a fault-injection strategy test (process_raw_state_transitions/v0/mod.rs:221-223) forces the split on one node and asserts the rejection is local	consensus
Partial application of proposed ops	M	H	the validator-path per-call savepoint with sequential validate-and-apply, chosen in 10.2.3 rather than left open (14.2); per-k root-hash test on both paths and in the block-event drain	consensus
Host fault inside the scheduled drain halts every block	L	H	the drain's guest-reachable outcome set is closed and fuzzed (10.2.6, 11.3); no denylist or freeze reaches a block event, so D6's coordinated binary behind a network-keyed activation height is day zero, rehearsed with a faulting queue entry before PV19 (11.2.5, 11.2.8)	consensus
Scheduled-call queue growth, starvation, divergent order	M	M	prepay at schedule time, max_scheduled_calls_per_block, a sub-cap inside max_settlements_per_block and a tenth of the block budget, canonical (fire time, entry id) order, bounded deferral then drop with refund (10.2.6)	drive-abci
Orphan chunks; code swapped under a listed contract id	M	M	deadline cleanup with refund and blob refcount (6.2); allowlist binds contract id to code hash	drive
Fuel drift inside the pinned wasmi line	M	H	= pin, golden vectors per engine generation, differential corpus per bump	runtime
wasmi sponsorship ends October 2026	H	M	fork-and-freeze or co-sponsor before PV17 (14.7 question 4, D16)	eng lead
Replay cost and binary size grow with every activated engine	M	M	bootstrap is replay from genesis (no state-sync handler, status/v0/mod.rs:69), so every activated engine stays linked: a retirement rule in 11.2.5 (retire a vendored engine once no supported bootstrap path replays its heights), replay throughput and binary size measured per PV (14.3, 14.5), and the bootstrap position itself, replay versus snapshot or checkpoint sync and who builds it, owed by section 05	release
Cross-arch CI slips past PV16	M	M	amd64 plus replay fallback; gates signalling, not merge	CI
FEE_VERSION2 renumbering misbehaves live	M	M	array invariant test, storage tables pinned byte-equal, upgraded-versus-replayed refund test; the fee registry repair lands alone	fees
Refunds hit CorruptedCodeExecution (op.rs:280-301) under a new fee number	M	H	previous_fee_versions required; audit every calculate_fee site still passing None	fees
Block budget miscalibrated	M	M	budget is deterministic credits summed identically by prepare_proposal and process_proposal, constant in SYSTEM_LIMITS_V5; the 5000 ms block_spacing_ms (packages/rs-drive-abci/src/config.rs:725) is a calibration input only, and proposer_tx_processing_time_limit is a node setting unset by default (abci/config.rs:37-39, honoured only while proposing), so it cannot be the source; calibration measures against D17's reference profile	drive-abci
Oracle slot value diverges on Core RPC height skew	L	H	eligibility and staleness read from the last committed platform state, never a live Core RPC call (6.4); two-node equality test in 14.5	consensus
Engine security patch, no expedited PV	M	H	globalFreeze (11.2.6) stops execution for already-listed modules, not just new listings; per-contract freeze, D6 runbook, flag-day escalation	release
Older clients cannot decode new variants	H	M	SDK releases tagged before the vote (section 13)	SDK
Masternodes decline to signal (more CPU, liability)	M	H	budget and allowlist first; D17's evonode cost report and hardware profile (storage and CPU delta, fee-mix change, applications unblocked)	product
Governance registry keys mishandled	L	H	11.2.6's controls (group writes rejected: no document group-action path): asymmetric freeze and unfreeze thresholds, the two key sets at different security levels, self-expiring globalFreeze, rotation by the same mechanism, key ceremony in the DIP	ops
Proposer extraction once value moves, from Phase 1b	M	M	11.2.9's assessment applied to 6.5 before Phase 1b signalling; min_auction_decay_window_ms, batch settlement, receipts	product
Release train coupled to one phase's soak	M	M	signalled-version cap or written release-manager ownership (14.1)	release

14.7 Open questions for reviewers

Numbering is stable: sections 01, 03, 05 and 10 cite these positions, so a resolved question keeps its number. Each carries the record that owns it, its due date and what happens if it is undecided by then.

1. Host branch: (a) v4.3-dev, (b) v5.0-dev, (c) a feature branch off v4.2-dev. Release manager (D9), by the Phase 1 PV-opening PR; default (c), which needs no branch-policy change.
2. Resolved. FEE_VERSION2 numbering: (a) register it as number 2, (b) leave it at 1 and start FEE_VERSION3 at 2. 14.2 binds (a), section 12's registry PR implements it, and the 14.2 invariant and replay tests are mandatory either way. Fees owner (D3), a Phase 1 merge gate.
3. Permissioning: (a) a named key-holder set with asymmetric thresholds (11.2.6 rejects group writes outright, and masternode votes for the freeze path as too slow for incidents), (b) a masternode-voted registry, (c) open deployment from PV17. Product owner with consensus lead (D5), by the Phase 3 design review; default allowlisted deployment from Phase 2 (07, 14.4) and open deployment at a later PV (05 Risks).
4. Engine stewardship: (a) co-sponsor wasmi, (b) fork and freeze under Dash maintenance, (c) the wasmtime 36 LTS interpreter plus finite-wasm (section 03). Release manager with consensus lead (D16), by October 2026 and before the Phase 3 stack opens; default, ship Phases 1 and 2 and stop (05 Risks).
5. Contract-to-contract calls (10.7): (a) never, (b) demand-gated after PV19, (c) planned for PV20. Consensus lead, by the PV19 soak report; default (b), 10.7's recommendation.
6. Ordering: (a) no protocol, (b) threshold-encrypted mempool study, (c) fair-ordering study before PV19. Consensus lead with product owner, by PV19 signalling; default (a) plus 11.2.9's per-grant assessment, which is what 10.2.7 ships.

Resolved here rather than left open, and cited elsewhere by that phrase, not by a number. Principal creation for contracts registered before the PV is lazy, priced to the transition that first needs it: the PV19 generations of insert_contract and update_contract create the principal balance under [96, id] when a module is attached and none exists, and transition_to_version_19 creates none. Eager creation at activation is an unbounded loop over every contract inside perform_events_on_first_block_of_protocol_change, where an Err halts the node, writing storage nobody pays for. The [64, contract_id, 2] subtree is separate and stays uncreated: blobs live in RootTree::CodeBlobs (04.3, 6.2). Hooks in check_tx: never. check_tx runs no guest code and requires balance >= base fee + declared max fuel * credits_per_fuel + declared footprint cost, reporting that sum as gas_wanted (abci/handler/check_tx.rs:66-70 reports total_base_fee() today), and an under-funded identity is rejected there rather than producing an UnpaidConsensusError that process_proposal rejects. Phase 1 audit scope: external for 6.4 and 6.5, internal for the rest (14.2).

14.8 How to review this document

Comment per section, quoting the section number and, for tasks, the checkbox line; cite decisions by ID and questions by number and letter. Objections to a rejected alternative go to section 03; to a price or cap, section 12; to a gate, generation or soak rule, here.

14.9 Section index

Each section carries its own task checkboxes; this index is the reading order, not a task list.

• Phase 0 (05): design DIP; decision records; naming and repository hygiene; stale documentation; threat model.
• Phase 1 (06): 6.1 budget; 6.2 code blobs; 6.3 range prove_elements; the 6.5 settlement queue; 6.6 events punt. Phase 1b (06): 6.4 oracle feeds; 6.5 escrow, allowance and auctions; 6.7 phase risks.
• Phase 2 (07): evaluator crate; rs-dpp; version tables; rs-drive, drive-abci, SDKs.
• Phase 3 (08): engine crate; prepare pass; document-type reference; ABI crate; seam, errors, fees; guest SDK, harness, CLI; determinism CI and security; activation and docs.
• Phase 4 (09): rs-dpp, ABI crate and version tables; rs-drive, rs-contract-runtime, drive-abci; SDKs and tooling.
• Phase 5 (10): rs-dpp, ABI, version tables; rs-contract-runtime; rs-drive; drive-abci; SDKs, DAPI, tooling.
• Cross-cutting (11): determinism; error classification; fees and budget; security review and engine governance; permissioning and limits.
• Cross-cutting (12): fee registry prerequisite; fuel pricing; declared caps, mempool, failure; storage, attribution, conservation; clients.
• Developer surface (13): groundwork (Phases 0 and 1); Phase 2; Phase 3; Phases 4 and 5; maintenance.
• Delivery (14): CI infrastructure; rollout gates.

---

End of document.

[QuantumExplorer]

Revision 2 (2026-09-08): edits made in place above, in response to an external review.

The body and all thirteen parts were edited in place rather than reposted, so section anchors are unchanged. The review found eight defects and one scoping problem; each is resolved as follows, with the sections that changed.

1. $contractVersion could not carry guard policy (section 7). The replace conversion re-stamps $contractVersion with the current contract version, so a version-1 document replaced under version 2 would have acquired version 2's delete prohibition. Guards' since now keys on a new immutable $createdAtContractVersion, written once at create, copied on replace, carried unchanged by transfer, price update and purchase, stored in document serialization format 4 (DOCUMENT_VERSIONS_V5, PV16). Pre-PV16 documents have no stamp and are never subject to a since guard, which is exact since they predate every guard. since may not be lower than the version installing the guard. Tests cover create, contract update, replace, delete. Sections 7 and 14.2.
2. Freezing guards would have bypassed application invariants (section 7). A frozenGuard or globalFreeze now rejects every guarded action, paid, deletes included, and never suppresses evaluation. Recovery authority is exactly two paths: unfreeze under 11.2.6's thresholds, or the contract owner removing the guard by contract update. Section 8.2.5 applies the same rule to frozen modules; only the permanent unavailability reasons keep deletes open. Sections 7, 8.2.5, 8.2.7, 11.2.6, 14.4.
3. Auction settlement bypassed guards (sections 6.5, 7). Section 7 now carries the same admissibility rule as 8.2.2 rule 6: a type whose documents can be written outside the batch seam declares no guards, so tradeMode: Auction is excluded beside contested types. Also excluded: on: [delete] guards on indexOnly types (no old, no stamp) and system data contracts. Section 7.
4. A nonce proof did not prove execution (section 10.2.5). Every executed ContractCall, success or paid failure, writes a fixed-size callReceipt document (call hash, nonce, outcome code, effects hash) in the ContractCalls system contract, one slot per caller per contract, replaced in place. VerifiedContractCallEffects is ExecutionProved only when the proven receipt's call hash matches the transition; otherwise AffectedState, consistent with the existing verifier's classifier. Sections 10.2.4, 10.2.5, 10.3, 10.4, 11.2.2, 11.3.
5. No execution-time affordability gate at PV16 (section 7). Section 7 gained the PV16 instance of 11.2.3's one bound per phase: validate_state_v1 receives the signer's PartialIdentity and, before the first guard runs, requires live balance minus accrued processing to cover the static guard bound G plus the nonce bump; a shortfall is InsufficientBalanceForGuardEvaluation, paid, with no guard evaluated. Sections 7, 11.2.3, 12.
6. The Phase 5 failure-fee bound was asserted, not derived (section 10.2.4). The claim that the degraded fee stays under floor is withdrawn. Every unit of work in a call (fuel, reads, each proposed operation's validation stages, predicates at their bound, dry runs) has a worst-case cost checked against max_fee before the unit runs, so the degraded fee is accrued <= max_fee <= live pre-call balance, which the in-block pre-check established. Scheduled calls apply the same rule against the prepaid remainder. Tests: a caller funded exactly to max_fee with maximal predicate-bearing operations failing at the last one. Sections 10.2.4, 10.2.6, 10.4, 11.2.3.
7. The oracle's at-most-k bound was not established (section 6.4). The committee for a slot is now computed once at slot open from the masternode list committed at that height and stored as a SlotCommittee element; observations are accepted only from stored members still in the list, uniqueness is checked against the block transaction, RecheckTx evicts committed duplicates, and pending duplicates are bounded per block by max_state_transitions_per_type_per_block. Equivocation is recorded as an accepted gap for Phase 1b. Sections 6.1, 6.4, 11.2.3, 14.5.
8. Contradictory requirements. No eager engine re-prepare sweep exists anywhere now: 8.2.7's lazy, charged re-preparation is canonical and the sweep was removed from 4.7, 6.1, 11.2.3, 11.2.5, 11.3 and 13. Deployment is allowlisted from PV16 everywhere: 5, 11.2.4, 11.2.6, 11.3 and 11.6 now agree with 7 and 14. Application-state rollback is specified separately from permitted failure effects: 14.5 row 5, 10.2.6, 10.4 and 11.3 require every touched subtree to equal its pre-call state while the fee debit, nonce, pools and receipt (or queue entry, prepaid balance and callOutcome) differ exactly by the paid-failure effects.

Scoping. Section 6 is now two tracks. Phase 1 (PV15) is the VM prerequisites: block budget, code blobs, range proofs and the settlement queue. Phase 1b is oracle feeds and the escrow, allowance and auction primitives: value-moving, externally audited, in its own protocol version, and a prerequisite of nothing in sections 7 to 10. Sections 1.1, 1.4, 1.6, 3.1, 5, 6, 9.2.2, 10.2.6, 11.3, 12, 13, 14.2, 14.5, 14.6, 14.9 reflect the split; 14.2 states the one-edit renumbering of contract-versions generations if Phase 1b lands after PV16.

Checkbox count: 211 (one added, the format 4 task in section 7). Revision 1 text is available from the edit history of each comment.