Skip to content

bitcoin jets: implement Bitcoin jet cost and CMR tables; split cost padding API - #405

Open
delta1 wants to merge 9 commits into
BlockstreamResearch:masterfrom
delta1:pr/bitcoin-jets-cost-padding-cjetptr
Open

delta1 wants to merge 9 commits into
BlockstreamResearch:masterfrom
delta1:pr/bitcoin-jets-cost-padding-cjetptr

Conversation

@delta1

@delta1 delta1 commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Includes and supercedes #386 #387 #388

Implements the rest of the Bitcoin jet environment from #331: the cost() and cmr() stubs for Bitcoin jets are replaced with full tables derived from the canonical primitiveJetNode.inc in libsimplicity, covering all 428 jets in the Bitcoin jet set.

Splits Cost::get_padding into a chain-agnostic get_padding_size plus a chain-specific get_padding_bytes. While Elements uses an annex item ([0x50] + zeros), Bitcoin must pad with a plain all-zero stack item.

Also declares the FFI bindings for the env-context Bitcoin jets (with tests exercising them against a real transaction environment) and drops the now-unnecessary Arcs in environments.

Closes the remaining gaps in RedeemNode::prune(): the Rust Bit Machine can now execute Bitcoin jets against a real CTxEnv in order to rewrite dead case branches into asserts.

Draft until I figure out how to resolve this with upstream code generation for simplicity-sys/src/c_jets/c_env/bitcoin.rs

Update the vendored libsimplicity to 4e0beb5947b7e75ee7974d82a1447e89a0b4b5d6
and regenerate the jet files with update_jets.sh.

At this revision GenRustJets emits the Bitcoin jet CMRs and costs that were
previously replaced by an unimplemented!() stub, so src/jet/init/bitcoin.rs
now carries the real CMR and cost tables for all 428 Bitcoin jets, and
update_jets.lock records their hashes rather than a hand-written value.

The vendored C tree is unchanged: the only difference between the previous
revision and this one is the generator guard that suppressed Bitcoin output.
Add src/jet/bitcoin/spec_tests.rs, asserting the CMR and cost of every
Bitcoin jet against the values in libsimplicity's primitiveJetNode.inc.

Both tables are generated from that file by update_jets.sh, so these tests
detect drift between the vendored C data and the generated Rust: if the
vendored revision changes and the regenerated tables move, the tests fail
rather than silently changing consensus behaviour.
Add Cost::get_padding_size, which returns the chain-agnostic byte length
of the witness stack item required to bring a program cost within budget.
The required length depends only on the item's serialized size, not its
content, and is the same for Bitcoin and Elements.

Add Cost::get_padding_bytes, which returns the chain-specific bytes that
fill that length:
- Bitcoin (cfg bitcoin, not elements): a plain all-zero item. A leading
  0x50 byte would be misread as an annex, so Bitcoin must not use one.
- Elements (cfg elements): an annex item: [0x50] followed by zeros.

Deprecate Cost::get_padding (Elements annex form), which now delegates
to get_padding_bytes. Make get_budget and is_budget_valid chain-agnostic
by computing the witness-stack serialized length with explicit CompactSize
math instead of the elements consensus encoder.

The padding arithmetic itself is unchanged; only the surrounding API is
split. Extend the Bitcoin test with the CompactSize boundary deficits
(254, 255, 65 539, 65 540), where the length prefix grows and the smallest
covering item is one byte larger than the deficit would suggest.
Declare the FFI bindings for the Bitcoin jets whose C implementations
read the transaction environment (sig_all_hash, check_lock_*,
current_index, num_inputs, tx_hash, tap_env_hash, annex_hash, the
tapbranch/tapleaf/taptweak builders, and the remaining tx-context jets
in bitcoinJets.c). These match the rustsimplicity_0_8_bitcoin_* symbols
already generated in jets_ffi for the elements backend.

c_jet_ptr itself is unchanged: the Bitcoin backend routes every jet,
including these, through the existing jets_wrapper wrappers, which
forward the Rust CTxEnv reference to the same C symbols. The new
declarations are not separately bound in the generated jet table.

Add src/jet/bitcoin/tests.rs, which exercises the environment path
end to end against a real transaction:

- c_jet_env_is_the_tx_env checks that the JetEnvironment hands out the
  same CTxEnv the backend was built with, rather than a unit value.
- env_jets_execute_with_real_environment runs an env-context jet through
  the Rust Bit Machine and checks it observes the live environment.
- bip_0340_verify_ptr_resolves covers the one env-free crypto jet, which
  resolves through the shared wrapper.
- check_lock_height_executes_against_env executes a jet that reads the
  environment and asserts on its result.

