13157733617

Committed 05 Feb 2025 12:49PM UTC coverage: 57.712% (-1.1%) from 58.82%

Build # 13157733617

Build Type

Pull #9447

github

Committed by

yyforyongyu

Commit Message

sweep: rename methods for clarity

We now rename "third party" to "unknown" as the inputs can be spent via
an older sweeping tx, a third party (anchor), or a remote party (pin).
In fee bumper we don't have the info to distinguish the above cases, and
leave them to be further handled by the sweeper as it has more context.

Pull Request Pull Request #9447: sweep: start tracking input spending status in the fee bumper

Run Details

83 of 87 new or added lines in 2 files covered. (95.4%)

19472 existing lines in 252 files now uncovered.

103634 of 179570 relevant lines covered (57.71%)

24840.31 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

79.38

/internal/musig2v040/context.go

// Copyright (c) 2013-2022 The btcsuite developers

package musig2v040

import (
        "fmt"

        "github.com/btcsuite/btcd/btcec/v2"
        "github.com/btcsuite/btcd/btcec/v2/schnorr"
)

var (
        // ErrSignersNotSpecified is returned when a caller attempts to create
        // a context without specifying either the total number of signers, or
        // the complete set of singers.
        ErrSignersNotSpecified = fmt.Errorf("total number of signers or all " +
                "signers must be known")

        // ErrSignerNotInKeySet is returned when a the private key for a signer
        // isn't included in the set of signing public keys.
        ErrSignerNotInKeySet = fmt.Errorf("signing key is not found in key" +
                " set")

        // ErrAlredyHaveAllNonces is called when RegisterPubNonce is called too
        // many times for a given signing session.
        ErrAlredyHaveAllNonces = fmt.Errorf("already have all nonces")

        // ErrNotEnoughSigners is returned when a caller attempts to create a
        // session from a context, but before all the required signers are
        // known.
        ErrNotEnoughSigners = fmt.Errorf("not enough signers")

        // ErrAlredyHaveAllNonces is returned when a caller attempts to
        // register a signer, once we already have the total set of known
        // signers.
        ErrAlreadyHaveAllSigners = fmt.Errorf("all signers registered")

        // ErrAlredyHaveAllSigs is called when CombineSig is called too many
        // times for a given signing session.
        ErrAlredyHaveAllSigs = fmt.Errorf("already have all sigs")

        // ErrSigningContextReuse is returned if a user attempts to sign using
        // the same signing context more than once.
        ErrSigningContextReuse = fmt.Errorf("nonce already used")

        // ErrFinalSigInvalid is returned when the combined signature turns out
        // to be invalid.
        ErrFinalSigInvalid = fmt.Errorf("final signature is invalid")

        // ErrCombinedNonceUnavailable is returned when a caller attempts to
        // sign a partial signature, without first having collected all the
        // required combined nonces.
        ErrCombinedNonceUnavailable = fmt.Errorf("missing combined nonce")

        // ErrTaprootInternalKeyUnavailable is returned when a user attempts to
        // obtain the
        ErrTaprootInternalKeyUnavailable = fmt.Errorf("taproot tweak not used")

        // ErrNotEnoughSigners is returned if a caller attempts to obtain an
        // early nonce when it wasn't specified
        ErrNoEarlyNonce = fmt.Errorf("no early nonce available")
)

// Context is a managed signing context for musig2. It takes care of things
// like securely generating secret nonces, aggregating keys and nonces, etc.
type Context struct {
        // signingKey is the key we'll use for signing.
        signingKey *btcec.PrivateKey

        // pubKey is our even-y coordinate public  key.
        pubKey *btcec.PublicKey

        // combinedKey is the aggregated public key.
        combinedKey *AggregateKey

        // uniqueKeyIndex is the index of the second unique key in the keySet.
        // This is used to speed up signing and verification computations.
        uniqueKeyIndex int

        // keysHash is the hash of all the keys as defined in musig2.
        keysHash []byte

        // opts is the set of options for the context.
        opts *contextOptions

        // shouldSort keeps track of if the public keys should be sorted before
        // any operations.
        shouldSort bool

        // sessionNonce will be populated if the earlyNonce option is true.
        // After the first session is created, this nonce will be blanked out.
        sessionNonce *Nonces
}

// ContextOption is a functional option argument that allows callers to modify
// the musig2 signing is done within a context.
type ContextOption func(*contextOptions)

