tapdb+universe: implement new Universe tree for 1st party burns #1456

Roasbeef · 2025-03-27T02:34:37Z

In this commit, we add a new interface, the BurnTree. This interface
will be used by a future sub-system to maintain the on-chain asset
commitment for a given asset group.

The structure of this tree is very similar to the existing issuance
tree. The main difference is that we'll only insert burn proofs into
this tree.

We then implement a concrete implementation of this interface
using the existing universe tree routines.

guggero

Did a first pass, very nice! Nothing major, so should be pretty close.
Nice unit tests too 💯

CI failures seem to be flakes.

universe/interface.go

tapdb/burn_tree.go

tapdb/burn_tree_test.go

Roasbeef · 2025-03-28T00:50:31Z

Pushed up a commit to consolidate a lot of the duplication between the ignore and burn trees.

Roasbeef · 2025-04-03T00:15:24Z

Pushed up a commit to solve the collision issues. We add a new interface for LeafKey, then make a new concrete BaseLeafKey implementation. This way any methods that needs the old leaf key can continue to accept it, so we're able to re-use many helper functions. We then add a UniqueLeafKey interface, along with a concrete implementation that'll be used by the burn tree.

For the ignore tree, we use the hash of the prev ID as a key, which already includes the asset ID, so we're safe there.

lightninglabs-deploy · 2025-04-10T00:18:22Z

@guggero: review reminder

guggero

Very nice refactor, code re-use and collision avoidance!
Code looks good to me (apart from a few mostly code style related nits, Aider still seems to struggle with our preferred code style. Or I struggle with its decisions, however you want to see it 😅 )

tapdb/burn_tree.go

tapdb/ignore_tree.go

tapdb/universe.go

guggero · 2025-04-14T16:31:31Z

tapdb/burn_tree.go