These guard the property that RedeemNode::prune() depends on: the Rust
Bit Machine must be able to execute Bitcoin jets against a real
transaction environment in order to rewrite dead case branches into
asserts.
@delta1
delta1 force-pushed the pr/bitcoin-jets-cost-padding-cjetptr branch from a717ac1 to b4cc29f Compare November 10, 2026 10:19
@delta1
delta1 marked this pull request as ready for review November 10, 2026 10:25
@delta1

delta1 commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

Rebased to revendor libsimplicity

@stringhandler stringhandler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

utACK b4cc29f

Comment thread src/analysis.rs Outdated
/// identically: a CompactSize item count, followed by each item as a
/// CompactSize length prefix and its bytes. The math is therefore
/// chain-agnostic, and this method is available under the `bitcoin` feature
/// (which `elements` implies) so it can be shared by both.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In c0bfd57

The elements feature does currently imply bitcoin, but that might not always be the case, so I think it would be better to add elements here as well.

This is a nit though, as it will show up in compiler problems if the dependency is removed.

Comment thread CHANGELOG.md Outdated
stack item needed to bring a cost within the witness budget, and `Cost::get_padding_bytes`,
returning the chain-specific bytes that fill it (an all-zero item on Bitcoin, an annex on
Elements). Deprecate `Cost::get_padding` in favour of these.
* `Cost::get_budget` and `Cost::is_budget_valid` now take `&[Vec<u8>]` instead of `&Vec<Vec<u8>>`

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LLMs tend to add random information to the CHANGELOG. This is a private method so I'd vote to remove it. Fine to do in follow up.

@stringhandler

Copy link
Copy Markdown
Contributor

ACK b4cc29f; Ran through local tests and fuzzing

@KyrylR KyrylR left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

Superseded by the inline review: #405 (review)

@KyrylR

KyrylR commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

Ran some of my AIs on the PR

This is a pilot test, so if you think that this "batch" is bad and distributing or you would like to see it in a different way, pls let me know for the future

@KyrylR KyrylR left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

@KyrylR authorized posting this review. It was written by AI reviewers: ten independent reviews of b4cc29f, each in its own worktree. Each inline comment ends with an "Agreed by" line naming the AI reviewers that reported it independently. Opus 5.5 = Claude Opus 5.5 (×2), Mythos = Claude Mythos 5.2, Fable = Claude Fable 5.2, Astra = GPT-6 Astra (×3), Sol = GPT-6.1 Sol (×3).

The generated Bitcoin CMR and cost tables are correct; the padding API and the hand-written FFI block need changes, as described in the 9 inline comments.

Checked and correct:

  • All 428 CMRs and costs match the vendored bitcoin/primitiveJetNode.inc, with 0 mismatches across independent parsers.
  • 3f0bb69..4e0beb5 changes only GenRustJets.hs, and update_jets.sh --check passes.
  • Elements budget and padding results are identical to the old encoder-based code.
  • Tests pass for every feature combination and on MSRV 1.74; clippy -D warnings, fmt and docs are clean.

The tables commit (ffd1c22) could land on its own.

Comment thread src/analysis.rs
/// This is the Bitcoin-specific form: the padding is a single all-zero
/// witness stack item. (Bitcoin has no annex, so the padding must be a
/// regular stack item; a leading `0x50` byte would be misread as an annex.)
#[cfg(all(feature = "bitcoin", not(feature = "elements")))]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

In c0bfd57

Major: get_padding_bytes returns different bytes depending on which Cargo features are enabled.

Cost::from_milliweight(56_000).get_padding_bytes(&[]) returns [00, 00, 00, 00] with --no-default-features --features bitcoin, but [50, 00, 00, 00] with default features.

elements is a default feature, and any crate in the dependency graph can enable it, so a Bitcoin user can silently get the annex form. A build with both features cannot get the Bitcoin form at all.

Suggest two explicitly named methods, or a chain parameter, rather than selecting behaviour with cfg(not(feature = "elements")).

Agreed by: Opus 5.5 ×2, Mythos, Fable, Astra ×3, Sol ×1

Comment thread src/analysis.rs Outdated
Comment on lines +216 to +217
/// witness stack item. (Bitcoin has no annex, so the padding must be a
/// regular stack item; a leading `0x50` byte would be misread as an annex.)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

In c0bfd57

