17830307614

Committed 18 Sep 2025 01:29PM UTC coverage: 54.617% (-12.0%) from 66.637%

Build # 17830307614

Build Type

Pull #10200

github

Committed by

web-flow

Commit Message

Merge 181a0a7bc into b34fc964b

Pull Request Pull Request #10200: github: change to form-based issue template

Run Details

109249 of 200028 relevant lines covered (54.62%)

21896.43 hits per line

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

67.21

/lnwallet/wallet.go

package lnwallet

import (
        "bytes"
        "crypto/sha256"
        "errors"
        "fmt"
        "math"
        "net"
        "sync"
        "sync/atomic"

        "github.com/btcsuite/btcd/blockchain"
        "github.com/btcsuite/btcd/btcec/v2"
        "github.com/btcsuite/btcd/btcec/v2/schnorr/musig2"
        "github.com/btcsuite/btcd/btcutil"
        "github.com/btcsuite/btcd/btcutil/psbt"
        "github.com/btcsuite/btcd/btcutil/txsort"
        "github.com/btcsuite/btcd/chaincfg"
        "github.com/btcsuite/btcd/chaincfg/chainhash"
        "github.com/btcsuite/btcd/txscript"
        "github.com/btcsuite/btcd/wire"
        "github.com/btcsuite/btcwallet/wallet"
        "github.com/lightningnetwork/lnd/channeldb"
        "github.com/lightningnetwork/lnd/fn/v2"
        "github.com/lightningnetwork/lnd/input"
        "github.com/lightningnetwork/lnd/keychain"
        "github.com/lightningnetwork/lnd/lntypes"
        "github.com/lightningnetwork/lnd/lnutils"
        "github.com/lightningnetwork/lnd/lnwallet/chainfee"
        "github.com/lightningnetwork/lnd/lnwallet/chanfunding"
        "github.com/lightningnetwork/lnd/lnwallet/chanvalidate"
        "github.com/lightningnetwork/lnd/lnwire"
        "github.com/lightningnetwork/lnd/shachain"
        "github.com/lightningnetwork/lnd/tlv"
)

const (
        // The size of the buffered queue of requests to the wallet from the
        // outside word.
        msgBufferSize = 100

        // AnchorChanReservedValue is the amount we'll keep around in the
        // wallet in case we have to fee bump anchor channels on force close.
        // TODO(halseth): update constant to target a specific commit size at
        // set fee rate.
        AnchorChanReservedValue = btcutil.Amount(10_000)

        // MaxAnchorChanReservedValue is the maximum value we'll reserve for
        // anchor channel fee bumping. We cap it at 10 times the per-channel
        // amount such that nodes with a high number of channels don't have to
        // keep around a very large amount for the unlikely scenario that they
        // all close at the same time.
        MaxAnchorChanReservedValue = 10 * AnchorChanReservedValue
)

var (
        // ErrPsbtFundingRequired is the error that is returned during the
        // contribution handling process if the process should be paused for
        // the construction of a PSBT outside of lnd's wallet.
        ErrPsbtFundingRequired = errors.New("PSBT funding required")

        // ErrReservedValueInvalidated is returned if we try to publish a
        // transaction that would take the walletbalance below what we require
        // to keep around to fee bump our open anchor channels.
        ErrReservedValueInvalidated = errors.New("reserved wallet balance " +
                "invalidated: transaction would leave insufficient funds for " +
                "fee bumping anchor channel closings (see debug log for details)")

        // ErrEmptyPendingChanID is returned when an empty value is used for
        // the pending channel ID.
        ErrEmptyPendingChanID = errors.New("pending channel ID is empty")

        // ErrDuplicatePendingChanID is returned when an existing pending
        // channel ID is registered again.
        ErrDuplicatePendingChanID = errors.New("duplicate pending channel ID")
)

// PsbtFundingRequired is a type that implements the error interface and
// contains the information needed to construct a PSBT.
type PsbtFundingRequired struct {
        // Intent is the pending PSBT funding intent that needs to be funded
        // if the wrapping error is returned.
        Intent *chanfunding.PsbtIntent
}

// Error returns the underlying error.
//
// NOTE: This method is part of the error interface.
func (p *PsbtFundingRequired) Error() string {
        return ErrPsbtFundingRequired.Error()
}

// AuxFundingDesc stores a series of attributes that may be used to modify the
// way the channel funding occurs. This struct contains information that can
// only be derived once both sides have received and sent their contributions
// to the channel (keys, etc.).
type AuxFundingDesc struct {
        // CustomFundingBlob is a custom blob that'll be stored in the database
        // within the OpenChannel struct. This should represent information
        // static to the channel lifetime.
        CustomFundingBlob tlv.Blob

        // CustomLocalCommitBlob is a custom blob that'll be stored in the
        // first commitment entry for the local party.
        CustomLocalCommitBlob tlv.Blob

        // CustomRemoteCommitBlob is a custom blob that'll be stored in the
        // first commitment entry for the remote party.
        CustomRemoteCommitBlob tlv.Blob

        // LocalInitAuxLeaves is the set of aux leaves that'll be used for our
        // very first commitment state.
        LocalInitAuxLeaves CommitAuxLeaves

        // RemoteInitAuxLeaves is the set of aux leaves that'll be used for the
        // very first commitment state for the remote party.
        RemoteInitAuxLeaves CommitAuxLeaves
}

// InitFundingReserveMsg is the first message sent to initiate the workflow
// required to open a payment channel with a remote peer. The initial required
// parameters are configurable across channels. These parameters are to be
// chosen depending on the fee climate within the network, and time value of
// funds to be locked up within the channel. Upon success a ChannelReservation
// will be created in order to track the lifetime of this pending channel.
// Outputs selected will be 'locked', making them unavailable, for any other
// pending reservations. Therefore, all channels in reservation limbo will be
// periodically timed out after an idle period in order to avoid "exhaustion"
// attacks.
type InitFundingReserveMsg struct {
        // ChainHash denotes that chain to be used to ultimately open the
        // target channel.
        ChainHash *chainhash.Hash

        // PendingChanID is the pending channel ID for this funding flow as
        // used in the wire protocol.
        PendingChanID [32]byte

        // NodeID is the ID of the remote node we would like to open a channel
        // with.
        NodeID *btcec.PublicKey

        // NodeAddr is the address port that we used to either establish or
        // accept the connection which led to the negotiation of this funding
        // workflow.
        NodeAddr net.Addr

        // SubtractFees should be set if we intend to spend exactly
        // LocalFundingAmt when opening the channel, subtracting the fees from
        // the funding output. This can be used for instance to use all our
        // remaining funds to open the channel, since it will take fees into
        // account.
        SubtractFees bool

        // LocalFundingAmt is the amount of funds requested from us for this
        // channel.
        LocalFundingAmt btcutil.Amount

        // RemoteFundingAmnt is the amount of funds the remote will contribute
        // to this channel.
        RemoteFundingAmt btcutil.Amount

        // FundUpToMaxAmt defines if channel funding should try to add as many
        // funds to the channel opening as possible up to this amount. If used,
        // then MinFundAmt is treated as the minimum amount of funds that must
        // be available to open the channel. If set to zero it is ignored.
        FundUpToMaxAmt btcutil.Amount

        // MinFundAmt denotes the minimum channel capacity that has to be
        // allocated iff the FundUpToMaxAmt is set.
        MinFundAmt btcutil.Amount

        // Outpoints is a list of client-selected outpoints that should be used
        // for funding a channel. If LocalFundingAmt is specified then this
        // amount is allocated from the sum of outpoints towards funding. If the
        // FundUpToMaxAmt is specified the entirety of selected funds is
        // allocated towards channel funding.
        Outpoints []wire.OutPoint

        // RemoteChanReserve is the channel reserve we required for the remote
        // peer.
        RemoteChanReserve btcutil.Amount

        // CommitFeePerKw is the starting accepted satoshis/Kw fee for the set
        // of initial commitment transactions. In order to ensure timely
        // confirmation, it is recommended that this fee should be generous,
        // paying some multiple of the accepted base fee rate of the network.
        CommitFeePerKw chainfee.SatPerKWeight

        // FundingFeePerKw is the fee rate in sat/kw to use for the initial
        // funding transaction.
        FundingFeePerKw chainfee.SatPerKWeight

        // PushMSat is the number of milli-satoshis that should be pushed over
        // the responder as part of the initial channel creation.
        PushMSat lnwire.MilliSatoshi

        // Flags are the channel flags specified by the initiator in the
        // open_channel message.
        Flags lnwire.FundingFlag

        // MinConfs indicates the minimum number of confirmations that each
        // output selected to fund the channel should satisfy.
        MinConfs int32

        // CommitType indicates what type of commitment type the channel should
        // be using, like tweakless or anchors.
        CommitType CommitmentType

        // ChanFunder is an optional channel funder that allows the caller to
        // control exactly how the channel funding is carried out. If not
        // specified, then the default chanfunding.WalletAssembler will be
        // used.
        ChanFunder chanfunding.Assembler

        // AllowUtxoForFunding enables the channel funding workflow to restrict
        // the selection of utxos when selecting the inputs for the channel
        // opening. This does ONLY apply for the internal wallet backed channel
        // opening case.
        //
        // NOTE: This is very useful when opening channels with unconfirmed
        // inputs to make sure stable non-replaceable inputs are used.
        AllowUtxoForFunding func(Utxo) bool

        // ZeroConf is a boolean that is true if a zero-conf channel was
        // negotiated.
        ZeroConf bool

        // OptionScidAlias is a boolean that is true if an option-scid-alias
        // channel type was explicitly negotiated.
        OptionScidAlias bool

        // ScidAliasFeature is true if the option-scid-alias feature bit was
        // negotiated.
        ScidAliasFeature bool

        // Memo is any arbitrary information we wish to store locally about the
        // channel that will be useful to our future selves.
        Memo []byte

        // TapscriptRoot is an optional tapscript root that if provided, will
        // be used to create the combined key for musig2 based channels.
        TapscriptRoot fn.Option[chainhash.Hash]

        // err is a channel in which all errors will be sent across. Will be
        // nil if this initial set is successful.
        //
        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        err chan error

        // resp is channel in which a ChannelReservation with our contributions
        // filled in will be sent across this channel in the case of a
        // successfully reservation initiation. In the case of an error, this
        // will read a nil pointer.
        //
        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        resp chan *ChannelReservation
}

// fundingReserveCancelMsg is a message reserved for cancelling an existing
// channel reservation identified by its reservation ID. Cancelling a reservation
// frees its locked outputs up, for inclusion within further reservations.
type fundingReserveCancelMsg struct {
        pendingFundingID uint64

        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        err chan error // Buffered
}

// addContributionMsg represents a message executing the second phase of the
// channel reservation workflow. This message carries the counterparty's
// "contribution" to the payment channel. In the case that this message is
// processed without generating any errors, then channel reservation will then
// be able to construct the funding tx, both commitment transactions, and
// finally generate signatures for all our inputs to the funding transaction,
// and for the remote node's version of the commitment transaction.
type addContributionMsg struct {
        pendingFundingID uint64

        contribution *ChannelContribution

        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        err chan error
}

// continueContributionMsg represents a message that signals that the
// interrupted funding process involving a PSBT can now be continued because the
// finalized transaction is now available.
type continueContributionMsg struct {
        pendingFundingID uint64

        // auxFundingDesc is an optional descriptor that contains information
        // about the custom channel funding flow.
        auxFundingDesc fn.Option[AuxFundingDesc]

        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        err chan error
}

// addSingleContributionMsg represents a message executing the second phase of
// a single funder channel reservation workflow. This messages carries the
// counterparty's "contribution" to the payment channel. As this message is
// sent when on the responding side to a single funder workflow, no further
// action apart from storing the provided contribution is carried out.
type addSingleContributionMsg struct {
        pendingFundingID uint64

        contribution *ChannelContribution

        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        err chan error
}

// addCounterPartySigsMsg represents the final message required to complete,
// and 'open' a payment channel. This message carries the counterparty's
// signatures for each of their inputs to the funding transaction, and also a
// signature allowing us to spend our version of the commitment transaction.
// If we're able to verify all the signatures are valid, the funding transaction
// will be broadcast to the network. After the funding transaction gains a
// configurable number of confirmations, the channel is officially considered
// 'open'.
type addCounterPartySigsMsg struct {
        pendingFundingID uint64

        // Should be order of sorted inputs that are theirs. Sorting is done
        // in accordance to BIP-69:
        // https://github.com/bitcoin/bips/blob/master/bip-0069.mediawiki.
        theirFundingInputScripts []*input.Script

        // This should be 1/2 of the signatures needed to successfully spend our
        // version of the commitment transaction.
        theirCommitmentSig input.Signature

        // This channel is used to return the completed channel after the wallet
        // has completed all of its stages in the funding process.
        completeChan chan *channeldb.OpenChannel

        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        err chan error
}

