Add/update block height keywords in Clarity

[obycode]

Description

Adding support for stacks-block-height and tenure-height in Clarity 3. This also includes using the tenure-height logic for block-height logic in Clarity 1 and 2.

Applicable issues

• fixes #3943

Additional info (benefits, drawbacks, caveats)

Checklist

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

[obycode]

I'm still checking on a couple of the integration tests, but @kantai, when you have some time, could you take a look at the approach here and let me know if you see anything troublesome. 🙏

[friedger]

Somehow related is the get-tenure-info https://github.com/stacks-network/stacks-core/issues/4716 Is that in scope for Clarity 3?

[obycode]

Thanks for the review @jcnelson. I've addressed the simple comments and will work on adding those tests you requested. I also added an integration test since you reviewed which was the main thing that I was not yet comfortable with.

[obycode]

Thanks for the review @kantai. Will address these comments shortly.

While adding the tests @jcnelson requested, I realized that I never implemented the analysis error when using block-height in Clarity 3. That will be included in the next commit. It's a bit weird, because the rest of the reserved words only hit an error at runtime, but this one will hit the error at analysis. In a future version of Clarity, I'd like to make all of these be detected at analysis time, but not now.

[obycode]

Ok, I added some more tests in 1bff5b7ce7828248672b74731a8855fa787b06b9. I'm not sure why test_block_heights_across_versions is failing yet. I need to resolve that and then add one more test for:

Can a Clarity 1 and Clarity 2 contract perform the above using at-block to call into the Clarity 3 contract from a block that's before epoch 3.0?

[obycode]

Can a Clarity 1 and Clarity 2 contract perform the above using at-block to call into the Clarity 3 contract from a block that's before epoch 3.0?

Is this actually possible? I don't think you can have a contract-call? inside an at-block because all contract calls are treated as not read-only and only read-only expressions can be inside an at-block.

Adding to this to clarify: ~~all contract calls to public functions are treated as not read-only, and only public functions can satisfy a trait.~~ Correcting again: all calls to trait functions are treated as not read-only, even if the contract implements the trait with a read-only function.

[obycode]

@wileyj Can we remove the "CI / Rust Format (pull_request_review)" from the required checks?

[wileyj]

@wileyj Can we remove the "CI / Rust Format (pull_request_review)" from the required checks?

it should happen as soon as this is merged: https://github.com/stacks-network/stacks-core/pull/4765

the status checks are valid for any action that triggers the workflow - it's not so fine-grained that we can disable a status check for a specific action (outside of some semi-complicated conditionals for each workflow job).

[obycode]

I pushed one small change that makes the mutants testing a bit happier. The other items it reports I think should be fixed in a more generic way, or else we'll end up with too many mutants::skip annotations throughout the code. E.g. it doesn't detect the tests using rstest macro templates as tests, and so it reports missed mutants for all of those.

[obycode]

Is there a test document somewhere that we can update so we can remember to put this PR through its paces on the Nakamoto testnet?

We probably should start a checklist like https://github.com/stacks-network/stacks-core/discussions/4620. cc @saralab