Skip to content

[clone of lightninglabs/taproot-assets#2331] supplyverifier: verify burn leaves against their input's provenance - #12

Draft
SadiqJaf wants to merge 5 commits into
satscrip/supplycommit-anchor-fixfrom
satscrip/supplycommit-burn-provenance
Draft

SadiqJaf wants to merge 5 commits into
satscrip/supplycommit-anchor-fixfrom
satscrip/supplycommit-burn-provenance

Conversation

@SadiqJaf

@SadiqJaf SadiqJaf commented Oct 10, 2026 •

Copy link
Copy Markdown

(Fixes lightninglabs#2285. Opus's summary follows.)

A burn leaf's proof is a bare state transition: it records what was burned, but carries no provenance for the input it consumes. The supply verifier treated it as self-contained, like a genesis proof, so it found no inputs and rejected every supply commitment carrying a burn. Any group that burned stopped publishing supply commitments.

The leaf itself is unchanged, as committed leaves are already on-chain. Instead, the provenance it lacks is supplied from where the protocol already keeps provenance: the universe.

  • Verification. A burn leaf is verified as the last proof of its full proof file, built from its input's provenance. A universe server takes that provenance from its own universe; a node syncing supply commitments fetches it from the servers it pulls from.
  • Publication. Before pushing a commitment that carries burns, the issuer inserts each burn's input provenance into the target server's universe, the same way a universe courier delivers a proof file. The universe must allow proofs to be inserted, so this is best effort only.
  • Cost. Walking provenance is expensive, so a commitment is now checked against its predecessor before its leaves are verified, and the provenance walk is bounded in length and by context.

The burn-leaf unit fixture embedded the input's proof file in AdditionalInputs, which the porter never does; it now matches production. The supply itests now assert that the universe server and a syncing peer both accept a burn commitment, including one burning an output the server had never seen.

Adaptations for v0.8.5

This is a clone of lightninglabs#2331 (db051d2a), stacked on satscrip/supplycommit-anchor-fix (#11) rather than on upstream main. The three code commits are cherry-picks, not a squash. Author, email, and author date are Jared Tobin's. This environment cannot GPG-sign, so the commits are unsigned. Nothing here is filed against lightninglabs/taproot-assets. Head is a307dc0d, rebased onto #11 ac101ed0.

Upstream This branch Notes
09a9c73a proof: bound the provenance walk 56dd4550 Applied cleanly aside from an auto-merge in proof/courier.go. Author Jared Tobin.
22712aa9 multi: verify burn leaves against their input's provenance 1df0f96b Applied with the conflict resolutions below. Author Jared Tobin.
715f4aad itest: assert burn commitments reach universe servers and peers 2fd243da Applied cleanly aside from an auto-merge in itest/supply_commit_test.go. Author Jared Tobin.
db051d2a docs: add release note not cherry-picked See release notes below. Follow-up 52313637.
— a307dc0d v0.8.5 follow-up. Not part of the upstream series.

The SHAs above are the commits after the rebase onto ac101ed0. The previous SHAs (853b752e, c8de3107, 49ef882c, fa4971c7, 71259960) were the same trees before that rebase.

Conflict resolutions inside 1df0f96b (required for the commit to compile on v0.8.5; no separate behavior change):

  • universe/supplyverifier/manager.go, verifier_test.go, and verifier_methods_test.go conflicted in the import block. v0.8.5 still uses tapgarden.ChainBridge and tapgarden.NewMockChainBridge. The tapnode and tapnode/tapnodemock packages do not exist on v0.8.5. The resolution keeps the tapgarden imports, adds the new proof imports, and replaces tapnodemock.NewChainBridge() with tapgarden.NewMockChainBridge().
  • universe/supplyverifier/syncer_test.go does not exist on v0.8.5. Upstream adds TestPushSupplyCommitmentPublishesBurnProvenance and TestProvenanceAcrossServers to that file, and the copy on main imports github.com/btcsuite/btcd/wire/v2. Those two unit tests are not in this port. The itest that a universe server and a syncing peer accept a burn commitment is included (2fd243da).

Release notes:

  • db051d2a appends a paragraph to docs/release-notes/release-notes-0.9.0.md. That file is not on v0.8.5, and taking the commit's version of the file would have copied the rest of the unreleased 0.9 notes. The commit is omitted. 52313637 records the same paragraph in docs/release-notes/release-notes-0.8.5.md.

Burn merkle proof (a307dc0d):

  • On v0.8.5, storeProofs fills TxMerkleProof on a decoded copy of the proof suffix. storePackageAnchorTxConf then sends the burn supply-commit event from the virtual-packet suffix, which has the confirmation header and height but not that merkle proof. The cloned verifier checks the burn leaf with proof.DefaultMerkleVerifier, so the universe server rejected the insert: burn leaf proof failed verification: invalid transaction merkle proof. Upstream main rebuilds the burn proof from the buried anchoring witness, which already carries the merkle proof. v0.8.5 records the event at first confirmation, so this follow-up calls UpdateTransitionProof on the burn proof before the event is sent.

Verification

Order matters. lightninglabs#2331 does not change upsertAssetGen. On this tree with only that write guard reverted, TestTransferProofKeepsCustomGenesisPreCommit fails (expected anchor chain txn id 1, actual 2). Migration 61 has already run and does not stop the later upsert. The send-before-commit itest on that same unguarded daemon stops in UpdateAndMineSupplyCommit with unable to find txns in mempool: wanted 1, found 0. With the guard, the same itest passes.

make unit three times on a307dc0d, each with -test.count=1 (nocache=1). No package failed, so nothing was classified against stock bb3f1c6b.

Run Result
1 PASS (exit 0)
2 PASS (exit 0)
3 PASS (exit 0)

make itest-parallel tranches=4 on this head, btcd backend. The makefile default is 8 processes. This host has 4 CPUs and 15GiB, so the run used the makefile tranches knob at 4. That still partitions and runs the whole registered list: tranche 0 tested 30 cases, tranche 1 tested 29, tranche 2 tested 29, tranche 3 tested 29 (117 cases, the same count the harness reports for the full list). Each tranche printed PASS. The make target exited 0. No case failed, so nothing was classified against bb3f1c6b.

The anchor-fix layer alone (ac101ed0) ran the supply and universe subset; see #11. That layer does not assert burn-leaf acceptance.

Commits are unsigned (--no-gpg-sign). Signed-off-by: Cursor Agent <cursoragent@cursor.com> on the follow-ups. Jared Tobin's cherry-picks keep his author and are unsigned in this clone.

Open in Web Open in Cursor 

@cursor
cursor Bot force-pushed the satscrip/supplycommit-burn-provenance branch 2 times, most recently from 042dbf9 to 7125996 Compare October 10, 2026 11:29
jtobin and others added 5 commits October 10, 2026 12:02
FetchProofProvenance follows each fetched proof's primary input back
until it reaches a genesis proof. Nothing but the proof source
guarantees it gets there: a source that serves a chain looping back
on itself, or one that never ends, keeps the walk going indefinitely,
and a cached source never consults the context.

Check the context on every step, and stop once the chain would be
longer than any proof file may hold.
A burn leaf's proof is the burn output's bare proof suffix: a state
transition with no provenance for the input it consumes. The supply
verifier checked it with no prior snapshot, so the transition had no
inputs, and every supply commitment carrying a burn was rejected with
"missing asset input(s)".

Verify the burn proof instead as the last proof of its full proof
file, assembled from the provenance of the burn's primary input. A
universe server takes that provenance from its own universe. A node
syncing supply commitments takes it from the universe servers it
pulls commitments from, walking their single proofs back to genesis.
The leaf's own claims, its asset ID, burn key and group, are
checked first, as they need no provenance.

Fetching and verifying that provenance is costly, so VerifyCommit now
checks that a commitment spends the issuer's pre-commitment outputs
or its previous commitment, and that its root matches its leaves,
before verifying the leaves themselves. A pushed commitment can then
only cause that work for leaves an issuer committed to.

The input is often unknown to the server: the change output of an
earlier transfer, or a coin that never passed through the server's
universe. So before pushing a commitment that carries burns, the
issuer inserts each burn's input provenance into the target server's
universe, one proof at a time, as a universe courier delivers a proof
file. The provenance is the burn output's local proof file without
its last proof, which is the burn itself and travels in the
commitment. The server absorbs proofs it already holds, so a retried
push republishes harmlessly.

The burn leaf test fixture embedded the input's proof file in the
burn proof's AdditionalInputs, which the chain porter never does. It
now returns the bare transition and its input's file separately.

Co-authored-by: Sadiq Jaffer <SadiqJaf@users.noreply.github.com>
The supply commitment itests asserted burn leaves on the issuing node
only, so a commitment that every universe server rejected went
unnoticed.

supply_commit_mint_burn now also fetches the commitment carrying the
burn from the universe server. supply_verify_peer_node burns part of
the issuer's change from its earlier transfer, an output whose
provenance never passed through the universe server, and asserts that
both the universe server and the syncing peer hold the resulting
commitment.
Upstream added this paragraph to release-notes-0.9.0.md, which is
not on v0.8.5. The same note is recorded here.

Signed-off-by: Cursor Agent <cursoragent@cursor.com>

Co-authored-by: Sadiq Jaffer <SadiqJaf@users.noreply.github.com>
storeProofs fills the transaction merkle proof on a decoded copy
of the proof suffix. The burn event kept the virtual-packet
suffix, which had the confirmation header but not that merkle
proof. Universe servers then rejected the burn leaf with
"invalid transaction merkle proof".

Copy the confirmation, including the merkle proof, onto the
burn proof before the supply-commit event is sent. Upstream
main rebuilds this proof from the buried anchoring witness;
v0.8.5 records the event at first confirmation.

Signed-off-by: Cursor Agent <cursoragent@cursor.com>

Co-authored-by: Sadiq Jaffer <SadiqJaf@users.noreply.github.com>
@cursor
cursor Bot force-pushed the satscrip/supplycommit-burn-provenance branch from 7125996 to a307dc0 Compare October 10, 2026 12:03
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