universe/supplycommit: create new state machine responsible for maintaining the supply commitment for an asset #1464

Roasbeef · 2025-04-09T06:16:34Z

In this commit, we add a new sub-package to the universe package which adds a new state machine responsible for managing the supply commitment for a given grouped asset.

A supply commitment is a special MS-SMT tree that tracks the total supply of a grouped asset. A supply can be modified by: minting new assets, doing an official burn of some assets, or adding some assets to the ignore proof cache.

To create a supply commitment (for an asset that opts into this), we'll spend the pre-commitment from all past minting batches that have been confirmed on chain. We'll then stage all the pending updates, to create new sub-trees (ignore, burn mint) for the grouped asset. With those trees created, we'll create the new root supply commitment.

With the root supply commitment created, we'll make a new transaction and commit to that using the non spendable script leaf that we use elsewhere to commit to asset IDs for a group key.

During this process, we'll continue to serve the old supply commitments. Only once the supply commitments have been confirmed on disk will we apply all the state transitions on disk. After we apply these state transitions, we'll start to serve the new commitments, and go back to our default state.

See the last commit's readme for more details.

Roasbeef · 2025-05-03T02:19:07Z

Removed from draft for now. Have unit tests, and additional documentation to commit.

coveralls · 2025-05-05T23:23:15Z

Pull Request Test Coverage Report for Build 15790016249

Details

782 of 1029 (76.0%) changed or added relevant lines in 7 files are covered.
12 unchanged lines in 5 files lost coverage.
Overall coverage increased (+0.6%) to 38.399%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
universe/supplycommit/states.go	135	139	97.12%
universe/interface.go	0	5	0.0%
universe/supplycommit/env.go	70	77	90.91%
universe/ignore_records.go	0	11	0.0%
universe/supplycommit/transitions.go	463	569	81.37%
universe/supplycommit/mock.go	113	227	49.78%

Files with Coverage Reduction	New Missed Lines	%
address/address.go	2	69.55%
asset/group_key.go	2	62.64%
tapchannel/aux_leaf_signer.go	2	43.08%
tapgarden/planter.go	2	60.82%
tapgarden/caretaker.go	4	68.19%

Totals
Change from base Build 15781486062:	0.6%
Covered Lines:	28972
Relevant Lines:	75450

💛 - Coveralls

ffranr

I reviewed this PR to see how I might copy its state‑machine architecture for the verification work.

I saw your note about still adding unit tests and doc comments, so I'm leaving these review comments with that in mind and hoping they're helpful.

ffranr · 2025-05-08T15:40:35Z

go.mod

+
+replace github.com/lightningnetwork/lnd => github.com/roasbeef/lnd v0.2.1-alpha.0.20250505223159-b58451faad16


Just a small reminder: this will need to be removed before merge. Maybe it can be removed now?

I see that this is used for the state transition scaffolding. Is there an LND PR for this that I could help (review) get merged?

The lnd PRs are here:

protofsm: add option to allow conf resp to return full block lightningnetwork/lnd#9726

protofsm: add ConfMapper to allow conf attribute projection for new events lightningnetwork/lnd#9725

Can be bumped to lnd v0.19.1-beta.rc1.

I don't think these made it into the minor release, but they are in master.

universe/supplycommit/supply_commit_states.go

universe/supplycommit/README.md

guggero

Looks great!

guggero · 2025-06-06T09:46:44Z

go.mod

+
+replace github.com/lightningnetwork/lnd => github.com/roasbeef/lnd v0.2.1-alpha.0.20250505223159-b58451faad16


Can be bumped to lnd v0.19.1-beta.rc1.

universe/supplycommit/env.go

universe/supplycommit/supply_commit_transitions.go

universe/supplycommit/README.md

Roasbeef · 2025-06-07T02:15:06Z

FWIW this won't build due to the replace until we fix the tags in lnd.

lightninglabs-deploy · 2025-06-16T01:04:05Z

