Merge pull request #1682 from lightninglabs/wip/supplycommit/align-mint-interface-terminology

mint: rename universe commit terminology to supply commit for consistency

Author: ffranr

cmd/commands/assets.go

@@ -99,7 +99,7 @@ var (
 	groupByGroupName              = "by_group"
 	assetIDName                   = "asset_id"
 	shortResponseName             = "short"
-	universeCommitmentsName       = "universe_commitments"
+	enableSupplyCommitmentsName   = "enable_supply_commitments"
 	feeRateName                   = "sat_per_vbyte"
 	skipProofCourierPingCheckName = "skip-proof-courier-ping-check"
 	assetAmountName               = "amount"
@@ -198,9 +198,9 @@ var mintAssetCommand = cli.Command{
 				"was derived from",
 		},
 		cli.BoolFlag{
-			Name: universeCommitmentsName,
+			Name: enableSupplyCommitmentsName,
 			Usage: "if set, the asset group will be minted with " +
-				"universe commitments enabled " +
+				"universe supply commitments enabled " +
 				"(minter-controlled, on-chain attestations " +
 				"that anchor and verify the state of an " +
 				"asset group); this option restricts the " +
@@ -434,8 +434,10 @@ func mintAsset(ctx *cli.Context) error {
 			AssetVersion: taprpc.AssetVersion(
 				ctx.Uint64(assetVersionName),
 			),
-			ExternalGroupKey:    externalKey,
-			UniverseCommitments: ctx.Bool(universeCommitmentsName),
+			ExternalGroupKey: externalKey,
+			EnableSupplyCommitments: ctx.Bool(
+				enableSupplyCommitmentsName,
+			),
 		},
 		ShortResponse: ctx.Bool(shortResponseName),
 	})

docs/release-notes/release-notes-0.7.0.md

@@ -65,9 +65,16 @@
   when requesting quotes. The field can contain optional user or authentication
   information that helps the price oracle to decide on the optimal price rate to
   return.
