tapdb: add implementation of supplycommit.SupplyTreeView #1507

Roasbeef · 2025-05-03T03:20:57Z

In this commit, we add an implementation of the supplycommitment.SupplyTreeView interface to tapdb. This provides us with a concrete interface to be used along side #1464.

The structure is similar to the existing multi-verse trees, but we instead of scoping by proof type (issuance or transfer), we instead scope by the group key of a given asset.

Along the way we do some refactors to allow us to do atomic inserts across all the sub-trees, and also the root tree.

In this commit, we add new namespace routines for the supply tree. We'll use these to modify exactly which namespace we use for the ignore and burn trees. Rather than store using the old universe namespace, we choose to roll a new set of namespaces, as these trees are specific to a given group key.

…space directly In this commit, as a prep for the new universe supply tree routines, we refactor the InsertBurns method to rely on a new internal helper function. We also change the namespace we store things under to use the new supply tree namespaces. Finally, we fix a bug that would use different roots for the merkle tree proofs after insertion. We'll now ensure that the merkle tree proofs all use the same merkle root.

…pace Similar to the last commit, in this commit, we refactor the AddTuples method to use a new helper function. We then start to use the new supply tree namespace just like we did for the burn tree.

…ce directly In this commit, we update the helper functions that the ignore and burn tree use to take the namespace directly instead of the universe.Identifier. This makes the functions more flexible, as they don't assume a namespace derivation.

In this commit, we break up the singular universeUpsertProofLeaf function into two: one for inserting into the universe tree, and one for taking the updated universe root to insert into the multi-verse tree.

In this commit, we add a new migration for the universe supply trees. Rather than use the multi-verse pointers (which are namespaced by proof type), we instead move to use a new set of smt tree pointers, that are scoped by the group key instead. We'll use these later to keep track of the new supply sub-trees, and also root supply tree. We also add a new proof type of mint_supply, to distinguish from the normal issuance type.

In this commit, we add a concrete implementation of SupplyTreeStore in tapdb. This is similar to the structs we used to manage the multiverse tree, which is scoped by proof type. Instead, the supply trees are scoped by group key. We can use this to stage a series of updates for a group key (mint, ignore, burn), and insert into a supply tree in a single atomic transaction. We also expose methods to fetch each sub supply tree as well.

In this commit, we add tests for the supply tree store. We use rapid to ensure that we can handle any combiniation of events when we go to update them in the tree.

lightninglabs-deploy · 2025-05-27T18:04:43Z

@ffranr: review reminder

ffranr · 2025-05-29T20:21:57Z

tapdb/burn_tree.go