// addSingleFunderSigsMsg represents the next-to-last message required to
// complete a single-funder channel workflow. Once the initiator is able to
// construct the funding transaction, they send both the outpoint and a
// signature for our version of the commitment transaction. Once this message
// is processed we (the responder) are able to construct both commitment
// transactions, signing the remote party's version.
type addSingleFunderSigsMsg struct {
        pendingFundingID uint64

        // auxFundingDesc is an optional descriptor that contains information
        // about the custom channel funding flow.
        auxFundingDesc fn.Option[AuxFundingDesc]

        // fundingOutpoint is the outpoint of the completed funding
        // transaction as assembled by the workflow initiator.
        fundingOutpoint *wire.OutPoint

        // theirCommitmentSig are the 1/2 of the signatures needed to
        // successfully spend our version of the commitment transaction.
        theirCommitmentSig input.Signature

        // This channel is used to return the completed channel after the wallet
        // has completed all of its stages in the funding process.
        completeChan chan *channeldb.OpenChannel

        // NOTE: In order to avoid deadlocks, this channel MUST be buffered.
        err chan error
}

// CheckReservedValueTxReq is the request struct used to call
// CheckReservedValueTx with. It contains the transaction to check as well as
// an optional explicitly defined index to denote a change output that is not
// watched by the wallet.
type CheckReservedValueTxReq struct {
        // Tx is the transaction to check the outputs for.
        Tx *wire.MsgTx

        // ChangeIndex denotes an optional output index that can be explicitly
        // set for a change that is not being watched by the wallet and would
        // otherwise not be recognized as a change output.
        ChangeIndex *int
}

// LightningWallet is a domain specific, yet general Bitcoin wallet capable of
// executing workflow required to interact with the Lightning Network. It is
// domain specific in the sense that it understands all the fancy scripts used
// within the Lightning Network, channel lifetimes, etc. However, it embeds a
// general purpose Bitcoin wallet within it. Therefore, it is also able to
// serve as a regular Bitcoin wallet which uses HD keys. The wallet is highly
// concurrent internally. All communication, and requests towards the wallet
// are dispatched as messages over channels, ensuring thread safety across all
// operations. Interaction has been designed independent of any peer-to-peer
// communication protocol, allowing the wallet to be self-contained and
// embeddable within future projects interacting with the Lightning Network.
//
// NOTE: At the moment the wallet requires a btcd full node, as it's dependent
// on btcd's websockets notifications as event triggers during the lifetime of a
// channel. However, once the chainntnfs package is complete, the wallet will
// be compatible with multiple RPC/notification services such as Electrum,
// Bitcoin Core + ZeroMQ, etc. Eventually, the wallet won't require a full-node
// at all, as SPV support is integrated into btcwallet.
type LightningWallet struct {
        started  int32 // To be used atomically.
        shutdown int32 // To be used atomically.

        nextFundingID uint64 // To be used atomically.

        // Cfg is the configuration struct that will be used by the wallet to
        // access the necessary interfaces and default it needs to carry on its
        // duties.
        Cfg Config

        // WalletController is the core wallet, all non Lightning Network
        // specific interaction is proxied to the internal wallet.
        WalletController

        // SecretKeyRing is the interface we'll use to derive any keys related
        // to our purpose within the network including: multi-sig keys, node
        // keys, revocation keys, etc.
        keychain.SecretKeyRing

        // This mutex MUST be held when performing coin selection in order to
        // avoid inadvertently creating multiple funding transaction which
        // double spend inputs across each other.
        coinSelectMtx sync.RWMutex

        // All messages to the wallet are to be sent across this channel.
        msgChan chan interface{}

        // Incomplete payment channels are stored in the map below. An intent
        // to create a payment channel is tracked as a "reservation" within
        // limbo. Once the final signatures have been exchanged, a reservation
        // is removed from limbo. Each reservation is tracked by a unique
        // monotonically integer. All requests concerning the channel MUST
        // carry a valid, active funding ID.
        fundingLimbo map[uint64]*ChannelReservation

        // reservationIDs maps a pending channel ID to the reservation ID used
        // as key in the fundingLimbo map. Used to easily look up a channel
        // reservation given a pending channel ID.
        reservationIDs map[[32]byte]uint64
        limboMtx       sync.RWMutex

        // lockedOutPoints is a set of the currently locked outpoint. This
        // information is kept in order to provide an easy way to unlock all
        // the currently locked outpoints.
        lockedOutPoints map[wire.OutPoint]struct{}

        // fundingIntents houses all the "interception" registered by a caller
        // using the RegisterFundingIntent method.
        intentMtx      sync.RWMutex
        fundingIntents map[[32]byte]chanfunding.Intent

        quit chan struct{}

        wg sync.WaitGroup
}

// NewLightningWallet creates/opens and initializes a LightningWallet instance.
// If the wallet has never been created (according to the passed dataDir), first-time
// setup is executed.
func NewLightningWallet(Cfg Config) (*LightningWallet, error) {

        return &LightningWallet{
                Cfg:              Cfg,
                SecretKeyRing:    Cfg.SecretKeyRing,
                WalletController: Cfg.WalletController,
                msgChan:          make(chan interface{}, msgBufferSize),
                nextFundingID:    0,
                fundingLimbo:     make(map[uint64]*ChannelReservation),
                reservationIDs:   make(map[[32]byte]uint64),
                lockedOutPoints:  make(map[wire.OutPoint]struct{}),
                fundingIntents:   make(map[[32]byte]chanfunding.Intent),
                quit:             make(chan struct{}),
        }, nil
}

// Startup establishes a connection to the RPC source, and spins up all
// goroutines required to handle incoming messages.
func (l *LightningWallet) Startup() error {
        // Already started?
        if atomic.AddInt32(&l.started, 1) != 1 {
                return nil
        }

        // Start the underlying wallet controller.
        if err := l.Start(); err != nil {
                return err
        }

        if l.Cfg.Rebroadcaster != nil {
                go func() {
                        if err := l.Cfg.Rebroadcaster.Start(); err != nil {
                                walletLog.Errorf("unable to start "+
                                        "rebroadcaster: %v", err)
                        }
                }()
        }

        l.wg.Add(1)
        go l.requestHandler()

        return nil
}

// Shutdown gracefully stops the wallet, and all active goroutines.
func (l *LightningWallet) Shutdown() error {
        if atomic.AddInt32(&l.shutdown, 1) != 1 {
                return nil
        }

        // Signal the underlying wallet controller to shutdown, waiting until
        // all active goroutines have been shutdown.
        if err := l.Stop(); err != nil {
                return err
        }

        if l.Cfg.Rebroadcaster != nil && l.Cfg.Rebroadcaster.Started() {
                l.Cfg.Rebroadcaster.Stop()
        }

        close(l.quit)
        l.wg.Wait()
        return nil
}

// PublishTransaction wraps the wallet controller tx publish method with an
// extra rebroadcaster layer if the sub-system is configured.
func (l *LightningWallet) PublishTransaction(tx *wire.MsgTx,
        label string) error {

        sendTxToWallet := func() error {
                return l.WalletController.PublishTransaction(tx, label)
        }

        // If we don't have rebroadcaster then we can exit early (and send only
        // to the wallet).
        if l.Cfg.Rebroadcaster == nil || !l.Cfg.Rebroadcaster.Started() {
                return sendTxToWallet()
        }

        // We pass this into the rebroadcaster first, so the initial attempt
        // will succeed if the transaction isn't yet in the mempool. However we
        // ignore the error here as this might be resent on start up and the
        // transaction already exists.
        _ = l.Cfg.Rebroadcaster.Broadcast(tx)

        // Then we pass things into the wallet as normal, which'll add the
        // transaction label on disk.
        if err := sendTxToWallet(); err != nil {
                return err
        }

        // TODO(roasbeef): want diff height actually? no context though
        _, bestHeight, err := l.Cfg.ChainIO.GetBestBlock()
        if err != nil {
                return err
        }

        txHash := tx.TxHash()
        go func() {
                const numConfs = 6

                txConf, err := l.Cfg.Notifier.RegisterConfirmationsNtfn(
                        &txHash, tx.TxOut[0].PkScript, numConfs,
                        uint32(bestHeight),
                )
                if err != nil {
                        return
                }

                select {
                case <-txConf.Confirmed:
                        // TODO(roasbeef): also want to remove from
                        // rebroadcaster if conflict happens...deeper wallet
                        // integration?
                        l.Cfg.Rebroadcaster.MarkAsConfirmed(tx.TxHash())

                case <-l.quit:
                        return
                }
        }()

        return nil
}

// ConfirmedBalance returns the current confirmed balance of a wallet account.
// This methods wraps the internal WalletController method so we're able to
// properly hold the coin select mutex while we compute the balance.
func (l *LightningWallet) ConfirmedBalance(confs int32,
        account string) (btcutil.Amount, error) {

        l.coinSelectMtx.Lock()
        defer l.coinSelectMtx.Unlock()

        return l.WalletController.ConfirmedBalance(confs, account)
}

// ListUnspentWitnessFromDefaultAccount returns all unspent outputs from the
// default wallet account which are version 0 witness programs. The 'minConfs'
// and 'maxConfs' parameters indicate the minimum and maximum number of
// confirmations an output needs in order to be returned by this method. Passing
// -1 as 'minConfs' indicates that even unconfirmed outputs should be returned.
// Using MaxInt32 as 'maxConfs' implies returning all outputs with at least
// 'minConfs'.
//
// NOTE: This method requires the global coin selection lock to be held.
func (l *LightningWallet) ListUnspentWitnessFromDefaultAccount(
        minConfs, maxConfs int32) ([]*Utxo, error) {

        return l.WalletController.ListUnspentWitness(
                minConfs, maxConfs, DefaultAccountName,
        )
}

// LockedOutpoints returns a list of all currently locked outpoint.
func (l *LightningWallet) LockedOutpoints() []*wire.OutPoint {
        outPoints := make([]*wire.OutPoint, 0, len(l.lockedOutPoints))
        for outPoint := range l.lockedOutPoints {
                outPoint := outPoint

                outPoints = append(outPoints, &outPoint)
        }

        return outPoints
}

// ResetReservations reset the volatile wallet state which tracks all currently
// active reservations.
func (l *LightningWallet) ResetReservations() {
        l.nextFundingID = 0
        l.fundingLimbo = make(map[uint64]*ChannelReservation)
        l.reservationIDs = make(map[[32]byte]uint64)

        for outpoint := range l.lockedOutPoints {
                _ = l.ReleaseOutput(chanfunding.LndInternalLockID, outpoint)
        }
        l.lockedOutPoints = make(map[wire.OutPoint]struct{})
}

// ActiveReservations returns a slice of all the currently active
// (non-canceled) reservations.
func (l *LightningWallet) ActiveReservations() []*ChannelReservation {
        reservations := make([]*ChannelReservation, 0, len(l.fundingLimbo))
        for _, reservation := range l.fundingLimbo {
                reservations = append(reservations, reservation)
        }

        return reservations
}

// requestHandler is the primary goroutine(s) responsible for handling, and
// dispatching replies to all messages.
func (l *LightningWallet) requestHandler() {
        defer l.wg.Done()

out:
        for {
                select {
                case m := <-l.msgChan:
                        switch msg := m.(type) {
                        case *InitFundingReserveMsg:
                                l.handleFundingReserveRequest(msg)
                        case *fundingReserveCancelMsg:
                                l.handleFundingCancelRequest(msg)
                        case *addSingleContributionMsg:
                                l.handleSingleContribution(msg)
                        case *addContributionMsg:
                                l.handleContributionMsg(msg)
                        case *continueContributionMsg:
                                l.handleChanPointReady(msg)
                        case *addSingleFunderSigsMsg:
                                l.handleSingleFunderSigs(msg)
                        case *addCounterPartySigsMsg:
                                l.handleFundingCounterPartySigs(msg)
                        }
                case <-l.quit:
                        // TODO: do some clean up
                        break out
                }
        }
}

