multi: hook up burn and mint events to the supply commit state machine #1675

Roasbeef · 2025-07-24T00:19:09Z

No description provided.

ffranr

Took a quick look, didn't go through every commit.

ffranr · 2025-08-06T20:19:17Z

address/book_test.go

+			// Set up mocks
+			tt.setupMocks(mockStorage)
+
+			// Call the method
+			hasDelegation, err := book.HasDelegationKey(ctx, tt.assetID)
+
+			// Check results
+			if tt.expectedError != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.expectedError)
+			} else {
+				require.NoError(t, err)
+			}
+
+			require.Equal(t, tt.expectedHas, hasDelegation)
+
+			// Verify expectations


comments can be removed here

tapgarden/planter.go

tapfreighter/chain_porter.go

guggero

Very nice! LGTM pending CI fixes.

tapfreighter/chain_porter.go

tapgarden/caretaker.go

coveralls · 2025-08-12T02:33:00Z

Pull Request Test Coverage Report for Build 17111730179

Details

450 of 523 (86.04%) changed or added relevant lines in 13 files are covered.
79 unchanged lines in 17 files lost coverage.
Overall coverage increased (+0.2%) to 56.819%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
address/book.go	29	31	93.55%
itest/assertions.go	38	40	95.0%
universe/supplycommit/transitions.go	83	85	97.65%
tapcfg/server.go	45	48	93.75%
tapdb/asset_minting.go	14	18	77.78%
tapfreighter/chain_porter.go	76	81	93.83%
universe/supplycommit/env.go	26	31	83.87%
tapdb/supply_commit.go	32	49	65.31%
tapgarden/caretaker.go	82	115	71.3%

Files with Coverage Reduction	New Missed Lines	%
tapdb/supply_commit.go	1	70.51%
universe/supplycommit/transitions.go	1	85.01%
asset/group_key.go	2	72.15%
tapdb/sqlc/transfers.sql.go	2	82.65%
tapdb/universe.go	2	81.11%
universe/syncer.go	2	82.73%
asset/mock.go	3	73.21%
tapchannel/aux_leaf_signer.go	3	43.43%
tapdb/interfaces.go	3	80.0%
authmailbox/receive_subscription.go	4	77.89%

Totals
Change from base Build 17057360543:	0.2%
Covered Lines:	61120
Relevant Lines:	107570

💛 - Coveralls

Roasbeef · 2025-08-15T01:23:03Z

Pushed a series of commits fixing some bugs:

We weren't storing the full internal key, so PSBT signing failed.
We weren't setting the taproot merkle tree in the input for the supply commit output, so signing failed again.
We weren't spending the pre-commitment outputs in the db, leading to double spends for attempts.

After all those were fixed, the itest added passes. We mint an asset, then another one in a group, then burn an asset. Along the way we check that all the commitment information has been updated along the way.

Roasbeef · 2025-08-19T02:29:08Z

Pushed up a commit to fix a rebase issue in the unit tests.

guggero · 2025-08-19T07:47:20Z

I cleaned up after the AI to fix the linter issues and added release notes to get the CI green.

guggero · 2025-08-20T06:56:56Z

I think you forgot to pull my linter fixes...

Roasbeef · 2025-08-20T18:49:44Z

Forgot to pull down those prior chagnes before applying a fixup commit.

Should be good now...

…n control This commit introduces a new DelegationKeyChecker interface that allows verification of whether we control the delegation key for a given asset. The interface is implemented by the address.Book, which checks if the local key ring contains the private key corresponding to an asset's delegation public key. The implementation queries the asset group and metadata to extract the delegation key, then attempts to locate the corresponding private key in the local keystore. This verification is essential for ensuring only authorized parties can create supply commitment proofs for assets with delegation keys.

This commit extends the MultiStateMachineManager to implement the MintCommitter and BurnSupplyCommitter interfaces. These new methods provide a type-safe way to send mint and burn events to the supply commitment state machines. The SendMintEvent method accepts universe-specific types for minting operations, while SendBurnEvent handles burn leaf submissions. Both methods internally construct the appropriate event types and delegate to the existing SendEvent infrastructure, maintaining consistency with the state machine architecture.

This commit enhances the GardenKit configuration by adding two new optional dependencies: DelegationKeyChecker and MintCommitter. These additions enable the garden subsystem to verify delegation key ownership and submit mint events to the supply commitment state machine. The GardenKit struct serves as the central configuration hub for the tapgarden package, and these new fields allow components like the BatchCaretaker to conditionally enable supply commitment functionality when the required dependencies are available.

This commit extends the ChainPorterConfig with DelegationKeyChecker and BurnSupplyCommitter dependencies to enable supply commitment tracking for asset burns. When processing burn events, the chain porter now filters assets to only submit supply commitment events for those where we control the delegation key. The sendBurnSupplyCommitEvents method uses functional filtering to pre-process the burn list, ensuring we only attempt to create supply commitments for assets we're authorized to manage. This prevents unnecessary processing and potential errors for assets where we lack delegation authority.

This commit enhances the BatchCaretaker to filter mint events based on delegation key ownership. The sendSupplyCommitEvents method now uses functional filtering to ensure supply commitment events are only sent for assets where we control the delegation key. Similar to the burn event filtering in tapfreighter, this change ensures the caretaker respects delegation authority when creating supply proofs for newly minted assets. The filtering happens early in the process to avoid unnecessary proof construction and event submission for assets we're not authorized to manage.

This commit completes the integration by wiring the address book's DelegationKeyChecker implementation to both the GardenKit and ChainPorterConfig. With this configuration, both minting and burning operations now properly verify delegation key ownership before submitting supply commitment events. The address book serves as the central authority for key ownership verification, leveraging its existing access to the key ring and asset metadata storage. This ensures consistent delegation checking across all supply commitment operations.

This commit introduces comprehensive test coverage for the delegation key filtering functionality in the BatchCaretaker. The tests verify that mint supply commitment events are only sent for assets where we control the delegation key. The test suite covers three key scenarios: all assets having delegation keys, partial delegation key ownership, and no delegation keys. Mock implementations of the MintCommitter and DelegationKeyChecker interfaces enable isolated testing of the filtering logic without requiring actual key management infrastructure.

This commit adds a unified test suite for burn supply commitment event processing in the ChainPorter. The tests verify delegation key filtering, error handling, and various burn scenarios through a table-driven approach with a helper function for cleaner test setup. The test coverage includes successful burn processing with mixed group keys, delegation key filtering scenarios, error handling for both the delegation checker and burn committer, handling of missing dependencies, and validation of invalid group key bytes. The setupChainPorterTest helper function eliminates repetitive mock configuration, making the tests more maintainable and focused on the scenarios being tested.

…mmitment

This'll be useful to fix a bug in the next commit, where we weren't actually able to effectivley look up which pre commitment was being spent by a new supply commit.

The call is idempotent so not explcitily a bug, but we have two calls to the function here. Likely was a rebase issue.

In this commit, we fix a bug where we wouldn't actually mark pre commitmetns as spent. We'll do so now, which makes sure that when we fetch the pre commits for a later batch, we aren't trying to include one that might be double spent.

This fixes a bug that would cause a spend of a supply commitment output to fail. We weren't storing the full key desc, so lnd wasn't able to sign the PSBT, as the bip32 information didn't match up (derived wrong key).

If this isn't set, then we can't do a spend, as lnd can't figure out how to sign for the PSBT input.

jtobin

I've gone over these changes in detail and think they look solid. LGTM. 👍

I'd recommend adding a brief description of the changes in the OP, for posterity. I also noted a few utterly-trivial typo-related nits I just happened to pick up on while going through the code, but they don't actually need to be fixed.

jtobin · 2025-08-27T16:08:36Z

address/book.go

+
+	assetGroup, err := b.cfg.Store.QueryAssetGroupByID(ctx, assetID)
+	if err != nil {
+		return false, fmt.Errorf("fail to find asset group given "+


nit: s/fail/failed

jtobin · 2025-08-27T16:40:25Z

address/book.go

+	}
+
+	// Now that we have the delegation key, we'll see if we know of the
+	// internal key loactor. If we do, then this means that we were the ones


nit: s/loactor/locator

jtobin · 2025-08-27T16:47:46Z

universe/supplycommit/multi_sm_manager.go

@@ -265,6 +266,30 @@ func (m *MultiStateMachineManager) SendEventSync(ctx context.Context,
 	return event.WaitForDone(ctx)
 }

+// SendMintEvent sends a mint event to the supply commitment state machine.


nit: I've observed that some interface implementations specify the interface they're implementing with a NOTE in the leading comment. Not sure if this is intended to be universal practice, but this (for example) is missing it.

jtobin · 2025-08-27T16:50:20Z

tapfreighter/chain_porter.go

@@ -49,6 +50,15 @@ type ProofImporter interface {
 		replace bool, proofs ...*proof.AnnotatedProof) error
 }

+// BurnSupplyCommitter is used by the chain porter to update the on-chain supply
+// commitment when burns new 1st party burns are confirmed.


nit: s/burns/

jtobin · 2025-08-27T18:21:44Z

Worth noting that this will also resolve #1648.

ffranr

I think we need to include setting the block height in both burn and mint events in this PR.

Here’s an example of the change needed for burn:

Subject: [PATCH] tapfreighter: set block header and height in burn proofs for commitments
---
Index: tapfreighter/chain_porter.go
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tapfreighter/chain_porter.go b/tapfreighter/chain_porter.go
--- a/tapfreighter/chain_porter.go	(revision ca914afd712ea0b6be7ae155803dce527a16084c)
+++ b/tapfreighter/chain_porter.go	(revision 6db075b18a823e12290aa6e09ca35e018ac9d14a)
@@ -815,7 +815,15 @@
 		)
 	}
 
+	anchorTxBlockHeight := int32(pkg.TransferTxConfEvent.BlockHeight)
+	anchorTxBlockHeader := pkg.TransferTxConfEvent.Block.Header
+
 	// Now we scan through the VPacket for any burns.
+	//
+	// Once the anchor transaction is confirmed, we must populate the block
+	// header and block height in the proof suffixes of all outputs. Without
+	// the block height, burn events cannot be considered valid for
+	// inclusion in supply commitments.
 	var burns []*AssetBurn
 
 	for _, v := range pkg.VirtualPackets {
@@ -841,6 +849,10 @@
 				OutPoint:   op,
 			}
 
+			// Set the block height and header in the burn proof.
+			b.Proof.BlockHeight = uint32(anchorTxBlockHeight)
+			b.Proof.BlockHeader = anchorTxBlockHeader
+
 			if o.Asset.GroupKey != nil {
 				groupKey := o.Asset.GroupKey.GroupPubKey
 				b.GroupKey = groupKey.SerializeCompressed()
@@ -862,7 +874,6 @@
 	// At this point we have the confirmation signal, so we can mark the
 	// parcel delivery as completed in the database.
 	anchorTXID := pkg.OutboundPkg.AnchorTx.TxHash()
-	anchorTxBlockHeight := int32(pkg.TransferTxConfEvent.BlockHeight)
 	err = p.cfg.ExportLog.LogAnchorTxConfirm(ctx, &AssetConfirmEvent{
 		AnchorTXID:             anchorTXID,
 		BlockHash:              *pkg.TransferTxConfEvent.BlockHash,

And here's the sort of thing I think we need for mint:

Subject: [PATCH] tapgarden+supplycommit: set mint block height in NewMintEvent
---
Index: tapgarden/caretaker.go
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tapgarden/caretaker.go b/tapgarden/caretaker.go
--- a/tapgarden/caretaker.go	(revision 6db075b18a823e12290aa6e09ca35e018ac9d14a)
+++ b/tapgarden/caretaker.go	(revision a5e97c86a59571d10d525ea7fd516be271259258)
@@ -1550,6 +1550,7 @@
 		// Finally we send all of the above to the supply commiter.
 		err = b.cfg.MintSupplyCommitter.SendMintEvent(
 			ctx, assetSpec, uniqueLeafKey, universeLeaf,
+			leafProof.BlockHeight,
 		)
 		if err != nil {
 			return fmt.Errorf("unable to send mint event for "+
Index: tapgarden/planter.go
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tapgarden/planter.go b/tapgarden/planter.go
--- a/tapgarden/planter.go	(revision 6db075b18a823e12290aa6e09ca35e018ac9d14a)
+++ b/tapgarden/planter.go	(revision a5e97c86a59571d10d525ea7fd516be271259258)
@@ -37,8 +37,8 @@
 	// SendMintEvent sends a mint event to the supply commitment state
 	// machine.
 	SendMintEvent(ctx context.Context, assetSpec asset.Specifier,
-		leafKey universe.UniqueLeafKey,
-		issuanceProof universe.Leaf) error
+		leafKey universe.UniqueLeafKey, issuanceProof universe.Leaf,
+		mintBlockHeight uint32) error
 }
 
 // GardenKit holds the set of shared fundamental interfaces all sub-systems of
Index: tapgarden/supply_commit_test.go
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tapgarden/supply_commit_test.go b/tapgarden/supply_commit_test.go
--- a/tapgarden/supply_commit_test.go	(revision 6db075b18a823e12290aa6e09ca35e018ac9d14a)
+++ b/tapgarden/supply_commit_test.go	(revision a5e97c86a59571d10d525ea7fd516be271259258)
@@ -44,9 +44,11 @@
 // SendMintEvent implements the SupplyCommitManager interface.
 func (m *MockSupplyCommitManager) SendMintEvent(ctx context.Context,
 	assetSpec asset.Specifier, leafKey universe.UniqueLeafKey,
-	issuanceProof universe.Leaf) error {
+	issuanceProof universe.Leaf, mintBlockHeight uint32) error {
 
-	args := m.Called(ctx, assetSpec, leafKey, issuanceProof)
+	args := m.Called(
+		ctx, assetSpec, leafKey, issuanceProof, mintBlockHeight,
+	)
 	return args.Error(0)
 }
 
@@ -132,7 +134,8 @@
 					mock.AnythingOfType(
 						"universe.AssetLeafKey",
 					),
-					mock.AnythingOfType("universe.Leaf")).
+					mock.AnythingOfType("universe.Leaf"),
+					mock.AnythingOfType("uint32")).
 					Return(nil).
 					Times(tc.expectedCallCount)
 			}
Index: universe/supplycommit/manager.go
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/universe/supplycommit/manager.go b/universe/supplycommit/manager.go
--- a/universe/supplycommit/manager.go	(revision 6db075b18a823e12290aa6e09ca35e018ac9d14a)
+++ b/universe/supplycommit/manager.go	(revision a5e97c86a59571d10d525ea7fd516be271259258)
@@ -266,11 +266,13 @@
 
 // SendMintEvent sends a mint event to the supply commitment state machine.
 func (m *Manager) SendMintEvent(ctx context.Context, assetSpec asset.Specifier,
-	leafKey universe.UniqueLeafKey, issuanceProof universe.Leaf) error {
+	leafKey universe.UniqueLeafKey, issuanceProof universe.Leaf,
+	mintBlockHeight uint32) error {
 
 	mintEvent := &NewMintEvent{
 		LeafKey:       leafKey,
 		IssuanceProof: issuanceProof,
+		MintHeight:    mintBlockHeight,
 	}
 
 	return m.SendEventSync(ctx, assetSpec, mintEvent)

ffranr · 2025-08-27T23:45:03Z

tapgarden/caretaker.go

+		// With the proof extracted, we can now create the universe
+		// key and leaf.
+		universeKey := universe.BaseLeafKey{
+			OutPoint:  mintedAsset.Genesis.FirstPrevOut,


I think this should be leafProof.OutPoint().

levmi assigned Roasbeef Jul 24, 2025

levmi added this to Taproot-Assets Project Board Jul 24, 2025

github-project-automation bot moved this to 🆕 New in Taproot-Assets Project Board Jul 24, 2025

levmi moved this from 🆕 New to 🏗 In progress in Taproot-Assets Project Board Jul 24, 2025

ffranr reviewed Aug 6, 2025

View reviewed changes

guggero self-requested a review August 7, 2025 14:15

Roasbeef force-pushed the state-machine-hookup branch from 58d8271 to b1b0ad7 Compare August 8, 2025 03:40

Roasbeef marked this pull request as ready for review August 8, 2025 03:40

guggero approved these changes Aug 8, 2025

View reviewed changes

tapfreighter/chain_porter.go Show resolved Hide resolved

tapfreighter/chain_porter.go Show resolved Hide resolved

tapgarden/caretaker.go Show resolved Hide resolved

Roasbeef force-pushed the state-machine-hookup branch from 236e50f to 81c687c Compare August 15, 2025 01:20

This was referenced Aug 15, 2025

docs/debug-handbook: create new debug run books for developers to help pattern match common issues and knowledge #1739

Open

universe/supplycommit: add done channel to enable sync processing of events #1729

Merged

Roasbeef force-pushed the state-machine-hookup branch from 81c687c to a1e821b Compare August 19, 2025 02:25

guggero force-pushed the state-machine-hookup branch from a1e821b to 0207a85 Compare August 19, 2025 07:47

Roasbeef mentioned this pull request Aug 20, 2025

supplyverifier: add push syncer and universe server verification #1674

Open

Roasbeef force-pushed the state-machine-hookup branch from 0207a85 to 5cb6e07 Compare August 20, 2025 02:10

Roasbeef force-pushed the state-machine-hookup branch from 5cb6e07 to eccebe8 Compare August 20, 2025 18:49

Roasbeef added 7 commits August 20, 2025 15:21

Roasbeef added 12 commits August 20, 2025 15:21

universe: add new CommitPoint() and TapscriptRoot() methods to RootCo…

09c1660

…mmitment

multi: add outpoint field to mint anchor uni commitment

adf1dc3

This'll be useful to fix a bug in the next commit, where we weren't actually able to effectivley look up which pre commitment was being spent by a new supply commit.

tapdb: set the outpoint of a pre commitment during insertion

48a3958

tapdb: remove extra call to applySupplyUpdatesInternal

553638a

The call is idempotent so not explcitily a bug, but we have two calls to the function here. Likely was a rebase issue.

tapdb: add test to ensure pre commitment spend detection works

2baebe2

tapdb: fix bug by ensuring that we write the full keydesc to disk

fecc411

This fixes a bug that would cause a spend of a supply commitment output to fail. We weren't storing the full key desc, so lnd wasn't able to sign the PSBT, as the bip32 information didn't match up (derived wrong key).

universe/supplycommit: fix PSBT bug, ensure the TaprootMerkleRoot is set

5c89755

If this isn't set, then we can't do a spend, as lnd can't figure out how to sign for the PSBT input.

universe/supplycommit: add additional logging

8841fec

itest: add supply commit mint/burn itests

34290c8

docs: add release notes

2d410bf

Roasbeef force-pushed the state-machine-hookup branch from eccebe8 to 2d410bf Compare August 20, 2025 22:21

jtobin approved these changes Aug 27, 2025

View reviewed changes

ffranr requested changes Aug 27, 2025

View reviewed changes

github-project-automation bot moved this from 🏗 In progress to 👀 In review in Taproot-Assets Project Board Aug 27, 2025

ffranr reviewed Aug 27, 2025

View reviewed changes

multi: hook up burn and mint events to the supply commit state machine #1675

Are you sure you want to change the base?

multi: hook up burn and mint events to the supply commit state machine #1675

Uh oh!

Conversation

Roasbeef commented Jul 24, 2025

Uh oh!

ffranr left a comment

Choose a reason for hiding this comment

Uh oh!

ffranr Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

guggero left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coveralls commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 17111730179

Details

💛 - Coveralls

Uh oh!

Roasbeef commented Aug 15, 2025

Uh oh!

Roasbeef commented Aug 19, 2025

Uh oh!

guggero commented Aug 19, 2025

Uh oh!

guggero commented Aug 20, 2025

Uh oh!

Roasbeef commented Aug 20, 2025

Uh oh!

jtobin left a comment

Choose a reason for hiding this comment

Uh oh!

jtobin Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

jtobin Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

jtobin Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

jtobin Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

jtobin commented Aug 27, 2025

Uh oh!

ffranr left a comment

Choose a reason for hiding this comment

Uh oh!

ffranr Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coveralls commented Aug 12, 2025 •

edited

Loading