refactor: Extract post-conditions from `stackslib` into separate crate by jbencin-stacks · Pull Request #7478 · stacks-network/stacks-core

jbencin-stacks · 2026-07-31T21:11:59Z

Description

Extract post-conditions from stackslib into separate crate (stacks-postconditions), so they can be built for WASM targets

Applicable issues

Required for Post conditions in simnet stx-labs/clarinet#2185

Additional info (benefits, drawbacks, caveats)

Checklist

Test coverage for new or modified code paths
For new Clarity features or consensus changes, add property tests (see docs/property-testing.md)
Changelog fragment(s) or "no changelog" label added (see changelog.d/README.md)
Required documentation changes (e.g., rpc/openapi.yaml for RPC endpoints, event-dispatcher.md for new events)
New clarity functions have corresponding PR in clarity-benchmarking repo

…tion Post-conditions constrain the assets a transaction may move. That check is a static function of the declared post-conditions, an `AssetMap`, the origin principal and the epoch — it needs no database or chainstate, and nothing about it is specific to Clarity as a source language. Hosting it in `stackslib` made it unreachable from wasm, and hosting it in `clarity` would tie it to one contract language as we look at supporting others. Move `check_transaction_postconditions` and its `HashableClarityValue` helper into a new `stacks-postconditions` crate, leaving a thin adapter in `stackslib` that projects `StacksAccount` onto the origin principal the check needs. The crate still depends on `clarity` for `AssetMap` and `VmExecutionError`, so this does not yet decouple from the Clarity VM; it isolates the logic so that the remaining step is a change to one crate rather than a change spread across `stackslib`. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

The three epoch-activation rules for post-conditions (`Originator` mode and NFT `MaybeSent` requiring Stacks 3.4, `Staking`/`Pox` requiring Stacks 4.0) were duplicated verbatim between `process_transaction_precheck` and `StacksBlock::validate_transaction_static_epoch`. Like the checker moved in the previous commit they are pure functions of the post-conditions, the mode and the epoch, with no chainstate dependency. Add `check_post_conditions_supported_in_epoch`, returning a typed `UnsupportedPostCondition` rather than a formatted message so both call sites keep their existing error channel and log level. This collapses the two copies into one predicate, and matters for wasm consumers: because `check_transaction_postconditions` evaluates explicit post-conditions in every epoch, a caller running only that function would return a pass/fail verdict for a transaction mainnet rejects outright. Behavior is unchanged, including the message text at both call sites. The `Display` impl carries the "before Stacks X.Y" phrasing that `process_transaction_precheck` puts in its error, and `subject()` exposes the offending feature on its own so `validate_transaction_static_epoch` can keep naming the current epoch in its log. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Move the tests that exercise the checker in isolation — a hand-built `AssetMap` plus a list of post-conditions — alongside the code they cover. The `process_transaction` pipeline tests that reach the checker through the node (fee handling, receipts, rollback) stay in `stackslib`. This is a pure move. The only changes to the test bodies are mechanical: the `make_account` helper is gone, since the relocated check takes a `&PrincipalData` rather than a `&StacksAccount`, so each case passes the origin principal directly instead of fabricating a nonce and balance the check ignored. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

`AssetMap::to_table()` excludes the stacking map and the pox-action set, so the staking and PoX coverage checks are hand-rolled loops reachable only through their own path. Several branches in them had no test: - `Originator` mode for staking/PoX coverage. Every existing test used `Deny`/`Allow`, leaving the non-origin skip in `enforce_unchecked_assets_for_principal` unexercised. - `PostConditionPrincipal::Standard` for `Staking`/`Pox`. All existing tests used `::Origin`, so non-origin resolution through `to_principal_data` was untested for these two variants. - The `amount_staked == 0` skip in the staking coverage loop. - What the epoch gate does *not* gate: explicit `Staking`/`Pox` post-conditions are evaluated in every epoch, and only the coverage requirement is gated. Existing pre-4.0 cases used empty post-condition lists. Also cover `check_post_conditions_supported_in_epoch` on both sides of the Stacks 3.4 and 4.0 boundaries, and add a test showing the admission and asset-movement checks are independent, so callers need both. Correct stale terminology in the PoX test comments, which referred to "unstaking" / "MaybeUnstaked" from an earlier naming iteration; the condition codes are `PoxConditionCode::{NotPerformed, MaybePerformed, Performed}` over general PoX actions. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