// contextOptions houses the set of functional options that can be used to
// musig2 signing protocol.
type contextOptions struct {
        // tweaks is the set of optinoal tweaks to apply to the combined public
        // key.
        tweaks []KeyTweakDesc

        // taprootTweak specifies the taproot tweak. If specified, then we'll
        // use this as the script root for the BIP 341 taproot (x-only) tweak.
        // Normally we'd just apply the raw 32 byte tweak, but for taproot, we
        // first need to compute the aggregated key before tweaking, and then
        // use it as the internal key. This is required as the taproot tweak
        // also commits to the public key, which in this case is the aggregated
        // key before the tweak.
        taprootTweak []byte

        // bip86Tweak if true, then the weak will just be
        // h_tapTweak(internalKey) as there is no true script root.
        bip86Tweak bool

        // keySet is the complete set of signers for this context.
        keySet []*btcec.PublicKey

        // numSigners is the total number of signers that will eventually be a
        // part of the context.
        numSigners int

        // earlyNonce determines if a nonce should be generated during context
        // creation, to be automatically passed to the created session.
        earlyNonce bool
}

// defaultContextOptions returns the default context options.
func defaultContextOptions() *contextOptions {
        return &contextOptions{}
}

// WithTweakedContext specifies that within the context, the aggregated public
// key should be tweaked with the specified tweaks.
func WithTweakedContext(tweaks ...KeyTweakDesc) ContextOption {
        return func(o *contextOptions) {
                o.tweaks = tweaks
        }
}

// WithTaprootTweakCtx specifies that within this context, the final key should
// use the taproot tweak as defined in BIP 341: outputKey = internalKey +
// h_tapTweak(internalKey || scriptRoot). In this case, the aggreaged key
// before the tweak will be used as the internal key.
func WithTaprootTweakCtx(scriptRoot []byte) ContextOption {
        return func(o *contextOptions) {
                o.taprootTweak = scriptRoot
        }
}

// WithBip86TweakCtx specifies that within this context, the final key should
// use the taproot tweak as defined in BIP 341, with the BIP 86 modification:
// outputKey = internalKey + h_tapTweak(internalKey)*G. In this case, the
// aggreaged key before the tweak will be used as the internal key.
func WithBip86TweakCtx() ContextOption {
        return func(o *contextOptions) {
                o.bip86Tweak = true
        }
}

// WithKnownSigners is an optional parameter that should be used if a session
// can be created as soon as all the singers are known.
func WithKnownSigners(signers []*btcec.PublicKey) ContextOption {
        return func(o *contextOptions) {
                o.keySet = signers
                o.numSigners = len(signers)
        }
}

// WithNumSigners is a functional option used to specify that a context should
// be created without knowing all the signers. Instead the total number of
// signers is specified to ensure that a session can only be created once all
// the signers are known.
//
// NOTE: Either WithKnownSigners or WithNumSigners MUST be specified.
func WithNumSigners(n int) ContextOption {
        return func(o *contextOptions) {
                o.numSigners = n
        }
}

// WithEarlyNonceGen allow a caller to specify that a nonce should be generated
// early, before the session is created. This should be used in protocols that
// require some partial nonce exchange before all the signers are known.
//
// NOTE: This option must only be specified with the WithNumSigners option.
func WithEarlyNonceGen() ContextOption {
        return func(o *contextOptions) {
                o.earlyNonce = true
        }
}

// NewContext creates a new signing context with the passed singing key and set
// of public keys for each of the other signers.
//
// NOTE: This struct should be used over the raw Sign API whenever possible.
func NewContext(signingKey *btcec.PrivateKey, shouldSort bool,
        ctxOpts ...ContextOption) (*Context, error) {

        // First, parse the set of optional context options.
        opts := defaultContextOptions()
        for _, option := range ctxOpts {
                option(opts)
        }

        pubKey, err := schnorr.ParsePubKey(
                schnorr.SerializePubKey(signingKey.PubKey()),
        )
        if err != nil {
                return nil, err
        }

        ctx := &Context{
                signingKey: signingKey,
                pubKey:     pubKey,
                opts:       opts,
                shouldSort: shouldSort,
        }

        switch {

        // We know all the signers, so we can compute the aggregated key, along
        // with all the other intermediate state we need to do signing and
        // verification.
        case opts.keySet != nil:
                if err := ctx.combineSignerKeys(); err != nil {
                        return nil, err
                }

        // The total signers are known, so we add ourselves, and skip key
        // aggregation.
        case opts.numSigners != 0:
                // Otherwise, we'll add ourselves as the only known signer, and
                // await further calls to RegisterSigner before a session can
                // be created.
                opts.keySet = make([]*btcec.PublicKey, 0, opts.numSigners)
                opts.keySet = append(opts.keySet, pubKey)

                // If early nonce generation is specified, then we'll generate
                // the nonce now to pass in to the session once all the callers
                // are known.
                if opts.earlyNonce {
                        ctx.sessionNonce, err = GenNonces()
                        if err != nil {
                                return nil, err
                        }
                }

        default:
                return nil, ErrSignersNotSpecified
        }

        return ctx, nil
}

