feat: add /v3/transactions/simulate endpoint by brice-stacks · Pull Request #7424 · stacks-network/stacks-core

brice-stacks · 2026-07-20T22:46:42Z

Added a new authenticated RPC endpoint POST /v3/transactions/simulate which simulates a single transaction on top of the canonical chain tip (discarding all state changes) and reports its result, events, and execution cost.

Applicable issues

fixes Transaction simulation endpoint #7423

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

Added a new authenticated RPC endpoint `POST /v3/transactions/simulate` which simulates a single transaction on top of the canonical chain tip (discarding all state changes) and reports its result, events, and execution cost.

Copilot

Pull request overview

Adds a new authenticated RPC endpoint to simulate a single signed Stacks transaction against the canonical chain tip, returning the execution result, events, and execution cost without persisting any state.

Changes:

Implement POST /v3/transactions/simulate request/response handling and simulation logic in an ephemeral Nakamoto tenure/block context.
Register the endpoint in the RPC router and add API tests covering success + auth/nonce failures.
Document the endpoint in OpenAPI and add a changelog fragment.

Reviewed changes

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

Show a summary per file

File	Description
stackslib/src/net/api/txsimulate.rs	Implements the new `/v3/transactions/simulate` RPC handler, simulation logic, and client request/response helpers.
stackslib/src/net/api/tests/txsimulate.rs	Adds tests for request parsing, error cases, and successful simulation behavior.
stackslib/src/net/api/tests/mod.rs	Wires the new txsimulate test module into the API test suite.
stackslib/src/net/api/mod.rs	Registers the new RPC endpoint in `StacksHttp`.
docs/rpc/openapi.yaml	Documents the new endpoint contract and response shape.
changelog.d/tx-simulate-endpoint.added	Changelog entry announcing the new endpoint.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Make `from_receipt` return a `Result` and properly handle a json serialization failure.

Copilot

Pull request overview

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

francesco-stacks

Overall LGTM, just a couple of points:

the OpenAPI CI step is failing
could we also add the same memory limit mechanism we use on the miners/signers to guarantee that the transaction we are executing actually stays within the limits and would be accepted by the miners/singers?

This cost will always have a value, so no need to complicate the result with an optional.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

coveralls · 2026-07-21T17:51:48Z

Coverage Report for CI Build 31536447506

Coverage increased (+0.005%) to 86.585%

Details

Coverage increased (+0.005%) from the base build.
Patch coverage: 54 uncovered changes across 1 file (239 of 293 lines covered, 81.57%).
103 coverage regressions across 24 files.

Uncovered Changes

File	Changed	Covered	%
stackslib/src/net/api/txsimulate.rs	291	237	81.44%
Total (2 files)	293	239	81.57%

Coverage Regressions

103 previously-covered lines in 24 files lost coverage.

Top 10 Files by Coverage Loss	Lines Losing Coverage	Coverage
stackslib/src/net/p2p.rs	20	74.09%
stackslib/src/net/stackerdb/sync.rs	12	76.57%
stacks-node/src/neon_node.rs	11	83.23%
stacks-common/src/util/pipe.rs	6	89.82%
stacks-signer/src/chainstate/v2.rs	6	88.38%
stackslib/src/chainstate/nakamoto/miner.rs	5	84.22%
stackslib/src/chainstate/nakamoto/mod.rs	5	84.77%
stacks-signer/src/v0/signer_state.rs	5	92.73%
stacks-common/src/deps_common/bitcoin/network/encodable.rs	4	88.71%
stacks-signer/src/client/stacks_client.rs	4	86.76%

Coverage Stats


Relevant Lines:	233295
Covered Lines:	201999
Line Coverage:	86.59%
Coverage Strength:	19270263.63 hits per line

💛 - Coveralls

rob-stacks · 2026-07-22T10:57:09Z

I like it, given that the block simulation rpc endpoint supports running transactions in any arbitrary block in the chain, can we have the same feature here?

brice-stacks · 2026-07-23T12:52:53Z

I like it, given that the block simulation rpc endpoint supports running transactions in any arbitrary block in the chain, can we have the same feature here?

Yup, that should be simple to support the standard tip query parameter that is used everywhere else. I'll add it.

francesco-stacks

LGTM!

brice-stacks · 2026-08-07T13:36:39Z

@rob-stacks can I get a re-review on this?

federico-stacks

LGTM! just added a small check.

heads-up: CI is red and the code currently fails to compile (tested locally)

brice-stacks · 2026-08-07T16:53:01Z

Fixing the errors from upstream changes merged in now.

francesco-stacks

LGTM

Separate errors in tx simulation from errors from chainstate.

federico-stacks

LGTM!

djordon-stacks · 2026-08-13T14:23:37Z

+        the current tenure. The transaction must be fully signed and valid
+        (correct nonce, sufficient balance for the fee). The simulation


What happens if there is a transaction in the node's mempool for the same nonce, but the fee for the new transaction is too low to be considered a valid RBF?