// InitChannelReservation kicks off the 3-step workflow required to successfully
// open a payment channel with a remote node. As part of the funding
// reservation, the inputs selected for the funding transaction are 'locked'.
// This ensures that multiple channel reservations aren't double spending the
// same inputs in the funding transaction. If reservation initialization is
// successful, a ChannelReservation containing our completed contribution is
// returned. Our contribution contains all the items necessary to allow the
// counterparty to build the funding transaction, and both versions of the
// commitment transaction. Otherwise, an error occurred and a nil pointer along
// with an error are returned.
//
// Once a ChannelReservation has been obtained, two additional steps must be
// processed before a payment channel can be considered 'open'. The second step
// validates, and processes the counterparty's channel contribution. The third,
// and final step verifies all signatures for the inputs of the funding
// transaction, and that the signature we record for our version of the
// commitment transaction is valid.
func (l *LightningWallet) InitChannelReservation(
        req *InitFundingReserveMsg) (*ChannelReservation, error) {

        req.resp = make(chan *ChannelReservation, 1)
        req.err = make(chan error, 1)

        select {
        case l.msgChan <- req:
        case <-l.quit:
                return nil, errors.New("wallet shutting down")
        }

        return <-req.resp, <-req.err
}

// RegisterFundingIntent allows a caller to signal to the wallet that if a
// pending channel ID of expectedID is found, then it can skip constructing a
// new chanfunding.Assembler, and instead use the specified chanfunding.Intent.
// As an example, this lets some of the parameters for funding transaction to
// be negotiated outside the regular funding protocol.
func (l *LightningWallet) RegisterFundingIntent(expectedID [32]byte,
        shimIntent chanfunding.Intent) error {

        l.intentMtx.Lock()
        defer l.intentMtx.Unlock()

        // Sanity check the pending channel ID is not empty.
        var zeroID [32]byte
        if expectedID == zeroID {
                return ErrEmptyPendingChanID
        }

        if _, ok := l.fundingIntents[expectedID]; ok {
                return fmt.Errorf("%w: already has intent registered: %x",
                        ErrDuplicatePendingChanID, expectedID[:])
        }

        l.fundingIntents[expectedID] = shimIntent

        return nil
}

// PsbtFundingVerify looks up a previously registered funding intent by its
// pending channel ID and tries to advance the state machine by verifying the
// passed PSBT.
func (l *LightningWallet) PsbtFundingVerify(pendingChanID [32]byte,
        packet *psbt.Packet, skipFinalize bool) error {

        l.intentMtx.Lock()
        defer l.intentMtx.Unlock()

        intent, ok := l.fundingIntents[pendingChanID]
        if !ok {
                return fmt.Errorf("no funding intent found for "+
                        "pendingChannelID(%x)", pendingChanID[:])
        }
        psbtIntent, ok := intent.(*chanfunding.PsbtIntent)
        if !ok {
                return fmt.Errorf("incompatible funding intent")
        }

        if skipFinalize && psbtIntent.ShouldPublishFundingTX() {
                return fmt.Errorf("cannot set skip_finalize for channel that " +
                        "did not set no_publish")
        }

        err := psbtIntent.Verify(packet, skipFinalize)
        if err != nil {
                return fmt.Errorf("error verifying PSBT: %w", err)
        }

        // Get the channel reservation for that corresponds to this pending
        // channel ID.
        l.limboMtx.Lock()
        pid, ok := l.reservationIDs[pendingChanID]
        if !ok {
                l.limboMtx.Unlock()
                return fmt.Errorf("no channel reservation found for "+
                        "pendingChannelID(%x)", pendingChanID[:])
        }

        pendingReservation, ok := l.fundingLimbo[pid]
        l.limboMtx.Unlock()

        if !ok {
                return fmt.Errorf("no channel reservation found for "+
                        "reservation ID %v", pid)
        }

        // Now the PSBT has been populated and verified, we can again check
        // whether the value reserved for anchor fee bumping is respected.
        isPublic := pendingReservation.partialState.ChannelFlags&lnwire.FFAnnounceChannel != 0
        hasAnchors := pendingReservation.partialState.ChanType.HasAnchors()
        return l.enforceNewReservedValue(intent, isPublic, hasAnchors)
}

// PsbtFundingFinalize looks up a previously registered funding intent by its
// pending channel ID and tries to advance the state machine by finalizing the
// passed PSBT.
func (l *LightningWallet) PsbtFundingFinalize(pid [32]byte, packet *psbt.Packet,
        rawTx *wire.MsgTx) error {

        l.intentMtx.Lock()
        defer l.intentMtx.Unlock()

        intent, ok := l.fundingIntents[pid]
        if !ok {
                return fmt.Errorf("no funding intent found for "+
                        "pendingChannelID(%x)", pid[:])
        }
        psbtIntent, ok := intent.(*chanfunding.PsbtIntent)
        if !ok {
                return fmt.Errorf("incompatible funding intent")
        }

        // Either the PSBT or the raw TX must be set.
        switch {
        case packet != nil && rawTx == nil:
                err := psbtIntent.Finalize(packet)
                if err != nil {
                        return fmt.Errorf("error finalizing PSBT: %w", err)
                }

        case rawTx != nil && packet == nil:
                err := psbtIntent.FinalizeRawTX(rawTx)
                if err != nil {
                        return fmt.Errorf("error finalizing raw TX: %w", err)
                }

        default:
                return fmt.Errorf("either a PSBT or raw TX must be specified")
        }

        return nil
}

// CancelFundingIntent allows a caller to cancel a previously registered
// funding intent. If no intent was found, then an error will be returned.
func (l *LightningWallet) CancelFundingIntent(pid [32]byte) error {
        l.intentMtx.Lock()
        defer l.intentMtx.Unlock()

        intent, ok := l.fundingIntents[pid]
        if !ok {
                return fmt.Errorf("no funding intent found for "+
                        "pendingChannelID(%x)", pid[:])
        }

        // Give the intent a chance to clean up after itself, removing coin
        // locks or similar reserved resources.
        intent.Cancel()

        delete(l.fundingIntents, pid)

        return nil
}

// handleFundingReserveRequest processes a message intending to create, and
// validate a funding reservation request.
func (l *LightningWallet) handleFundingReserveRequest(req *InitFundingReserveMsg) {

        noFundsCommitted := req.LocalFundingAmt == 0 &&
                req.RemoteFundingAmt == 0 && req.FundUpToMaxAmt == 0

        // It isn't possible to create a channel with zero funds committed.
        if noFundsCommitted {
                err := ErrZeroCapacity()
                req.err <- err
                req.resp <- nil
                return
        }

        // If the funding request is for a different chain than the one the
        // wallet is aware of, then we'll reject the request.
        if !bytes.Equal(l.Cfg.NetParams.GenesisHash[:], req.ChainHash[:]) {
                err := ErrChainMismatch(
                        l.Cfg.NetParams.GenesisHash, req.ChainHash,
                )
                req.err <- err
                req.resp <- nil
                return
        }

        // We need to avoid enforcing reserved value in the middle of PSBT
        // funding because some of the following steps may add UTXOs funding
        // the on-chain wallet.
        // The enforcement still happens at the last step - in PsbtFundingVerify
        enforceNewReservedValue := true

        // If no chanFunder was provided, then we'll assume the default
        // assembler, which is backed by the wallet's internal coin selection.
        if req.ChanFunder == nil {
                // We use the P2WSH dust limit since it is larger than the
                // P2WPKH dust limit and to avoid threading through two
                // different dust limits.
                cfg := chanfunding.WalletConfig{
                        CoinSource: NewCoinSource(
                                l, req.AllowUtxoForFunding,
                        ),
                        CoinSelectLocker: l,
                        CoinLeaser:       l,
                        Signer:           l.Cfg.Signer,
                        DustLimit: DustLimitForSize(
                                input.P2WSHSize,
                        ),
                        CoinSelectionStrategy: l.Cfg.CoinSelectionStrategy,
                }
                req.ChanFunder = chanfunding.NewWalletAssembler(cfg)
        } else {
                _, isPsbtFunder := req.ChanFunder.(*chanfunding.PsbtAssembler)
                enforceNewReservedValue = !isPsbtFunder
        }

        localFundingAmt := req.LocalFundingAmt
        remoteFundingAmt := req.RemoteFundingAmt
        hasAnchors := req.CommitType.HasAnchors()

        var (
                fundingIntent chanfunding.Intent
                err           error
        )

        // If we've just received an inbound funding request that we have a
        // registered shim intent to, then we'll obtain the backing intent now.
        // In this case, we're doing a special funding workflow that allows
        // more advanced constructions such as channel factories to be
        // instantiated.
        l.intentMtx.Lock()
        fundingIntent, ok := l.fundingIntents[req.PendingChanID]
        l.intentMtx.Unlock()

        // Otherwise, this is a normal funding flow, so we'll use the chan
        // funder in the attached request to provision the inputs/outputs
        // that'll ultimately be used to construct the funding transaction.
        if !ok {
                var err error
                var numAnchorChans int

                // Get the number of anchor channels to determine if there is a
                // reserved value that must be respected when funding up to the
                // maximum amount. Since private channels (most likely) won't be
                // used for routing other than the last hop, they bear a smaller
                // risk that we must force close them in order to resolve a HTLC
                // up/downstream. Hence we exclude them from the count of anchor
                // channels in order to attribute the respective anchor amount
                // to the channel capacity.
                if req.FundUpToMaxAmt > 0 && req.MinFundAmt > 0 {
                        numAnchorChans, err = l.CurrentNumAnchorChans()
                        if err != nil {
                                req.err <- err
                                req.resp <- nil
                                return
                        }

                        isPublic := req.Flags&lnwire.FFAnnounceChannel != 0
                        if hasAnchors && isPublic {
                                numAnchorChans++
                        }
                }

                // Coin selection is done on the basis of sat/kw, so we'll use
                // the fee rate passed in to perform coin selection.
                fundingReq := &chanfunding.Request{
                        RemoteAmt:         req.RemoteFundingAmt,
                        LocalAmt:          req.LocalFundingAmt,
                        FundUpToMaxAmt:    req.FundUpToMaxAmt,
                        MinFundAmt:        req.MinFundAmt,
                        RemoteChanReserve: req.RemoteChanReserve,
                        PushAmt: lnwire.MilliSatoshi.ToSatoshis(
                                req.PushMSat,
                        ),
                        WalletReserve: l.RequiredReserve(
                                uint32(numAnchorChans),
                        ),
                        Outpoints:    req.Outpoints,
                        MinConfs:     req.MinConfs,
                        SubtractFees: req.SubtractFees,
                        FeeRate:      req.FundingFeePerKw,
                        ChangeAddr: func() (btcutil.Address, error) {
                                return l.NewAddress(
                                        TaprootPubkey, true, DefaultAccountName,
                                )
                        },
                        Musig2: req.CommitType.IsTaproot(),
                }
                fundingIntent, err = req.ChanFunder.ProvisionChannel(
                        fundingReq,
                )
                if err != nil {
                        req.err <- err
                        req.resp <- nil
                        return
                }

                // Register the funding intent now in case we need to access it
                // again later, as it's the case for the PSBT state machine for
                // example.
                err = l.RegisterFundingIntent(req.PendingChanID, fundingIntent)
                if err != nil {
                        req.err <- err
                        req.resp <- nil
                        return
                }

                walletLog.Debugf("Registered funding intent for "+
                        "PendingChanID: %x", req.PendingChanID)

                localFundingAmt = fundingIntent.LocalFundingAmt()
                remoteFundingAmt = fundingIntent.RemoteFundingAmt()
        }

        // At this point there _has_ to be a funding intent, otherwise something
        // went really wrong.
        if fundingIntent == nil {
                req.err <- fmt.Errorf("no funding intent present")
                req.resp <- nil
                return
        }

        // If this is a shim intent, then it may be attempting to use an
        // existing set of keys for the funding workflow. In this case, we'll
        // make a simple wrapper keychain.KeyRing that will proxy certain
        // derivation calls to future callers.
        var (
                keyRing    keychain.KeyRing = l.SecretKeyRing
                thawHeight uint32
        )
        if shimIntent, ok := fundingIntent.(*chanfunding.ShimIntent); ok {
                keyRing = &shimKeyRing{
                        KeyRing:    keyRing,
                        ShimIntent: shimIntent,
                }

                // As this was a registered shim intent, we'll obtain the thaw
                // height of the intent, if present at all. If this is
                // non-zero, then we'll mark this as the proper channel type.
                thawHeight = shimIntent.ThawHeight()
        }

        // Now that we have a funding intent, we'll check whether funding a
        // channel using it would violate our reserved value for anchor channel
        // fee bumping.
        //
        // Check the reserved value using the inputs and outputs given by the
        // intent. Note that for the PSBT intent type we don't yet have the
        // funding tx ready, so this will always pass.  We'll do another check
        // when the PSBT has been verified.
        isPublic := req.Flags&lnwire.FFAnnounceChannel != 0
        if enforceNewReservedValue {
                err = l.enforceNewReservedValue(fundingIntent, isPublic, hasAnchors)
                if err != nil {
                        fundingIntent.Cancel()

                        req.err <- err
                        req.resp <- nil
                        return
                }
        }

        // The total channel capacity will be the size of the funding output we
        // created plus the remote contribution.
        capacity := localFundingAmt + remoteFundingAmt

        id := atomic.AddUint64(&l.nextFundingID, 1)
        reservation, err := NewChannelReservation(
                capacity, localFundingAmt, l, id, l.Cfg.NetParams.GenesisHash,
                thawHeight, req,
        )
        if err != nil {
                fundingIntent.Cancel()

                req.err <- err
                req.resp <- nil
                return
        }

        err = l.initOurContribution(
                reservation, fundingIntent, req.NodeAddr, req.NodeID, keyRing,
        )
        if err != nil {
                fundingIntent.Cancel()

                req.err <- err
                req.resp <- nil
                return
        }

        // Create a limbo and record entry for this newly pending funding
        // request.
        l.limboMtx.Lock()
        l.fundingLimbo[id] = reservation
        l.reservationIDs[req.PendingChanID] = id
        l.limboMtx.Unlock()

        // Funding reservation request successfully handled. The funding inputs
        // will be marked as unavailable until the reservation is either
        // completed, or canceled.
        req.resp <- reservation
        req.err <- nil

        walletLog.Debugf("Successfully handled funding reservation with "+
                "pendingChanID: %x, reservationID: %v",
                reservation.pendingChanID, reservation.reservationID)
}