Major: the all-zero padding item produces invalid witnesses, and the premise in this doc comment is wrong.

  • Appending it breaks the witness. test_get_padding_bitcoin appends the padding item, which puts it where Taproot expects the control block. With witness [0x51 script, valid 33-byte control block] and cost 90,000 mWU, this returns [0, 0] and is_budget_valid then reports true, but ControlBlock::decode on the last item fails with InvalidControlBlockSize(2).
  • "Bitcoin has no annex" is incorrect. BIP341 defines the annex on Bitcoin, and this crate extracts it in src/jet/bitcoin/c_env.rs and has AnnexHash / CurrentAnnexHash jets.
  • The Elements advice (L232-L235) gives an invalid spend. Elements interpreter.cpp requires stack.size() == 2 after removing annex, control block and script, and otherwise fails with SCRIPT_ERR_SIMPLICITY_WRONG_LENGTH.

Suggest using annex padding on both chains, or dropping the Bitcoin variant until Bitcoin Simplicity defines a witness layout. Tests should parse the full witness rather than only check the budget.

Agreed by: Opus 5.5 ×2, Mythos, Fable, Astra ×3, Sol ×3 (Elements stack.size() == 2: Mythos, Fable)

Comment thread src/jet/bitcoin/spec_tests.rs Resolved
Comment thread src/jet/bitcoin/tests.rs Outdated
@@ -0,0 +1,135 @@
// SPDX-License-Identifier: CC0-1.0

//! Tests that the Bitcoin backend actually executes (and prunes) tx-context /

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

In b4cc29f

Minor: several tests here don't check what their names claim.

  • c_jet_env_is_the_tx_env compares a value with itself, because c_jet_env is self.c_tx_env().
  • bip_0340_verify_ptr_resolves can't fail: c_jet_ptr has an arm for every jet, so "Unwired jets still panic here" (L102) is not true.
  • TxHash, TapEnvHash and SigAllHash are only checked for output type 2^256, not their values.
  • check_lock_height uses lock time 0 with a final sequence, so a jet that ignored the environment would also pass.
  • This doc says "(and prunes)", but nothing calls prune.

Agreed by: Opus 5.5 ×2, Mythos, Fable, Astra ×3, Sol ×1

Comment thread src/analysis.rs Outdated
Comment on lines +190 to +191
// Note `deficit >= 2` here: the function returns early when the cost
// already fits, and a deficit of 0 or 1 cannot occur.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

In c0bfd57

Minor: "a deficit of 0 or 1 cannot occur" is false.

Cost::from_milliweight(51_001) on an empty witness has a deficit of 1, and get_padding_size returns Some(1). On Bitcoin an empty item already satisfies is_budget_valid. Across deficits 1..70,000, this is the only case where the size is larger than needed.

Agreed by: Opus 5.5 ×2, Mythos, Fable

Comment thread src/analysis.rs
// and 5 bytes for larger values. The overhead subtracted must account
// for the actual CompactSize encoding length of the resulting annex.
// for the actual CompactSize encoding length of the resulting item.
let deficit = (weight - budget).0 as usize; // cast safety: 32-bit machine or higher

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

In c0bfd57 (logic already on master)

Minor (already on master): the padding calculation ignores growth of the item-count prefix.

When the padding item takes the stack from 252 to 253 items (or from 65,535 to 65,536), the count's CompactSize grows by 2 bytes, and this calculation doesn't account for it. For example, 252 empty items with a 4 WU deficit returns 3 bytes when 1 is enough. It only over-pads, never under-pads.

The "padding must be minimal" test removes the whole item instead of shortening it, so it misses this.

Agreed by: Mythos, Fable, Astra ×3, Sol ×2

Comment thread CHANGELOG.md Outdated
Comment on lines +4 to +11
* Add `Cost::get_padding_size`, returning the chain-agnostic length of the padding witness
stack item needed to bring a cost within the witness budget, and `Cost::get_padding_bytes`,
returning the chain-specific bytes that fill it (an all-zero item on Bitcoin, an annex on
Elements). Deprecate `Cost::get_padding` in favour of these.
* `Cost::get_budget` and `Cost::is_budget_valid` now take `&[Vec<u8>]` instead of `&Vec<Vec<u8>>`
and compute the serialized witness length directly rather than via the Elements consensus
encoder, making them available under the `bitcoin` feature (which `elements` implies) as
well as `elements`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of @KyrylR

In c0bfd57

Minor: this entry is incomplete.

It omits the main change: Bitcoin::cmr() and Bitcoin::cost() no longer panic. It also omits the libsimplicity bump, and it lists the private get_budget as changed API.

Agreed by: Opus 5.5, Mythos, Fable

Comment thread src/analysis.rs Resolved
Review follow-up on the split padding API.

Get_padding_size over-padded in two cases, both verified against an
independent model of the budget arithmetic over deficits 1..70000:

- A deficit of 1 was assumed impossible ("deficit >= 2 here"), but it is
  reachable: Cost::from_milliweight(51_001) on an empty witness has a
  deficit of 1 and the old code returned a 1-byte item where a single
  zero byte suffices. Restore an explicit deficit <= 1 arm.