// combineSignerKeys is used to compute the aggregated signer key once all the
// signers are known.
func (c *Context) combineSignerKeys() error {
        // As a sanity check, make sure the signing key is actually
        // amongst the sit of signers.
        var keyFound bool
        for _, key := range c.opts.keySet {
                if key.IsEqual(c.pubKey) {
                        keyFound = true
                        break
                }
        }
        if !keyFound {
                return ErrSignerNotInKeySet
        }

        // Now that we know that we're actually a signer, we'll
        // generate the key hash finger print and second unique key
        // index so we can speed up signing later.
        c.keysHash = keyHashFingerprint(c.opts.keySet, c.shouldSort)
        c.uniqueKeyIndex = secondUniqueKeyIndex(
                c.opts.keySet, c.shouldSort,
        )

        keyAggOpts := []KeyAggOption{
                WithKeysHash(c.keysHash),
                WithUniqueKeyIndex(c.uniqueKeyIndex),
        }
        switch {
        case c.opts.bip86Tweak:
                keyAggOpts = append(
                        keyAggOpts, WithBIP86KeyTweak(),
                )
        case c.opts.taprootTweak != nil:
                keyAggOpts = append(
                        keyAggOpts, WithTaprootKeyTweak(c.opts.taprootTweak),
                )
        case len(c.opts.tweaks) != 0:
                keyAggOpts = append(keyAggOpts, WithKeyTweaks(c.opts.tweaks...))
        }

        // Next, we'll use this information to compute the aggregated
        // public key that'll be used for signing in practice.
        var err error
        c.combinedKey, _, _, err = AggregateKeys(
                c.opts.keySet, c.shouldSort, keyAggOpts...,
        )
        if err != nil {
                return err
        }

        return nil
}

// EarlySessionNonce returns the early session nonce, if available.
func (c *Context) EarlySessionNonce() (*Nonces, error) {
        if c.sessionNonce == nil {
                return nil, ErrNoEarlyNonce
        }

        return c.sessionNonce, nil
}

// RegisterSigner allows a caller to register a signer after the context has
// been created. This will be used in scenarios where the total number of
// signers is known, but nonce exchange needs to happen before all the signers
// are known.
//
// A bool is returned which indicates if all the signers have been registered.
//
// NOTE: If the set of keys are not to be sorted during signing, then the
// ordering each key is registered with MUST match the desired ordering.
func (c *Context) RegisterSigner(pub *btcec.PublicKey) (bool, error) {
        haveAllSigners := len(c.opts.keySet) == c.opts.numSigners
        if haveAllSigners {
                return false, ErrAlreadyHaveAllSigners
        }

        c.opts.keySet = append(c.opts.keySet, pub)

        // If we have the expected number of signers at this point, then we can
        // generate the aggregated key and other necessary information.
        haveAllSigners = len(c.opts.keySet) == c.opts.numSigners
        if haveAllSigners {
                if err := c.combineSignerKeys(); err != nil {
                        return false, err
                }
        }

        return haveAllSigners, nil
}

// NumRegisteredSigners returns the total number of registered signers.
func (c *Context) NumRegisteredSigners() int {
        return len(c.opts.keySet)
}

// CombinedKey returns the combined public key that will be used to generate
// multi-signatures  against.
func (c *Context) CombinedKey() (*btcec.PublicKey, error) {
        // If the caller hasn't registered all the signers at this point, then
        // the combined key won't be available.
        if c.combinedKey == nil {
                return nil, ErrNotEnoughSigners
        }

        return c.combinedKey.FinalKey, nil
}

// PubKey returns the public key of the signer of this session.
func (c *Context) PubKey() btcec.PublicKey {
        return *c.pubKey
}

// SigningKeys returns the set of keys used for signing.
func (c *Context) SigningKeys() []*btcec.PublicKey {
        keys := make([]*btcec.PublicKey, len(c.opts.keySet))
        copy(keys, c.opts.keySet)

        return keys
}