// enforceReservedValue enforces that the wallet, upon a new channel being
// opened, meets the minimum amount of funds required for each advertised anchor
// channel.
//
// We only enforce the reserve if we are contributing funds to the channel. This
// is done to still allow incoming channels even though we have no UTXOs
// available, as in bootstrapping phases.
func (l *LightningWallet) enforceNewReservedValue(fundingIntent chanfunding.Intent,
        isPublic, hasAnchors bool) error {

        // Only enforce the reserve when an advertised channel is being opened
        // in which we are contributing funds to. This ensures we never dip
        // below the reserve.
        if !isPublic || fundingIntent.LocalFundingAmt() == 0 {
                return nil
        }

        numAnchors, err := l.CurrentNumAnchorChans()
        if err != nil {
                return err
        }

        // Add the to-be-opened channel.
        if hasAnchors {
                numAnchors++
        }

        return l.WithCoinSelectLock(func() error {
                _, err := l.CheckReservedValue(
                        fundingIntent.Inputs(), fundingIntent.Outputs(),
                        numAnchors,
                )
                return err
        })
}

// CurrentNumAnchorChans returns the current number of non-private anchor
// channels the wallet should be ready to fee bump if needed.
func (l *LightningWallet) CurrentNumAnchorChans() (int, error) {
        // Count all anchor channels that are open or pending
        // open, or waiting close.
        chans, err := l.Cfg.Database.FetchAllChannels()
        if err != nil {
                return 0, err
        }

        var numAnchors int
        cntChannel := func(c *channeldb.OpenChannel) {
                // We skip private channels, as we assume they won't be used
                // for routing.
                if c.ChannelFlags&lnwire.FFAnnounceChannel == 0 {
                        return
                }

                // Count anchor channels.
                if c.ChanType.HasAnchors() {
                        numAnchors++
                }
        }

        for _, c := range chans {
                cntChannel(c)
        }

        // We also count pending close channels.
        pendingClosed, err := l.Cfg.Database.FetchClosedChannels(
                true,
        )
        if err != nil {
                return 0, err
        }

        for _, c := range pendingClosed {
                c, err := l.Cfg.Database.FetchHistoricalChannel(
                        &c.ChanPoint,
                )
                if err != nil {
                        // We don't have a guarantee that all channels re found
                        // in the historical channels bucket, so we continue.
                        walletLog.Warnf("Unable to fetch historical "+
                                "channel: %v", err)
                        continue
                }

                cntChannel(c)
        }

        return numAnchors, nil
}

// CheckReservedValue checks whether publishing a transaction with the given
// inputs and outputs would violate the value we reserve in the wallet for
// bumping the fee of anchor channels. The numAnchorChans argument should be
// set the number of open anchor channels controlled by the wallet after
// the transaction has been published.
//
// If the reserved value is violated, the returned error will be
// ErrReservedValueInvalidated. The method will also return the current
// reserved value, both in case of success and in case of
// ErrReservedValueInvalidated.
//
// NOTE: This method should only be run with the CoinSelectLock held.
func (l *LightningWallet) CheckReservedValue(in []wire.OutPoint,
        out []*wire.TxOut, numAnchorChans int) (btcutil.Amount, error) {

        // Get all unspent coins in the wallet. We only care about those part of
        // the wallet's default account as we know we can readily sign for those
        // at any time.
        witnessOutputs, err := l.ListUnspentWitnessFromDefaultAccount(
                0, math.MaxInt32,
        )
        if err != nil {
                return 0, err
        }

        ourInput := make(map[wire.OutPoint]struct{})
        for _, op := range in {
                ourInput[op] = struct{}{}
        }

        // When crafting a transaction with inputs from the wallet, these coins
        // will usually be locked in the process, and not be returned when
        // listing unspents. In this case they have already been deducted from
        // the wallet balance. In case they haven't been properly locked, we
        // check whether they are still listed among our unspents and deduct
        // them.
        var walletBalance btcutil.Amount
        for _, in := range witnessOutputs {
                // Spending an unlocked wallet UTXO, don't add it to the
                // balance.
                if _, ok := ourInput[in.OutPoint]; ok {
                        continue
                }

                walletBalance += in.Value
        }

        // Now we go through the outputs of the transaction, if any of the
        // outputs are paying into the wallet (likely a change output), we add
        // it to our final balance.
        for _, txOut := range out {
                _, addrs, _, err := txscript.ExtractPkScriptAddrs(
                        txOut.PkScript, &l.Cfg.NetParams,
                )
                if err != nil {
                        // Non-standard outputs can safely be skipped because
                        // they're not supported by the wallet.
                        continue
                }

                for _, addr := range addrs {
                        if !l.IsOurAddress(addr) {
                                continue
                        }

                        walletBalance += btcutil.Amount(txOut.Value)

                        // We break since we don't want to double count the output.
                        break
                }
        }

        // We reserve a given amount for each anchor channel.
        reserved := l.RequiredReserve(uint32(numAnchorChans))

        if walletBalance < reserved {
                walletLog.Debugf("Reserved value=%v above final "+
                        "walletbalance=%v with %d anchor channels open",
                        reserved, walletBalance, numAnchorChans)
                return reserved, ErrReservedValueInvalidated
        }

        return reserved, nil
}

// CheckReservedValueTx calls CheckReservedValue with the inputs and outputs
// from the given tx, with the number of anchor channels currently open in the
// database.
//
// NOTE: This method should only be run with the CoinSelectLock held.
func (l *LightningWallet) CheckReservedValueTx(req CheckReservedValueTxReq) (
        btcutil.Amount, error) {

        numAnchors, err := l.CurrentNumAnchorChans()
        if err != nil {
                return 0, err
        }

        var inputs []wire.OutPoint
        for _, txIn := range req.Tx.TxIn {
                inputs = append(inputs, txIn.PreviousOutPoint)
        }

        reservedVal, err := l.CheckReservedValue(
                inputs, req.Tx.TxOut, numAnchors,
        )
        switch {
        // If the error returned from CheckReservedValue is
        // ErrReservedValueInvalidated, then it did nonetheless return
        // the required reserved value and we check for the optional
        // change index.
        case errors.Is(err, ErrReservedValueInvalidated):
                // Without a change index provided there is nothing more to
                // check and the error is returned.
                if req.ChangeIndex == nil {
                        return reservedVal, err
                }

                // If a change index was provided we make only sure that it
                // would leave sufficient funds for the reserved balance value.
                //
                // Note: This is used if a change output index is explicitly set
                // but that may not be watched by the wallet and therefore is
                // not picked up by the call to CheckReservedValue above.
                chIdx := *req.ChangeIndex
                if chIdx < 0 || chIdx >= len(req.Tx.TxOut) ||
                        req.Tx.TxOut[chIdx].Value < int64(reservedVal) {

                        return reservedVal, err
                }

        case err != nil:
                return reservedVal, err
        }

        return reservedVal, nil
}

// initOurContribution initializes the given ChannelReservation with our coins
// and change reserved for the channel, and derives the keys to use for this
// channel.
func (l *LightningWallet) initOurContribution(reservation *ChannelReservation,
        fundingIntent chanfunding.Intent, nodeAddr net.Addr,
        nodeID *btcec.PublicKey, keyRing keychain.KeyRing) error {

        // Grab the mutex on the ChannelReservation to ensure thread-safety
        reservation.Lock()
        defer reservation.Unlock()

        // At this point, if we have a funding intent, we'll use it to populate
        // the existing reservation state entries for our coin selection.
        if fundingIntent != nil {
                if intent, ok := fundingIntent.(*chanfunding.FullIntent); ok {
                        for _, coin := range intent.InputCoins {
                                reservation.ourContribution.Inputs = append(
                                        reservation.ourContribution.Inputs,
                                        &wire.TxIn{
                                                PreviousOutPoint: coin.OutPoint,
                                        },
                                )
                        }
                        reservation.ourContribution.ChangeOutputs = intent.ChangeOutputs
                }

                reservation.fundingIntent = fundingIntent
        }

        reservation.nodeAddr = nodeAddr
        reservation.partialState.IdentityPub = nodeID

        var err error
        reservation.ourContribution.MultiSigKey, err = keyRing.DeriveNextKey(
                keychain.KeyFamilyMultiSig,
        )
        if err != nil {
                return err
        }
        reservation.ourContribution.RevocationBasePoint, err = keyRing.DeriveNextKey(
                keychain.KeyFamilyRevocationBase,
        )
        if err != nil {
                return err
        }
        reservation.ourContribution.HtlcBasePoint, err = keyRing.DeriveNextKey(
                keychain.KeyFamilyHtlcBase,
        )
        if err != nil {
                return err
        }
        reservation.ourContribution.PaymentBasePoint, err = keyRing.DeriveNextKey(
                keychain.KeyFamilyPaymentBase,
        )
        if err != nil {
                return err
        }
        reservation.ourContribution.DelayBasePoint, err = keyRing.DeriveNextKey(
                keychain.KeyFamilyDelayBase,
        )
        if err != nil {
                return err
        }

        // With the above keys created, we'll also need to initialize our
        // revocation tree state, and from that generate the per-commitment
        // point.
        producer, taprootNonceProducer, err := l.nextRevocationProducer(
                reservation, keyRing,
        )
        if err != nil {
                return err
        }

        firstPreimage, err := producer.AtIndex(0)
        if err != nil {
                return err
        }
        reservation.ourContribution.FirstCommitmentPoint = input.ComputeCommitmentPoint(
                firstPreimage[:],
        )

        reservation.partialState.RevocationProducer = producer
        reservation.ourContribution.CommitmentParams.DustLimit =
                DustLimitUnknownWitness()

        // If taproot channels are active, then we'll generate our verification
        // nonce here. We'll use this nonce to verify the signature for our
        // local commitment transaction. If we need to force close, then this
        // is also what'll be used to sign that transaction.
        if reservation.partialState.ChanType.IsTaproot() {
                firstNoncePreimage, err := taprootNonceProducer.AtIndex(0)
                if err != nil {
                        return err
                }

                // As we'd like the local nonce we send over to be generated
                // deterministically, we'll provide a custom reader that
                // actually just uses our sha-chain pre-image as the primary
                // randomness source.
                shaChainRand := musig2.WithCustomRand(
                        bytes.NewBuffer(firstNoncePreimage[:]),
                )
                pubKeyOpt := musig2.WithPublicKey(
                        reservation.ourContribution.MultiSigKey.PubKey,
                )
                reservation.ourContribution.LocalNonce, err = musig2.GenNonces(
                        pubKeyOpt, shaChainRand,
                )
                if err != nil {
                        return err
                }
        }

        return nil
}