brice-stacks

LGTM

benjamin-stacks

LGTM overall, just a few smaller things.

brice-stacks

lgtm

cylewitruk-stacks · 2026-08-13T15:30:59Z

Tbh, I would prefer to see this and the transaction types which previously ended up under stacks-codec colocated within a stacks-transactions crate; similar to what I did in this structural PoC: cylewitruk-stacks#4. Otherwise, I think the scope of this crate is too narrow and isn't pulling its weight, contributing to the dependency-direction spaghetti.

Of course, to keep the diff manageable, that could be achieved by just renaming this new crate to stacks-transactions and we can move the other types over in another PR.

Thoughts?

jbencin-stacks · 2026-08-13T16:05:29Z

@cylewitruk-stacks I think that makes sense, but if we're trying to minimize diffs here, then I should move it to crates/stacks-transactions, right? Since that's where it'll eventually go

jbencin-stacks · 2026-08-13T16:50:20Z

@cylewitruk-stacks Looking into this more, it seems that stacks-postconditions currently requires the entire Clarity VM (it doesn't actually need the VM, but some types that aren't in clarity-types), whereas stacks-codec does not, so that would add a big dependency for any consumer that just want's the codec

Having a larger number of smaller crates won't be an issue once we clean up the top level and organize them. Maybe we can have:

crates/stacks-transactions/codec
crates/stacks-transactions/postconditions

But let's save that for another PR

cylewitruk-stacks · 2026-08-13T19:18:35Z

but if we're trying to minimize diffs here, then I should move it to crates/stacks-transactions, right? Since that's where it'll eventually go

Yeah, exactly what I was thinking :)

@cylewitruk-stacks Looking into this more, it seems that stacks-postconditions currently requires the entire Clarity VM (it doesn't actually need the VM, but some types that aren't in clarity-types), whereas stacks-codec does not, so that would add a big dependency for any consumer that just want's the codec

Having a larger number of smaller crates won't be an issue once we clean up the top level and organize them. Maybe we can have:

crates/stacks-transactions/codec

crates/stacks-transactions/postconditions

But let's save that for another PR

Right, so, I think that:

