Merge pull request #1839 from lightninglabs/wip/1833-extend-rpc-supply-leaves-with-block-data

Add block header support to supply RPCs and related integration tests

Author: ffranr

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

@@ -179,6 +179,15 @@
   configured with public read access. This matches the behavior of the  
   existing FetchSupplyCommit RPC endpoint.
 
+- [PR#1839](https://github.com/lightninglabs/taproot-assets/pull/1839) The
+  `FetchSupplyLeaves` and `FetchSupplyCommit` RPC endpoints now
+  include a new `block_headers` field. This field is a map from block
+  height to a `SupplyLeafBlockHeader` message, which provides the block
+  header timestamp (in seconds since the Unix epoch) and the 32-byte
+  block header hash. This allows clients to obtain block timing and hash
+  information directly from the RPC response without performing separate
+  blockchain queries.
+
 ## tapcli Additions
 
 - [Rename](https://github.com/lightninglabs/taproot-assets/pull/1682) the mint

itest/assertions.go

@@ -2882,3 +2882,20 @@ func WaitForSupplyCommit(t *testing.T, ctx context.Context,
 
 	return fetchResp, supplyCommitOutpoint
 }
+
+// AssertSupplyLeafBlockHeaders makes sure that the given block header exists
+// in the map of block headers and that its contents matches the expected
+// values.
+func AssertSupplyLeafBlockHeaders(t *testing.T, expectedBlockHeight uint32,
+	expectedTimestamp int64, expectedBlockHash chainhash.Hash,
+	actualBlockHeaders map[uint32]*unirpc.SupplyLeafBlockHeader) {
+
+	actualBlockMeta, ok := actualBlockHeaders[expectedBlockHeight]
+	require.True(t, ok, "no block header for height %d",
+		expectedBlockHeight)
+
+	require.EqualValues(
+		t, fn.ByteSlice(expectedBlockHash), actualBlockMeta.Hash,
+	)
+	require.EqualValues(t, expectedTimestamp, actualBlockMeta.Timestamp)
+}

itest/supply_commit_test.go

@@ -17,6 +17,7 @@ import (
 	"github.com/lightninglabs/taproot-assets/fn"
 	"github.com/lightninglabs/taproot-assets/itest/rpcassert"
 	"github.com/lightninglabs/taproot-assets/mssmt"
+	"github.com/lightninglabs/taproot-assets/proof"
 	"github.com/lightninglabs/taproot-assets/tapgarden"
 	"github.com/lightninglabs/taproot-assets/taprpc"
 	"github.com/lightninglabs/taproot-assets/taprpc/mintrpc"
@@ -1044,7 +1045,9 @@ func testSupplyCommitMintBurn(t *harnessTest) {
 //  4. Calling FetchSupplyLeaves to verify burn leaves are included.
 //  5. Minting another tranche into the same group.
 //  6. Calling FetchSupplyLeaves to verify all leaves are present.
-//  7. Testing inclusion proof generation for various leaf types.
+//  7. Ignoring an asset outpoint from the second mint.
+//  8. Calling FetchSupplyLeaves to verify ignore leaves are included.
+//  9. Testing inclusion proof generation for various leaf types.
 func testFetchSupplyLeaves(t *harnessTest) {
 	ctxb := context.Background()
 
@@ -1105,6 +1108,30 @@ func testFetchSupplyLeaves(t *harnessTest) {
 		"issuance leaf amount mismatch",
 	)
 
+	actualMintEvent := new(supplycommit.NewMintEvent)
+	err = actualMintEvent.Decode(bytes.NewReader(issuanceLeaf1.RawLeaf))
+	require.NoError(t.t, err)
+
+	// Compare the issuance leaf proof block details with those given in
+	// *unirpc.SupplyLeafBlockHeader message field.
+	//
+	// Decode the block header from the issuance raw proof.
+	var actualBlockHeader wire.BlockHeader
+	err = proof.SparseDecode(
+		bytes.NewReader(actualMintEvent.IssuanceProof.RawProof),
+		proof.BlockHeaderRecord(&actualBlockHeader),
+	)
+	require.NoError(t.t, err)
+
+	proofBlockHeight := actualMintEvent.BlockHeight()
+	proofBlockTimestamp := actualBlockHeader.Timestamp.Unix()
+	proofBlockHash := actualBlockHeader.BlockHash()
+
+	AssertSupplyLeafBlockHeaders(
+		t.t, proofBlockHeight, proofBlockTimestamp, proofBlockHash,
+		leavesResp1.BlockHeaders,
+	)
+
 	t.Log("Burning portion of the asset")
 	const (
 		burnAmt  = 1500
@@ -1177,6 +1204,24 @@ func testFetchSupplyLeaves(t *harnessTest) {
 	require.EqualValues(t.t, burnAmt, burnLeaf.LeafNode.RootSum,
 		"burn leaf amount mismatch")
 
+	// Compare the burn leaf proof block details with those given in
+	// *unirpc.SupplyLeafBlockHeader message field.
+	//
+	// Decode the burn raw proof.
+	actualBurnEvent := new(supplycommit.NewBurnEvent)
+	err = actualBurnEvent.Decode(bytes.NewReader(burnLeaf.RawLeaf))
+	require.NoError(t.t, err)
+
+	proofBlockHeight = actualBurnEvent.BurnProof.BlockHeight
+	proofBlockTimestamp =
+		actualBurnEvent.BurnProof.BlockHeader.Timestamp.Unix()
+	proofBlockHash = actualBurnEvent.BurnProof.BlockHeader.BlockHash()
+
+	AssertSupplyLeafBlockHeaders(
+		t.t, proofBlockHeight, proofBlockTimestamp, proofBlockHash,
+		leavesResp2.BlockHeaders,
+	)
+
 	t.Log("Minting second tranche into the same asset group")
 	secondMintReq := &mintrpc.MintAssetRequest{
 		Asset: &mintrpc.MintAsset{
@@ -1216,7 +1261,7 @@ func testFetchSupplyLeaves(t *harnessTest) {
 	expectedIssuanceTotal := int64(
 		mintReq.Asset.Amount + secondMintReq.Asset.Amount,
 	)
-	_, _ = WaitForSupplyCommit(
+	_, supplyOutpoint = WaitForSupplyCommit(
 		t.t, ctxb, t.tapd, groupKeyBytes, fn.Some(supplyOutpoint),
 		func(resp *unirpc.FetchSupplyCommitResponse) bool {
 			return resp.IssuanceSubtreeRoot != nil &&
@@ -1259,6 +1304,103 @@ func testFetchSupplyLeaves(t *harnessTest) {
 		"total issuance amount mismatch",
 	)
 
+	t.Log("Ignoring an asset outpoint from the second mint")
+
+	// Get the outpoint from the second minted asset to ignore it.
+	// We must ignore the entire asset at the outpoint, not just a portion.
+	ignoreAmount := rpcSecondAsset[0].Amount
+	ignoreAssetOutpoint := taprpc.AssetOutPoint{
+		AnchorOutPoint: rpcSecondAsset[0].ChainAnchor.AnchorOutpoint,
+		AssetId:        rpcSecondAsset[0].AssetGenesis.AssetId,
+		ScriptKey:      rpcSecondAsset[0].ScriptKey,
+	}
+	ignoreReq := &unirpc.IgnoreAssetOutPointRequest{
+		AssetOutPoint: &ignoreAssetOutpoint,
+		Amount:        ignoreAmount,
+	}
+
+	respIgnore, err := t.tapd.IgnoreAssetOutPoint(ctxb, ignoreReq)
+	require.NoError(t.t, err)
+	require.NotNil(t.t, respIgnore)
+	require.EqualValues(t.t, ignoreAmount, respIgnore.Leaf.RootSum)
+
+	t.Log("Updating supply commitment after ignoring asset outpoint")
+	UpdateAndMineSupplyCommit(
+		t.t, ctxb, t.tapd, t.lndHarness.Miner().Client,
+		groupKeyBytes, 1,
+	)
+
+	t.Log("Wait for the supply commitment to include the ignored outpoint.")
+	_, _ = WaitForSupplyCommit(
+		t.t, ctxb, t.tapd, groupKeyBytes, fn.Some(supplyOutpoint),
+		func(resp *unirpc.FetchSupplyCommitResponse) bool {
+			if resp.IgnoreSubtreeRoot == nil {
+				return false
+			}
+
+			return resp.IgnoreSubtreeRoot.RootNode.RootSum ==
+				int64(ignoreAmount)
+		},
+	)
+
+	t.Log("Fetching supply leaves after ignoring asset outpoint")
+	req = unirpc.FetchSupplyLeavesRequest{
+		GroupKey: &unirpc.FetchSupplyLeavesRequest_GroupKeyBytes{
+			GroupKeyBytes: groupKeyBytes,
+		},
+	}
+	leavesResp4, err := t.tapd.FetchSupplyLeaves(ctxb, &req)
+	require.NoError(t.t, err)
+	require.NotNil(t.t, leavesResp4)
+
+	// Verify we have two issuance leaves, one burn leaf, and one ignore
+	// leaf.
+	require.Len(
+		t.t, leavesResp4.IssuanceLeaves, 2,
+		"expected 2 issuance leaves after ignore",
+	)
+	require.Len(
+		t.t, leavesResp4.BurnLeaves, 1,
+		"expected 1 burn leaf after ignore",
+	)
+	require.Len(
+		t.t, leavesResp4.IgnoreLeaves, 1,
+		"expected 1 ignore leaf after ignore",
+	)
+
+	// Verify the ignore leaf amount.
+	ignoreLeaf := leavesResp4.IgnoreLeaves[0]
+	require.EqualValues(
+		t.t, ignoreAmount, ignoreLeaf.LeafNode.RootSum,
+		"ignore leaf amount mismatch",
+	)
+
+	// Compare the ignore leaf block data with that given in
+	// *unirpc.SupplyLeafBlockHeader message field.
+	//
+	// TODO(ffranr): Extend t.lndHarness.Miner() with
+	//  GetBlockHeaderByHeight and use here.
+	//
+	// We can't retrieve the block header from the miner based on block
+	// height, so we fetch it given the block hash in the field we are
+	// testing. This is not ideal, but it covers timestamp and height
+	// verification.
+	expectedBlockHeight := ignoreLeaf.BlockHeight
+	ignoreLeafBlockHeader :=
+		leavesResp4.BlockHeaders[expectedBlockHeight]
+
+	ignoreBlockHash, err := chainhash.NewHash(ignoreLeafBlockHeader.Hash)
+	require.NoError(t.t, err)
+
+	ignoreLeafBlock := t.lndHarness.Miner().GetBlock(ignoreBlockHash)
+	require.NotNil(t.t, ignoreLeafBlock)
+	expectedBlockTimestamp := ignoreLeafBlock.Header.Timestamp.Unix()
+
+	AssertSupplyLeafBlockHeaders(
+		t.t, expectedBlockHeight, expectedBlockTimestamp,
+		*ignoreBlockHash, leavesResp4.BlockHeaders,
+	)
+
 	t.Log("Testing inclusion proof generation for supply leaves")
 
 	// Collect leaf keys for inclusion proof request.

lndservices/chain_bridge.go

@@ -151,6 +151,50 @@ func (l *LndRpcChainBridge) GetBlockHeader(ctx context.Context,
 	)
 }
 
+// GetBlockHeaderByHeight returns a block header given the block height.
+func (l *LndRpcChainBridge) GetBlockHeaderByHeight(ctx context.Context,
+	blockHeight int64) (*wire.BlockHeader, error) {
+
+	// First, we need to resolve the block hash at the given height.
+	blockHash, err := fn.RetryFuncN(
+		ctx, l.retryConfig, func() (chainhash.Hash, error) {
+			var zero chainhash.Hash
+
+			blockHash, err := l.lnd.ChainKit.GetBlockHash(
+				ctx, blockHeight,
+			)
+			if err != nil {
+				return zero, fmt.Errorf(
+					"unable to retrieve block hash: %w",
+					err,
+				)
+			}
+
+			return blockHash, nil
+		},
+	)
+	if err != nil {
+		return nil, fmt.Errorf("unable to retrieve block hash: %w", err)
+	}
+
+	// Now that we have the block hash, we can fetch the block header.
+	return fn.RetryFuncN(
+		ctx, l.retryConfig, func() (*wire.BlockHeader, error) {
+			header, err := l.lnd.ChainKit.GetBlockHeader(
+				ctx, blockHash,
+			)
+			if err != nil {
+				return nil, fmt.Errorf(
+					"unable to retrieve block header: %w",
+					err,
+				)
+			}
+
+			return header, nil
+		},
+	)
+}
+
 // GetBlockHash returns the hash of the block in the best blockchain at the
 // given height.
 func (l *LndRpcChainBridge) GetBlockHash(ctx context.Context,

rpcserver.go

@@ -4282,6 +4282,17 @@ func (r *rpcServer) FetchSupplyCommit(ctx context.Context,
 			"outstanding supply: %w", err)
 	}
 
+	// Extract block headers for all block heights that have supply leaves.
+	// And then marshal them into the RPC format.
+	heightHeaderMap, err := supplycommit.ExtractSupplyLeavesBlockHeaders(
+		ctx, r.cfg.ChainBridge, commit.Leaves,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("failed to extract block headers for "+
+			"supply leaves: %w", err)
+	}
+	rpcHeightHeaderMap := marshalSupplyLeafBlockHeaders(heightHeaderMap)
+
 	return &unirpc.FetchSupplyCommitResponse{
 		ChainData:       chainData,
 		TxChainFeesSats: commitBlock.ChainFees,
@@ -4296,6 +4307,8 @@ func (r *rpcServer) FetchSupplyCommit(ctx context.Context,
 
 		TotalOutstandingSupply:  totalOutstandingSupply,
 		SpentCommitmentOutpoint: spentCommitmentOutpoint,
+
+		BlockHeaders: rpcHeightHeaderMap,
 	}, nil
 }
 
@@ -4339,6 +4352,25 @@ func marshalSupplyLeaves(
 	return rpcIssuanceLeaves, rpcBurnLeaves, rpcIgnoreLeaves, nil
 }
 
+// marshalSupplyLeafBlockHeaders converts a map of block heights to block
+// headers into a map of block heights to RPC SupplyLeafBlockHeader objects.
+//
+// nolint: lll
+func marshalSupplyLeafBlockHeaders(
+	heightHeaderMap map[uint32]wire.BlockHeader) map[uint32]*unirpc.SupplyLeafBlockHeader {
+
+	rpcHeightHeader := make(map[uint32]*unirpc.SupplyLeafBlockHeader)
+
+	for height, header := range heightHeaderMap {
+		rpcHeightHeader[height] = &unirpc.SupplyLeafBlockHeader{
+			Timestamp: header.Timestamp.Unix(),
+			Hash:      fn.ByteSlice(header.BlockHash()),
+		}
+	}
+
+	return rpcHeightHeader
+}
+
 // FetchSupplyLeaves fetches the supply leaves for a specific asset group
 // within a specified block height range. The leaves include issuance, burn,
 // and ignore leaves, which represent the supply changes for the asset group.
@@ -4433,13 +4465,25 @@ func (r *rpcServer) FetchSupplyLeaves(ctx context.Context,
 		}
 	}
 
+	// Extract block headers for all block heights that have supply leaves.
+	// And then marshal them into the RPC format.
+	heightHeaderMap, err := supplycommit.ExtractSupplyLeavesBlockHeaders(
+		ctx, r.cfg.ChainBridge, resp,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("failed to extract block headers for "+
+			"supply leaves: %w", err)
+	}
+	rpcHeightHeaderMap := marshalSupplyLeafBlockHeaders(heightHeaderMap)
+
 	return &unirpc.FetchSupplyLeavesResponse{
 		IssuanceLeaves:              issuanceLeaves,
 		BurnLeaves:                  burnLeaves,
 		IgnoreLeaves:                ignoreLeaves,
 		IssuanceLeafInclusionProofs: issuanceInclusionProofs,
 		BurnLeafInclusionProofs:     burnInclusionProofs,
 		IgnoreLeafInclusionProofs:   ignoreInclusionProofs,
+		BlockHeaders:                rpcHeightHeaderMap,
 	}, nil
 }
 

tapgarden/interface.go

@@ -350,6 +350,10 @@ type ChainBridge interface {
 	// height.
 	GetBlockTimestamp(context.Context, uint32) int64
 
+	// GetBlockHeaderByHeight returns a block header given the block height.
+	GetBlockHeaderByHeight(ctx context.Context,
+		blockHeight int64) (*wire.BlockHeader, error)
+
 	// PublishTransaction attempts to publish a new transaction to the
 	// network.
 	PublishTransaction(context.Context, *wire.MsgTx, string) error

tapgarden/mock.go

@@ -688,6 +688,13 @@ func (m *MockChainBridge) GetBlock(ctx context.Context,
 	return block, nil
 }
 
+// GetBlockHeaderByHeight returns a block header given the block height.
+func (m *MockChainBridge) GetBlockHeaderByHeight(ctx context.Context,
+	blockHeight int64) (*wire.BlockHeader, error) {
+
+	return &wire.BlockHeader{}, nil
+}
+
 // GetBlockHash returns the hash of the block in the best blockchain at the
 // given height.
 func (m *MockChainBridge) GetBlockHash(ctx context.Context,