brice-stacks requested review from francesco-stacks and rob-stacks July 20, 2026 22:46

feat: add /v3/transactions/simulate endpoint

80176de

Added a new authenticated RPC endpoint `POST /v3/transactions/simulate` which simulates a single transaction on top of the canonical chain tip (discarding all state changes) and reports its result, events, and execution cost.

brice-stacks force-pushed the feat/txsimulate branch from 890e338 to 80176de Compare July 20, 2026 22:48

francesco-stacks requested a review from Copilot July 21, 2026 08:28

Copilot started reviewing on behalf of francesco-stacks July 21, 2026 08:29 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Comment thread stackslib/src/net/api/txsimulate.rs Outdated

Comment thread docs/rpc/openapi.yaml

chore: fix OpenAPI spec and improve impl

68ca2ef

Make `from_receipt` return a `Result` and properly handle a json serialization failure.

brice-stacks requested a review from Copilot July 21, 2026 12:36

Copilot started reviewing on behalf of brice-stacks July 21, 2026 12:37 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Comment thread stackslib/src/net/api/txsimulate.rs Outdated

Comment thread docs/rpc/openapi.yaml

francesco-stacks reviewed Jul 21, 2026

View reviewed changes

Comment thread stackslib/src/net/api/txsimulate.rs Outdated

brice-stacks added 3 commits July 21, 2026 10:36

feat: add memory limit and use signer time limits

06bb2e7

fix: make ExecutionCost non-optional in result

b698e74

This cost will always have a value, so no need to complicate the result with an optional.

feat: SendError when missing transaction

9028e89

brice-stacks requested review from Copilot and francesco-stacks July 21, 2026 15:09

Copilot started reviewing on behalf of brice-stacks July 21, 2026 15:10 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Comment thread stackslib/src/net/api/tests/txsimulate.rs

Comment thread docs/rpc/openapi.yaml

Comment thread docs/rpc/openapi.yaml Outdated

brice-stacks and others added 2 commits July 21, 2026 11:20

test: improve txsimulate test

b66e064

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

fix: openapi improvements from copilot

75b0620

brice-stacks requested a review from Copilot July 21, 2026 15:32

Copilot started reviewing on behalf of brice-stacks July 21, 2026 15:32 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Comment thread stackslib/src/net/api/txsimulate.rs

fix: fix bug in copilot test suggestion

ff32547

feat: support tip query param for txsimulate

293838c

francesco-stacks previously approved these changes Jul 23, 2026

View reviewed changes

brice-stacks added 3 commits August 4, 2026 15:40

Merge branch 'main' into feat/txsimulate

800fffa

Merge branch 'main' into feat/txsimulate

bd0f058

Merge branch 'main' into feat/txsimulate

1cfad07

federico-stacks reviewed Aug 7, 2026

View reviewed changes

Comment thread stackslib/src/net/api/txsimulate.rs Outdated

brice-stacks added 2 commits August 7, 2026 12:54

fix: resolve errors from upstream changes

e43de48

fix: return error 400 for a bad tip (e.g. epoch 2.x block)

e12f2e8

brice-stacks dismissed francesco-stacks’s stale review via e12f2e8 August 7, 2026 17:24

brice-stacks requested review from federico-stacks and francesco-stacks August 7, 2026 17:24

Merge branch 'main' into feat/txsimulate

ee49639

djordon-stacks mentioned this pull request Aug 11, 2026

[Feature]: Simulate contract calls before submitting them stx-labs/spox#58

Open

1 task

francesco-stacks previously approved these changes Aug 12, 2026

View reviewed changes

refactor: add TxSimulateError

e31db15

Separate errors in tx simulation from errors from chainstate.

brice-stacks dismissed francesco-stacks’s stale review via e31db15 August 12, 2026 14:57

brice-stacks requested a review from francesco-stacks August 12, 2026 14:58

federico-stacks approved these changes Aug 12, 2026

View reviewed changes

djordon-stacks reviewed Aug 13, 2026

View reviewed changes

		the current tenure. The transaction must be fully signed and valid
		(correct nonce, sufficient balance for the fee). The simulation

Uh oh!

Conversation

brice-stacks commented Jul 20, 2026

Applicable issues

Additional info (benefits, drawbacks, caveats)

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

francesco-stacks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

coveralls commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 31536447506

Coverage increased (+0.005%) to 86.585%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

rob-stacks commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brice-stacks commented Jul 23, 2026

Uh oh!

francesco-stacks left a comment

Choose a reason for hiding this comment

Uh oh!

brice-stacks commented Aug 7, 2026

Uh oh!

federico-stacks left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

brice-stacks commented Aug 7, 2026

Uh oh!

francesco-stacks left a comment

Choose a reason for hiding this comment

Uh oh!

federico-stacks left a comment

Choose a reason for hiding this comment

Uh oh!

djordon-stacks Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

coveralls commented Jul 21, 2026 •

edited

Loading

rob-stacks commented Jul 22, 2026 •

edited

Loading

federico-stacks left a comment •

edited

Loading