refactor: encapsulate transaction processing in a typestate-based processor

[cylewitruk-stacks]

Summary

Introduce a typestate-based TransactionProcessor that encapsulates Stacks transaction processing, makes invalid configurations unrepresentable at compile time, and supports attaching Clarity evaluation hooks (including execution tracers).

This provides the stackslib processing foundation for transaction trace replay (secondary) while providing a little more structure and compile-time safety for the primary transaction processing interface (primary).

This is 99% a structural refactor and isn't intended to change any functionality aside from the optional eval-hook wire-up.

Changes

• Move transaction processing off StacksChainState into TransactionProcessor.
• Require callers to explicitly provide:
  • an execute or skip disposition;
  • the appropriate Clarity context; and
  • a limited or unlimited resource policy.
• Expose terminal operations only for valid typestates.
• Unify ordinary and problematic-transaction processing through TxToProcess.
• Preserve receipt validation, evaluation-hook propagation, fee charging, nonce updates, and legacy skip semantics.
• Organize processing into focused account, validation, payload, post-condition, and poison-microblock modules.
• Move common microblock signer recovery onto StacksMicroblockHeader.
• Migrate production and test callers to the new API.
• Add compile-fail coverage for invalid typestate combinations.

Checklist

• Test coverage for new or modified code paths

[Copilot]

Pull request overview

Refactors transaction execution into a typestate-based processor while preserving consensus behavior and enabling Clarity tracing.

Changes:

• Adds TransactionProcessor, processing modules, and compile-fail coverage.
• Migrates transaction-processing callers and propagates evaluation hooks.
• Clarifies resource-budget and microblock signer APIs.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
stackslib/src/net/api/postblock_proposal.rs	Updates resource-budget construction.
stackslib/src/net/api/fastcallreadonly.rs	Updates read-only execution budgets.
stackslib/src/net/api/callreadonly.rs	Updates read-only execution budgets.
stackslib/src/clarity_vm/clarity.rs	Adds evaluation hooks and processor integration.
stackslib/src/chainstate/tests/static_analysis_tests.rs	Updates processor references.
stackslib/src/chainstate/tests/runtime_analysis_tests.rs	Updates budget documentation.
stackslib/src/chainstate/tests/mod.rs	Migrates test transaction processing.
stackslib/src/chainstate/tests/consensus.rs	Updates TxToProcess import.
stackslib/src/chainstate/stacks/mod.rs	Re-exports signer comparison type.
stackslib/src/chainstate/stacks/miner.rs	Migrates miner processing and budgets.
stackslib/src/chainstate/stacks/db/transactions/processing/validation.rs	Extracts static validation.
stackslib/src/chainstate/stacks/db/transactions/processing/tests/typestate_compile_fail.rs	Adds invalid-typestate tests.
stackslib/src/chainstate/stacks/db/transactions/processing/tests/mod.rs	Registers processing tests.
stackslib/src/chainstate/stacks/db/transactions/processing/post_conditions.rs	Extracts post-condition evaluation.
stackslib/src/chainstate/stacks/db/transactions/processing/poison_microblock.rs	Extracts poison-microblock handling.
stackslib/src/chainstate/stacks/db/transactions/processing/payload.rs	Extracts payload execution.
stackslib/src/chainstate/stacks/db/transactions/processing/mod.rs	Implements processor typestates.
stackslib/src/chainstate/stacks/db/transactions/processing/accounts.rs	Extracts account and fee operations.
stackslib/src/chainstate/stacks/db/transactions.rs	Exposes processor and migrates tests.
stackslib/src/chainstate/stacks/db/mod.rs	Migrates boot transaction processing.
stackslib/src/chainstate/stacks/db/blocks.rs	Migrates block and mempool processing.
stackslib/src/chainstate/nakamoto/mod.rs	Relocates TxToProcess.
stackslib/src/chainstate/nakamoto/miner.rs	Uses processor receipt checks.
stacks-node/src/tests/mem_abort.rs	Updates test budget construction.
stacks-node/src/nakamoto_node/miner.rs	Uses an in-memory test database.
stacks-codec/src/transaction.rs	Adds microblock signer comparison.
clarity/src/vm/resource_limiter.rs	Clarifies unlimited budget construction.
clarity/src/vm/mod.rs	Updates execution budget construction.
clarity/src/vm/analysis/type_checker/v2_1/tests/mod.rs	Updates deadline test budgets.
clarity/src/vm/analysis/tests/mod.rs	Updates analysis test budgets.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated no new comments.