- The calculation ignored growth of the CompactSize *item-count* prefix
  when appending the padding item crosses 252 or 65535 items. Those extra
  bytes are free budget, so the required item is shorter: 252 empty items
  with a 3 WU deficit returned 2 bytes where 1 is enough. Subtract the
  prefix growth from the deficit. This bug predates the split and only
  ever over-pads, never under-pads.

Also restore saturation at the u32 boundary in get_budget: the previous
version converted before saturating, so lengths within 50 of u32::MAX
would panic rather than clamp. Only reachable with ~4 GiB witnesses.

Two doc comments were wrong:

- "Bitcoin has no annex": BIP 341 defines the annex on Bitcoin and this
  crate extracts it (jet/bitcoin/c_env.rs) and has AnnexHash and
  CurrentAnnexHash jets. Say instead that a 0x50-leading item would be
  read as the annex rather than as padding. The stronger claim that an
  all-zero item is invalid does not hold, because Bitcoin Simplicity has
  no witness layout yet; document that the caller owns placement.

- The Elements advice to build an all-zero item for non-Liquid Elements
  describes an invalid spend: Elements requires stack.size() == 2 after
  removing the annex, control block and script, so padding must be an
  annex. Drop the advice.

Strengthen both padding tests: assert the padding item is minimal by
shortening it rather than removing it (removal hid the prefix-growth
bug), and add the deficit-1 and 252-item cases.
The 8 extern declarations and their 8 wrappers duplicate what the
jet generator already emits: each declaration repeats the same
#[link_name] in jets_ffi.rs, and each wrapper duplicates a
jets_wrapper::bitcoin_* function, which is what c_jet_ptr actually
routes Bitcoin jets through. Nothing referenced them.

They also diverge from the generated declarations on the ABI: they take
`frameItem src` by value where the generated ones take
`*const CFrameItem`, the form the WRAP_ macro uses so the signature is
valid on wasm32. Keeping both invites the by-value version being wired
up later.

Delete the declarations, the wrappers and the macro, and the two stale
"will uncomment in a later commit" comments. This also settles the
code-generation question in the pull request description: the Bitcoin
env jets are covered by the generator, so there is nothing to reconcile.
The previous spec_tests.rs copied the generated CMR and cost tables back
into the test source. That compares the generator against itself and
never reads the vendored C, so it cannot catch drift between
primitiveJetNode.inc and the generated Rust, which is the thing worth
checking. It also has to be regenerated by hand whenever a cost changes.

Replace the 4065-line copy with a parser over the vendored .inc that,
for every jet in Bitcoin::ALL, looks up the entry by the C symbol the
generated c_jet_ptr dispatches to and compares both the CMR (eight
big-endian u32 words) and the cost. This fails if the .inc moves under a
stale table. It also stops the test from passing vacuously: an assertion
that cannot find its entry now fails instead of being skipped.
Five of the tests did not check what their names claimed:

- c_jet_env_is_the_tx_env compared a value with itself, because
  c_jet_env() is implemented as self.c_tx_env(). Replace it with a
  behavioural check: num_inputs and current_index must observe the
  transaction the environment was built from.

- bip_0340_verify_ptr_resolves could not fail, since c_jet_ptr has an
  arm for every jet. Rename it to say what it does and drop the claim
  that it detects unwired jets.

- TxHash, TapEnvHash and SigAllHash were only checked for output type
  2^256. Assert what they commit to instead: TxHash is stable for one
  environment and changes with the transaction; SigAllHash depends on
  lock time and input index; TapEnvHash depends only on the control
  block and script CMR, so it must not react to either. Note that
  TxHash is not the txid: the C returns a Simplicity commitment over
  version, locktime, inputsHash, outputsHash and inputUTXOsHash.

- check_lock_height used lock time 0 with a final sequence, so lock-time
  checking was disabled and every height failed. Use a non-final
  sequence and a non-zero lock time, and keep the assertion that is
  load-bearing: a height below the transaction's must succeed, which a
  jet ignoring the environment would reject. Add a final-sequence case
  to pin the disabled behaviour.

- The module comment claimed the tests prune, which none of them do.
The entry omitted the main change on this branch: Bitcoin::cmr() and
Bitcoin::cost() no longer panic and now return the generated tables. It
also omitted the libsimplicity bump, and listed get_budget as changed
public API when it is private.

Reorganise it around what a reader has to know: the Bitcoin tables
replacing the stubs, the padding API split, and the FFI declarations
for the Bitcoin tx-context jets.
@delta1

delta1 commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

Pushed some updates for the review comments, feel free to pick this up @KyrylR thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants