feat: add macros for contract consensus tests

[Jiloc]

Description

This PR introduces an overhaul to the smart contract consensus testing suite, replacing manual test setups with a declarative framework. The goal is to make it significantly easier to write robust, multi-epoch, and multi-Clarity-version consensus tests.

We focus on ensuring we don't break consensus for state transitions that already happened, can happen now, or will happen in the future.

• Past Events: For consensus-breaking changes in past epochs (e.g., 2.0, 3.1):

  • If a specific scenario never actually occurred on mainnet, we don't need to test it, as it can no longer happen.
  • If a scenario did happen, Genesis Sync is the mechanism responsible for capturing the real-world historical state. Our test suite does not need to replicate it.

• Current and Future Events:

  • Contract Calls: Contracts deployed in old epochs (e.g., 2.0+) can still be called today (in 3.2+) and in the future. Therefore, the strategy here is to deploy test contracts across all epochs (2.0+) using every Clarity version that was valid at the time, but execute the function calls only from the current epoch (3.2) onwards.
  • Everything Else (Deploys without calls, Transfers, etc.): For new transactions that don't interact with historical state, we only need to test them from the current (3.2) and future epochs.

• New Macros:

  • contract_call_consensus_test!: Allows defining a full contract deployment and function call test scenario that automatically implements the strategy described above.
  • contract_deploy_consensus_test!: A specialized version for testing only the contract deployment phase, focusing on current and future epochs.

Applicable issues

• fixes AAC: Add clarity version support to the Test harness #6565 , AAC: add automatic permutations of the clarity/epoch versions for a test #6566

Additional info (benefits, drawbacks, caveats)

Checklist

• Test coverage for new or modified code paths
• Changelog is updated
• Required documentation changes (e.g., docs/rpc/openapi.yaml and rpc-endpoints.md for v2 endpoints, event-dispatcher.md for new events)
• New clarity functions have corresponding PR in clarity-benchmarking repo
• New integration test(s) added to bitcoin-tests.yml

[codecov]

Codecov Report

❌ Patch coverage is 79.29515% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.48%. Comparing base (7762d88) to head (d7cd95e).
⚠️ Report is 22 commits behind head on develop.

Files with missing lines	Patch %	Lines
stackslib/src/chainstate/tests/consensus.rs	79.29%	47 Missing ⚠️

❌ Your project status has failed because the head coverage (68.48%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

❗ There is a different number of reports uploaded between BASE (7762d88) and HEAD (d7cd95e). Click for more details.

HEAD has 51 uploads less than BASE

Flag	BASE (7762d88)	HEAD (d7cd95e)
	140	89

Additional details and impacted files

@@             Coverage Diff              @@
##           develop    #6562       +/-   ##
============================================
- Coverage    79.96%   68.48%   -11.48%     
============================================
  Files          571      571               
  Lines       351591   351613       +22     
============================================
- Hits        281135   240813    -40322     
- Misses       70456   110800    +40344     

Files with missing lines	Coverage Δ
clarity/src/vm/version.rs	76.19% <ø> (+16.66%)	⬆️
stacks-common/src/types/mod.rs	75.69% <ø> (-5.38%)	⬇️
stackslib/src/chainstate/tests/consensus.rs	84.00% <79.29%> (-14.60%)	⬇️

... and 296 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7762d88...d7cd95e. Read the comment docs.

🚀 New features to boost your workflow:

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

[jferrant]

Nice! I think this will be a great help when we start flushing out the tests.

[fdefelici]

heads-up: the are some conflicts to manage