// TaprootInternalKey returns the internal taproot key, which is the aggregated
// key _before_ the tweak is applied. If a taproot tweak was specified, then
// CombinedKey() will return the fully tweaked output key, with this method
// returning the internal key. If a taproot tweak wasn't specified, then this
// method will return an error.
func (c *Context) TaprootInternalKey() (*btcec.PublicKey, error) {
        // If the caller hasn't registered all the signers at this point, then
        // the combined key won't be available.
        if c.combinedKey == nil {
                return nil, ErrNotEnoughSigners
        }

        if c.opts.taprootTweak == nil && !c.opts.bip86Tweak {
                return nil, ErrTaprootInternalKeyUnavailable
        }

        return c.combinedKey.PreTweakedKey, nil
}

// SessionOption is a functional option argument that allows callers to modify
// the musig2 signing is done within a session.
type SessionOption func(*sessionOptions)

// sessionOptions houses the set of functional options that can be used to
// modify the musig2 signing protocol.
type sessionOptions struct {
        externalNonce *Nonces
}

// defaultSessionOptions returns the default session options.
func defaultSessionOptions() *sessionOptions {
        return &sessionOptions{}
}

// WithPreGeneratedNonce allows a caller to start a session using a nonce
// they've generated themselves. This may be useful in protocols where all the
// signer keys may not be known before nonce exchange needs to occur.
func WithPreGeneratedNonce(nonce *Nonces) SessionOption {
        return func(o *sessionOptions) {
                o.externalNonce = nonce
        }
}

// Session represents a musig2 signing session. A new instance should be
// created each time a multi-signature is needed. The session struct handles
// nonces management, incremental partial sig vitrifaction, as well as final
// signature combination. Errors are returned when unsafe behavior such as
// nonce re-use is attempted.
//
// NOTE: This struct should be used over the raw Sign API whenever possible.
type Session struct {
        opts *sessionOptions

        ctx *Context

        localNonces *Nonces

        pubNonces [][PubNonceSize]byte

        combinedNonce *[PubNonceSize]byte

        msg [32]byte

        ourSig *PartialSignature
        sigs   []*PartialSignature

        finalSig *schnorr.Signature
}

// NewSession creates a new musig2 signing session.
func (c *Context) NewSession(options ...SessionOption) (*Session, error) {
        opts := defaultSessionOptions()
        for _, opt := range options {
                opt(opts)
        }

        // At this point we verify that we know of all the signers, as
        // otherwise we can't proceed with the session. This check is intended
        // to catch misuse of the API wherein a caller forgets to register the
        // remaining signers if they're doing nonce generation ahead of time.
        if len(c.opts.keySet) != c.opts.numSigners {
                return nil, ErrNotEnoughSigners
        }

        // If an early nonce was specified, then we'll automatically add the
        // corresponding session option for the caller.
        var localNonces *Nonces
        if c.sessionNonce != nil {
                // Apply the early nonce to the session, and also blank out the
                // session nonce on the context to ensure it isn't ever re-used
                // for another session.
                localNonces = c.sessionNonce
                c.sessionNonce = nil
        } else if opts.externalNonce != nil {
                // Otherwise if there's a custom nonce passed in via the
                // session options, then use that instead.
                localNonces = opts.externalNonce
        }

        // Now that we know we have enough signers, we'll either use the caller
        // specified nonce, or generate a fresh set.
        var err error
        if localNonces == nil {
                // At this point we need to generate a fresh nonce. We'll pass
                // in some auxiliary information to strengthen the nonce
                // generated.
                localNonces, err = GenNonces(
                        WithNonceSecretKeyAux(c.signingKey),
                        WithNonceCombinedKeyAux(c.combinedKey.FinalKey),
                )
                if err != nil {
                        return nil, err
                }
        }

        s := &Session{
                opts:        opts,
                ctx:         c,
                localNonces: localNonces,
                pubNonces:   make([][PubNonceSize]byte, 0, c.opts.numSigners),
                sigs:        make([]*PartialSignature, 0, c.opts.numSigners),
        }

        s.pubNonces = append(s.pubNonces, localNonces.PubNonce)

        return s, nil
}

// PublicNonce returns the public nonce for a signer. This should be sent to
// other parties before signing begins, so they can compute the aggregated
// public nonce.
func (s *Session) PublicNonce() [PubNonceSize]byte {
        return s.localNonces.PubNonce
}

// NumRegisteredNonces returns the total number of nonces that have been
// regsitered so far.
func (s *Session) NumRegisteredNonces() int {
        return len(s.pubNonces)
}