// handleFundingReserveCancel cancels an existing channel reservation. As part
// of the cancellation, outputs previously selected as inputs for the funding
// transaction via coin selection are freed allowing future reservations to
// include them.
func (l *LightningWallet) handleFundingCancelRequest(req *fundingReserveCancelMsg) {
        l.limboMtx.Lock()
        defer l.limboMtx.Unlock()

        pendingReservation, ok := l.fundingLimbo[req.pendingFundingID]
        if !ok {
                // TODO(roasbeef): make new error, "unknown funding state" or something
                req.err <- fmt.Errorf("attempted to cancel non-existent funding state")
                return
        }

        // Grab the mutex on the ChannelReservation to ensure thread-safety
        pendingReservation.Lock()
        defer pendingReservation.Unlock()

        // Mark all previously locked outpoints as usable for future funding
        // requests.
        for _, unusedInput := range pendingReservation.ourContribution.Inputs {
                delete(l.lockedOutPoints, unusedInput.PreviousOutPoint)
                _ = l.ReleaseOutput(
                        chanfunding.LndInternalLockID,
                        unusedInput.PreviousOutPoint,
                )
        }

        delete(l.fundingLimbo, req.pendingFundingID)

        pid := pendingReservation.pendingChanID
        delete(l.reservationIDs, pid)

        l.intentMtx.Lock()
        if intent, ok := l.fundingIntents[pid]; ok {
                intent.Cancel()

                delete(l.fundingIntents, pendingReservation.pendingChanID)
        }
        l.intentMtx.Unlock()

        req.err <- nil
}

// createCommitOpts is a struct that holds the options for creating a new
// commitment transaction.
type createCommitOpts struct {
        localAuxLeaves  fn.Option[CommitAuxLeaves]
        remoteAuxLeaves fn.Option[CommitAuxLeaves]
}

// defaultCommitOpts returns a new createCommitOpts with default values.
func defaultCommitOpts() createCommitOpts {
        return createCommitOpts{}
}

// WithAuxLeaves is a functional option that can be used to set the aux leaves
// for a new commitment transaction.
func WithAuxLeaves(localLeaves,
        remoteLeaves fn.Option[CommitAuxLeaves]) CreateCommitOpt {

        return func(o *createCommitOpts) {
                o.localAuxLeaves = localLeaves
                o.remoteAuxLeaves = remoteLeaves
        }
}

// CreateCommitOpt is a functional option that can be used to modify the way a
// new commitment transaction is created.
type CreateCommitOpt func(*createCommitOpts)

// CreateCommitmentTxns is a helper function that creates the initial
// commitment transaction for both parties. This function is used during the
// initial funding workflow as both sides must generate a signature for the
// remote party's commitment transaction, and verify the signature for their
// version of the commitment transaction.
func CreateCommitmentTxns(localBalance, remoteBalance btcutil.Amount,
        ourChanCfg, theirChanCfg *channeldb.ChannelConfig,
        localCommitPoint, remoteCommitPoint *btcec.PublicKey,
        fundingTxIn wire.TxIn, chanType channeldb.ChannelType, initiator bool,
        leaseExpiry uint32, opts ...CreateCommitOpt) (*wire.MsgTx, *wire.MsgTx,
        error) {

        options := defaultCommitOpts()
        for _, optFunc := range opts {
                optFunc(&options)
        }

        localCommitmentKeys := DeriveCommitmentKeys(
                localCommitPoint, lntypes.Local, chanType, ourChanCfg,
                theirChanCfg,
        )
        remoteCommitmentKeys := DeriveCommitmentKeys(
                remoteCommitPoint, lntypes.Remote, chanType, ourChanCfg,
                theirChanCfg,
        )

        ourCommitTx, err := CreateCommitTx(
                chanType, fundingTxIn, localCommitmentKeys, ourChanCfg,
                theirChanCfg, localBalance, remoteBalance, 0, initiator,
                leaseExpiry, options.localAuxLeaves,
        )
        if err != nil {
                return nil, nil, err
        }

        otxn := btcutil.NewTx(ourCommitTx)
        if err := blockchain.CheckTransactionSanity(otxn); err != nil {
                return nil, nil, err
        }

        theirCommitTx, err := CreateCommitTx(
                chanType, fundingTxIn, remoteCommitmentKeys, theirChanCfg,
                ourChanCfg, remoteBalance, localBalance, 0, !initiator,
                leaseExpiry, options.remoteAuxLeaves,
        )
        if err != nil {
                return nil, nil, err
        }

        ttxn := btcutil.NewTx(theirCommitTx)
        if err := blockchain.CheckTransactionSanity(ttxn); err != nil {
                return nil, nil, err
        }

        return ourCommitTx, theirCommitTx, nil
}

// handleContributionMsg processes the second workflow step for the lifetime of
// a channel reservation. Upon completion, the reservation will carry a
// completed funding transaction (minus the counterparty's input signatures),
// both versions of the commitment transaction, and our signature for their
// version of the commitment transaction.
func (l *LightningWallet) handleContributionMsg(req *addContributionMsg) {

        l.limboMtx.Lock()
        pendingReservation, ok := l.fundingLimbo[req.pendingFundingID]
        l.limboMtx.Unlock()
        if !ok {
                req.err <- fmt.Errorf("attempted to update non-existent funding state")
                return
        }

        // Grab the mutex on the ChannelReservation to ensure thread-safety
        pendingReservation.Lock()
        defer pendingReservation.Unlock()

        // If UpfrontShutdownScript is set, validate that it is a valid script.
        shutdown := req.contribution.UpfrontShutdown
        if len(shutdown) > 0 {
                // Validate the shutdown script.
                if !ValidateUpfrontShutdown(shutdown, &l.Cfg.NetParams) {
                        req.err <- fmt.Errorf("invalid shutdown script")
                        return
                }
        }

        // Some temporary variables to cut down on the resolution verbosity.
        pendingReservation.theirContribution = req.contribution
        theirContribution := req.contribution
        ourContribution := pendingReservation.ourContribution

        // Perform bounds-checking on both ChannelReserve and DustLimit
        // parameters.
        if !pendingReservation.validateReserveBounds() {
                req.err <- fmt.Errorf("invalid reserve and dust bounds")
                return
        }

        var (
                chanPoint *wire.OutPoint
                err       error
        )

        // At this point, we can now construct our channel point. Depending on
        // which type of intent we obtained from our chanfunding.Assembler,
        // we'll carry out a distinct set of steps.
        switch fundingIntent := pendingReservation.fundingIntent.(type) {
        // The transaction was created outside of the wallet and might already
        // be published. Nothing left to do other than using the correct
        // outpoint.
        case *chanfunding.ShimIntent:
                chanPoint, err = fundingIntent.ChanPoint()
                if err != nil {
                        req.err <- fmt.Errorf("unable to obtain chan point: %w",
                                err)
                        return
                }

                pendingReservation.partialState.FundingOutpoint = *chanPoint

        // The user has signaled that they want to use a PSBT to construct the
        // funding transaction. Because we now have the multisig keys from both
        // parties, we can create the multisig script that needs to be funded
        // and then pause the process until the user supplies the PSBT
        // containing the eventual funding transaction.
        case *chanfunding.PsbtIntent:
                if fundingIntent.PendingPsbt != nil {
                        req.err <- fmt.Errorf("PSBT funding already in" +
                                "progress")
                        return
                }

                // Now that we know our contribution, we can bind both the local
                // and remote key which will be needed to calculate the multisig
                // funding output in a next step.
                pendingChanID := pendingReservation.pendingChanID

                walletLog.Debugf("Advancing PSBT funding flow for "+
                        "pending_id(%x), binding keys local_key=%v, "+
                        "remote_key=%x", pendingChanID,
                        &ourContribution.MultiSigKey,
                        theirContribution.MultiSigKey.PubKey.SerializeCompressed())

                fundingIntent.BindKeys(
                        &ourContribution.MultiSigKey,
                        theirContribution.MultiSigKey.PubKey,
                )

                // We might have a tapscript root, so we'll bind that now to
                // ensure we make the proper funding output.
                fundingIntent.BindTapscriptRoot(
                        pendingReservation.partialState.TapscriptRoot,
                )

                // Exit early because we can't continue the funding flow yet.
                req.err <- &PsbtFundingRequired{
                        Intent: fundingIntent,
                }
                return

        case *chanfunding.FullIntent:
                // Now that we know their public key, we can bind theirs as
                // well as ours to the funding intent.
                fundingIntent.BindKeys(
                        &pendingReservation.ourContribution.MultiSigKey,
                        theirContribution.MultiSigKey.PubKey,
                )

                // With our keys bound, we can now construct+sign the final
                // funding transaction and also obtain the chanPoint that
                // creates the channel.
                fundingTx, err := fundingIntent.CompileFundingTx(
                        theirContribution.Inputs,
                        theirContribution.ChangeOutputs,
                )
                if err != nil {
                        req.err <- fmt.Errorf("unable to construct funding "+
                                "tx: %v", err)
                        return
                }
                chanPoint, err = fundingIntent.ChanPoint()
                if err != nil {
                        req.err <- fmt.Errorf("unable to obtain chan "+
                                "point: %v", err)
                        return
                }

                // Finally, we'll populate the relevant information in our
                // pendingReservation so the rest of the funding flow can
                // continue as normal.
                pendingReservation.fundingTx = fundingTx
                pendingReservation.partialState.FundingOutpoint = *chanPoint
                pendingReservation.ourFundingInputScripts = make(
                        []*input.Script, 0, len(ourContribution.Inputs),
                )
                for _, txIn := range fundingTx.TxIn {
                        _, err := l.FetchOutpointInfo(&txIn.PreviousOutPoint)
                        if err != nil {
                                continue
                        }

                        pendingReservation.ourFundingInputScripts = append(
                                pendingReservation.ourFundingInputScripts,
                                &input.Script{
                                        Witness:   txIn.Witness,
                                        SigScript: txIn.SignatureScript,
                                },
                        )
                }

                walletLog.Tracef("Funding tx for ChannelPoint(%v) "+
                        "generated: %v", chanPoint,
                        lnutils.SpewLogClosure(fundingTx))
        }

        // If we landed here and didn't exit early, it means we already have
        // the channel point ready. We can jump directly to the next step.
        l.handleChanPointReady(&continueContributionMsg{
                pendingFundingID: req.pendingFundingID,
                err:              req.err,
        })
}

// genMusigSession generates a new musig2 pair session that we can use to sign
// the commitment transaction for the remote party, and verify their incoming
// partial signature.
func genMusigSession(ourContribution, theirContribution *ChannelContribution,
        signer input.MuSig2Signer, fundingOutput *wire.TxOut,
        tapscriptRoot fn.Option[chainhash.Hash]) *MusigPairSession {

        return NewMusigPairSession(&MusigSessionCfg{
                LocalKey:       ourContribution.MultiSigKey,
                RemoteKey:      theirContribution.MultiSigKey,
                LocalNonce:     *ourContribution.LocalNonce,
                RemoteNonce:    *theirContribution.LocalNonce,
                Signer:         signer,
                InputTxOut:     fundingOutput,
                TapscriptTweak: tapscriptRoot,
        })
}

// signCommitTx generates a valid input.Signature to send to the remote party
// for their version of the commitment transaction. For regular channels, this
// will be a normal ECDSA signature. For taproot channels, this will instead be
// a musig2 partial signature that also includes the nonce used to generate it.
func (l *LightningWallet) signCommitTx(pendingReservation *ChannelReservation,
        commitTx *wire.MsgTx, fundingOutput *wire.TxOut,
        fundingWitnessScript []byte) (input.Signature, error) {

        ourContribution := pendingReservation.ourContribution
        theirContribution := pendingReservation.theirContribution

        var (
                sigTheirCommit input.Signature
                err            error
        )
        switch {
        // For regular channels, we can just send over a normal ECDSA signature
        // w/o any extra steps.
        case !pendingReservation.partialState.ChanType.IsTaproot():
                ourKey := ourContribution.MultiSigKey
                signDesc := input.SignDescriptor{
                        WitnessScript: fundingWitnessScript,
                        KeyDesc:       ourKey,
                        Output:        fundingOutput,
                        HashType:      txscript.SigHashAll,
                        SigHashes: input.NewTxSigHashesV0Only(
                                commitTx,
                        ),
                        InputIndex: 0,
                }
                sigTheirCommit, err = l.Cfg.Signer.SignOutputRaw(
                        commitTx, &signDesc,
                )
                if err != nil {
                        return nil, err
                }

        // If this is a taproot channel, then we'll need to create an initial
        // musig2 session here as we'll be sending over a _partial_ signature.
        default:
                // We're now ready to sign the first commitment. However, we'll
                // only create the session if that hasn't been done already.
                if pendingReservation.musigSessions == nil {
                        musigSessions := genMusigSession(
                                ourContribution, theirContribution,
                                l.Cfg.Signer, fundingOutput,
                                pendingReservation.partialState.TapscriptRoot,
                        )
                        pendingReservation.musigSessions = musigSessions
                }

                // Now that we have the funding outpoint, we'll generate a
                // musig2 signature for their version of the commitment
                // transaction. We use the remote session as this is for the
                // remote commitment transaction.
                musigSessions := pendingReservation.musigSessions
                partialSig, err := musigSessions.RemoteSession.SignCommit(
                        commitTx,
                )
                if err != nil {
                        return nil, fmt.Errorf("unable to sign "+
                                "commitment: %w", err)
                }

                sigTheirCommit = partialSig
        }

        return sigTheirCommit, nil
}

// handleChanPointReady continues the funding process once the channel point is
// known and the funding transaction can be completed.
func (l *LightningWallet) handleChanPointReady(req *continueContributionMsg) {
        l.limboMtx.Lock()
        pendingReservation, ok := l.fundingLimbo[req.pendingFundingID]
        l.limboMtx.Unlock()
        if !ok {
                req.err <- fmt.Errorf("attempted to update non-existent " +
                        "funding state")
                return
        }

        chanState := pendingReservation.partialState

        // If we have an aux funding desc, then we can use it to populate some
        // of the optional, but opaque TLV blobs we'll carry for the channel.
        chanState.CustomBlob = fn.MapOption(func(desc AuxFundingDesc) tlv.Blob {
                return desc.CustomFundingBlob
        })(req.auxFundingDesc)

        chanState.LocalCommitment.CustomBlob = fn.MapOption(
                func(desc AuxFundingDesc) tlv.Blob {
                        return desc.CustomLocalCommitBlob
                },
        )(req.auxFundingDesc)

        chanState.RemoteCommitment.CustomBlob = fn.MapOption(
                func(desc AuxFundingDesc) tlv.Blob {
                        return desc.CustomRemoteCommitBlob
                },
        )(req.auxFundingDesc)

        ourContribution := pendingReservation.ourContribution
        theirContribution := pendingReservation.theirContribution
        chanPoint := pendingReservation.partialState.FundingOutpoint

        // If we're in the PSBT funding flow, we now should have everything that
        // is needed to construct and publish the full funding transaction.
        intent := pendingReservation.fundingIntent
        if psbtIntent, ok := intent.(*chanfunding.PsbtIntent); ok {
                // With our keys bound, we can now construct and possibly sign
                // the final funding transaction and also obtain the chanPoint
                // that creates the channel. We _have_ to call CompileFundingTx
                // even if we don't publish ourselves as that sets the actual
                // funding outpoint in stone for this channel.
                fundingTx, err := psbtIntent.CompileFundingTx()
                if err != nil {
                        req.err <- fmt.Errorf("unable to construct funding "+
                                "tx: %v", err)
                        return
                }
                chanPointPtr, err := psbtIntent.ChanPoint()
                if err != nil {
                        req.err <- fmt.Errorf("unable to obtain chan "+
                                "point: %v", err)
                        return
                }

                pendingReservation.partialState.FundingOutpoint = *chanPointPtr
                chanPoint = *chanPointPtr

                // Finally, we'll populate the relevant information in our
                // pendingReservation so the rest of the funding flow can
                // continue as normal in case we are going to publish ourselves.
                if psbtIntent.ShouldPublishFundingTX() {
                        pendingReservation.fundingTx = fundingTx
                        pendingReservation.ourFundingInputScripts = make(
                                []*input.Script, 0, len(ourContribution.Inputs),
                        )
                        for _, txIn := range fundingTx.TxIn {
                                pendingReservation.ourFundingInputScripts = append(
                                        pendingReservation.ourFundingInputScripts,
                                        &input.Script{
                                                Witness:   txIn.Witness,
                                                SigScript: txIn.SignatureScript,
                                        },
                                )
                        }
                }
        }

        // Initialize an empty sha-chain for them, tracking the current pending
        // revocation hash (we don't yet know the preimage so we can't add it
        // to the chain).
        s := shachain.NewRevocationStore()
        pendingReservation.partialState.RevocationStore = s

        // Store their current commitment point. We'll need this after the
        // first state transition in order to verify the authenticity of the
        // revocation.
        chanState.RemoteCurrentRevocation = theirContribution.FirstCommitmentPoint

        // Create the txin to our commitment transaction; required to construct
        // the commitment transactions.
        fundingTxIn := wire.TxIn{
                PreviousOutPoint: chanPoint,
        }

        // With the funding tx complete, create both commitment transactions.
        localBalance := pendingReservation.partialState.LocalCommitment.LocalBalance.ToSatoshis()
        remoteBalance := pendingReservation.partialState.LocalCommitment.RemoteBalance.ToSatoshis()
        var leaseExpiry uint32
        if pendingReservation.partialState.ChanType.HasLeaseExpiration() {
                leaseExpiry = pendingReservation.partialState.ThawHeight
        }

        localAuxLeaves := fn.MapOption(
                func(desc AuxFundingDesc) CommitAuxLeaves {
                        return desc.LocalInitAuxLeaves
                },
        )(req.auxFundingDesc)
        remoteAuxLeaves := fn.MapOption(
                func(desc AuxFundingDesc) CommitAuxLeaves {
                        return desc.RemoteInitAuxLeaves
                },
        )(req.auxFundingDesc)

        ourCommitTx, theirCommitTx, err := CreateCommitmentTxns(
                localBalance, remoteBalance, ourContribution.ChannelConfig,
                theirContribution.ChannelConfig,
                ourContribution.FirstCommitmentPoint,
                theirContribution.FirstCommitmentPoint, fundingTxIn,
                pendingReservation.partialState.ChanType,
                pendingReservation.partialState.IsInitiator, leaseExpiry,
                WithAuxLeaves(localAuxLeaves, remoteAuxLeaves),
        )
        if err != nil {
                req.err <- err
                return
        }

        // With both commitment transactions constructed, generate the state
        // obfuscator then use it to encode the current state number within
        // both commitment transactions.
        var stateObfuscator [StateHintSize]byte
        if chanState.ChanType.IsSingleFunder() {
                stateObfuscator = DeriveStateHintObfuscator(
                        ourContribution.PaymentBasePoint.PubKey,
                        theirContribution.PaymentBasePoint.PubKey,
                )
        } else {
                ourSer := ourContribution.PaymentBasePoint.PubKey.SerializeCompressed()
                theirSer := theirContribution.PaymentBasePoint.PubKey.SerializeCompressed()
                switch bytes.Compare(ourSer, theirSer) {
                case -1:
                        stateObfuscator = DeriveStateHintObfuscator(
                                ourContribution.PaymentBasePoint.PubKey,
                                theirContribution.PaymentBasePoint.PubKey,
                        )
                default:
                        stateObfuscator = DeriveStateHintObfuscator(
                                theirContribution.PaymentBasePoint.PubKey,
                                ourContribution.PaymentBasePoint.PubKey,
                        )
                }
        }
        err = initStateHints(ourCommitTx, theirCommitTx, stateObfuscator)
        if err != nil {
                req.err <- err
                return
        }

        // Sort both transactions according to the agreed upon canonical
        // ordering. This lets us skip sending the entire transaction over,
        // instead we'll just send signatures.
        txsort.InPlaceSort(ourCommitTx)
        txsort.InPlaceSort(theirCommitTx)

        walletLog.Tracef("Local commit tx for ChannelPoint(%v): %v",
                chanPoint, lnutils.SpewLogClosure(ourCommitTx))
        walletLog.Tracef("Remote commit tx for ChannelPoint(%v): %v",
                chanPoint, lnutils.SpewLogClosure(theirCommitTx))

        // Record newly available information within the open channel state.
        chanState.FundingOutpoint = chanPoint
        chanState.LocalCommitment.CommitTx = ourCommitTx
        chanState.RemoteCommitment.CommitTx = theirCommitTx

        // Next, we'll obtain the funding witness script, and the funding
        // output itself so we can generate a valid signature for the remote
        // party.
        fundingIntent := pendingReservation.fundingIntent
        fundingWitnessScript, fundingOutput, err := fundingIntent.FundingOutput()
        if err != nil {
                req.err <- fmt.Errorf("unable to obtain funding "+
                        "output: %w", err)
                return
        }

        // Generate a signature for their version of the initial commitment
        // transaction.
        sigTheirCommit, err := l.signCommitTx(
                pendingReservation, theirCommitTx, fundingOutput,
                fundingWitnessScript,
        )
        if err != nil {
                req.err <- err
                return
        }

        pendingReservation.ourCommitmentSig = sigTheirCommit

        req.err <- nil
}

// handleSingleContribution is called as the second step to a single funder
// workflow to which we are the responder. It simply saves the remote peer's
// contribution to the channel, as solely the remote peer will contribute any
// funds to the channel.
func (l *LightningWallet) handleSingleContribution(req *addSingleContributionMsg) {
        l.limboMtx.Lock()
        pendingReservation, ok := l.fundingLimbo[req.pendingFundingID]
        l.limboMtx.Unlock()
        if !ok {
                req.err <- fmt.Errorf("attempted to update non-existent funding state")
                return
        }

        // Grab the mutex on the channelReservation to ensure thread-safety.
        pendingReservation.Lock()
        defer pendingReservation.Unlock()

        // Validate that the remote's UpfrontShutdownScript is a valid script
        // if it's set.
        shutdown := req.contribution.UpfrontShutdown
        if len(shutdown) > 0 {
                // Validate the shutdown script.
                if !ValidateUpfrontShutdown(shutdown, &l.Cfg.NetParams) {
                        req.err <- fmt.Errorf("invalid shutdown script")
                        return
                }
        }

        // Simply record the counterparty's contribution into the pending
        // reservation data as they'll be solely funding the channel entirely.
        pendingReservation.theirContribution = req.contribution
        theirContribution := pendingReservation.theirContribution
        chanState := pendingReservation.partialState

        // Perform bounds checking on both ChannelReserve and DustLimit
        // parameters. The ChannelReserve may have been changed by the
        // ChannelAcceptor RPC, so this is necessary.
        if !pendingReservation.validateReserveBounds() {
                req.err <- fmt.Errorf("invalid reserve and dust bounds")
                return
        }

        // Initialize an empty sha-chain for them, tracking the current pending
        // revocation hash (we don't yet know the preimage so we can't add it
        // to the chain).
        remotePreimageStore := shachain.NewRevocationStore()
        chanState.RevocationStore = remotePreimageStore

        // Now that we've received their first commitment point, we'll store it
        // within the channel state so we can sync it to disk once the funding
        // process is complete.
        chanState.RemoteCurrentRevocation = theirContribution.FirstCommitmentPoint

        req.err <- nil
}

// verifyFundingInputs attempts to verify all remote inputs to the funding
// transaction.
func (l *LightningWallet) verifyFundingInputs(fundingTx *wire.MsgTx,
        remoteInputScripts []*input.Script) error {

        sigIndex := 0
        fundingHashCache := input.NewTxSigHashesV0Only(fundingTx)
        inputScripts := remoteInputScripts
        for i, txin := range fundingTx.TxIn {
                if len(inputScripts) != 0 && len(txin.Witness) == 0 {
                        // Attach the input scripts so we can verify it below.
                        txin.Witness = inputScripts[sigIndex].Witness
                        txin.SignatureScript = inputScripts[sigIndex].SigScript

                        // Fetch the alleged previous output along with the
                        // pkscript referenced by this input.
                        //
                        // TODO(roasbeef): when dual funder pass actual
                        // height-hint
                        //
                        // TODO(roasbeef): this fails for neutrino always as it
                        // treats the height hint as an exact birthday of the
                        // utxo rather than a lower bound
                        pkScript, err := txscript.ComputePkScript(
                                txin.SignatureScript, txin.Witness,
                        )
                        if err != nil {
                                return fmt.Errorf("cannot create script: %w",
                                        err)
                        }
                        output, err := l.Cfg.ChainIO.GetUtxo(
                                &txin.PreviousOutPoint,
                                pkScript.Script(), 0, l.quit,
                        )
                        if output == nil {
                                return fmt.Errorf("input to funding tx does "+
                                        "not exist: %v", err)
                        }

                        // Ensure that the witness+sigScript combo is valid.
                        vm, err := txscript.NewEngine(
                                output.PkScript, fundingTx, i,
                                txscript.StandardVerifyFlags, nil,
                                fundingHashCache, output.Value,
                                txscript.NewCannedPrevOutputFetcher(
                                        output.PkScript, output.Value,
                                ),
                        )
                        if err != nil {
                                return fmt.Errorf("cannot create script "+
                                        "engine: %s", err)
                        }
                        if err = vm.Execute(); err != nil {
                                return fmt.Errorf("cannot validate "+
                                        "transaction: %s", err)
                        }

                        sigIndex++
                }
        }

        return nil
}

