commitment: support AltLeaf trimming and merging

In this commit, we add logic to handle adding and removing altLeaves
from a TapCommitment. Unlike normal Assets, we never want to update an
AltLeaf once inserted into the AltCommitment. This means we need to
assert that AltLeaves being added to a TapCommitment don't collide with
already committed AltLeaves.

Author: jharveyb

commitment/commitment_test.go

@@ -1164,7 +1164,7 @@ func TestUpdateTapCommitment(t *testing.T) {
 	groupKey1 := asset.RandGroupKey(t, genesis1, protoAsset1)
 	groupKey2 := asset.RandGroupKey(t, genesis2, protoAsset2)
 
-	// We also create a thirds asset which is in the same group as the first
+	// We also create a third asset which is in the same group as the first
 	// one, to ensure that we can properly create Taproot Asset commitments
 	// from asset commitments of the same group.
 	genesis3 := asset.RandGenesis(t, asset.Normal)
@@ -1316,6 +1316,90 @@ func TestUpdateTapCommitment(t *testing.T) {
 	)
 }
 
+// TestTapCommitmentAltLeaves asserts that we can properly fetch, trim, and
+// merge alt leaves to and from a TapCommitment.
+func TestTapCommitmentAltLeaves(t *testing.T) {
+	t.Parallel()
+
+	// Create two random assets, to populate our Tap commitment.
+	asset1 := asset.RandAsset(t, asset.Normal)
+	asset2 := asset.RandAsset(t, asset.Collectible)
+
+	// We'll create three AltLeaves. Leaves 1 and 2 are valid, and leaf 3
+	// will collide with leaf 1.
+	leaf1 := asset.RandAltLeaf(t)
+	leaf2 := asset.RandAltLeaf(t)
+	leaf3 := asset.RandAltLeaf(t)
+	leaf3.ScriptKey.PubKey = leaf1.ScriptKey.PubKey
+	leaf4 := asset.RandAltLeaf(t)
+
+	// Create our initial, asset-only, Tap commitment.
+	commitment, err := FromAssets(nil, asset1, asset2)
+	require.NoError(t, err)
+	assetOnlyTapLeaf := commitment.TapLeaf()
+
+	// If we try to trim any alt leaves, we should get none back.
+	_, altLeaves, err := TrimAltLeaves(commitment)
+	require.NoError(t, err)
+	require.Empty(t, altLeaves)
+
+	// Trying to merge colliding alt leaves should fail.
+	err = commitment.MergeAltLeaves([]asset.AltLeaf[asset.Asset]{
+		leaf1, leaf3,
+	})
+	require.ErrorIs(t, err, asset.ErrDuplicateAltLeafKey)
+
+	// Merging non-colliding, valid alt leaves should succeed. The new
+	// commitment should contain three AssetCommitments, since we've created
+	// an AltCommitment.
+	err = commitment.MergeAltLeaves([]asset.AltLeaf[asset.Asset]{
+		leaf1, leaf2,
+	})
+	require.NoError(t, err)
+	require.Len(t, commitment.assetCommitments, 3)
+
+	// Trying to merge an alt leaf that will collide with an existing leaf
+	// should also fail.
+	err = commitment.MergeAltLeaves([]asset.AltLeaf[asset.Asset]{leaf3})
+	require.ErrorIs(t, err, asset.ErrDuplicateAltLeafKey)
+
+	// Merging a valid, non-colliding, new alt leaf into an existing
+	// AltCommitment should succeed.
+	err = commitment.MergeAltLeaves([]asset.AltLeaf[asset.Asset]{leaf4})
+	require.NoError(t, err)
+
+	// If we fetch the alt leaves, they should not be removed from the
+	// commitment.
+	finalTapLeaf := commitment.TapLeaf()
+	fetchedAltLeaves, err := commitment.FetchAltLeaves()
+	require.NoError(t, err)
+	require.Equal(t, finalTapLeaf, commitment.TapLeaf())
+	insertedAltLeaves := []*asset.Asset{leaf1, leaf2, leaf4}
+
+	// The fetched leaves must be equal to the three leaves we successfully
+	// inserted.
+	asset.CompareAltLeaves(
+		t, asset.ToAltLeaves(insertedAltLeaves),
+		asset.ToAltLeaves(fetchedAltLeaves),
+	)
+
+	// Now, if we trim out the alt leaves, the AltCommitment should be fully
+	// removed.
+	originalCommitment, _, err := TrimAltLeaves(commitment)
+	require.NoError(t, err)
+
+	trimmedTapLeaf := originalCommitment.TapLeaf()
+	require.NotEqual(t, finalTapLeaf, trimmedTapLeaf)
+	require.Equal(t, assetOnlyTapLeaf, trimmedTapLeaf)
+
+	// The trimmed leaves should match the leaves we successfully merged
+	// into the commitment.
+	asset.CompareAltLeaves(
+		t, asset.ToAltLeaves(fetchedAltLeaves),
+		asset.ToAltLeaves(insertedAltLeaves),
+	)
+}
+
 // TestAssetCommitmentDeepCopy tests that we're able to properly perform a deep
 // copy of a given asset commitment.
 func TestAssetCommitmentDeepCopy(t *testing.T) {

commitment/tap.go

@@ -662,3 +662,102 @@ func TrimSplitWitnesses(version *TapCommitmentVersion,
 
 	return tapCommitment, nil
 }
+
+// TrimAltLeaves creates a new TapCommitment with any AltLeaves removed, if
+// present. The removed AltLeaves are returned separately.
+func TrimAltLeaves(c *TapCommitment) (*TapCommitment, []*asset.Asset, error) {
+	altAssets, err := c.FetchAltLeaves()
+	if err != nil {
+		return nil, nil, fmt.Errorf("cannot trim: %w", err)
+	}
+
+	// Remove the AltCommitment and reconstruct the Tap commitment.
+	allCommitments := c.Commitments()
+	delete(allCommitments, asset.EmptyGenesisID)
+
+	tapCommitment, err := NewTapCommitment(
+		&c.Version, maps.Values(allCommitments)...,
+	)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return tapCommitment, altAssets, nil
+}
+
+// FetchAltLeaves returns a copy of any AltLeaves present in the TapCommitment.
+func (c *TapCommitment) FetchAltLeaves() ([]*asset.Asset, error) {
+	if c.assetCommitments == nil {
+		return nil, errors.New("tap commitment has no leaves")
+	}
+
+	altCommit := c.assetCommitments[asset.EmptyGenesisID]
+	if altCommit == nil {
+		return nil, nil
+	}
+
+	return maps.Values(altCommit.Assets()), nil
+}
+
+// MergeAltLeaves adds a set of AltLeaves to an existing TapCommitment. Merging
+// fails if the new AltLeaves collide with any existing AltLeaves.
+func (c *TapCommitment) MergeAltLeaves(
+	altLeaves []asset.AltLeaf[asset.Asset]) error {
+
+	if len(altLeaves) == 0 {
+		return nil
+	}
+
+	// First, check that the given alt leaves have unique
+	// AssetCommitmentKeys.
+	newLeafKeys := asset.NewLeafKeySet()
+	err := asset.AddLeafKeysVerifyUnique(newLeafKeys, altLeaves)
+	if err != nil {
+		return err
+	}
+
+	// Check if any alt leaves are already present.
+	var currentAltCommit *AssetCommitment
+	if c.assetCommitments != nil {
+		currentAltCommit = c.assetCommitments[asset.EmptyGenesisID]
+		if currentAltCommit != nil {
+			currentLeaves := currentAltCommit.Assets()
+
+			// If any alt leaves are already committed, new alt
+			// leaves must not collide with existing alt leaves.
+			for leafKey := range currentLeaves {
+				if newLeafKeys.Contains(leafKey) {
+					return fmt.Errorf("%w: existing alt "+
+						"leaf: %x",
+						asset.ErrDuplicateAltLeafKey,
+						leafKey)
+				}
+			}
+		}
+	}
+
+	// None of the new or existing alt leaves collide; we can now update
+	// the AltCommitment and Tap commitment.
+	if currentAltCommit == nil {
+		currentAltCommit, err = NewAssetCommitment(
+			altLeaves[0].(*asset.Asset),
+		)
+		if err != nil {
+			return err
+		}
+	}
+
+	for _, newLeaf := range altLeaves {
+		err := currentAltCommit.Upsert(newLeaf.(*asset.Asset))
+		if err != nil {
+			return err
+		}
+	}
+
+	err = c.Upsert(currentAltCommit)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}