asset: add AltLeaf type and encoder

In this commit, we add the AltLeaf interface, which is used to carry
non-Asset data inside a Tap commitment. The Asset type meets this
interface, and we add a separate encoder that removes static fields for
an Asset being used as an AltLeaf.

Author: jharveyb

asset/asset.go

@@ -106,6 +106,9 @@ var (
 	// asset split leaves.
 	ZeroPrevID PrevID
 
+	// EmptyGenesis is the empty Genesis struct used for alt leaves.
+	EmptyGenesis Genesis
+
 	// NUMSBytes is the NUMs point we'll use for un-spendable script keys.
 	// It was generated via a try-and-increment approach using the phrase
 	// "taproot-assets" with SHA2-256. The code for the try-and-increment
@@ -2238,3 +2241,137 @@ type ChainAsset struct {
 	// available for coin selection.
 	AnchorLeaseExpiry *time.Time
 }
+
+// An AltLeaf is a type that is used to carry arbitrary data, and does not
+// represent a Taproot asset. An AltLeaf can be used to anchor other protocols
+// alongside Taproot Asset transactions.
+type AltLeaf[T any] interface {
+	// Copyable asserts that the target type of this interface satisfies
+	// the Copyable interface.
+	fn.Copyable[T]
+
+	// ValidateAltLeaf ensures that an AltLeaf is valid.
+	ValidateAltLeaf() error
+
+	// EncodeAltLeaf encodes an AltLeaf into a TLV stream.
+	EncodeAltLeaf(w io.Writer) error
+
+	// DecodeAltLeaf decodes an AltLeaf from a TLV stream.
+	DecodeAltLeaf(r io.Reader) error
+}
+
+// NewAltLeaf instantiates a new valid AltLeaf.
+func NewAltLeaf(key ScriptKey, keyVersion ScriptVersion,
+	prevWitness []Witness) (*Asset, error) {
+
+	if key.PubKey == nil {
+		return nil, fmt.Errorf("script key must be non-nil")
+	}
+
+	return &Asset{
+		Version:             V0,
+		Genesis:             EmptyGenesis,
+		Amount:              0,
+		LockTime:            0,
+		RelativeLockTime:    0,
+		PrevWitnesses:       prevWitness,
+		SplitCommitmentRoot: nil,
+		GroupKey:            nil,
+		ScriptKey:           key,
+		ScriptVersion:       keyVersion,
+	}, nil
+}
+
+// CopyAltLeaf performs a deep copy of an AltLeaf.
+func CopyAltLeaf[T AltLeaf[T]](a AltLeaf[T]) AltLeaf[T] {
+	return a.Copy()
+}
+
+// CopyAltLeaves performs a deep copy of an AltLeaf slice.
+func CopyAltLeaves[T AltLeaf[T]](a []AltLeaf[T]) []AltLeaf[T] {
+	return fn.Map(a, CopyAltLeaf[T])
+}
+
+// Validate checks that an Asset is a valid AltLeaf. An Asset used as an AltLeaf
+// must meet these constraints:
+// - Version must be V0.
+// - Genesis must be the empty Genesis.
+// - Amount, LockTime, and RelativeLockTime must be 0.
+// - SplitCommitmentRoot and GroupKey must be nil.
+// - ScriptKey must be non-nil.
+func (a *Asset) ValidateAltLeaf() error {
+	if a.Version != V0 {
+		return fmt.Errorf("alt leaf version must be 0")
+	}
+
+	if a.Genesis != EmptyGenesis {
+		return fmt.Errorf("alt leaf genesis must be the empty genesis")
+	}
+
+	if a.Amount != 0 {
+		return fmt.Errorf("alt leaf amount must be 0")
+	}
+
+	if a.LockTime != 0 {
+		return fmt.Errorf("alt leaf lock time must be 0")
+	}
+
+	if a.RelativeLockTime != 0 {
+		return fmt.Errorf("alt leaf relative lock time must be 0")
+	}
+
+	if a.SplitCommitmentRoot != nil {
+		return fmt.Errorf(
+			"alt leaf split commitment root must be empty",
+		)
+	}
+
+	if a.GroupKey != nil {
+		return fmt.Errorf("alt leaf group key must be empty")
+	}
+
+	if a.ScriptKey.PubKey == nil {
+		return fmt.Errorf("alt leaf script key must be non-nil")
+	}
+
+	return nil
+}
+
+// encodeAltLeafRecords determines the set of non-nil records to include when
+// encoding an AltLeaf. Since the Genesis, Group Key, Amount, and Version fields
+// are static, we can omit those fields.
+func (a *Asset) encodeAltLeafRecords() []tlv.Record {
+	records := make([]tlv.Record, 0, 3)
+
+	// Always use the normal witness encoding, since the asset version is
+	// always V0.
+	if len(a.PrevWitnesses) > 0 {
+		records = append(records, NewLeafPrevWitnessRecord(
+			&a.PrevWitnesses, EncodeNormal,
+		))
+	}
+	records = append(records, NewLeafScriptVersionRecord(&a.ScriptVersion))
+	records = append(records, NewLeafScriptKeyRecord(&a.ScriptKey.PubKey))
+
+	// Add any unknown odd types that were encountered during decoding.
+	return CombineRecords(records, a.UnknownOddTypes)
+}
+
+// EncodeAltLeaf encodes an AltLeaf into a TLV stream.
+func (a *Asset) EncodeAltLeaf(w io.Writer) error {
+	stream, err := tlv.NewStream(a.encodeAltLeafRecords()...)
+	if err != nil {
+		return err
+	}
+	return stream.Encode(w)
+}
+
+// DecodeAltLeaf decodes an AltLeaf from a TLV stream. The normal Asset decoder
+// can be reused here, since any Asset field not encoded in the AltLeaf will
+// be set to its default value, which matches the AltLeaf validity constraints.
+func (a *Asset) DecodeAltLeaf(r io.Reader) error {
+	return a.Decode(r)
+}
+
+// Ensure Asset implements the AltLeaf interface.
+var _ AltLeaf[*Asset] = (*Asset)(nil)

asset/encoding.go

@@ -32,6 +32,10 @@ var (
 	// ErrByteSliceTooLarge is returned when an encoded byte slice is too
 	// large.
 	ErrByteSliceTooLarge = errors.New("bytes: too large")
+
+	// ErrDuplicateScriptKeys is returned when two alt leaves have the same
+	// script key.
+	ErrDuplicateScriptKeys = errors.New("alt leaf: duplicate script keys")
 )
 
 func VarIntEncoder(w io.Writer, val any, buf *[8]byte) error {
@@ -803,3 +807,91 @@ func DecodeTapLeaf(leafData []byte) (*txscript.TapLeaf, error) {
 
 	return &leaf, nil
 }
+
+func AltLeavesEncoder(w io.Writer, val any, buf *[8]byte) error {
+	if t, ok := val.(*[]AltLeaf[*Asset]); ok {
+		if err := tlv.WriteVarInt(w, uint64(len(*t)), buf); err != nil {
+			return err
+		}
+
+		var streamBuf bytes.Buffer
+		leafKeys := make(map[SerializedKey]struct{})
+		for _, leaf := range *t {
+			// Check that this leaf has a unique script key compared
+			// to all previous leaves. This type assertion is safe
+			// as we've made an equivalent assertion above.
+			leafKey := ToSerialized(leaf.(*Asset).ScriptKey.PubKey)
+			_, ok := leafKeys[leafKey]
+			if ok {
+				return fmt.Errorf("%w: %x",
+					ErrDuplicateScriptKeys, leafKey)
+			}
+
+			leafKeys[leafKey] = struct{}{}
+			err := leaf.EncodeAltLeaf(&streamBuf)
+			if err != nil {
+				return err
+			}
+			streamBytes := streamBuf.Bytes()
+			err = InlineVarBytesEncoder(w, &streamBytes, buf)
+			if err != nil {
+				return err
+			}
+
+			streamBuf.Reset()
+		}
+		return nil
+	}
+	return tlv.NewTypeForEncodingErr(val, "[]AltLeaf")
+}
+
+func AltLeavesDecoder(r io.Reader, val any, buf *[8]byte, l uint64) error {
+	// There is no limit on the number of alt leaves, but the total size of
+	// all alt leaves must be below 64 KiB.
+	if l > math.MaxUint16 {
+		return tlv.ErrRecordTooLarge
+	}
+
+	if typ, ok := val.(*[]AltLeaf[*Asset]); ok {
+		// Each alt leaf is at least 42 bytes, which limits the total
+		// number of aux leaves. So we don't need to enforce a strict
+		// limit here.
+		numItems, err := tlv.ReadVarInt(r, buf)
+		if err != nil {
+			return err
+		}
+
+		leaves := make([]AltLeaf[*Asset], 0, numItems)
+		leafKeys := make(map[SerializedKey]struct{})
+		for i := uint64(0); i < numItems; i++ {
+			var streamBytes []byte
+			err = InlineVarBytesDecoder(
+				r, &streamBytes, buf, math.MaxUint16,
+			)
+			if err != nil {
+				return err
+			}
+
+			var leaf Asset
+			err = leaf.DecodeAltLeaf(bytes.NewReader(streamBytes))
+			if err != nil {
+				return err
+			}
+
+			// Check that each alt leaf has a unique script key.
+			leafKey := ToSerialized(leaf.ScriptKey.PubKey)
+			_, ok := leafKeys[leafKey]
+			if ok {
+				return fmt.Errorf("%w: %x",
+					ErrDuplicateScriptKeys, leafKey)
+			}
+
+			leafKeys[leafKey] = struct{}{}
+			leaves = append(leaves, AltLeaf[*Asset](&leaf))
+		}
+
+		*typ = leaves
+		return nil
+	}
+	return tlv.NewTypeForEncodingErr(val, "[]*AltLeaf")
+}