@Roasbeef, remember to re-request review from reviewers when ready

ffranr · 2025-06-18T13:44:13Z

This patch fixes the lint and unit-race CI errors:

Index: universe/supplycommit/supply_commit_test.go
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/universe/supplycommit/supply_commit_test.go b/universe/supplycommit/supply_commit_test.go
--- a/universe/supplycommit/supply_commit_test.go	(revision bab9a94047f48e54580beaf6d7e1fbf94ed5efc2)
+++ b/universe/supplycommit/supply_commit_test.go	(date 1750254593179)
@@ -292,7 +292,7 @@
 	h.sendEvent(event)
 	h.assertNoStateTransitions()
 
-	require.ErrorIs(h.t, h.mockErrReporter.reportedError, expectedErr)
+	require.ErrorIs(h.t, h.mockErrReporter.GetReportedError(), expectedErr)
 }
 
 // assertAndGetCurrentState fetches the current state from the state machine,
@@ -635,7 +635,7 @@
 		h.assertNoStateTransitions()
 
 		require.ErrorIs(
-			t, h.mockErrReporter.reportedError,
+			t, h.mockErrReporter.GetReportedError(),
 			ErrInvalidStateTransition,
 		)
 	})
@@ -938,7 +938,9 @@
 		h.start()
 		defer h.stopAndAssert()
 
-		h.assertHandlesInvalidEvent(&unknownEvent{}, ErrInvalidStateTransition)
+		h.assertHandlesInvalidEvent(
+			&unknownEvent{}, ErrInvalidStateTransition,
+		)
 	})
 }
 
@@ -988,7 +990,9 @@
 		h.start()
 		defer h.stopAndAssert()
 
-		h.assertHandlesInvalidEvent(&unknownEvent{}, ErrInvalidStateTransition)
+		h.assertHandlesInvalidEvent(
+			&unknownEvent{}, ErrInvalidStateTransition,
+		)
 	})
 }
 
Index: universe/supplycommit/mock.go
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/universe/supplycommit/mock.go b/universe/supplycommit/mock.go
--- a/universe/supplycommit/mock.go	(revision bab9a94047f48e54580beaf6d7e1fbf94ed5efc2)
+++ b/universe/supplycommit/mock.go	(date 1750254094424)
@@ -2,6 +2,7 @@
 
 import (
 	"context"
+	"sync"
 
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/btcutil"
@@ -373,9 +374,18 @@
 type mockErrorReporter struct {
 	mock.Mock
 	reportedError error
+	mu            sync.Mutex
 }
 
 func (m *mockErrorReporter) ReportError(err error) {
-	m.Called(err)
+	m.mu.Lock()
+	defer m.mu.Unlock()
 	m.reportedError = err
+	m.Called(err)
+}
+
+func (m *mockErrorReporter) GetReportedError() error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.reportedError
 }

universe/supplycommit/supply_commit_states.go

ffranr · 2025-06-18T16:16:06Z

universe/supplycommit/supply_commit_states.go

@@ -0,0 +1,553 @@
+package supplycommit


files in supplycommit directory start with supply_commit_. That prefix is probably redundant?

universe/supplycommit/supply_commit_states.go

universe/supplycommit/supply_commit_test.go

universe/supplycommit/supply_commit_transitions.go

In this commit, we add an IsBurn bool to the Leaf struct. This is needed as we'll re-use this Leaf field for the burn proofs. However, for burns we always want to track the actual amt burned.

This version has updates to `protofsm` that we'll be using in the state machine.

This makes the generator more consistent and useful.

guggero

Very cool, really like the way the new state machine approach works with the different event types!

guggero · 2025-06-19T13:06:01Z

go.mod

 	github.com/lightninglabs/neutrino/cache v1.1.2
 	github.com/lightninglabs/taproot-assets/taprpc v1.0.7
-	github.com/lightningnetwork/lnd v0.19.0-beta
+	github.com/lightningnetwork/lnd v0.19.0-beta.rc5.0.20250611041824-9e9524766c8a


nit: can use v0.19.1-beta now.

#1464 (comment)

Ah, damn, I thought I added them. But then we have to move them to the 0.19.2 milestone to include them there, otherwise we'll have a problem in litd.

guggero · 2025-06-19T13:06:31Z

universe/interface.go

 	// Amt is the amount of units associated with the coin.
 	Amt uint64
+
+	// IsBurn is a boolean that indicates whether the leaf represents a burn


Is the [temp] commit message suffix still needed?

I don't think so, but I consider this a sort of hack. Basically we need this to use the full value of the burnt amount instead of just 1 (as we do for transfers).

It think an alternative here is either to make a new wrapper struct, or modify this logic, but still only conditionally (we still insert just 1 for the multiverse transfer tree.

guggero · 2025-06-19T13:06:57Z

universe/supplycommit/supply_commit_states.go

@@ -0,0 +1,553 @@
+package supplycommit


universe/supplycommit/supply_commit_transitions.go

universe/supplycommit/env.go

…achine In this commit, we add the initial set of states for the SupplyCommit state machine. This will be the primary state machine that'll be used to stage, then apply updates to the root supply tree as well as the sub supply trees associated with the root tree.

In this commit, we populate the environment that the state machine will use. This includes the set of fundamental interfaces (related to persistence and the new supply trees).

…state machine In this commit, we build on the two prior commits and add defined state transitions for the supply commit state machine. We start in a default state, until we hear about a new update. We'll continue in that state untli we get a commit tick, at which point we'll enter the main logic of the state machine. After a tick, we'll construct the final tree, make a commit transaction from that, sign it, then write everything to disk. We'll then resume by broadcasting the commit tx. Once we reecive a confirmation, we'll apply the state tranition which will update all the relevant state on disk.

These were from a much earlier draft, well before the current design of the commit state machine.

levmi assigned Roasbeef Apr 10, 2025

levmi added this to Taproot-Assets Project Board Apr 10, 2025

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

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

Roasbeef mentioned this pull request Apr 12, 2025

mssmt: add new Copy method and InsertMany to optimize slightly #1467

Merged

Roasbeef force-pushed the asset-commitment-creator branch 2 times, most recently from 90b04f6 to aaeddf4 Compare May 3, 2025 02:18

Roasbeef changed the base branch from burn-tree to main May 3, 2025 02:18

Roasbeef marked this pull request as ready for review May 3, 2025 02:18

Roasbeef changed the title ~~Asset commitment creator~~ universe/supplycommit: create new state machine responsible for maintaining the supply commitment for an aseset May 3, 2025

Roasbeef changed the title ~~universe/supplycommit: create new state machine responsible for maintaining the supply commitment for an aseset~~ universe/supplycommit: create new state machine responsible for maintaining the supply commitment for an asset May 3, 2025

This was referenced May 3, 2025

tapdb: add implementation of supplycommit.SupplyTreeView #1507

Merged

tapdb: add implementation of supplycommit.CommitmentTracker and supplycommit.StateMachineStore #1508

Merged

Roasbeef force-pushed the asset-commitment-creator branch 2 times, most recently from 8d5041c to 648cb72 Compare May 5, 2025 23:02

levmi moved this from 🏗 In progress to 👀 In review in Taproot-Assets Project Board May 8, 2025

ffranr reviewed May 8, 2025

View reviewed changes

guggero self-requested a review May 28, 2025 06:57

guggero reviewed Jun 6, 2025

View reviewed changes

Roasbeef force-pushed the asset-commitment-creator branch 2 times, most recently from b65aade to a0cdbd9 Compare June 7, 2025 02:12

Roasbeef force-pushed the asset-commitment-creator branch from a0cdbd9 to 414823f Compare June 12, 2025 01:35

Roasbeef added enhancement New feature or request supply commit Work on the supply commitment feature, enabling issuers to attest to total asset supply on-chain. labels Jun 18, 2025

Roasbeef force-pushed the asset-commitment-creator branch 2 times, most recently from 6c86168 to bab9a94 Compare June 18, 2025 02:06

ffranr reviewed Jun 18, 2025

View reviewed changes

ffranr requested a review from guggero June 18, 2025 16:29

Roasbeef force-pushed the asset-commitment-creator branch from bab9a94 to 83e4172 Compare June 18, 2025 23:02

Roasbeef added 4 commits June 18, 2025 16:20

universe: add IsBurn bool to Leaf [temp]

0db18c4

In this commit, we add an IsBurn bool to the Leaf struct. This is needed as we'll re-use this Leaf field for the burn proofs. However, for burns we always want to track the actual amt burned.

universe: allow SignedIgnoreTuple to satisfy the UniverseKey interface

d35ee49

build: point to latest version of lnd

68673f6

This version has updates to `protofsm` that we'll be using in the state machine.

asset: modify ScriptKeyGen to always populate the internal pubkey

c2bfa76

This makes the generator more consistent and useful.

Roasbeef force-pushed the asset-commitment-creator branch from 83e4172 to b5acb6f Compare June 18, 2025 23:25

Roasbeef requested a review from ffranr June 18, 2025 23:33

Roasbeef force-pushed the asset-commitment-creator branch from b5acb6f to 035e250 Compare June 18, 2025 23:51

guggero approved these changes Jun 19, 2025

View reviewed changes

levmi added the P0 label Jun 19, 2025

ffranr approved these changes Jun 20, 2025

View reviewed changes

universe/supplycommit/env.go Show resolved Hide resolved

Roasbeef force-pushed the asset-commitment-creator branch 2 times, most recently from 31a5fc6 to 03eb6b0 Compare June 21, 2025 00:09

Roasbeef added 5 commits June 20, 2025 17:11

universe/supplycommit: add definitions of fundamental interfaces

2d184ac

In this commit, we populate the environment that the state machine will use. This includes the set of fundamental interfaces (related to persistence and the new supply trees).

universe: get rid of obsolete types and interfaces

6b5c36e

These were from a much earlier draft, well before the current design of the commit state machine.

universe/supplycommit: add README.md

53cd06a

Roasbeef force-pushed the asset-commitment-creator branch from 03eb6b0 to 70c7f3b Compare June 21, 2025 00:12

universe/supplycommit: add unit tests

82f4ee3

Roasbeef force-pushed the asset-commitment-creator branch from 70c7f3b to 82f4ee3 Compare June 21, 2025 00:20

Roasbeef merged commit 2f518d2 into lightninglabs:main Jun 21, 2025
17 of 18 checks passed

github-project-automation bot moved this from 👀 In review to ✅ Done in Taproot-Assets Project Board Jun 21, 2025


		replace github.com/lightningnetwork/lnd => github.com/roasbeef/lnd v0.2.1-alpha.0.20250505223159-b58451faad16

universe/supplycommit: create new state machine responsible for maintaining the supply commitment for an asset #1464

universe/supplycommit: create new state machine responsible for maintaining the supply commitment for an asset #1464

Uh oh!

Conversation

Roasbeef commented Apr 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Roasbeef commented May 3, 2025

Uh oh!

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

Uh oh!

Pull Request Test Coverage Report for Build 15790016249

Details

💛 - Coveralls

Uh oh!

ffranr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

guggero left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Roasbeef commented Jun 7, 2025

Uh oh!

lightninglabs-deploy commented Jun 16, 2025

Uh oh!

ffranr commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

guggero left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Roasbeef commented Apr 9, 2025 •

edited

Loading

coveralls commented May 5, 2025 •

edited

Loading

ffranr commented Jun 18, 2025 •

edited

Loading