multi: add type to script key

With this commit we add a type enum to the script key. This will mostly
be used on the database level to filter assets when listing or
calculating balances.
We can only be 100% certain about the type of a key in the case of
BIP-0086 or where we explicitly create them in the tapchannel package.
Anything else is a bit of a guess, since the keys are coming over the
RPC interface. So we just assume any key that has a non-empty script
path is an externally-defined (external app) script spend.

This heuristic should be good enough to filter out channel related
assets or assets that can't be spent without external instructions in
balance RPC calls.

Author: guggero

address/book.go

@@ -140,7 +140,7 @@ type Storage interface {
 	// being relevant for the local wallet (e.g. show assets received on
 	// this key in the asset list and balances).
 	InsertScriptKey(ctx context.Context, scriptKey asset.ScriptKey,
-		declareAsKnown bool) error
+		declareAsKnown bool, keyType asset.ScriptKeyType) error
 }
 
 // KeyRing is used to create script and internal keys for Taproot Asset
@@ -401,7 +401,12 @@ func (b *Book) NewAddressWithKeys(ctx context.Context, addrVersion Version,
 	if err != nil {
 		return nil, fmt.Errorf("unable to insert internal key: %w", err)
 	}
-	err = b.cfg.Store.InsertScriptKey(ctx, scriptKey, true)
+
+	// We might not know the type of script key, if it was given to us
+	// through an RPC call. So we make a guess here.
+	keyType := scriptKey.GuessType()
+
+	err = b.cfg.Store.InsertScriptKey(ctx, scriptKey, true, keyType)
 	if err != nil {
 		return nil, fmt.Errorf("unable to insert script key: %w", err)
 	}
@@ -438,9 +443,11 @@ func (b *Book) IsLocalKey(ctx context.Context,
 
 // InsertScriptKey inserts an address related script key into the database.
 func (b *Book) InsertScriptKey(ctx context.Context, scriptKey asset.ScriptKey,
-	declareAsKnown bool) error {
+	declareAsKnown bool, keyType asset.ScriptKeyType) error {
 
-	return b.cfg.Store.InsertScriptKey(ctx, scriptKey, declareAsKnown)
+	return b.cfg.Store.InsertScriptKey(
+		ctx, scriptKey, declareAsKnown, keyType,
+	)
 }
 
 // NextInternalKey derives then inserts an internal key into the database to
@@ -475,7 +482,9 @@ func (b *Book) NextScriptKey(ctx context.Context,
 	}
 
 	scriptKey := asset.NewScriptKeyBip86(keyDesc)
-	err = b.cfg.Store.InsertScriptKey(ctx, scriptKey, true)
+	err = b.cfg.Store.InsertScriptKey(
+		ctx, scriptKey, true, asset.ScriptKeyBip86,
+	)
 	if err != nil {
 		return asset.ScriptKey{}, err
 	}

asset/asset.go

@@ -108,6 +108,50 @@ const (
 	EncodeSegwit
 )
 
+// ScriptKeyType denotes the type of script key used for an asset. This type is
+// serialized to the database, so we don't use iota for the values to ensure
+// they don't change by accident.
+type ScriptKeyType uint8
+
+const (
+	// ScriptKeyUnknown is the default script key type used for assets that
+	// we don't know the type of. This should only be stored for assets
+	// where we don't know the internal key of the script key (e.g. for
+	// imported proofs).
+	ScriptKeyUnknown ScriptKeyType = 0
+
+	// ScriptKeyBip86 is the script key type used for assets that use the
+	// BIP86 style tweak (e.g. an empty tweak).
+	ScriptKeyBip86 ScriptKeyType = 1
+
+	// ScriptKeyScriptPathExternal is the script key type used for assets
+	// that use a script path that is defined by an external application.
+	// Keys with script paths are normally not shown in asset balances and
+	// by default aren't used for coin selection unless specifically
+	// requested.
+	ScriptKeyScriptPathExternal ScriptKeyType = 2
+
+	// ScriptKeyBurn is the script key type used for assets that are burned
+	// and not spendable.
+	ScriptKeyBurn ScriptKeyType = 3
+
+	// ScriptKeyTombstone is the script key type used for assets that are
+	// not spendable and have been marked as tombstones. This is only the
+	// case for zero-value assets that result from a non-interactive (TAP
+	// address) send where no change was left over. The script key used for
+	// this is a NUMS key that is not spendable.
+	ScriptKeyTombstone ScriptKeyType = 4
+
+	// ScriptKeyScriptPathChannel is the script key type used for assets
+	// that use a script path that is somehow related to Taproot Asset
+	// Channels. That means the script key is either a funding key
+	// (OP_TRUE), a commitment output key (to_local, to_remote, htlc), or a
+	// HTLC second-level transaction output key.
+	// Keys related to channels are not shown in asset balances (unless
+	// specifically requested) and are _never_ used for coin selection.
+	ScriptKeyScriptPathChannel ScriptKeyType = 5
+)
+
 var (
 	// ZeroPrevID is the blank prev ID used for genesis assets and also
 	// asset split leaves.
@@ -984,6 +1028,9 @@ type TweakedScriptKey struct {
 	// flag has is that assets with a declared key are shown in the asset
 	// list/balance.
 	DeclaredKnown bool
+
+	// Type is the type of script key that is being used.
+	Type ScriptKeyType
 }
 
 // IsEqual returns true is this tweaked script key is exactly equivalent to the
@@ -1069,15 +1116,49 @@ func (s *ScriptKey) HasScriptPath() bool {
 	return s.TweakedScriptKey != nil && len(s.TweakedScriptKey.Tweak) > 0
 }
 
+// GuessType tries to guess the type of the script key based on the information
+// available.
+func (s *ScriptKey) GuessType() ScriptKeyType {
+	// If we have an explicit script key type set, we can return that.
+	if s.TweakedScriptKey != nil &&
+		s.TweakedScriptKey.Type != ScriptKeyUnknown {
+
+		return s.TweakedScriptKey.Type
+	}
+
+	// If there is a known tweak, then we know that this is a script path
+	// key. We never return the channel type, since those keys should always
+	// be declared properly, and we never should need to guess their type.
+	if s.HasScriptPath() {
+		return ScriptKeyScriptPathExternal
+	}
+
+	// Is it the known NUMS key? Then this is a tombstone output.
+	if s.PubKey != nil && s.PubKey.IsEqual(NUMSPubKey) {
+		return ScriptKeyTombstone
+	}
+
+	// Do we know the internal key? Then we can check whether it is a
+	// BIP-0086 key.
+	if s.PubKey != nil && s.TweakedScriptKey != nil &&
+		s.TweakedScriptKey.RawKey.PubKey != nil {
+
+		bip86 := NewScriptKeyBip86(s.TweakedScriptKey.RawKey)
+		if bip86.PubKey.IsEqual(s.PubKey) {
+			return ScriptKeyBip86
+		}
+	}
+
+	return ScriptKeyUnknown
+}
+
 // NewScriptKey constructs a ScriptKey with only the publicly available
 // information. This resulting key may or may not have a tweak applied to it.
 func NewScriptKey(key *btcec.PublicKey) ScriptKey {
 	// Since we'll never query lnd for a tweaked key, it doesn't matter if
 	// we lose the parity information here. And this will only ever be
 	// serialized on chain in a 32-bit representation as well.
-	key, _ = schnorr.ParsePubKey(
-		schnorr.SerializePubKey(key),
-	)
+	key, _ = schnorr.ParsePubKey(schnorr.SerializePubKey(key))
 	return ScriptKey{
 		PubKey: key,
 	}
@@ -1089,9 +1170,7 @@ func NewScriptKey(key *btcec.PublicKey) ScriptKey {
 func NewScriptKeyBip86(rawKey keychain.KeyDescriptor) ScriptKey {
 	// Tweak the script key BIP-0086 style (such that we only commit to the
 	// internal key when signing).
-	tweakedPubKey := txscript.ComputeTaprootKeyNoScript(
-		rawKey.PubKey,
-	)
+	tweakedPubKey := txscript.ComputeTaprootKeyNoScript(rawKey.PubKey)
 
 	// Since we'll never query lnd for a tweaked key, it doesn't matter if
 	// we lose the parity information here. And this will only ever be
@@ -1104,6 +1183,7 @@ func NewScriptKeyBip86(rawKey keychain.KeyDescriptor) ScriptKey {
 		PubKey: tweakedPubKey,
 		TweakedScriptKey: &TweakedScriptKey{
 			RawKey: rawKey,
+			Type:   ScriptKeyBip86,
 		},
 	}
 }
@@ -1491,6 +1571,7 @@ func (a *Asset) Copy() *Asset {
 	if a.ScriptKey.TweakedScriptKey != nil {
 		assetCopy.ScriptKey.TweakedScriptKey = &TweakedScriptKey{
 			DeclaredKnown: a.ScriptKey.DeclaredKnown,
+			Type:          a.ScriptKey.Type,
 		}
 		assetCopy.ScriptKey.RawKey = a.ScriptKey.RawKey
 

asset/generators.go

@@ -74,6 +74,9 @@ var (
 			RawKey:        KeyDescGen.Draw(t, "raw_key"),
 			Tweak:         HashBytesGen.Draw(t, "tweak"),
 			DeclaredKnown: rapid.Bool().Draw(t, "declared_known"),
+			Type: ScriptKeyType(
+				rapid.Int16().Draw(t, "script_key_type"),
+			),
 		}
 	})
 	ScriptKeyGen = rapid.Custom(func(t *rapid.T) ScriptKey {

rpcserver.go

@@ -7857,7 +7857,12 @@ func (r *rpcServer) DeclareScriptKey(ctx context.Context,
 			err)
 	}
 
-	err = r.cfg.TapAddrBook.InsertScriptKey(ctx, *scriptKey, true)
+	// Because we've been given the key over the RPC interface, we can't be
+	// 100% sure of the type. But we can make a best effort guess based on
+	// the fields the user has set.
+	keyType := scriptKey.GuessType()
+
+	err = r.cfg.TapAddrBook.InsertScriptKey(ctx, *scriptKey, true, keyType)
 	if err != nil {
 		return nil, fmt.Errorf("error inserting script key: %w", err)
 	}

tapchannel/aux_funding_controller.go

@@ -781,7 +781,9 @@ func (f *FundingController) fundVirtualPacket(ctx context.Context,
 	// We'll also need to import the funding script key into the wallet so
 	// the asset will be materialized in the asset table and show up in the
 	// balance correctly.
-	err := f.cfg.AddrBook.InsertScriptKey(ctx, fundingScriptKey, true)
+	err := f.cfg.AddrBook.InsertScriptKey(
+		ctx, fundingScriptKey, true, asset.ScriptKeyScriptPathChannel,
+	)
 	if err != nil {
 		return nil, fmt.Errorf("unable to insert script key: %w", err)
 	}

tapchannel/aux_sweeper.go

@@ -1280,7 +1280,9 @@ func (a *AuxSweeper) importCommitScriptKeys(req lnwallet.ResolutionReq) error {
 
 	ctxb := context.Background()
 	for _, key := range keysToImport {
-		err := a.cfg.AddrBook.InsertScriptKey(ctxb, key, true)
+		err := a.cfg.AddrBook.InsertScriptKey(
+			ctxb, key, true, asset.ScriptKeyScriptPathChannel,
+		)
 		if err != nil {
 			return fmt.Errorf("unable to insert script "+
 				"key: %w", err)
@@ -1312,7 +1314,9 @@ func (a *AuxSweeper) importOutputScriptKeys(desc tapscriptSweepDescs) error {
 		log.Debugf("Importing script_keys=%v",
 			limitSpewer.Sdump(scriptKey))
 
-		return a.cfg.AddrBook.InsertScriptKey(ctxb, scriptKey, true)
+		return a.cfg.AddrBook.InsertScriptKey(
+			ctxb, scriptKey, true, asset.ScriptKeyScriptPathChannel,
+		)
 	}
 
 	if err := importScriptKey(desc.firstLevel); err != nil {
@@ -1505,7 +1509,9 @@ func (a *AuxSweeper) importCommitTx(req lnwallet.ResolutionReq,
 	// the asset will be materialized in the asset table and show up in the
 	// balance correctly.
 	ctxb := context.Background()
-	err := a.cfg.AddrBook.InsertScriptKey(ctxb, fundingScriptKey, true)
+	err := a.cfg.AddrBook.InsertScriptKey(
+		ctxb, fundingScriptKey, true, asset.ScriptKeyScriptPathChannel,
+	)
 	if err != nil {
 		return fmt.Errorf("unable to insert script key: %w", err)
 	}

tapdb/addrs.go

@@ -268,6 +268,9 @@ func (t *TapAddressBook) InsertAddrs(ctx context.Context,
 				InternalKeyID:    rawScriptKeyID,
 				TweakedScriptKey: addr.ScriptKey.SerializeCompressed(),
 				Tweak:            addr.ScriptKeyTweak.Tweak,
+				KeyType: sqlInt16(
+					addr.ScriptKeyTweak.Type,
+				),
 			})
 			if err != nil {
 				return fmt.Errorf("unable to insert script "+
@@ -649,7 +652,8 @@ func (t *TapAddressBook) InsertInternalKey(ctx context.Context,
 // it can be recognized as belonging to the wallet when a transfer comes in
 // later on.
 func (t *TapAddressBook) InsertScriptKey(ctx context.Context,
-	scriptKey asset.ScriptKey, declaredKnown bool) error {
+	scriptKey asset.ScriptKey, declaredKnown bool,
+	keyType asset.ScriptKeyType) error {
 
 	var writeTxOpts AddrBookTxOptions
 	return t.db.ExecTx(ctx, &writeTxOpts, func(q AddrBook) error {
@@ -666,6 +670,7 @@ func (t *TapAddressBook) InsertScriptKey(ctx context.Context,
 			TweakedScriptKey: scriptKey.PubKey.SerializeCompressed(),
 			Tweak:            scriptKey.Tweak,
 			DeclaredKnown:    sqlBool(declaredKnown),
+			KeyType:          sqlInt16(keyType),
 		})
 		return err
 	})