// verifyCommitSig verifies an incoming signature for our version of the
// commitment transaction. For normal channels, this will verify that the ECDSA
// signature is valid. For taproot channels, we'll verify that their partial
// signature is valid, so it can properly be combined with our eventual
// signature when we need to broadcast.
func (l *LightningWallet) verifyCommitSig(res *ChannelReservation,
        commitSig input.Signature, commitTx *wire.MsgTx) error {

        localKey := res.ourContribution.MultiSigKey.PubKey
        remoteKey := res.theirContribution.MultiSigKey.PubKey
        channelValue := int64(res.partialState.Capacity)

        switch {
        // If this isn't a taproot channel, then we'll construct a segwit v0
        // p2wsh sighash.
        case !res.partialState.ChanType.IsTaproot():
                hashCache := input.NewTxSigHashesV0Only(commitTx)
                witnessScript, _, err := input.GenFundingPkScript(
                        localKey.SerializeCompressed(),
                        remoteKey.SerializeCompressed(), channelValue,
                )
                if err != nil {
                        return err
                }

                sigHash, err := txscript.CalcWitnessSigHash(
                        witnessScript, hashCache, txscript.SigHashAll,
                        commitTx, 0, channelValue,
                )
                if err != nil {
                        return err
                }

                // Verify that we've received a valid signature from the remote
                // party for our version of the commitment transaction.
                if !commitSig.Verify(sigHash, remoteKey) {
                        return fmt.Errorf("counterparty's commitment " +
                                "signature is invalid")
                }

                return nil

        // Otherwise for taproot channels, we'll compute the segwit v1 sighash,
        // which is slightly different.
        default:
                // First, check to see if we've generated the musig session
                // already. If we're the responder in the funding flow, we may
                // not have generated it already.
                if res.musigSessions == nil {
                        _, fundingOutput, err := input.GenTaprootFundingScript(
                                localKey, remoteKey, channelValue,
                                res.partialState.TapscriptRoot,
                        )
                        if err != nil {
                                return err
                        }

                        res.musigSessions = genMusigSession(
                                res.ourContribution, res.theirContribution,
                                l.Cfg.Signer, fundingOutput,
                                res.partialState.TapscriptRoot,
                        )
                }

                // For the musig2 based channels, we'll use the generated local
                // musig2 session to verify the signature.
                localSession := res.musigSessions.LocalSession

                // At this point, the commitment signature passed in should
                // actually be a wrapped musig2 signature, so we'll do a type
                // asset to the get the signature we actually need.
                partialSig, ok := commitSig.(*MusigPartialSig)
                if !ok {
                        return fmt.Errorf("expected *musig2.PartialSignature, "+
                                "got: %T", commitSig)
                }

                _, err := localSession.VerifyCommitSig(
                        commitTx, partialSig.ToWireSig(),
                )

                return err
        }
}

// handleFundingCounterPartySigs is the final step in the channel reservation
// workflow. During this step, we validate *all* the received signatures for
// inputs to the funding transaction. If any of these are invalid, we bail,
// and forcibly cancel this funding request. Additionally, we ensure that the
// signature we received from the counterparty for our version of the commitment
// transaction allows us to spend from the funding output with the addition of
// our signature.
func (l *LightningWallet) handleFundingCounterPartySigs(msg *addCounterPartySigsMsg) {
        l.limboMtx.RLock()
        res, ok := l.fundingLimbo[msg.pendingFundingID]
        l.limboMtx.RUnlock()
        if !ok {
                msg.err <- fmt.Errorf("attempted to update non-existent funding state")
                return
        }

        // Grab the mutex on the ChannelReservation to ensure thread-safety
        res.Lock()
        defer res.Unlock()

        // Now we can complete the funding transaction by adding their
        // signatures to their inputs.
        res.theirFundingInputScripts = msg.theirFundingInputScripts
        inputScripts := msg.theirFundingInputScripts

        // Only if we have the final funding transaction do we need to verify
        // the final set of inputs. Otherwise, it may be the case that the
        // channel was funded via an external wallet.
        fundingTx := res.fundingTx
        if res.partialState.ChanType.HasFundingTx() {
                err := l.verifyFundingInputs(fundingTx, inputScripts)
                if err != nil {
                        msg.err <- err
                        msg.completeChan <- nil
                        return
                }
        }

        // At this point, we can also record and verify their signature for our
        // commitment transaction.
        res.theirCommitmentSig = msg.theirCommitmentSig
        commitTx := res.partialState.LocalCommitment.CommitTx

        err := l.verifyCommitSig(res, msg.theirCommitmentSig, commitTx)
        if err != nil {
                msg.err <- fmt.Errorf("counterparty's commitment signature is "+
                        "invalid: %w", err)
                msg.completeChan <- nil
                return
        }

        theirCommitSigBytes := msg.theirCommitmentSig.Serialize()
        res.partialState.LocalCommitment.CommitSig = theirCommitSigBytes

        // Funding complete, this entry can be removed from limbo.
        l.limboMtx.Lock()
        delete(l.fundingLimbo, res.reservationID)
        delete(l.reservationIDs, res.pendingChanID)
        l.limboMtx.Unlock()

        l.intentMtx.Lock()
        delete(l.fundingIntents, res.pendingChanID)
        l.intentMtx.Unlock()

        // As we're about to broadcast the funding transaction, we'll take note
        // of the current height for record keeping purposes.
        _, bestHeight, err := l.Cfg.ChainIO.GetBestBlock()
        if err != nil {
                msg.err <- err
                msg.completeChan <- nil
                return
        }

        // As we've completed the funding process, we'll no convert the
        // contribution structs into their underlying channel config objects to
        // he stored within the database.
        res.partialState.LocalChanCfg = res.ourContribution.toChanConfig()
        res.partialState.RemoteChanCfg = res.theirContribution.toChanConfig()

        // We'll also record the finalized funding txn, which will allow us to
        // rebroadcast on startup in case we fail.
        res.partialState.FundingTxn = fundingTx

        // Set optional upfront shutdown scripts on the channel state so that they
        // are persisted. These values may be nil.
        res.partialState.LocalShutdownScript =
                res.ourContribution.UpfrontShutdown
        res.partialState.RemoteShutdownScript =
                res.theirContribution.UpfrontShutdown

        res.partialState.RevocationKeyLocator = res.nextRevocationKeyLoc

        // Add the complete funding transaction to the DB, in its open bucket
        // which will be used for the lifetime of this channel.
        nodeAddr := res.nodeAddr
        err = res.partialState.SyncPending(nodeAddr, uint32(bestHeight))
        if err != nil {
                msg.err <- err
                msg.completeChan <- nil
                return
        }

        msg.completeChan <- res.partialState
        msg.err <- nil
}

// handleSingleFunderSigs is called once the remote peer who initiated the
// single funder workflow has assembled the funding transaction, and generated
// a signature for our version of the commitment transaction. This method
// progresses the workflow by generating a signature for the remote peer's
// version of the commitment transaction.
func (l *LightningWallet) handleSingleFunderSigs(req *addSingleFunderSigsMsg) {
        l.limboMtx.RLock()
        pendingReservation, ok := l.fundingLimbo[req.pendingFundingID]
        l.limboMtx.RUnlock()
        if !ok {
                req.err <- fmt.Errorf("attempted to update non-existent funding state")
                req.completeChan <- nil
                return
        }

        // Grab the mutex on the ChannelReservation to ensure thread-safety
        pendingReservation.Lock()
        defer pendingReservation.Unlock()

        chanState := pendingReservation.partialState

        // If we have an aux funding desc, then we can use it to populate some
        // of the optional, but opaque TLV blobs we'll carry for the channel.
        chanState.CustomBlob = fn.MapOption(func(desc AuxFundingDesc) tlv.Blob {
                return desc.CustomFundingBlob
        })(req.auxFundingDesc)
        chanState.LocalCommitment.CustomBlob = fn.MapOption(
                func(desc AuxFundingDesc) tlv.Blob {
                        return desc.CustomLocalCommitBlob
                },
        )(req.auxFundingDesc)
        chanState.RemoteCommitment.CustomBlob = fn.MapOption(
                func(desc AuxFundingDesc) tlv.Blob {
                        return desc.CustomRemoteCommitBlob
                },
        )(req.auxFundingDesc)

        chanType := pendingReservation.partialState.ChanType
        chanState.FundingOutpoint = *req.fundingOutpoint
        fundingTxIn := wire.NewTxIn(req.fundingOutpoint, nil, nil)

        // Now that we have the funding outpoint, we can generate both versions
        // of the commitment transaction, and generate a signature for the
        // remote node's commitment transactions.
        localBalance := pendingReservation.partialState.LocalCommitment.LocalBalance.ToSatoshis()
        remoteBalance := pendingReservation.partialState.LocalCommitment.RemoteBalance.ToSatoshis()
        var leaseExpiry uint32
        if pendingReservation.partialState.ChanType.HasLeaseExpiration() {
                leaseExpiry = pendingReservation.partialState.ThawHeight
        }

        localAuxLeaves := fn.MapOption(
                func(desc AuxFundingDesc) CommitAuxLeaves {
                        return desc.LocalInitAuxLeaves
                },
        )(req.auxFundingDesc)
        remoteAuxLeaves := fn.MapOption(
                func(desc AuxFundingDesc) CommitAuxLeaves {
                        return desc.RemoteInitAuxLeaves
                },
        )(req.auxFundingDesc)

        ourCommitTx, theirCommitTx, err := CreateCommitmentTxns(
                localBalance, remoteBalance,
                pendingReservation.ourContribution.ChannelConfig,
                pendingReservation.theirContribution.ChannelConfig,
                pendingReservation.ourContribution.FirstCommitmentPoint,
                pendingReservation.theirContribution.FirstCommitmentPoint,
                *fundingTxIn, chanType,
                pendingReservation.partialState.IsInitiator, leaseExpiry,
                WithAuxLeaves(localAuxLeaves, remoteAuxLeaves),
        )
        if err != nil {
                req.err <- err
                req.completeChan <- nil
                return
        }

        // With both commitment transactions constructed, we can now use the
        // generator state obfuscator to encode the current state number within
        // both commitment transactions.
        stateObfuscator := DeriveStateHintObfuscator(
                pendingReservation.theirContribution.PaymentBasePoint.PubKey,
                pendingReservation.ourContribution.PaymentBasePoint.PubKey,
        )
        err = initStateHints(ourCommitTx, theirCommitTx, stateObfuscator)
        if err != nil {
                req.err <- err
                req.completeChan <- nil
                return
        }

        // Sort both transactions according to the agreed upon canonical
        // ordering. This ensures that both parties sign the same sighash
        // without further synchronization.
        txsort.InPlaceSort(ourCommitTx)
        txsort.InPlaceSort(theirCommitTx)
        chanState.LocalCommitment.CommitTx = ourCommitTx
        chanState.RemoteCommitment.CommitTx = theirCommitTx

        walletLog.Debugf("Local commit tx for ChannelPoint(%v): %v",
                req.fundingOutpoint, lnutils.SpewLogClosure(ourCommitTx))
        walletLog.Debugf("Remote commit tx for ChannelPoint(%v): %v",
                req.fundingOutpoint, lnutils.SpewLogClosure(theirCommitTx))

        // With both commitment transactions created, we'll now verify their
        // signature on our commitment.
        err = l.verifyCommitSig(
                pendingReservation, req.theirCommitmentSig, ourCommitTx,
        )
        if err != nil {
                req.err <- err
                req.completeChan <- nil
                return
        }

        theirCommitSigBytes := req.theirCommitmentSig.Serialize()
        chanState.LocalCommitment.CommitSig = theirCommitSigBytes

        channelValue := int64(pendingReservation.partialState.Capacity)
        theirKey := pendingReservation.theirContribution.MultiSigKey
        ourKey := pendingReservation.ourContribution.MultiSigKey

        var (
                fundingWitnessScript []byte
                fundingTxOut         *wire.TxOut
        )
        if chanType.IsTaproot() {
                //nolint:ll
                fundingWitnessScript, fundingTxOut, err = input.GenTaprootFundingScript(
                        ourKey.PubKey, theirKey.PubKey, channelValue,
                        pendingReservation.partialState.TapscriptRoot,
                )
        } else {
                //nolint:ll
                fundingWitnessScript, fundingTxOut, err = input.GenFundingPkScript(
                        ourKey.PubKey.SerializeCompressed(),
                        theirKey.PubKey.SerializeCompressed(), channelValue,
                )
        }
        if err != nil {
                req.err <- err
                req.completeChan <- nil
                return
        }

        // With their signature for our version of the commitment transactions
        // verified, we can now generate a signature for their version,
        // allowing the funding transaction to be safely broadcast.
        sigTheirCommit, err := l.signCommitTx(
                pendingReservation, theirCommitTx, fundingTxOut,
                fundingWitnessScript,
        )
        if err != nil {
                req.err <- err
                req.completeChan <- nil
                return
        }

        pendingReservation.ourCommitmentSig = sigTheirCommit

        _, bestHeight, err := l.Cfg.ChainIO.GetBestBlock()
        if err != nil {
                req.err <- err
                req.completeChan <- nil
                return
        }

        // Set optional upfront shutdown scripts on the channel state so that they
        // are persisted. These values may be nil.
        chanState.LocalShutdownScript =
                pendingReservation.ourContribution.UpfrontShutdown
        chanState.RemoteShutdownScript =
                pendingReservation.theirContribution.UpfrontShutdown

        // Add the complete funding transaction to the DB, in it's open bucket
        // which will be used for the lifetime of this channel.
        chanState.LocalChanCfg = pendingReservation.ourContribution.toChanConfig()
        chanState.RemoteChanCfg = pendingReservation.theirContribution.toChanConfig()

        chanState.RevocationKeyLocator = pendingReservation.nextRevocationKeyLoc

        err = chanState.SyncPending(pendingReservation.nodeAddr, uint32(bestHeight))
        if err != nil {
                req.err <- err
                req.completeChan <- nil
                return
        }

        req.completeChan <- chanState
        req.err <- nil

        l.limboMtx.Lock()
        delete(l.fundingLimbo, req.pendingFundingID)
        delete(l.reservationIDs, pendingReservation.pendingChanID)
        l.limboMtx.Unlock()

        l.intentMtx.Lock()
        delete(l.fundingIntents, pendingReservation.pendingChanID)
        l.intentMtx.Unlock()
}

