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.

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 makes the generator more consistent and useful.

…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.

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

Pull Request Test Coverage Report for Build 14847982056

Details

1 of 789 (0.13%) changed or added relevant lines in 6 files are covered.
22 unchanged lines in 7 files lost coverage.
Overall coverage decreased (-0.4%) to 36.563%

Changes Missing Coverage	Changed/Added Lines	%
universe/interface.go	5	0.0%
universe/ignore_records.go	11	0.0%
universe/supplycommit/env.go	77	0.0%
universe/supplycommit/supply_commit_states.go	139	0.0%
universe/supplycommit/supply_commit_transitions.go	556	0.0%

Files with Coverage Reduction	New Missed Lines	%
address/address.go	2	67.47%
tapgarden/planter.go	2	60.85%
asset/asset.go	3	46.84%
tapchannel/aux_leaf_signer.go	3	43.43%
asset/mock.go	4	64.71%
commitment/tap.go	4	71.59%
tapgarden/caretaker.go	4	68.68%

Totals
Change from base Build 14790497726:	-0.4%
Covered Lines:	26474
Relevant Lines:	72406

💛 - 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

ffranr · 2025-05-08T22:27:48Z

universe/supplycommit/supply_commit_states.go

+// eventSealed is a special method that is used to seal the interface.
+func (c *CommitTickEvent) eventSealed() {}
+
+// UpdatePendingState is the state of the state machine when we have From this


unfinished sentence: when we have From.

ffranr · 2025-05-08T22:30:26Z

universe/supplycommit/supply_commit_states.go

+// StateMachine is a state machine that handles creating and updating the
+// on-chain universe supply commitment for a given asset.
+//
+// nolint:lll
+type StateMachine = protofsm.StateMachine[Event, *Environment]
+
+// Config is a configuration struct that is used to initialize a new supply
+// commit state machine.
+type Config = protofsm.StateMachineCfg[Event, *Environment]


I don't think these are used and they might be the only reason for the lnd replace in go.mod. I'm not sure.

So the state machine isn't instantiated externally yet, once it is these will be used.

The lnd fork dep is needed to we can access the block block after confirmation, and also pass that into the state machine.

ffranr · 2025-05-08T22:39:40Z

universe/supplycommit/supply_commit_states.go

+// State transitions:
+//   - SignTxEvent -> CommitBroadcastState
+type CommitTxSignState struct {


I'm not sure if I understand the state transition in the doc comment. Should this be:

// State transitions: // - SignTxEvent -> CommitTxSignState // - CommitTxSignState -> BroadcastEvent

Are we describing to and from states in doc State transitions?

This is meant to indicate that from this state, we can go to the sign state.

ffranr · 2025-05-08T22:42:20Z

universe/supplycommit/supply_commit_states.go

+// State transitions:
+//   - BroadcastEvent -> CommitBroadcastState
+//   - ConfEvent -> DefaultState
+type CommitBroadcastState struct {


I don't understand ConfEvent -> DefaultState in the doc here.

Once our latest commitment transaction confirms on chain the state machine could transition to DefaultState?

This is slightly out of date, a new CommitFinalizeState state is was transitions us to the default.

ffranr · 2025-05-08T22:51:04Z

universe/supplycommit/README.md

+    Universe server components).
+
+*   Managing commitments for multiple different assets simultaneously (each
+    asset specifier typically gets its own state machine instance).


asset specifier -> asset group

lightninglabs-deploy · 2025-06-03T02:27:49Z

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

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

Open

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

Open

Roasbeef force-pushed the asset-commitment-creator branch from 195d65b to 8d5041c Compare May 5, 2025 22:45

Roasbeef added 9 commits May 5, 2025 15:54

universe: add IsBurn bool to Leaf [temp]

2d277dc

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

68558b2

build: point to temp version of roasbeeef's fork

2832f42

asset: modify ScriptKeyGen to always populate the internal pubkey

2200a44

This makes the generator more consistent and useful.

universe/supplycommit: add definitions of fundamental interfaces

f08ec6e

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

cba12e9

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

universe/supplycommit: add README.md

648cb72

Roasbeef force-pushed the asset-commitment-creator branch 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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!

Roasbeef commented Apr 9, 2025 •

edited

Loading

Uh oh!

Roasbeef commented May 3, 2025

Uh oh!

coveralls commented May 5, 2025

Uh oh!

ffranr left a comment

Uh oh!

ffranr May 8, 2025

Uh oh!

ffranr May 8, 2025

Uh oh!

Roasbeef May 13, 2025

Uh oh!

ffranr May 8, 2025

Uh oh!

ffranr May 8, 2025

Uh oh!

Roasbeef May 13, 2025

Uh oh!

ffranr May 8, 2025

Uh oh!

Roasbeef May 13, 2025

Uh oh!

ffranr May 8, 2025

Uh oh!

Roasbeef May 13, 2025

Uh oh!

ffranr May 8, 2025

Uh oh!

lightninglabs-deploy commented Jun 3, 2025

Uh oh!

Uh oh!


		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

Are you sure you want to change the base?

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

Pull Request Test Coverage Report for Build 14847982056

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!

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!

lightninglabs-deploy commented Jun 3, 2025

Uh oh!

Uh oh!

Roasbeef commented Apr 9, 2025 •

edited

Loading