AssetMap and AssetMapEntry could be moved into clarity-types rather easily and was probably a miss (I haven't deep-dived this, but they look to only depend on std and other types in clarity-types at a glance).
Instead of using the two error types from clarity, post-conditions should have their own PostConditionError (or whatever) error type if being extracted, and then consumers within clarity would map those to their own relevant vm-error type.

Assuming my assumptions hold, I think that would be the cleaner structural direction, and the moving of AssetMap etc. could be done in a separate PR to keep this PR's diff focused. What do you think?

jbencin-stacks · 2026-08-13T20:23:00Z

Instead of using the two error types from clarity, post-conditions should have their own PostConditionError (or whatever)

Yeah, eventually we'd like postconditions to be completely independent of Clarity so that we could use them with other languages (like Rust compiled to Wasm). My first attempt at this refactor moved them into clarity, and Brice pointed that out

I don't have a strong opinion one way or the other whether this in theory belongs in the same crate as the codec, but for now I don't think it makes sense because of the Clarity dependency. We can revisit later once the dependency is eliminated

cylewitruk-stacks · 2026-08-13T21:57:18Z

Instead of using the two error types from clarity, post-conditions should have their own PostConditionError (or whatever)

Yeah, eventually we'd like postconditions to be completely independent of Clarity so that we could use them with other languages (like Rust compiled to Wasm). My first attempt at this refactor moved them into clarity, and Brice pointed that out

I don't have a strong opinion one way or the other whether this in theory belongs in the same crate as the codec, but for now I don't think it makes sense because of the Clarity dependency. We can revisit later once the dependency is eliminated

The clarity dependency is trivially removed; see #7513. Then you'd handle the remaining error types in the same way I did with the newly introduced AssetMapError there -- by having the caller map the error to their own error variant.

jbencin-stacks mentioned this pull request Jul 31, 2026

refactor: Move post-conditions from stackslib -> clarity #7474

Closed

5 tasks

jbencin-stacks marked this pull request as draft July 31, 2026 21:12

jbencin-stacks force-pushed the refactor/stacks-postconditions-crate branch from e65c562 to 856cdd7 Compare August 3, 2026 17:50

jbencin-stacks and others added 5 commits August 3, 2026 15:45

Add changelog fragment

cdbf6ca

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

jbencin-stacks force-pushed the refactor/stacks-postconditions-crate branch from 856cdd7 to cdbf6ca Compare August 3, 2026 19:45

jbencin-stacks added 2 commits August 3, 2026 15:54

Fix language in changelog fragment

b5af70b

Move logging out of stacks-postconditions

e0be975

jbencin-stacks marked this pull request as ready for review August 3, 2026 20:41

brice-stacks previously approved these changes Aug 4, 2026

View reviewed changes

Comment thread changelog.d/stacks-postconditions-crate.changed Outdated

brice-stacks requested a review from benjamin-stacks August 4, 2026 20:52

jbencin-stacks mentioned this pull request Aug 4, 2026

Make simnet work more like devnet/testnet/mainnet stx-labs/clarinet#2489

Open

benjamin-stacks reviewed Aug 5, 2026

View reviewed changes

Comment thread stacks-postconditions/src/lib.rs Outdated

Comment thread stacks-postconditions/src/lib.rs Outdated

Comment thread stacks-postconditions/src/tests.rs Outdated

Comment thread stacks-postconditions/src/lib.rs

Fix typo

a92af8a

jbencin-stacks dismissed brice-stacks’s stale review via a92af8a August 6, 2026 20:12

jbencin-stacks added 3 commits August 6, 2026 16:37

Minor comment fixes

dbe9448

Add TODO comment to address PR feedback

8fa157f

Merge branch stacks/main into refactor/stacks-postconditions-crate

d6b5525

brice-stacks reviewed Aug 7, 2026

View reviewed changes

Comment thread stacks-postconditions/src/lib.rs Outdated

brice-stacks previously approved these changes Aug 7, 2026

View reviewed changes

Address PR comments

6eb60cd

jbencin-stacks dismissed brice-stacks’s stale review via 6eb60cd August 10, 2026 17:09

Remove unnecessary unit test

65c6f5b

jbencin-stacks requested review from benjamin-stacks and brice-stacks August 10, 2026 18:07

brice-stacks approved these changes Aug 11, 2026

View reviewed changes

dhaney-stacks requested review from hstove-stacks and removed request for benjamin-stacks August 13, 2026 16:27

cylewitruk-stacks mentioned this pull request Aug 13, 2026

refactor: move AssetMap from clarity into the clarity-types crate #7513

Open

Navigation Menu

Uh oh!

refactor: Extract post-conditions from `stackslib` into separate crate - #7478

refactor: Extract post-conditions from `stackslib` into separate crate#7478
jbencin-stacks wants to merge 13 commits into
stacks-network:mainfrom
jbencin-stacks:refactor/stacks-postconditions-crate

jbencin-stacks commented Jul 31, 2026

Uh oh!

brice-stacks left a comment

Uh oh!

Uh oh!

benjamin-stacks left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brice-stacks left a comment

Uh oh!

cylewitruk-stacks commented Aug 13, 2026 •

edited

Loading

Uh oh!

jbencin-stacks commented Aug 13, 2026 •

edited

Loading

Uh oh!

jbencin-stacks commented Aug 13, 2026

Uh oh!

cylewitruk-stacks commented Aug 13, 2026 •

edited

Loading

Uh oh!

jbencin-stacks commented Aug 13, 2026

Uh oh!

cylewitruk-stacks commented Aug 13, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

jbencin-stacks commented Jul 31, 2026

Description

Applicable issues

Additional info (benefits, drawbacks, caveats)

Checklist

Uh oh!

brice-stacks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

benjamin-stacks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brice-stacks left a comment

Choose a reason for hiding this comment

Uh oh!

cylewitruk-stacks commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jbencin-stacks commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jbencin-stacks commented Aug 13, 2026

Uh oh!

cylewitruk-stacks commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jbencin-stacks commented Aug 13, 2026

Uh oh!

cylewitruk-stacks commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cylewitruk-stacks commented Aug 13, 2026 •

edited

Loading

jbencin-stacks commented Aug 13, 2026 •

edited

Loading

cylewitruk-stacks commented Aug 13, 2026 •

edited

Loading

cylewitruk-stacks commented Aug 13, 2026 •

edited

Loading