universerpc: add locator and update response in FetchSupplyCommit RPC

Add `locator` field to the FetchSupplyCommit RPC request to specify
which supply commit to retrieve. Supported options include: the first
supply commit, the supply commit committed to at a given outpoint, and
the supply commit that spends a given outpoint.

Also update the response message for this endpoint. The response now
includes all leaves new to the specified supply commit, as well as the
outpoint that the fetched supply commit spends.

Also add total outstanding asset amount helper field.

Author: ffranr

itest/assertions.go

@@ -2786,8 +2786,9 @@ func UpdateAndMineSupplyCommit(t *testing.T, ctx context.Context,
 // it when the specified condition is met.
 func WaitForSupplyCommit(t *testing.T, ctx context.Context,
 	tapd unirpc.UniverseClient, groupKeyBytes []byte,
+	spentCommitOutpoint fn.Option[wire.OutPoint],
 	condition func(*unirpc.FetchSupplyCommitResponse) bool,
-) *unirpc.FetchSupplyCommitResponse {
+) (*unirpc.FetchSupplyCommitResponse, wire.OutPoint) {
 
 	groupKeyReq := &unirpc.FetchSupplyCommitRequest_GroupKeyBytes{
 		GroupKeyBytes: groupKeyBytes,
@@ -2796,18 +2797,50 @@ func WaitForSupplyCommit(t *testing.T, ctx context.Context,
 	var fetchResp *unirpc.FetchSupplyCommitResponse
 	var err error
 
-	require.Eventually(t, func() bool {
-		fetchResp, err = tapd.FetchSupplyCommit(
-			ctx, &unirpc.FetchSupplyCommitRequest{
-				GroupKey: groupKeyReq,
+	// By default, we start the fetch from the very first commitment.
+	// If a spent outpoint is given, we start from there.
+	req := &unirpc.FetchSupplyCommitRequest{
+		GroupKey: groupKeyReq,
+		Locator: &unirpc.FetchSupplyCommitRequest_VeryFirst{
+			VeryFirst: true,
+		},
+	}
+
+	// nolint: lll
+	spentCommitOutpoint.WhenSome(func(outPoint wire.OutPoint) {
+		req = &unirpc.FetchSupplyCommitRequest{
+			GroupKey: groupKeyReq,
+			Locator: &unirpc.FetchSupplyCommitRequest_SpentCommitOutpoint{
+				SpentCommitOutpoint: &taprpc.OutPoint{
+					Txid:        outPoint.Hash[:],
+					OutputIndex: outPoint.Index,
+				},
 			},
-		)
+		}
+	})
+
+	require.Eventually(t, func() bool {
+		fetchResp, err = tapd.FetchSupplyCommit(ctx, req)
 		if err != nil {
 			return false
 		}
 
 		return fetchResp != nil && condition(fetchResp)
 	}, defaultWaitTimeout, time.Second)
 
-	return fetchResp
+	// Return the supply commit outpoint used to fetch the next supply
+	// commitment. The next commitment is retrieved by referencing the
+	// outpoint of the previously spent commitment.
+	require.NotNil(t, fetchResp)
+
+	var msgTx wire.MsgTx
+	err = msgTx.Deserialize(bytes.NewReader(fetchResp.ChainData.Txn))
+	require.NoError(t, err)
+
+	supplyCommitOutpoint := wire.OutPoint{
+		Hash:  msgTx.TxHash(),
+		Index: fetchResp.ChainData.TxOutIdx,
+	}
+
+	return fetchResp, supplyCommitOutpoint
 }

itest/supply_commit_mint_burn_test.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/chaincfg/chainhash"
+	"github.com/btcsuite/btcd/wire"
 	taprootassets "github.com/lightninglabs/taproot-assets"
 	"github.com/lightninglabs/taproot-assets/fn"
 	"github.com/lightninglabs/taproot-assets/taprpc"
@@ -48,18 +49,19 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 	// Update the on-chain supply commitment for the asset group.
 	//
 	// TODO(roasbeef): still rely on the time based ticker here?
-	t.Log("Updating and mining supply commitment for asset group")
+	t.Log("Create first supply commitment tx for asset group")
 	UpdateAndMineSupplyCommit(
 		t.t, ctxb, t.tapd, t.lndHarness.Miner().Client,
 		groupKeyBytes, 1,
 	)
 
 	// Fetch the latest supply commitment for the asset group.
-	t.Log("Fetching supply commitment to verify mint leaves")
-	fetchResp := WaitForSupplyCommit(
-		t.t, ctxb, t.tapd, groupKeyBytes,
+	t.Log("Fetching first supply commitment to verify mint leaves")
+	fetchResp, supplyOutpoint := WaitForSupplyCommit(
+		t.t, ctxb, t.tapd, groupKeyBytes, fn.None[wire.OutPoint](),
 		func(resp *unirpc.FetchSupplyCommitResponse) bool {
-			return resp.BlockHeight > 0 && len(resp.BlockHash) > 0
+			return resp.ChainData.BlockHeight > 0 &&
+				len(resp.ChainData.BlockHash) > 0
 		},
 	)
 
@@ -72,7 +74,7 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 
 	// Verify the issuance leaf inclusion in the supply tree.
 	AssertSubtreeInclusionProof(
-		t, fetchResp.SupplyCommitmentRoot.RootHash,
+		t, fetchResp.ChainData.SupplyRootHash,
 		fetchResp.IssuanceSubtreeRoot,
 	)
 
@@ -106,8 +108,6 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 	)
 
 	t.Log("Updating supply commitment after second mint")
-
-	// Update and mine the supply commitment after second mint.
 	UpdateAndMineSupplyCommit(
 		t.t, ctxb, t.tapd, t.lndHarness.Miner().Client,
 		groupKeyBytes, 1,
@@ -119,8 +119,8 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 	expectedTotal := int64(
 		mintReq.Asset.Amount + secondMintReq.Asset.Amount,
 	)
-	fetchResp = WaitForSupplyCommit(
-		t.t, ctxb, t.tapd, groupKeyBytes,
+	fetchResp, supplyOutpoint = WaitForSupplyCommit(
+		t.t, ctxb, t.tapd, groupKeyBytes, fn.Some(supplyOutpoint),
 		func(resp *unirpc.FetchSupplyCommitResponse) bool {
 			return resp.IssuanceSubtreeRoot != nil &&
 				resp.IssuanceSubtreeRoot.RootNode.RootSum == expectedTotal //nolint:lll
@@ -175,7 +175,8 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 	t.Log("Verifying supply tree includes burn leaves")
 
 	// Fetch and verify the supply tree now includes burn leaves.
-	fetchResp = WaitForSupplyCommit(t.t, ctxb, t.tapd, groupKeyBytes,
+	fetchResp, _ = WaitForSupplyCommit(
+		t.t, ctxb, t.tapd, groupKeyBytes, fn.Some(supplyOutpoint),
 		func(resp *unirpc.FetchSupplyCommitResponse) bool {
 			return resp.BurnSubtreeRoot != nil &&
 				resp.BurnSubtreeRoot.RootNode.RootSum == int64(burnAmt) //nolint:lll
@@ -184,7 +185,7 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 
 	// Verify the burn subtree inclusion in the supply tree.
 	AssertSubtreeInclusionProof(
-		t, fetchResp.SupplyCommitmentRoot.RootHash,
+		t, fetchResp.ChainData.SupplyRootHash,
 		fetchResp.BurnSubtreeRoot,
 	)
 
@@ -234,16 +235,16 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 	block := finalMinedBlocks[0]
 	blockHash, _ := t.lndHarness.Miner().GetBestBlock()
 
-	fetchBlockHash, err := chainhash.NewHash(fetchResp.BlockHash)
+	fetchBlockHash, err := chainhash.NewHash(fetchResp.ChainData.BlockHash)
 	require.NoError(t.t, err)
 	require.True(t.t, fetchBlockHash.IsEqual(blockHash))
 
 	// Re-compute the supply commitment root hash from the latest fetch,
 	// then use that to derive the expected commitment output.
 	supplyCommitRootHash := fn.ToArray[[32]byte](
-		fetchResp.SupplyCommitmentRoot.RootHash,
+		fetchResp.ChainData.SupplyRootHash,
 	)
-	internalKey, err := btcec.ParsePubKey(fetchResp.AnchorTxOutInternalKey)
+	internalKey, err := btcec.ParsePubKey(fetchResp.ChainData.InternalKey)
 	require.NoError(t.t, err)
 	expectedTxOut, _, err := supplycommit.RootCommitTxOut(
 		internalKey, nil, supplyCommitRootHash,

itest/supply_commit_test.go

@@ -247,11 +247,13 @@ func testSupplyCommitIgnoreAsset(t *harnessTest) {
 			GroupKey: &unirpc.FetchSupplyCommitRequest_GroupKeyBytes{
 				GroupKeyBytes: groupKeyBytes,
 			},
+			Locator: &unirpc.FetchSupplyCommitRequest_VeryFirst{
+				VeryFirst: true,
+			},
 		},
 	)
 	require.Nil(t.t, fetchRespNil)
-	require.ErrorContains(t.t, err, "supply commitment not found for "+
-		"asset group with key")
+	require.ErrorContains(t.t, err, "commitment not found")
 
 	t.Log("Update on-chain supply commitment for asset group")
 
@@ -281,26 +283,35 @@ func testSupplyCommitIgnoreAsset(t *harnessTest) {
 				GroupKey: &unirpc.FetchSupplyCommitRequest_GroupKeyBytes{
 					GroupKeyBytes: groupKeyBytes,
 				},
+				Locator: &unirpc.FetchSupplyCommitRequest_VeryFirst{
+					VeryFirst: true,
+				},
 			},
 		)
 		require.NoError(t.t, err)
 
 		// If the fetch response has no block height or hash,
 		// it means that the supply commitment transaction has not
 		// been mined yet, so we should retry.
-		if fetchResp.BlockHeight == 0 || len(fetchResp.BlockHash) == 0 {
+		if fetchResp.ChainData.BlockHeight == 0 ||
+			len(fetchResp.ChainData.BlockHash) == 0 {
+
 			return false
 		}
 
 		// Once the ignore tree includes the ignored asset outpoint, we
 		// know that the supply commitment has been updated.
+		if fetchResp.IgnoreSubtreeRoot == nil {
+			return false
+		}
+
 		return fetchResp.IgnoreSubtreeRoot.RootNode.RootSum ==
 			int64(sendAssetAmount+sendChangeAmount)
 	}, defaultWaitTimeout, time.Second)
 
 	// Verify that the supply commitment tree commits to the ignore subtree.
 	supplyCommitRootHash := fn.ToArray[[32]byte](
-		fetchResp.SupplyCommitmentRoot.RootHash,
+		fetchResp.ChainData.SupplyRootHash,
 	)
 
 	// Formulate the ignore leaf node as it should appear in the supply
@@ -369,18 +380,18 @@ func testSupplyCommitIgnoreAsset(t *harnessTest) {
 
 	// Ensure that the block hash and height matches the values in the fetch
 	// response.
-	fetchBlockHash, err := chainhash.NewHash(fetchResp.BlockHash)
+	fetchBlockHash, err := chainhash.NewHash(fetchResp.ChainData.BlockHash)
 	require.NoError(t.t, err)
 	require.True(t.t, fetchBlockHash.IsEqual(blockHash))
 
-	require.EqualValues(t.t, blockHeight, fetchResp.BlockHeight)
+	require.EqualValues(t.t, blockHeight, fetchResp.ChainData.BlockHeight)
 
 	// We expect two transactions in the block:
 	// 1. The supply commitment transaction.
 	// 2. The coinbase transaction.
 	require.Len(t.t, block.Transactions, 2)
 
-	internalKey, err := btcec.ParsePubKey(fetchResp.AnchorTxOutInternalKey)
+	internalKey, err := btcec.ParsePubKey(fetchResp.ChainData.InternalKey)
 	require.NoError(t.t, err)
 
 	expectedTxOut, _, err := supplycommit.RootCommitTxOut(
@@ -415,7 +426,9 @@ func testSupplyCommitIgnoreAsset(t *harnessTest) {
 	}
 
 	require.True(t.t, foundCommitTxOut)
-	require.EqualValues(t.t, actualBlockTxIndex, fetchResp.BlockTxIndex)
+	require.EqualValues(
+		t.t, actualBlockTxIndex, fetchResp.ChainData.TxIndex,
+	)
 
 	// If we try to ignore the same asset outpoint using the secondary
 	// node, it should fail because the secondary node does not have access