-		}
+// decodeAndBuildAuthBurnLeaf decodes the raw leaf, reconstructs the key, and
+// builds the AuthenticatedBurnLeaf.
+func decodeAndBuildAuthBurnLeaf(dbLeaf UniverseLeaf) (


So here we're using the:

func myFuncName(param, param) ( returnVal, returnVal) {

style, while further down we're using

func myFuncName(param, param ) (returnVal, returnVal) {

Can we please at least get consistency in terms of this decision? I way prefer the first one, for reasons previously stated.

tapdb/ignore_tree.go

tapdb/universe.go

guggero · 2025-04-14T16:34:56Z

universe/interface.go

-type LeafKey struct {
+// LeafKey is an interface that allows us to obtain the universe key for a leaf
+// within a universe.
+type LeafKey interface {


Very nice solution! Awesome to be able to leave behind the universe collision issue for new trees 💯

In this commit, we add a new interface, the BurnTree. This interface will be used by a future sub-system to maintain the on-chain asset commitment for a given asset group. The structure of this tree is very similar to the existing issuance tree. The main difference is that we'll only insert burn proofs into this tree.

This is a bug fix to ensure that randProof makes proofs that have unique outpoints. Otherwise, it's possbile that the outpoints collide if used as a map key.

In this commit, we add an option to skip multi-verse insertion. This is useful as for the new burn and ignore trees, we won't put them in a multi-verse of all the other ignore/burn trees. Instead, they'll go in a special tree for a given group, which contains these trees as sub-trees.

We're able to re-use a lot of code for the insertion routines here as the tree structure is identical to the issuance tree.

…rnTree Previously, the `BurnUniverseTree` and `IgnoreUniverseTree` implementations contained significant duplicated logic for common operations such as: - Deriving a universe identifier from an asset specifier. - Calculating the total sum of leaf values in a tree. - Querying specific leaves and generating their MS-SMT inclusion proofs. - Listing all leaves within a specific universe namespace. This commit introduces several generic helper functions within `tapdb/universe.go` to centralize this logic: - `specifierToIdentifier`: Creates a universe identifier for a given specifier and proof type. - `getUniverseTreeSum`: Calculates the sum of a universe tree root. - `queryUniverseLeavesAndProofs`: A generic function to query leaves, decode them, fetch MS-SMT proofs, and build authenticated results. - `listUniverseLeaves`: A generic function to list and decode all leaves in a namespace. The `BurnUniverseTree` and `IgnoreUniverseTree` methods (`Sum`, `QueryBurns`, `ListBurns`, `QueryTuples`, `ListTuples`) have been refactored to utilize these new helpers. This significantly reduces code duplication and improves the maintainability of universe tree interactions. The `IgnoreTree` interface and related tests were updated to reflect changes in the `ListTuples` return type.

This is a prep for fixing an issue with Universe keys that have an identical 2-tuple, but distinct 3-tuple.

We then also add a new concrete implementation of this leaf key. The interface will allow us to pass it in anywhere that the normal LeafKey is expected.

This ensures that we avoid collision issues when an output has multiple assets that have the same script key and same group key. The asset ID will now be the tie breaker here.

Roasbeef · 2025-04-16T03:55:38Z

Pushed up latest iteration. This is dependent on the ignore tree PR.

ffranr · 2025-04-16T15:41:35Z

I've changed base branch to main now that ignore-tree-impl PR is merged.

ffranr · 2025-04-08T18:11:46Z

universe/interface.go

+
+// BurnTree sum is the response to a query of the total amount burned in a given
+// burn tree.
+type BurnTreeSum = SumQueryResp


We should probably consider generalising the doc for SumQueryResp in this PR, because it's specific to ignore right now.

ffranr · 2025-04-17T09:22:58Z

universe/interface.go

+	// BurnProof is the burn proof that is stored within the burn leaf.
+	BurnProof *proof.Proof


I don't think this field needs to be a pointer type.

ffranr · 2025-04-17T09:27:13Z

universe/interface.go

+type AuthenticatedBurnLeaf struct {
+	*BurnLeaf
+
+	// BurnTreeRoot is the root of the ignore tree that the burn leaf


ignore tree -> burn tree

ffranr · 2025-04-17T11:00:31Z

tapdb/ignore_tree.go

+// decodeAndBuildAuthIgnoreTuple decodes the raw leaf, reconstructs the key,
+// and builds the AuthenticatedIgnoreTuple.
+func decodeAndBuildAuthIgnoreTuple(dbLeaf UniverseLeaf,


maybe function name could be: parseDbSignedIgnoreTuple

ffranr · 2025-04-17T11:01:42Z

tapdb/ignore_tree.go

+}
+
+// buildAuthIgnoreTuple constructs the final AuthenticatedIgnoreTuple.
+func buildAuthIgnoreTuple(decodedLeaf *universe.SignedIgnoreTuple,


Perhaps this can become a universe.AuthenticatedIgnoreTuple constructor called NewAuthIgnoreTuple

BTW, I'm getting an error in my IDE because decodedLeaf is a pointer where as field SignedIgnoreTuple is not.

ffranr · 2025-04-17T11:11:48Z

rpcserver.go

@@ -5276,7 +5276,7 @@ func (r *rpcServer) AssetLeaves(ctx context.Context,

 // unmarshalLeafKey un-marshals a leaf key from the RPC form.
 func unmarshalLeafKey(key *unirpc.AssetKey) (universe.LeafKey, error) {
-	var leafKey universe.LeafKey
+	var leafKey universe.BaseLeafKey


Perhaps we can follow the same pattern we used for the GroupKeyReveal upgrade from V0 to V1. That would mean introducing a new interface, renaming universe.LeafKey to universe.LeafKeyV0, and adding a new universe.LeafKeyV1, rather than layering changes on top of a shared base. Might help keep the original V0 implementation clearly identifiable.

And then in the doc for V0 we can explain why it's been depreciated.

Roasbeef added the universe label Mar 27, 2025

Roasbeef requested review from guggero and GeorgeTsagk March 27, 2025 02:34

levmi assigned Roasbeef Mar 27, 2025

levmi added this to Taproot-Assets Project Board Mar 27, 2025

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

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

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

guggero reviewed Mar 27, 2025

View reviewed changes

universe/interface.go Outdated Show resolved Hide resolved

universe/interface.go Show resolved Hide resolved

tapdb/burn_tree.go Show resolved Hide resolved

tapdb/burn_tree.go Outdated Show resolved Hide resolved

tapdb/burn_tree_test.go Outdated Show resolved Hide resolved

Roasbeef force-pushed the burn-tree branch from ac9f862 to fd5f6a1 Compare April 3, 2025 00:13

guggero self-requested a review April 3, 2025 13:29

levmi requested review from ffranr and removed request for GeorgeTsagk April 7, 2025 15:43

guggero approved these changes Apr 14, 2025

View reviewed changes

Roasbeef added 9 commits April 15, 2025 20:52

universe: ensure that randProof produces unique outpoints

b0ab2b7

This is a bug fix to ensure that randProof makes proofs that have unique outpoints. Otherwise, it's possbile that the outpoints collide if used as a map key.

tapdb: add implementation of universe.BurnTree

a3b0635

We're able to re-use a lot of code for the insertion routines here as the tree structure is identical to the issuance tree.

tapdb: add unit tests for the new burn tree

9c2f72f

universe: create new LeafKey interface

4755d20

This is a prep for fixing an issue with Universe keys that have an identical 2-tuple, but distinct 3-tuple.

universe: add new UniqueLeafKey that includes the asset ID

ca22bda

We then also add a new concrete implementation of this leaf key. The interface will allow us to pass it in anywhere that the normal LeafKey is expected.

tapdb: use AssetLeafKey for new burn tree

907db70

This ensures that we avoid collision issues when an output has multiple assets that have the same script key and same group key. The asset ID will now be the tie breaker here.

Roasbeef force-pushed the burn-tree branch from 52d6017 to 907db70 Compare April 16, 2025 03:55

Roasbeef force-pushed the ignore-tree-impl branch from 4a29c11 to 9668caa Compare April 16, 2025 03:55

ffranr changed the base branch from ignore-tree-impl to main April 16, 2025 15:40

ffranr reviewed Apr 17, 2025

View reviewed changes

ffranr mentioned this pull request Apr 17, 2025

[feature]: resolve inadvertent 1st party universe tree collision mapping #1455

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tapdb+universe: implement new Universe tree for 1st party burns #1456

tapdb+universe: implement new Universe tree for 1st party burns #1456

Roasbeef commented Mar 27, 2025

guggero left a comment

Roasbeef commented Mar 28, 2025

Roasbeef commented Apr 3, 2025

lightninglabs-deploy commented Apr 10, 2025

guggero left a comment

guggero Apr 14, 2025

guggero Apr 14, 2025

Roasbeef commented Apr 16, 2025

ffranr commented Apr 16, 2025

ffranr Apr 8, 2025

ffranr Apr 17, 2025

ffranr Apr 17, 2025

ffranr Apr 17, 2025

ffranr Apr 17, 2025

ffranr Apr 17, 2025

ffranr Apr 17, 2025 •

edited

Loading

		// BurnProof is the burn proof that is stored within the burn leaf.
		BurnProof *proof.Proof

tapdb+universe: implement new Universe tree for 1st party burns #1456

Are you sure you want to change the base?

tapdb+universe: implement new Universe tree for 1st party burns #1456

Conversation

Roasbeef commented Mar 27, 2025

guggero left a comment

Choose a reason for hiding this comment

Roasbeef commented Mar 28, 2025

Roasbeef commented Apr 3, 2025

lightninglabs-deploy commented Apr 10, 2025

guggero left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Roasbeef commented Apr 16, 2025

ffranr commented Apr 16, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ffranr Apr 17, 2025 • edited Loading

Choose a reason for hiding this comment

ffranr Apr 17, 2025 •

edited

Loading