// RegisterPubNonce should be called for each public nonce from the set of
// signers. This method returns true once all the public nonces have been
// accounted for.
func (s *Session) RegisterPubNonce(nonce [PubNonceSize]byte) (bool, error) {
        // If we already have all the nonces, then this method was called too
        // many times.
        haveAllNonces := len(s.pubNonces) == s.ctx.opts.numSigners
        if haveAllNonces {
                return false, ErrAlredyHaveAllNonces
        }

        // Add this nonce and check again if we already have tall the nonces we
        // need.
        s.pubNonces = append(s.pubNonces, nonce)
        haveAllNonces = len(s.pubNonces) == s.ctx.opts.numSigners

        // If we have all the nonces, then we can go ahead and combine them
        // now.
        if haveAllNonces {
                combinedNonce, err := AggregateNonces(s.pubNonces)
                if err != nil {
                        return false, err
                }

                s.combinedNonce = &combinedNonce
        }

        return haveAllNonces, nil
}

// Sign generates a partial signature for the target message, using the target
// context. If this method is called more than once per context, then an error
// is returned, as that means a nonce was re-used.
func (s *Session) Sign(msg [32]byte,
        signOpts ...SignOption) (*PartialSignature, error) {

        switch {
        // If no local nonce is present, then this means we already signed, so
        // we'll return an error to prevent nonce re-use.
        case s.localNonces == nil:
                return nil, ErrSigningContextReuse

        // We also need to make sure we have the combined nonce, otherwise this
        // function was called too early.
        case s.combinedNonce == nil:
                return nil, ErrCombinedNonceUnavailable
        }

        switch {
        case s.ctx.opts.bip86Tweak:
                signOpts = append(
                        signOpts, WithBip86SignTweak(),
                )
        case s.ctx.opts.taprootTweak != nil:
                signOpts = append(
                        signOpts, WithTaprootSignTweak(s.ctx.opts.taprootTweak),
                )
        case len(s.ctx.opts.tweaks) != 0:
                signOpts = append(signOpts, WithTweaks(s.ctx.opts.tweaks...))
        }

        partialSig, err := Sign(
                s.localNonces.SecNonce, s.ctx.signingKey, *s.combinedNonce,
                s.ctx.opts.keySet, msg, signOpts...,
        )

        // Now that we've generated our signature, we'll make sure to blank out
        // our signing nonce.
        s.localNonces = nil

        if err != nil {
                return nil, err
        }

        s.msg = msg

        s.ourSig = partialSig
        s.sigs = append(s.sigs, partialSig)

        return partialSig, nil
}

// CombineSig buffers a partial signature received from a signing party. The
// method returns true once all the signatures are available, and can be
// combined into the final signature.
func (s *Session) CombineSig(sig *PartialSignature) (bool, error) {
        // First check if we already have all the signatures we need. We
        // already accumulated our own signature when we generated the sig.
        haveAllSigs := len(s.sigs) == len(s.ctx.opts.keySet)
        if haveAllSigs {
                return false, ErrAlredyHaveAllSigs
        }

        // TODO(roasbeef): incremental check for invalid sig, or just detect at
        // the very end?

        // Accumulate this sig, and check again if we have all the sigs we
        // need.
        s.sigs = append(s.sigs, sig)
        haveAllSigs = len(s.sigs) == len(s.ctx.opts.keySet)

        // If we have all the signatures, then we can combine them all into the
        // final signature.
        if haveAllSigs {
                var combineOpts []CombineOption
                switch {
                case s.ctx.opts.bip86Tweak:
                        combineOpts = append(
                                combineOpts, WithBip86TweakedCombine(
                                        s.msg, s.ctx.opts.keySet,
                                        s.ctx.shouldSort,
                                ),
                        )
                case s.ctx.opts.taprootTweak != nil:
                        combineOpts = append(
                                combineOpts, WithTaprootTweakedCombine(
                                        s.msg, s.ctx.opts.keySet,
                                        s.ctx.opts.taprootTweak, s.ctx.shouldSort,
                                ),
                        )
                case len(s.ctx.opts.tweaks) != 0:
                        combineOpts = append(
                                combineOpts, WithTweakedCombine(
                                        s.msg, s.ctx.opts.keySet,
                                        s.ctx.opts.tweaks, s.ctx.shouldSort,
                                ),
                        )
                }

                finalSig := CombineSigs(s.ourSig.R, s.sigs, combineOpts...)

                // We'll also verify the signature at this point to ensure it's
                // valid.
                //
                // TODO(roasbef): allow skipping?
                if !finalSig.Verify(s.msg[:], s.ctx.combinedKey.FinalKey) {
                        return false, ErrFinalSigInvalid
                }

                s.finalSig = finalSig
        }

        return haveAllSigs, nil
}

// FinalSig returns the final combined multi-signature, if present.
func (s *Session) FinalSig() *schnorr.Signature {
        return s.finalSig
}

lightningnetwork / lnd / 13157733617

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous