Adds bitcoin clarity builtins

[brice-stacks]

Built on top of #7173. Adds new get-bitcoin-tx-output? and verify-merkle-proof Clarity builtins.

[coveralls]

Coverage Report for CI Build 25279731464

Warning

No base build found for commit 8096edd on pox-wf-integration.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 62.459%

Details

• Patch coverage: 527 uncovered changes across 16 files (399 of 926 lines covered, 43.09%).

Uncovered Changes

Top 10 Files by Coverage Impact	Changed	Covered	%
clarity/src/vm/functions/bitcoin.rs	307	98	31.92%
clarity/src/vm/costs/costs_5.rs	438	249	56.85%
clarity/src/vm/analysis/type_checker/v2_1/natives/mod.rs	72	0	0.0%
clarity/src/vm/functions/mod.rs	8	0	0.0%
clarity/src/vm/analysis/errors.rs	7	0	0.0%
clarity/src/vm/costs/costs_1.rs	6	0	0.0%
clarity/src/vm/costs/costs_2.rs	6	0	0.0%
clarity/src/vm/costs/costs_2_testnet.rs	6	0	0.0%
clarity/src/vm/costs/costs_3.rs	6	0	0.0%
clarity/src/vm/costs/costs_4.rs	6	0	0.0%

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	218016
Covered Lines:	136171
Line Coverage:	62.46%
Coverage Strength:	14040461.82 hits per line

---

💛 - Coveralls

[brice-stacks]

With this change, we can basically revert #7168, but let's do that in a separate PR.

[brice-stacks]

@rob-stacks has volunteered to do the benchmarking to fill in real values for the new cost functions. That can happen in a separate PR built off of this one, so this one is ready for review.

[brice-stacks]

With this new design, we can remove the p2wsh output DBs and related work from PR #7168. I'll do that in a separate PR as well.

[hstove-stacks]

@brice-stacks can you share how you've found test fixtures and/or real data for the merkle proof validation stuff? Ie how to get the arguments you need for a given txid/block?

[brice-stacks]

@brice-stacks can you share how you've found test fixtures and/or real data for the merkle proof validation stuff? Ie how to get the arguments you need for a given txid/block?

The real data just came from real bitcoin transactions (genesis, pizza tx, BIP141 SegWit announcement). I also generated some merkle proofs for the merkle_ unit tests. An LLM notified me about the CVE-2012-2459 issue.

EDIT: just realized maybe that's not what you were asking. I got the transactions from public APIs:

curl https://mempool.space/api/tx/a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d/hex > pizza.hex

curl https://blockstream.info/api/tx/a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d/merkle-proof

[rob-stacks]

Benchmark results are here: #7179 (comment)

Based on the last iteration (done for secp256r1-verify):

verify-merkle-proof depends on the number of siblings: base cost: 502, cost for each sibling: 125
get-bitcoin-tx-output? is not dependent on the size of the transaction (obviously it will impact the read count): 291

[brice-stacks]

@hstove-stacks check out 58b86c0, I added tests for those same 3 transactions and clear comments about where the values come from.

[brice-stacks]

Thanks @rob-stacks! Added in b871e0c.

[brice-stacks]

@rob-stacks I was just looking at this again. Shouldn't at least tx.txid() be linear in the size of the transaction?

[rob-stacks]

@brice-stacks it should, but the size limit of 1024 bytes for the transaction body makes the difference mostly irrelevant at the cpu side (and we are already charging for the size of the transaction in terms of read)

[brice-stacks]

@brice-stacks it should, but the size limit of 1024 bytes for the transaction body makes the difference mostly irrelevant at the cpu side (and we are already charging for the size of the transaction in terms of read)

The 1024 byte-limit is just for the requested output. The total size of the tx body is only limited by the Clarity value size limit, so 1MB. Did the benchmark include transactions that are ~1 MB?

[rob-stacks]

Damn, my bad I just noticed that the argument limit is BUFFER_MAX and not BUFFER_1024. I will send you the updated numbers asap

[rob-stacks]

@brice-stacks ok, the load almost linearly scales every 1K, I would suggest 125 units every 1024 bytes of transaction.

[brice-stacks]

@brice-stacks ok, the load almost linearly scales every 1K, I would suggest 125 units every 1024 bytes of transaction.

Got it, thanks Roberto. I'll make that change.

[rob-stacks]

@brice-stacks LGTM but do you think you can add a prop-test scrambling outputs and their numbers/amounts ?

[brice-stacks]

Added proptests in ea51c49

[aaronb-stacks]

Just had a few comments, otherwise looks good to me.