// WithCoinSelectLock will execute the passed function closure in a
// synchronized manner preventing any coin selection operations from proceeding
// while the closure is executing. This can be seen as the ability to execute a
// function closure under an exclusive coin selection lock.
func (l *LightningWallet) WithCoinSelectLock(f func() error) error {
        l.coinSelectMtx.Lock()
        defer l.coinSelectMtx.Unlock()

        return f()
}

// DeriveStateHintObfuscator derives the bytes to be used for obfuscating the
// state hints from the root to be used for a new channel. The obfuscator is
// generated via the following computation:
//
//   - sha256(initiatorKey || responderKey)[26:]
//     -- where both keys are the multi-sig keys of the respective parties
//
// The first 6 bytes of the resulting hash are used as the state hint.
func DeriveStateHintObfuscator(key1, key2 *btcec.PublicKey) [StateHintSize]byte {
        h := sha256.New()
        h.Write(key1.SerializeCompressed())
        h.Write(key2.SerializeCompressed())

        sha := h.Sum(nil)

        var obfuscator [StateHintSize]byte
        copy(obfuscator[:], sha[26:])

        return obfuscator
}

// initStateHints properly sets the obfuscated state hints on both commitment
// transactions using the passed obfuscator.
func initStateHints(commit1, commit2 *wire.MsgTx,
        obfuscator [StateHintSize]byte) error {

        if err := SetStateNumHint(commit1, 0, obfuscator); err != nil {
                return err
        }
        if err := SetStateNumHint(commit2, 0, obfuscator); err != nil {
                return err
        }

        return nil
}

// ValidateChannel will attempt to fully validate a newly mined channel, given
// its funding transaction and existing channel state. If this method returns
// an error, then the mined channel is invalid, and shouldn't be used.
func (l *LightningWallet) ValidateChannel(channelState *channeldb.OpenChannel,
        fundingTx *wire.MsgTx) error {

        var chanOpts []ChannelOpt
        l.Cfg.AuxLeafStore.WhenSome(func(s AuxLeafStore) {
                chanOpts = append(chanOpts, WithLeafStore(s))
        })
        l.Cfg.AuxSigner.WhenSome(func(s AuxSigner) {
                chanOpts = append(chanOpts, WithAuxSigner(s))
        })

        // First, we'll obtain a fully signed commitment transaction so we can
        // pass into it on the chanvalidate package for verification.
        channel, err := NewLightningChannel(
                l.Cfg.Signer, channelState, nil, chanOpts...,
        )
        if err != nil {
                return err
        }

        localKey := channelState.LocalChanCfg.MultiSigKey.PubKey
        remoteKey := channelState.RemoteChanCfg.MultiSigKey.PubKey

        // We'll also need the multi-sig witness script itself so the
        // chanvalidate package can check it for correctness against the
        // funding transaction, and also commitment validity.
        var fundingScript []byte
        if channelState.ChanType.IsTaproot() {
                fundingScript, _, err = input.GenTaprootFundingScript(
                        localKey, remoteKey, int64(channel.Capacity),
                        channelState.TapscriptRoot,
                )
                if err != nil {
                        return err
                }
        } else {
                witnessScript, err := input.GenMultiSigScript(
                        localKey.SerializeCompressed(),
                        remoteKey.SerializeCompressed(),
                )
                if err != nil {
                        return err
                }
                fundingScript, err = input.WitnessScriptHash(witnessScript)
                if err != nil {
                        return err
                }
        }

        signedCommitTx, err := channel.getSignedCommitTx()
        if err != nil {
                return err
        }
        commitCtx := &chanvalidate.CommitmentContext{
                Value:               channel.Capacity,
                FullySignedCommitTx: signedCommitTx,
        }

        // Finally, we'll pass in all the necessary context needed to fully
        // validate that this channel is indeed what we expect, and can be
        // used.
        _, err = chanvalidate.Validate(&chanvalidate.Context{
                Locator: &chanvalidate.OutPointChanLocator{
                        ChanPoint: channelState.FundingOutpoint,
                },
                MultiSigPkScript: fundingScript,
                FundingTx:        fundingTx,
                CommitCtx:        commitCtx,
        })
        if err != nil {
                return err
        }

        return nil
}

// CancelRebroadcast cancels the rebroadcast of the given transaction.
func (l *LightningWallet) CancelRebroadcast(txid chainhash.Hash) {
        // For neutrino, we don't config the rebroadcaster for the wallet as it
        // manages the rebroadcasting logic in neutrino itself.
        if l.Cfg.Rebroadcaster != nil {
                l.Cfg.Rebroadcaster.MarkAsConfirmed(txid)
        }
}

// CoinSource is a wrapper around the wallet that implements the
// chanfunding.CoinSource interface.
type CoinSource struct {
        wallet    *LightningWallet
        allowUtxo func(Utxo) bool
}

// NewCoinSource creates a new instance of the CoinSource wrapper struct.
func NewCoinSource(w *LightningWallet, allowUtxo func(Utxo) bool) *CoinSource {
        return &CoinSource{
                wallet:    w,
                allowUtxo: allowUtxo,
        }
}

// ListCoins returns all UTXOs from the source that have between
// minConfs and maxConfs number of confirmations.
func (c *CoinSource) ListCoins(minConfs int32,
        maxConfs int32) ([]wallet.Coin, error) {

        utxos, err := c.wallet.ListUnspentWitnessFromDefaultAccount(
                minConfs, maxConfs,
        )
        if err != nil {
                return nil, err
        }

        var coins []wallet.Coin

        for _, utxo := range utxos {
                // If there is a filter function supplied all utxos not adhering
                // to these conditions will be discarded.
                if c.allowUtxo != nil && !c.allowUtxo(*utxo) {
                        walletLog.Infof("Cannot use unconfirmed "+
                                "utxo=%v because it is unstable and could be "+
                                "replaced", utxo.OutPoint)

                        continue
                }

                coins = append(coins, wallet.Coin{
                        TxOut: wire.TxOut{
                                Value:    int64(utxo.Value),
                                PkScript: utxo.PkScript,
                        },
                        OutPoint: utxo.OutPoint,
                })
        }

        return coins, nil
}

// CoinFromOutPoint attempts to locate details pertaining to a coin based on
// its outpoint. If the coin isn't under the control of the backing CoinSource,
// then an error should be returned.
func (c *CoinSource) CoinFromOutPoint(op wire.OutPoint) (*wallet.Coin, error) {
        inputInfo, err := c.wallet.FetchOutpointInfo(&op)
        if err != nil {
                return nil, err
        }

        return &wallet.Coin{
                TxOut: wire.TxOut{
                        Value:    int64(inputInfo.Value),
                        PkScript: inputInfo.PkScript,
                },
                OutPoint: inputInfo.OutPoint,
        }, nil
}

// shimKeyRing is a wrapper struct that's used to provide the proper multi-sig
// key for an initiated external funding flow.
type shimKeyRing struct {
        keychain.KeyRing

        *chanfunding.ShimIntent
}

// DeriveNextKey intercepts the normal DeriveNextKey call to a keychain.KeyRing
// instance, and supplies the multi-sig key specified by the ShimIntent. This
// allows us to transparently insert new keys into the existing funding flow,
// as these keys may not come from the wallet itself.
func (s *shimKeyRing) DeriveNextKey(keyFam keychain.KeyFamily) (keychain.KeyDescriptor, error) {
        if keyFam != keychain.KeyFamilyMultiSig {
                return s.KeyRing.DeriveNextKey(keyFam)
        }

        fundingKeys, err := s.ShimIntent.MultiSigKeys()
        if err != nil {
                return keychain.KeyDescriptor{}, err
        }

        return *fundingKeys.LocalKey, nil
}

// ValidateUpfrontShutdown checks whether the provided upfront_shutdown_script
// is of a valid type that we accept.
func ValidateUpfrontShutdown(shutdown lnwire.DeliveryAddress,
        params *chaincfg.Params) bool {

        // We don't need to worry about a large UpfrontShutdownScript since it
        // was already checked in lnwire when decoding from the wire.
        scriptClass, _, _, _ := txscript.ExtractPkScriptAddrs(shutdown, params)

        switch {
        case scriptClass == txscript.WitnessV0PubKeyHashTy,
                scriptClass == txscript.WitnessV0ScriptHashTy,
                scriptClass == txscript.WitnessV1TaprootTy:

                // The above three types are permitted according to BOLT#02 and
                // BOLT#05.  Everything else is disallowed.
                return true

        // In this case, we don't know about the actual script template, but it
        // might be a witness program with versions 2-16. So we'll check that
        // now
        case txscript.IsWitnessProgram(shutdown):
                version, _, err := txscript.ExtractWitnessProgramInfo(shutdown)
                if err != nil {
                        walletLog.Warnf("unable to extract witness program "+
                                "version (script=%x): %v", shutdown, err)
                        return false
                }

                return version >= 1 && version <= 16

        default:
                return false
        }
}

// WalletPrevOutputFetcher is a txscript.PrevOutputFetcher that can fetch
// outputs from a given wallet controller.
type WalletPrevOutputFetcher struct {
        wc WalletController
}

// A compile time assertion that WalletPrevOutputFetcher implements the
// txscript.PrevOutputFetcher interface.
var _ txscript.PrevOutputFetcher = (*WalletPrevOutputFetcher)(nil)

// NewWalletPrevOutputFetcher creates a new WalletPrevOutputFetcher that fetches
// previous outputs from the given wallet controller.
func NewWalletPrevOutputFetcher(wc WalletController) *WalletPrevOutputFetcher {
        return &WalletPrevOutputFetcher{
                wc: wc,
        }
}

// FetchPrevOutput attempts to fetch the previous output referenced by the
// passed outpoint. A nil value will be returned if the passed outpoint doesn't
// exist.
func (w *WalletPrevOutputFetcher) FetchPrevOutput(op wire.OutPoint) *wire.TxOut {
        utxo, err := w.wc.FetchOutpointInfo(&op)
        if err != nil {
                return nil
        }

        return &wire.TxOut{
                Value:    int64(utxo.Value),
                PkScript: utxo.PkScript,
        }
}

lightningnetwork / lnd / 17830307614

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