-	id, err := specifierToIdentifier(spec, universe.ProofTypeBurn)
-	if err != nil {
-		return lfn.Err[lfn.Option[uint64]](err)
+	groupKey := spec.UnwrapGroupKeyToPtr()


another possibility: spec.UnwrapGroupKeyOrErr

ffranr · 2025-05-29T21:05:41Z

tapdb/burn_tree.go

+	txErr := bt.db.ExecTx(ctx, &writeTx, func(db BaseUniverseStore) error {
+		finalResults, err = insertBurnsInternal(
+			ctx, db, spec, burnLeaves...,
+		)
+
+		// TODO(roasbeef): also update the root supply tree?
+		return err


I suspect it probably would be best to update the supply tree root here also as the TODO suggests. Within the same db transaction. If not here then where?

ffranr · 2025-05-29T21:26:34Z

tapdb/ignore_tree.go

+		// To insert the universe leaf below, we'll need both the db the
+		// outpoint to be ignored. primary key for the asset genesis,
+		// and also the raw bytes of
+		assetGenID, err := db.FetchGenesisIDByAssetID(


unfinished comment

ffranr · 2025-05-29T21:31:17Z

tapdb/ignore_tree.go

+		scriptKey := ignoreTup.ScriptKey
+		err = db.UpsertUniverseLeaf(ctx, UpsertUniverseLeaf{
+			AssetGenesisID:    assetGenID,
+			ScriptKeyBytes:    scriptKey.SchnorrSerialized(), //nolint:lll


//nolint:lll unnecessary here

ffranr · 2025-05-29T21:32:28Z

tapdb/ignore_tree.go

+// addTuplesInternal performs the insertion of ignore tuples within a database
+// transaction. It also updates the main supply tree with the new ignore
+// sub-tree root.
+//
+// NOTE: This function must be called within a database transaction.
+func addTuplesInternal(ctx context.Context, db BaseUniverseStore,


this in the doc comment is not currently true for this function:

It also updates the main supply tree with the new ignore // sub-tree root.

ffranr · 2025-05-29T21:33:19Z

tapdb/ignore_tree.go

+	txErr := it.db.ExecTx(ctx, &writeTx, func(db BaseUniverseStore) error {
+		finalResults, err = addTuplesInternal(ctx, db, spec, tuples...)
+		return err
 	})


consider updating supply tree root here, similar to burn tree insertion

ffranr · 2025-05-29T21:44:59Z

tapdb/universe.go

-
-	namespace := id.String()
+	namespace string, proofTypeStr string, groupKey *btcec.PublicKey,
+	key universe.LeafKey, leaf *universe.Leaf,


this commit doesn't compile, perhaps we should squash into another commit?

ffranr · 2025-05-29T21:59:06Z

tapdb/sqlc/migrations/000035_supply_tree.up.sql

+    -- Reference to the root supply tree this leaf belongs to.
+    supply_root_id BIGINT NOT NULL REFERENCES universe_supply_roots(id) ON DELETE CASCADE,
+
+    -- The type of sub-tree this leaf represents (issuance, burn, ignore).


issuence should be mint_supply in this comment?

ffranr · 2025-05-29T22:08:54Z

tapdb/supply_tree.go

+		LeafNodeNamespace: subNs,
+	})
+	if err != nil {
+		fmt.Println("sub tree: ", subTreeType.String())


fmt.Println left over from debugging?

ffranr · 2025-05-29T22:19:10Z

tapdb/sqlc/migrations/000035_supply_tree.up.sql

+INSERT INTO proof_types (proof_type) VALUES ('burn'), ('ignore'), ('mint_supply')
+    ON CONFLICT (proof_type) DO NOTHING;


We also add a new proof type of mint_supply, to distinguish from the normal issuance type.

Is the new proof type (mint_supply) necessary here? I thought we already added supply commit specific prefixes to the relevant namespaces? If true, then I think we could just reuse the issuance proof type.

Roasbeef added universe supply tree labels May 3, 2025

levmi assigned Roasbeef May 5, 2025

levmi added this to Taproot-Assets Project Board May 5, 2025

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

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

Roasbeef force-pushed the universe-supply-trees branch from 7c88480 to 522c3ee Compare May 5, 2025 22:46

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

Roasbeef force-pushed the universe-supply-trees branch 2 times, most recently from d786104 to af5f8f5 Compare May 5, 2025 23:15

Roasbeef added 9 commits May 5, 2025 16:46

tapdb: refactor AddTuples to use new helper fun, use new supply names…

21248b8

…pace Similar to the last commit, in this commit, we refactor the AddTuples method to use a new helper function. We then start to use the new supply tree namespace just like we did for the burn tree.

tapdb: refactor multiverse tree insertion

39c825c

In this commit, we break up the singular universeUpsertProofLeaf function into two: one for inserting into the universe tree, and one for taking the updated universe root to insert into the multi-verse tree.

tapdb/sqlc/queries: add queries for the universe supply trees

b16c4b2

tapdb/sqlc: generate SQL structs

8b6cdfb

Roasbeef force-pushed the universe-supply-trees branch from af5f8f5 to 64516c9 Compare May 5, 2025 23:54

Roasbeef added 2 commits May 5, 2025 16:59

tapdb: add tests for the SupplyTreeStore

afc03c2

In this commit, we add tests for the supply tree store. We use rapid to ensure that we can handle any combiniation of events when we go to update them in the tree.

tapdb: add supply_tree.md documentation for supply tree

bba9b08

Roasbeef force-pushed the universe-supply-trees branch from 64516c9 to 6e0b6a4 Compare May 6, 2025 01:19

tapdb: fix test compile error

aa782c8

Roasbeef force-pushed the universe-supply-trees branch from 6e0b6a4 to aa782c8 Compare May 6, 2025 01:27

levmi added this to the v0.7 milestone May 8, 2025

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

levmi requested a review from ffranr May 13, 2025 16:39

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

ffranr reviewed May 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

tapdb: add implementation of supplycommit.SupplyTreeView #1507

tapdb: add implementation of supplycommit.SupplyTreeView #1507

Uh oh!

Roasbeef commented May 3, 2025

Uh oh!

lightninglabs-deploy commented May 27, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

ffranr May 29, 2025

Uh oh!

Uh oh!

		INSERT INTO proof_types (proof_type) VALUES ('burn'), ('ignore'), ('mint_supply')
		ON CONFLICT (proof_type) DO NOTHING;

tapdb: add implementation of supplycommit.SupplyTreeView #1507

Are you sure you want to change the base?

tapdb: add implementation of supplycommit.SupplyTreeView #1507

Uh oh!

Conversation

Roasbeef commented May 3, 2025

Uh oh!

lightninglabs-deploy commented May 27, 2025

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!

Uh oh!