[coveralls]

Coverage Report for CI Build 31843262178

Coverage increased (+0.04%) to 86.608%

Details

• Coverage increased (+0.04%) from the base build.
• Patch coverage: 90 uncovered changes across 9 files (1417 of 1507 lines covered, 94.03%).
• 85 coverage regressions across 25 files.

Uncovered Changes

File	Changed	Covered	%
stackslib/src/chainstate/stacks/db/transactions/processing/poison_microblock.rs	102	81	79.41%
stackslib/src/chainstate/stacks/miner.rs	39	24	61.54%
stackslib/src/chainstate/stacks/db/transactions/processing/post_conditions.rs	191	178	93.19%
stackslib/src/chainstate/stacks/db/transactions/processing/payload.rs	340	329	96.76%
stackslib/src/chainstate/stacks/db/transactions/processing/validation.rs	71	60	84.51%
stackslib/src/chainstate/stacks/db/blocks.rs	48	38	79.17%
stackslib/src/chainstate/stacks/db/transactions/processing/mod.rs	273	268	98.17%
stackslib/src/chainstate/stacks/db/transactions/processing/accounts.rs	86	84	97.67%
stackslib/src/clarity_vm/clarity.rs	41	39	95.12%
Total (19 files)	1507	1417	94.03%

Coverage Regressions

85 previously-covered lines in 25 files lost coverage.

Top 10 Files by Coverage Loss	Lines Losing Coverage	Coverage
stacks-node/src/neon_node.rs	18	82.92%
stackslib/src/net/inv/epoch2x.rs	10	79.44%
stackslib/src/chainstate/nakamoto/mod.rs	5	84.78%
stackslib/src/net/stackerdb/sync.rs	5	76.57%
stacks-signer/src/v0/signer.rs	5	87.14%
stacks-common/src/deps_common/bitcoin/blockdata/transaction.rs	4	95.18%
stacks-common/src/deps_common/bitcoin/network/encodable.rs	4	88.71%
stackslib/src/net/relay.rs	4	74.67%
stackslib/src/burnchains/bitcoin/indexer.rs	3	35.08%
stackslib/src/net/chat.rs	3	93.0%

---

Coverage Stats

Relevant Lines:	233242
Covered Lines:	202006
Line Coverage:	86.61%
Coverage Strength:	19438682.08 hits per line

---

💛 - Coveralls

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated no new comments.

Suppressed comments (3)

clarity/src/vm/resource_limiter.rs:181

• Removing the public new() constructor and Default implementation makes this release source-incompatible for downstream clarity consumers, even though both had exactly the same semantics as unlimited(). Retain compatibility shims (they can be deprecated) so this refactor does not force unrelated consumer changes.

impl ResourceBudget {
    /// Creates a new instance with no configured budgets.
    pub fn unlimited() -> Self {
        Self {
            max_duration: None,

stackslib/src/chainstate/stacks/db/transactions/processing/tests/typestate_compile_fail.rs:17

• The explicit intra-doc target points at the tests module, but TransactionProcessor is defined in its parent (processing). This link is unresolved when rustdoc processes the compile-fail module; point it up two module levels.

//! Compile-fail coverage for invalid [`TransactionProcessor`](super::TransactionProcessor)
//! typestate transitions.

stackslib/src/chainstate/stacks/miner.rs:789

• This removes the existing public TransactionResourceBudgets::new() API even though its behavior is still represented by unlimited(). Downstream stackslib users will fail to compile for a naming-only change; retain a deprecated forwarding constructor while migrating in-repository callers.

impl TransactionResourceBudgets {
    /// Creates resource budgets with no configured limits.
    pub fn unlimited() -> Self {
        Self {
            execution_budget: ResourceBudget::unlimited(),