+- [Rename](https://github.com/lightninglabs/taproot-assets/pull/1682) the
+  `MintAsset` RPC message field from `universe_commitments` to
+  `enable_supply_commitments`.
 
 ## tapcli Additions
 
+- [Rename](https://github.com/lightninglabs/taproot-assets/pull/1682) the mint
+  asset command flag from `--universe_commitments` to
+  `--enable_supply_commitments` for consistency with the updated terminology.
+
 # Improvements
 
 ## Functional Updates

itest/supply_commit_test.go

@@ -89,7 +89,7 @@ func assertAnchorTxPreCommitOut(
 // universe/supply commitments enabled.
 func testPreCommitOutput(t *harnessTest) {
 	mintReq := CopyRequest(issuableAssets[0])
-	mintReq.Asset.UniverseCommitments = true
+	mintReq.Asset.EnableSupplyCommitments = true
 	rpcAssets := MintAssetsConfirmBatch(
 		t.t, t.lndHarness.Miner().Client, t.tapd,
 		[]*mintrpc.MintAssetRequest{mintReq},
@@ -119,7 +119,7 @@ func testPreCommitOutput(t *harnessTest) {
 			GroupedAsset:    true,
 			GroupKey:        tweakedGroupKey,
 
-			UniverseCommitments: true,
+			EnableSupplyCommitments: true,
 		},
 	}
 	rpcAssets = MintAssetsConfirmBatch(
@@ -156,7 +156,7 @@ func testSupplyCommitIgnoreAsset(t *harnessTest) {
 	t.Log("Minting asset group with a single normal asset and " +
 		"universe/supply commitments enabled")
 	mintReq := issuableAssets[0]
-	mintReq.Asset.UniverseCommitments = true
+	mintReq.Asset.EnableSupplyCommitments = true
 	rpcAssets := MintAssetsConfirmBatch(
 		t.t, t.lndHarness.Miner().Client, t.tapd,
 		[]*mintrpc.MintAssetRequest{mintReq},

proof/meta_test.go

@@ -333,7 +333,7 @@ func TestMetaDataRevealEncoding(t *testing.T) {
 				0x4f, 0x4e,
 				// DecDisplay:
 				0x05, 0x04, 0x00, 0x00, 0x00, 0x08,
-				// UniverseCommitments:
+				// SupplyCommitments:
 				0x07, 0x01, 0x01,
 				// CanonicalUniverses:
 				0x09, 0x1e, 0x01, 0x1c, 0x75, 0x6e, 0x69, 0x76,

rpcserver.go

@@ -615,13 +615,13 @@ func (r *rpcServer) MintAsset(ctx context.Context,
 	}
 
 	seedling := &tapgarden.Seedling{
-		AssetVersion:        assetVersion,
-		AssetType:           asset.Type(req.Asset.AssetType),
-		AssetName:           req.Asset.Name,
-		Amount:              req.Asset.Amount,
-		EnableEmission:      req.Asset.NewGroupedAsset,
-		Meta:                &seedlingMeta,
-		UniverseCommitments: req.Asset.UniverseCommitments,
+		AssetVersion:      assetVersion,
+		AssetType:         asset.Type(req.Asset.AssetType),
+		AssetName:         req.Asset.Name,
+		Amount:            req.Asset.Amount,
+		EnableEmission:    req.Asset.NewGroupedAsset,
+		Meta:              &seedlingMeta,
+		SupplyCommitments: req.Asset.EnableSupplyCommitments,
 	}
 
 	rpcsLog.Infof("[MintAsset]: version=%v, type=%v, name=%v, amt=%v, "+

tapdb/asset_minting.go

@@ -484,7 +484,7 @@ func (a *AssetMintingStore) CommitMintingBatch(ctx context.Context,
 			BatchID:             batchID,
 			HeightHint:          int32(newBatch.HeightHint),
 			CreationTimeUnix:    newBatch.CreationTime.UTC(),
-			UniverseCommitments: newBatch.UniverseCommitments,
+			UniverseCommitments: newBatch.SupplyCommitments,
 		}); err != nil {
 			return fmt.Errorf("unable to insert minting "+
 				"batch: %w", err)
@@ -552,7 +552,7 @@ func (a *AssetMintingStore) CommitMintingBatch(ctx context.Context,
 				EmissionEnabled: seedling.EnableEmission,
 
 				// nolint: lll
-				UniverseCommitments: seedling.UniverseCommitments,
+				UniverseCommitments: seedling.SupplyCommitments,
 			}
 
 			scriptKeyID, err := upsertScriptKey(
@@ -697,7 +697,7 @@ func (a *AssetMintingStore) AddSeedlingsToBatch(ctx context.Context,
 				EmissionEnabled: seedling.EnableEmission,
 
 				// nolint: lll
-				UniverseCommitments: seedling.UniverseCommitments,
+				UniverseCommitments: seedling.SupplyCommitments,
 			}
 
 			scriptKeyID, err := upsertScriptKey(
@@ -793,8 +793,8 @@ func fetchAssetSeedlings(ctx context.Context, q PendingAssetStore,
 			Amount: uint64(
 				dbSeedling.AssetSupply,
 			),
-			EnableEmission:      dbSeedling.EmissionEnabled,
-			UniverseCommitments: dbSeedling.UniverseCommitments,
+			EnableEmission:    dbSeedling.EmissionEnabled,
+			SupplyCommitments: dbSeedling.UniverseCommitments,
 		}
 
 		if dbSeedling.TweakedScriptKey != nil {
@@ -1298,9 +1298,9 @@ func marshalMintingBatch(ctx context.Context, q PendingAssetStore,
 			},
 			PubKey: batchKey,
 		},
-		HeightHint:          uint32(dbBatch.HeightHint),
-		CreationTime:        dbBatch.CreationTimeUnix.UTC(),
-		UniverseCommitments: dbBatch.UniverseCommitments,
+		HeightHint:        uint32(dbBatch.HeightHint),
+		CreationTime:      dbBatch.CreationTimeUnix.UTC(),
+		SupplyCommitments: dbBatch.UniverseCommitments,
 	}
 
 	batchState, err := tapgarden.NewBatchState(uint8(dbBatch.BatchState))

tapdb/asset_minting_test.go

@@ -94,7 +94,7 @@ func assertBatchEqual(t *testing.T, a, b *tapgarden.MintingBatch) {
 		t, &a.GenesisPacket.FundedPsbt, &b.GenesisPacket.FundedPsbt,
 	)
 	require.Equal(t, a.RootAssetCommitment, b.RootAssetCommitment)
-	require.Equal(t, a.UniverseCommitments, b.UniverseCommitments)
+	require.Equal(t, a.SupplyCommitments, b.SupplyCommitments)
 }
 
 func assertSeedlingBatchLen(t *testing.T, batches []*tapgarden.MintingBatch,
@@ -624,7 +624,7 @@ func TestInsertFetchUniCommitBatch(t *testing.T) {
 		t, tapgarden.WithTotalGroups([]int{1}),
 		tapgarden.WithUniverseCommitments(true),
 	)
-	require.True(t, batch.UniverseCommitments)
+	require.True(t, batch.SupplyCommitments)
 
 	// Generate the group genesis, persist it, and assign the group details
 	// to the seedling.
@@ -641,7 +641,7 @@ func TestInsertFetchUniCommitBatch(t *testing.T) {
 
 	// Assert that the seedling is in the expected state.
 	seedling := batch.Seedlings[assetName]
-	require.True(t, seedling.UniverseCommitments)
+	require.True(t, seedling.SupplyCommitments)
 	require.True(t, seedling.DelegationKey.IsSome())
 
 	// Commit the minting batch to the database.
@@ -655,13 +655,13 @@ func TestInsertFetchUniCommitBatch(t *testing.T) {
 	require.NoError(t, err)
 
 	// Assert that the batch is in the expected state.
-	require.True(t, dbBatch.UniverseCommitments)
+	require.True(t, dbBatch.SupplyCommitments)
 
 	// Assert that the seedling is in the expected state.
 	require.Len(t, dbBatch.Seedlings, 1)
 
 	dbSeedling := dbBatch.Seedlings[assetName]
-	require.True(t, dbSeedling.UniverseCommitments)
+	require.True(t, dbSeedling.SupplyCommitments)
 	require.True(t, dbSeedling.DelegationKey.IsSome())
 	require.Equal(t, dbSeedling.DelegationKey, seedling.DelegationKey)
 }
@@ -1925,7 +1925,7 @@ func TestUpsertMintAnchorUniCommitment(t *testing.T) {
 
 	// Create a new batch with one asset group seedling.
 	mintingBatch := tapgarden.RandSeedlingMintingBatch(t, 1)
-	mintingBatch.UniverseCommitments = true
+	mintingBatch.SupplyCommitments = true
 
 	_, _, group := addRandGroupToBatch(
 		t, assetStore, ctx, mintingBatch.Seedlings,

tapdb/sqlc/migrations/000040_asset_commit.up.sql

@@ -76,7 +76,10 @@ CREATE TABLE supply_commit_state_machines (
     latest_commitment_id BIGINT REFERENCES supply_commitments(commit_id)
 );
 
--- Table tracking a pending state transition for a state machine.
+-- Table tracking an in-progress transition from one supply commitment to a
+-- newer one. A transition represents the process of creating a new on-chain
+-- supply commitment that succeeds a prior version, which remains valid as a
+-- historical record.
 CREATE TABLE supply_commit_transitions (
     transition_id INTEGER PRIMARY KEY,
 
@@ -102,7 +105,11 @@ CREATE TABLE supply_commit_transitions (
     creation_time BIGINT NOT NULL
 );
 
--- Table storing individual update events associated with a pending transition.
+-- Table recording supply update events associated with a pending supply
+-- commitment transition. A transition is the process of creating a newer
+-- on-chain supply commitment that follows a previous one. Update events are
+-- asset group supply-specific events handled by the supply commitment state
+-- machine.
 CREATE TABLE supply_update_events (
     event_id INTEGER PRIMARY KEY,
 

tapgarden/batch.go

@@ -63,13 +63,14 @@ type MintingBatch struct {
 	// reveal for that asset, if it has one.
 	AssetMetas AssetMetas
 
-	// UniverseCommitments is a flag that determines whether the minting
-	// event supports universe commitments. When set to true, the batch must
-	// include only assets that share the same asset group key.
+	// SupplyCommitments is a flag that determines whether the minting
+	// event supports universe supply commitments. When set to true, the
+	// batch must include only assets that share the same asset group key.
 	//
-	// Universe commitments are minter-controlled, on-chain anchored
-	// attestations regarding the state of the universe.
-	UniverseCommitments bool
+	// Universe supply commitments are minter-controlled, on-chain anchored
+	// attestations regarding the state of the universe supply (issued,
+	// ignored, burnt, etc).
+	SupplyCommitments bool
 
 	// mintingPubKey is the top-level Taproot output key that will be used
 	// to commit to the Taproot Asset commitment above.
@@ -110,7 +111,7 @@ func (m *MintingBatch) Copy() *MintingBatch {
 		// set, so a shallow copy is sufficient.
 		BatchKey:            m.BatchKey,
 		RootAssetCommitment: m.RootAssetCommitment,
-		UniverseCommitments: m.UniverseCommitments,
+		SupplyCommitments:   m.SupplyCommitments,
 		mintingPubKey:       m.mintingPubKey,
 		tapSibling:          m.tapSibling,
 	}
@@ -323,7 +324,7 @@ func (m *MintingBatch) HasSeedlings() bool {
 func (m *MintingBatch) validateDelegationKey(newSeedling Seedling) error {
 	// If the universe commitment flag is disabled, then the delegation key
 	// should not be set.
-	if !newSeedling.UniverseCommitments {
+	if !newSeedling.SupplyCommitments {
 		if newSeedling.DelegationKey.IsSome() {
 			return fmt.Errorf("delegation key must not be set " +
 				"for seedling without universe commitments")
@@ -395,7 +396,7 @@ func (m *MintingBatch) validateUniCommitment(newSeedling Seedling) error {
 		// If there are no seedlings in the batch, and the first
 		// (subject) seedling doesn't enable universe commitment, we can
 		// accept it without further checks.
-		if !newSeedling.UniverseCommitments {
+		if !newSeedling.SupplyCommitments {
 			return nil
 		}
 
@@ -442,14 +443,14 @@ func (m *MintingBatch) validateUniCommitment(newSeedling Seedling) error {
 	// Therefore, when evaluating this new candidate seedling for inclusion
 	// in the batch, we must ensure that its universe commitment flag state
 	// matches the flag state of the batch.
-	if m.UniverseCommitments != newSeedling.UniverseCommitments {
+	if m.SupplyCommitments != newSeedling.SupplyCommitments {
 		return fmt.Errorf("seedling universe commitment flag does " +
 			"not match batch")
 	}
 
 	// If the universe commitment flag is disabled for both the seedling and
 	// the batch, no additional checks are required.
-	if !m.UniverseCommitments && !newSeedling.UniverseCommitments {
+	if !m.SupplyCommitments && !newSeedling.SupplyCommitments {
 		return nil
 	}
 
@@ -459,7 +460,7 @@ func (m *MintingBatch) validateUniCommitment(newSeedling Seedling) error {
 	// * the batch contains at least one seedling.
 	//
 	// For clarity, we will assert these conditions now.
-	if !m.UniverseCommitments || !newSeedling.UniverseCommitments ||
+	if !m.SupplyCommitments || !newSeedling.SupplyCommitments ||
 		!m.HasSeedlings() {
 
 		return fmt.Errorf("unexpected code path reached")
@@ -520,7 +521,7 @@ func (m *MintingBatch) AddSeedling(newSeedling Seedling) error {
 	// seedling being added to the batch, the batch universe commitment flag
 	// can be set to match the seedling's flag state.
 	if !m.HasSeedlings() {
-		m.UniverseCommitments = newSeedling.UniverseCommitments
+		m.SupplyCommitments = newSeedling.SupplyCommitments
 	}
 
 	// Ensure that the delegation key is valid for the seedling being

tapgarden/batch_test.go

@@ -147,7 +147,7 @@ func TestValidateUniCommitment(t *testing.T) {
 		t, anchorSeedling.AssetVersion, anchorSeedling.AssetType,
 		anchorSeedling.AssetName, anchorSeedling.Meta.Data,
 		anchorSeedling.DelegationKey,
-		anchorSeedling.UniverseCommitments,
+		anchorSeedling.SupplyCommitments,
 	)
 
 	testCases = append(testCases, TestCase{