12343072627

Committed 15 Dec 2024 11:09PM UTC coverage: 57.504% (-1.1%) from 58.636%

Build # 12343072627

Build Type

Pull #9315

github

Committed by

yyforyongyu

Commit Message

contractcourt: offer outgoing htlc one block earlier before its expiry

We need to offer the outgoing htlc one block earlier to make sure when
the expiry height hits, the sweeper will not miss sweeping it in the
same block. This also means the outgoing contest resolver now only does
one thing - watch for preimage spend till height expiry-1, which can
easily be moved into the timeout resolver instead in the future.

Pull Request Pull Request #9315: Implement `blockbeat`

Run Details

1445 of 2007 new or added lines in 26 files covered. (72.0%)

19246 existing lines in 249 files now uncovered.

102342 of 177975 relevant lines covered (57.5%)

24772.24 hits per line

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

75.08

/contractcourt/channel_arbitrator.go

package contractcourt

import (
        "bytes"
        "context"
        "errors"
        "fmt"
        "math"
        "sync"
        "sync/atomic"
        "time"

        "github.com/btcsuite/btcd/btcutil"
        "github.com/btcsuite/btcd/chaincfg/chainhash"
        "github.com/btcsuite/btcd/txscript"
        "github.com/btcsuite/btcd/wire"
        "github.com/lightningnetwork/lnd/chainio"
        "github.com/lightningnetwork/lnd/channeldb"
        "github.com/lightningnetwork/lnd/fn/v2"
        "github.com/lightningnetwork/lnd/graph/db/models"
        "github.com/lightningnetwork/lnd/htlcswitch/hop"
        "github.com/lightningnetwork/lnd/input"
        "github.com/lightningnetwork/lnd/invoices"
        "github.com/lightningnetwork/lnd/kvdb"
        "github.com/lightningnetwork/lnd/labels"
        "github.com/lightningnetwork/lnd/lntypes"
        "github.com/lightningnetwork/lnd/lnutils"
        "github.com/lightningnetwork/lnd/lnwallet"
        "github.com/lightningnetwork/lnd/lnwire"
        "github.com/lightningnetwork/lnd/sweep"
)

var (
        // errAlreadyForceClosed is an error returned when we attempt to force
        // close a channel that's already in the process of doing so.
        errAlreadyForceClosed = errors.New("channel is already in the " +
                "process of being force closed")
)

const (
        // arbitratorBlockBufferSize is the size of the buffer we give to each
        // channel arbitrator.
        arbitratorBlockBufferSize = 20

        // AnchorOutputValue is the output value for the anchor output of an
        // anchor channel.
        // See BOLT 03 for more details:
        // https://github.com/lightning/bolts/blob/master/03-transactions.md
        AnchorOutputValue = btcutil.Amount(330)
)

// WitnessSubscription represents an intent to be notified once new witnesses
// are discovered by various active contract resolvers. A contract resolver may
// use this to be notified of when it can satisfy an incoming contract after we
// discover the witness for an outgoing contract.
type WitnessSubscription struct {
        // WitnessUpdates is a channel that newly discovered witnesses will be
        // sent over.
        //
        // TODO(roasbeef): couple with WitnessType?
        WitnessUpdates <-chan lntypes.Preimage

        // CancelSubscription is a function closure that should be used by a
        // client to cancel the subscription once they are no longer interested
        // in receiving new updates.
        CancelSubscription func()
}

// WitnessBeacon is a global beacon of witnesses. Contract resolvers will use
// this interface to lookup witnesses (preimages typically) of contracts
// they're trying to resolve, add new preimages they resolve, and finally
// receive new updates each new time a preimage is discovered.
//
// TODO(roasbeef): need to delete the pre-images once we've used them
// and have been sufficiently confirmed?
type WitnessBeacon interface {
        // SubscribeUpdates returns a channel that will be sent upon *each* time
        // a new preimage is discovered.
        SubscribeUpdates(chanID lnwire.ShortChannelID, htlc *channeldb.HTLC,
                payload *hop.Payload,
                nextHopOnionBlob []byte) (*WitnessSubscription, error)

        // LookupPreImage attempts to lookup a preimage in the global cache.
        // True is returned for the second argument if the preimage is found.
        LookupPreimage(payhash lntypes.Hash) (lntypes.Preimage, bool)

        // AddPreimages adds a batch of newly discovered preimages to the global
        // cache, and also signals any subscribers of the newly discovered
        // witness.
        AddPreimages(preimages ...lntypes.Preimage) error
}

// ArbChannel is an abstraction that allows the channel arbitrator to interact
// with an open channel.
type ArbChannel interface {
        // ForceCloseChan should force close the contract that this attendant
        // is watching over. We'll use this when we decide that we need to go
        // to chain. It should in addition tell the switch to remove the
        // corresponding link, such that we won't accept any new updates. The
        // returned summary contains all items needed to eventually resolve all
        // outputs on chain.
        ForceCloseChan() (*wire.MsgTx, error)

        // NewAnchorResolutions returns the anchor resolutions for currently
        // valid commitment transactions.
        NewAnchorResolutions() (*lnwallet.AnchorResolutions, error)
}

// ChannelArbitratorConfig contains all the functionality that the
// ChannelArbitrator needs in order to properly arbitrate any contract dispute
// on chain.
type ChannelArbitratorConfig struct {
        // ChanPoint is the channel point that uniquely identifies this
        // channel.
        ChanPoint wire.OutPoint

        // Channel is the full channel data structure. For legacy channels, this
        // field may not always be set after a restart.
        Channel ArbChannel

        // ShortChanID describes the exact location of the channel within the
        // chain. We'll use this to address any messages that we need to send
        // to the switch during contract resolution.
        ShortChanID lnwire.ShortChannelID

        // ChainEvents is an active subscription to the chain watcher for this
        // channel to be notified of any on-chain activity related to this
        // channel.
        ChainEvents *ChainEventSubscription

        // MarkCommitmentBroadcasted should mark the channel as the commitment
        // being broadcast, and we are waiting for the commitment to confirm.
        MarkCommitmentBroadcasted func(*wire.MsgTx, lntypes.ChannelParty) error

        // MarkChannelClosed marks the channel closed in the database, with the
        // passed close summary. After this method successfully returns we can
        // no longer expect to receive chain events for this channel, and must
        // be able to recover from a failure without getting the close event
        // again. It takes an optional channel status which will update the
        // channel status in the record that we keep of historical channels.
        MarkChannelClosed func(*channeldb.ChannelCloseSummary,
                ...channeldb.ChannelStatus) error

        // IsPendingClose is a boolean indicating whether the channel is marked
        // as pending close in the database.
        IsPendingClose bool

        // ClosingHeight is the height at which the channel was closed. Note
        // that this value is only valid if IsPendingClose is true.
        ClosingHeight uint32

        // CloseType is the type of the close event in case IsPendingClose is
        // true. Otherwise this value is unset.
        CloseType channeldb.ClosureType

        // MarkChannelResolved is a function closure that serves to mark a
        // channel as "fully resolved". A channel itself can be considered
        // fully resolved once all active contracts have individually been
        // fully resolved.
        //
        // TODO(roasbeef): need RPC's to combine for pendingchannels RPC
        MarkChannelResolved func() error

        // PutResolverReport records a resolver report for the channel. If the
        // transaction provided is nil, the function should write the report
        // in a new transaction.
        PutResolverReport func(tx kvdb.RwTx,
                report *channeldb.ResolverReport) error

        // FetchHistoricalChannel retrieves the historical state of a channel.
        // This is mostly used to supplement the ContractResolvers with
        // additional information required for proper contract resolution.
        FetchHistoricalChannel func() (*channeldb.OpenChannel, error)

        // FindOutgoingHTLCDeadline returns the deadline in absolute block
        // height for the specified outgoing HTLC. For an outgoing HTLC, its
        // deadline is defined by the timeout height of its corresponding
        // incoming HTLC - this is the expiry height the that remote peer can
        // spend his/her outgoing HTLC via the timeout path.
        FindOutgoingHTLCDeadline func(htlc channeldb.HTLC) fn.Option[int32]

        ChainArbitratorConfig
}

// ReportOutputType describes the type of output that is being reported
// on.
type ReportOutputType uint8

const (
        // ReportOutputIncomingHtlc is an incoming hash time locked contract on
        // the commitment tx.
        ReportOutputIncomingHtlc ReportOutputType = iota

        // ReportOutputOutgoingHtlc is an outgoing hash time locked contract on
        // the commitment tx.
        ReportOutputOutgoingHtlc

        // ReportOutputUnencumbered is an uncontested output on the commitment
        // transaction paying to us directly.
        ReportOutputUnencumbered

        // ReportOutputAnchor is an anchor output on the commitment tx.
        ReportOutputAnchor
)

// ContractReport provides a summary of a commitment tx output.
type ContractReport struct {
        // Outpoint is the final output that will be swept back to the wallet.
        Outpoint wire.OutPoint

        // Type indicates the type of the reported output.
        Type ReportOutputType

        // Amount is the final value that will be swept in back to the wallet.
        Amount btcutil.Amount

        // MaturityHeight is the absolute block height that this output will
        // mature at.
        MaturityHeight uint32

        // Stage indicates whether the htlc is in the CLTV-timeout stage (1) or
        // the CSV-delay stage (2). A stage 1 htlc's maturity height will be set
        // to its expiry height, while a stage 2 htlc's maturity height will be
        // set to its confirmation height plus the maturity requirement.
        Stage uint32

        // LimboBalance is the total number of frozen coins within this
        // contract.
        LimboBalance btcutil.Amount

        // RecoveredBalance is the total value that has been successfully swept
        // back to the user's wallet.
        RecoveredBalance btcutil.Amount
}

// resolverReport creates a resolve report using some of the information in the
// contract report.
func (c *ContractReport) resolverReport(spendTx *chainhash.Hash,
        resolverType channeldb.ResolverType,
        outcome channeldb.ResolverOutcome) *channeldb.ResolverReport {

        return &channeldb.ResolverReport{
                OutPoint:        c.Outpoint,
                Amount:          c.Amount,
                ResolverType:    resolverType,
                ResolverOutcome: outcome,
                SpendTxID:       spendTx,
        }
}

// htlcSet represents the set of active HTLCs on a given commitment
// transaction.
type htlcSet struct {
        // incomingHTLCs is a map of all incoming HTLCs on the target
        // commitment transaction. We may potentially go onchain to claim the
        // funds sent to us within this set.
        incomingHTLCs map[uint64]channeldb.HTLC

        // outgoingHTLCs is a map of all outgoing HTLCs on the target
        // commitment transaction. We may potentially go onchain to reclaim the
        // funds that are currently in limbo.
        outgoingHTLCs map[uint64]channeldb.HTLC
}

// newHtlcSet constructs a new HTLC set from a slice of HTLC's.
func newHtlcSet(htlcs []channeldb.HTLC) htlcSet {
        outHTLCs := make(map[uint64]channeldb.HTLC)
        inHTLCs := make(map[uint64]channeldb.HTLC)
        for _, htlc := range htlcs {
                if htlc.Incoming {
                        inHTLCs[htlc.HtlcIndex] = htlc
                        continue
                }

                outHTLCs[htlc.HtlcIndex] = htlc
        }

        return htlcSet{
                incomingHTLCs: inHTLCs,
                outgoingHTLCs: outHTLCs,
        }
}

// HtlcSetKey is a two-tuple that uniquely identifies a set of HTLCs on a
// commitment transaction.
type HtlcSetKey struct {
        // IsRemote denotes if the HTLCs are on the remote commitment
        // transaction.
        IsRemote bool

        // IsPending denotes if the commitment transaction that HTLCS are on
        // are pending (the higher of two unrevoked commitments).
        IsPending bool
}

var (
        // LocalHtlcSet is the HtlcSetKey used for local commitments.
        LocalHtlcSet = HtlcSetKey{IsRemote: false, IsPending: false}

        // RemoteHtlcSet is the HtlcSetKey used for remote commitments.
        RemoteHtlcSet = HtlcSetKey{IsRemote: true, IsPending: false}

        // RemotePendingHtlcSet is the HtlcSetKey used for dangling remote
        // commitment transactions.
        RemotePendingHtlcSet = HtlcSetKey{IsRemote: true, IsPending: true}
)

// String returns a human readable string describing the target HtlcSetKey.
func (h HtlcSetKey) String() string {
        switch h {
        case LocalHtlcSet:
                return "LocalHtlcSet"
        case RemoteHtlcSet:
                return "RemoteHtlcSet"
        case RemotePendingHtlcSet:
                return "RemotePendingHtlcSet"
        default:
                return "unknown HtlcSetKey"
        }
}

// ChannelArbitrator is the on-chain arbitrator for a particular channel. The
// struct will keep in sync with the current set of HTLCs on the commitment
// transaction. The job of the attendant is to go on-chain to either settle or
// cancel an HTLC as necessary iff: an HTLC times out, or we known the
// pre-image to an HTLC, but it wasn't settled by the link off-chain. The
// ChannelArbitrator will factor in an expected confirmation delta when
// broadcasting to ensure that we avoid any possibility of race conditions, and
// sweep the output(s) without contest.
type ChannelArbitrator struct {
        started int32 // To be used atomically.
        stopped int32 // To be used atomically.

        // Embed the blockbeat consumer struct to get access to the method
        // `NotifyBlockProcessed` and the `BlockbeatChan`.
        chainio.BeatConsumer

        // startTimestamp is the time when this ChannelArbitrator was started.
        startTimestamp time.Time

        // log is a persistent log that the attendant will use to checkpoint
        // its next action, and the state of any unresolved contracts.
        log ArbitratorLog

        // activeHTLCs is the set of active incoming/outgoing HTLC's on all
        // currently valid commitment transactions.
        activeHTLCs map[HtlcSetKey]htlcSet

        // unmergedSet is used to update the activeHTLCs map in two callsites:
        // checkLocalChainActions and sweepAnchors. It contains the latest
        // updates from the link. It is not deleted from, its entries may be
        // replaced on subsequent calls to notifyContractUpdate.
        unmergedSet map[HtlcSetKey]htlcSet
        unmergedMtx sync.RWMutex

        // cfg contains all the functionality that the ChannelArbitrator requires
        // to do its duty.
        cfg ChannelArbitratorConfig

        // signalUpdates is a channel that any new live signals for the channel
        // we're watching over will be sent.
        signalUpdates chan *signalUpdateMsg

        // activeResolvers is a slice of any active resolvers. This is used to
        // be able to signal them for shutdown in the case that we shutdown.
        activeResolvers []ContractResolver

        // activeResolversLock prevents simultaneous read and write to the
        // resolvers slice.
        activeResolversLock sync.RWMutex

        // resolutionSignal is a channel that will be sent upon by contract
        // resolvers once their contract has been fully resolved. With each
        // send, we'll check to see if the contract is fully resolved.
        resolutionSignal chan struct{}

        // forceCloseReqs is a channel that requests to forcibly close the
        // contract will be sent over.
        forceCloseReqs chan *forceCloseReq

        // state is the current state of the arbitrator. This state is examined
        // upon start up to decide which actions to take.
        state ArbitratorState

        wg   sync.WaitGroup
        quit chan struct{}
}

// NewChannelArbitrator returns a new instance of a ChannelArbitrator backed by
// the passed config struct.
func NewChannelArbitrator(cfg ChannelArbitratorConfig,
        htlcSets map[HtlcSetKey]htlcSet, log ArbitratorLog) *ChannelArbitrator {

        // Create a new map for unmerged HTLC's as we will overwrite the values
        // and want to avoid modifying activeHTLCs directly. This soft copying
        // is done to ensure that activeHTLCs isn't reset as an empty map later
        // on.
        unmerged := make(map[HtlcSetKey]htlcSet)
        unmerged[LocalHtlcSet] = htlcSets[LocalHtlcSet]
        unmerged[RemoteHtlcSet] = htlcSets[RemoteHtlcSet]

        // If the pending set exists, write that as well.
        if _, ok := htlcSets[RemotePendingHtlcSet]; ok {
                unmerged[RemotePendingHtlcSet] = htlcSets[RemotePendingHtlcSet]
        }

        c := &ChannelArbitrator{
                log:              log,
                signalUpdates:    make(chan *signalUpdateMsg),
                resolutionSignal: make(chan struct{}),
                forceCloseReqs:   make(chan *forceCloseReq),
                activeHTLCs:      htlcSets,
                unmergedSet:      unmerged,
                cfg:              cfg,
                quit:             make(chan struct{}),
        }

        // Mount the block consumer.
        c.BeatConsumer = chainio.NewBeatConsumer(c.quit, c.Name())

        return c
}

// Compile-time check for the chainio.Consumer interface.
var _ chainio.Consumer = (*ChannelArbitrator)(nil)

// chanArbStartState contains the information from disk that we need to start
// up a channel arbitrator.
type chanArbStartState struct {
        currentState ArbitratorState
        commitSet    *CommitSet
}

// getStartState retrieves the information from disk that our channel arbitrator
// requires to start.
func (c *ChannelArbitrator) getStartState(tx kvdb.RTx) (*chanArbStartState,
        error) {

        // First, we'll read our last state from disk, so our internal state
        // machine can act accordingly.
        state, err := c.log.CurrentState(tx)
        if err != nil {
                return nil, err
        }

        // Next we'll fetch our confirmed commitment set. This will only exist
        // if the channel has been closed out on chain for modern nodes. For
        // older nodes, this won't be found at all, and will rely on the
        // existing written chain actions. Additionally, if this channel hasn't
        // logged any actions in the log, then this field won't be present.
        commitSet, err := c.log.FetchConfirmedCommitSet(tx)
        if err != nil && err != errNoCommitSet && err != errScopeBucketNoExist {
                return nil, err
        }

        return &chanArbStartState{
                currentState: state,
                commitSet:    commitSet,
        }, nil
}

// Start starts all the goroutines that the ChannelArbitrator needs to operate.
// If takes a start state, which will be looked up on disk if it is not
// provided.
func (c *ChannelArbitrator) Start(state *chanArbStartState,
        beat chainio.Blockbeat) error {

        if !atomic.CompareAndSwapInt32(&c.started, 0, 1) {
                return nil
        }
        c.startTimestamp = c.cfg.Clock.Now()

        // If the state passed in is nil, we look it up now.
        if state == nil {
                var err error
                state, err = c.getStartState(nil)
                if err != nil {
                        return err
                }
        }

        log.Debugf("Starting ChannelArbitrator(%v), htlc_set=%v, state=%v",
                c.cfg.ChanPoint, lnutils.SpewLogClosure(c.activeHTLCs),
                state.currentState)

        // Set our state from our starting state.
        c.state = state.currentState

        // Get the starting height.
        bestHeight := beat.Height()

        c.wg.Add(1)
        go c.channelAttendant(bestHeight, state.commitSet)

        return nil
}

// progressStateMachineAfterRestart attempts to progress the state machine
// after a restart. This makes sure that if the state transition failed, we
// will try to progress the state machine again. Moreover it will relaunch
// resolvers if the channel is still in the pending close state and has not
// been fully resolved yet.
func (c *ChannelArbitrator) progressStateMachineAfterRestart(bestHeight int32,
        commitSet *CommitSet) error {

        // If the channel has been marked pending close in the database, and we
        // haven't transitioned the state machine to StateContractClosed (or a
        // succeeding state), then a state transition most likely failed. We'll
        // try to recover from this by manually advancing the state by setting
        // the corresponding close trigger.
        trigger := chainTrigger
        triggerHeight := uint32(bestHeight)
        if c.cfg.IsPendingClose {
                switch c.state {
                case StateDefault:
                        fallthrough
                case StateBroadcastCommit:
                        fallthrough
                case StateCommitmentBroadcasted:
                        switch c.cfg.CloseType {

                        case channeldb.CooperativeClose:
                                trigger = coopCloseTrigger

                        case channeldb.BreachClose:
                                trigger = breachCloseTrigger

                        case channeldb.LocalForceClose:
                                trigger = localCloseTrigger

                        case channeldb.RemoteForceClose:
                                trigger = remoteCloseTrigger
                        }

                        log.Warnf("ChannelArbitrator(%v): detected stalled "+
                                "state=%v for closed channel",
                                c.cfg.ChanPoint, c.state)
                }

                triggerHeight = c.cfg.ClosingHeight
        }

        log.Infof("ChannelArbitrator(%v): starting state=%v, trigger=%v, "+
                "triggerHeight=%v", c.cfg.ChanPoint, c.state, trigger,
                triggerHeight)

        // We'll now attempt to advance our state forward based on the current
        // on-chain state, and our set of active contracts.
        startingState := c.state
        nextState, _, err := c.advanceState(
                triggerHeight, trigger, commitSet,
        )
        if err != nil {
                switch err {

                // If we detect that we tried to fetch resolutions, but failed,
                // this channel was marked closed in the database before
                // resolutions successfully written. In this case there is not
                // much we can do, so we don't return the error.
                case errScopeBucketNoExist:
                        fallthrough
                case errNoResolutions:
                        log.Warnf("ChannelArbitrator(%v): detected closed"+
                                "channel with no contract resolutions written.",
                                c.cfg.ChanPoint)

                default:
                        return err
                }
        }

        // If we start and ended at the awaiting full resolution state, then
        // we'll relaunch our set of unresolved contracts.
        if startingState == StateWaitingFullResolution &&
                nextState == StateWaitingFullResolution {

                // In order to relaunch the resolvers, we'll need to fetch the
                // set of HTLCs that were present in the commitment transaction
                // at the time it was confirmed. commitSet.ConfCommitKey can't
                // be nil at this point since we're in
                // StateWaitingFullResolution. We can only be in
                // StateWaitingFullResolution after we've transitioned from
                // StateContractClosed which can only be triggered by the local
                // or remote close trigger. This trigger is only fired when we
                // receive a chain event from the chain watcher that the
                // commitment has been confirmed on chain, and before we
                // advance our state step, we call InsertConfirmedCommitSet.
                err := c.relaunchResolvers(commitSet, triggerHeight)
                if err != nil {
                        return err
                }
        }

        return nil
}

// maybeAugmentTaprootResolvers will update the contract resolution information
// for taproot channels. This ensures that all the resolvers have the latest
// resolution, which may also include data such as the control block and tap
// tweaks.
func maybeAugmentTaprootResolvers(chanType channeldb.ChannelType,
        resolver ContractResolver,
        contractResolutions *ContractResolutions) {

        if !chanType.IsTaproot() {
                return
        }

        // The on disk resolutions contains all the ctrl block
        // information, so we'll set that now for the relevant
        // resolvers.
        switch r := resolver.(type) {
        case *commitSweepResolver:
                if contractResolutions.CommitResolution != nil {
                        //nolint:ll
                        r.commitResolution = *contractResolutions.CommitResolution
                }
        case *htlcOutgoingContestResolver:
                //nolint:ll
                htlcResolutions := contractResolutions.HtlcResolutions.OutgoingHTLCs
                for _, htlcRes := range htlcResolutions {
                        htlcRes := htlcRes

                        if r.htlcResolution.ClaimOutpoint ==
                                htlcRes.ClaimOutpoint {

                                r.htlcResolution = htlcRes
                        }
                }

        case *htlcTimeoutResolver:
                //nolint:ll
                htlcResolutions := contractResolutions.HtlcResolutions.OutgoingHTLCs
                for _, htlcRes := range htlcResolutions {
                        htlcRes := htlcRes

                        if r.htlcResolution.ClaimOutpoint ==
                                htlcRes.ClaimOutpoint {

                                r.htlcResolution = htlcRes
                        }
                }

        case *htlcIncomingContestResolver:
                //nolint:ll
                htlcResolutions := contractResolutions.HtlcResolutions.IncomingHTLCs
                for _, htlcRes := range htlcResolutions {
                        htlcRes := htlcRes

                        if r.htlcResolution.ClaimOutpoint ==
                                htlcRes.ClaimOutpoint {

                                r.htlcResolution = htlcRes
                        }
                }
        case *htlcSuccessResolver:
                //nolint:ll
                htlcResolutions := contractResolutions.HtlcResolutions.IncomingHTLCs
                for _, htlcRes := range htlcResolutions {
                        htlcRes := htlcRes

                        if r.htlcResolution.ClaimOutpoint ==
                                htlcRes.ClaimOutpoint {

                                r.htlcResolution = htlcRes
                        }
                }
        }
}

// relauchResolvers relaunches the set of resolvers for unresolved contracts in
// order to provide them with information that's not immediately available upon
// starting the ChannelArbitrator. This information should ideally be stored in
// the database, so this only serves as a intermediate work-around to prevent a
// migration.
func (c *ChannelArbitrator) relaunchResolvers(commitSet *CommitSet,
        heightHint uint32) error {

        // We'll now query our log to see if there are any active unresolved
        // contracts. If this is the case, then we'll relaunch all contract
        // resolvers.
        unresolvedContracts, err := c.log.FetchUnresolvedContracts()
        if err != nil {
                return err
        }

        // Retrieve the commitment tx hash from the log.
        contractResolutions, err := c.log.FetchContractResolutions()
        if err != nil {
                log.Errorf("unable to fetch contract resolutions: %v",
                        err)
                return err
        }
        commitHash := contractResolutions.CommitHash

        // In prior versions of lnd, the information needed to supplement the
        // resolvers (in most cases, the full amount of the HTLC) was found in
        // the chain action map, which is now deprecated.  As a result, if the
        // commitSet is nil (an older node with unresolved HTLCs at time of
        // upgrade), then we'll use the chain action information in place. The
        // chain actions may exclude some information, but we cannot recover it
        // for these older nodes at the moment.
        var confirmedHTLCs []channeldb.HTLC
        if commitSet != nil && commitSet.ConfCommitKey.IsSome() {
                confCommitKey, err := commitSet.ConfCommitKey.UnwrapOrErr(
                        fmt.Errorf("no commitKey available"),
                )
                if err != nil {
                        return err
                }
                confirmedHTLCs = commitSet.HtlcSets[confCommitKey]
        } else {
                chainActions, err := c.log.FetchChainActions()
                if err != nil {
                        log.Errorf("unable to fetch chain actions: %v", err)
                        return err
                }
                for _, htlcs := range chainActions {
                        confirmedHTLCs = append(confirmedHTLCs, htlcs...)
                }
        }

        // Reconstruct the htlc outpoints and data from the chain action log.
        // The purpose of the constructed htlc map is to supplement to
        // resolvers restored from database with extra data. Ideally this data
        // is stored as part of the resolver in the log. This is a workaround
        // to prevent a db migration. We use all available htlc sets here in
        // order to ensure we have complete coverage.
        htlcMap := make(map[wire.OutPoint]*channeldb.HTLC)
        for _, htlc := range confirmedHTLCs {
                htlc := htlc
                outpoint := wire.OutPoint{
                        Hash:  commitHash,
                        Index: uint32(htlc.OutputIndex),
                }
                htlcMap[outpoint] = &htlc
        }

        // We'll also fetch the historical state of this channel, as it should
        // have been marked as closed by now, and supplement it to each resolver
        // such that we can properly resolve our pending contracts.
        var chanState *channeldb.OpenChannel
        chanState, err = c.cfg.FetchHistoricalChannel()
        switch {
        // If we don't find this channel, then it may be the case that it
        // was closed before we started to retain the final state
        // information for open channels.
        case err == channeldb.ErrNoHistoricalBucket:
                fallthrough
        case err == channeldb.ErrChannelNotFound:
                log.Warnf("ChannelArbitrator(%v): unable to fetch historical "+
                        "state", c.cfg.ChanPoint)

        case err != nil:
                return err
        }

        log.Infof("ChannelArbitrator(%v): relaunching %v contract "+
                "resolvers", c.cfg.ChanPoint, len(unresolvedContracts))

        for i := range unresolvedContracts {
                resolver := unresolvedContracts[i]

                if chanState != nil {
                        resolver.SupplementState(chanState)

                        // For taproot channels, we'll need to also make sure
                        // the control block information was set properly.
                        maybeAugmentTaprootResolvers(
                                chanState.ChanType, resolver,
                                contractResolutions,
                        )
                }

                unresolvedContracts[i] = resolver

                htlcResolver, ok := resolver.(htlcContractResolver)
                if !ok {
                        continue
                }

                htlcPoint := htlcResolver.HtlcPoint()
                htlc, ok := htlcMap[htlcPoint]
                if !ok {
                        return fmt.Errorf(
                                "htlc resolver %T unavailable", resolver,
                        )
                }

                htlcResolver.Supplement(*htlc)

                // If this is an outgoing HTLC, we will also need to supplement
                // the resolver with the expiry block height of its
                // corresponding incoming HTLC.
                if !htlc.Incoming {
                        deadline := c.cfg.FindOutgoingHTLCDeadline(*htlc)
                        htlcResolver.SupplementDeadline(deadline)
                }
        }

        // The anchor resolver is stateless and can always be re-instantiated.
        if contractResolutions.AnchorResolution != nil {
                anchorResolver := newAnchorResolver(
                        contractResolutions.AnchorResolution.AnchorSignDescriptor,
                        contractResolutions.AnchorResolution.CommitAnchor,
                        heightHint, c.cfg.ChanPoint,
                        ResolverConfig{
                                ChannelArbitratorConfig: c.cfg,
                        },
                )

                anchorResolver.SupplementState(chanState)

                unresolvedContracts = append(unresolvedContracts, anchorResolver)

                // TODO(roasbeef): this isn't re-launched?
        }

        c.resolveContracts(unresolvedContracts)

        return nil
}

// Report returns htlc reports for the active resolvers.
func (c *ChannelArbitrator) Report() []*ContractReport {
        c.activeResolversLock.RLock()
        defer c.activeResolversLock.RUnlock()

        var reports []*ContractReport
        for _, resolver := range c.activeResolvers {
                r, ok := resolver.(reportingContractResolver)
                if !ok {
                        continue
                }

                report := r.report()
                if report == nil {
                        continue
                }

                reports = append(reports, report)
        }

        return reports
}

// Stop signals the ChannelArbitrator for a graceful shutdown.
func (c *ChannelArbitrator) Stop() error {
        if !atomic.CompareAndSwapInt32(&c.stopped, 0, 1) {
                return nil
        }

        log.Debugf("Stopping ChannelArbitrator(%v)", c.cfg.ChanPoint)

        if c.cfg.ChainEvents.Cancel != nil {
                go c.cfg.ChainEvents.Cancel()
        }

        c.activeResolversLock.RLock()
        for _, activeResolver := range c.activeResolvers {
                activeResolver.Stop()
        }
        c.activeResolversLock.RUnlock()

        close(c.quit)
        c.wg.Wait()

        return nil
}

// transitionTrigger is an enum that denotes exactly *why* a state transition
// was initiated. This is useful as depending on the initial trigger, we may
// skip certain states as those actions are expected to have already taken
// place as a result of the external trigger.
type transitionTrigger uint8

const (
        // chainTrigger is a transition trigger that has been attempted due to
        // changing on-chain conditions such as a block which times out HTLC's
        // being attached.
        chainTrigger transitionTrigger = iota

        // userTrigger is a transition trigger driven by user action. Examples
        // of such a trigger include a user requesting a force closure of the
        // channel.
        userTrigger

        // remoteCloseTrigger is a transition trigger driven by the remote
        // peer's commitment being confirmed.
        remoteCloseTrigger

        // localCloseTrigger is a transition trigger driven by our commitment
        // being confirmed.
        localCloseTrigger

        // coopCloseTrigger is a transition trigger driven by a cooperative
        // close transaction being confirmed.
        coopCloseTrigger

        // breachCloseTrigger is a transition trigger driven by a remote breach
        // being confirmed. In this case the channel arbitrator will wait for
        // the BreachArbitrator to finish and then clean up gracefully.
        breachCloseTrigger
)

// String returns a human readable string describing the passed
// transitionTrigger.
func (t transitionTrigger) String() string {
        switch t {
        case chainTrigger:
                return "chainTrigger"

        case remoteCloseTrigger:
                return "remoteCloseTrigger"

        case userTrigger:
                return "userTrigger"

        case localCloseTrigger:
                return "localCloseTrigger"

        case coopCloseTrigger:
                return "coopCloseTrigger"

        case breachCloseTrigger:
                return "breachCloseTrigger"

        default:
                return "unknown trigger"
        }
}

// stateStep is a help method that examines our internal state, and attempts
// the appropriate state transition if necessary. The next state we transition
// to is returned, Additionally, if the next transition results in a commitment
// broadcast, the commitment transaction itself is returned.
func (c *ChannelArbitrator) stateStep(
        triggerHeight uint32, trigger transitionTrigger,
        confCommitSet *CommitSet) (ArbitratorState, *wire.MsgTx, error) {

        var (
                nextState ArbitratorState
                closeTx   *wire.MsgTx
        )
        switch c.state {

        // If we're in the default state, then we'll check our set of actions
        // to see if while we were down, conditions have changed.
        case StateDefault:
                log.Debugf("ChannelArbitrator(%v): new block (height=%v) "+
                        "examining active HTLC's", c.cfg.ChanPoint,
                        triggerHeight)

                // As a new block has been connected to the end of the main
                // chain, we'll check to see if we need to make any on-chain
                // claims on behalf of the channel contract that we're
                // arbitrating for. If a commitment has confirmed, then we'll
                // use the set snapshot from the chain, otherwise we'll use our
                // current set.
                var (
                        chainActions ChainActionMap
                        err          error
                )

                // Normally if we force close the channel locally we will have
                // no confCommitSet. However when the remote commitment confirms
                // without us ever broadcasting our local commitment we need to
                // make sure we cancel all upstream HTLCs for outgoing dust
                // HTLCs as well hence we need to fetch the chain actions here
                // as well.
                if confCommitSet == nil {
                        // Update the set of activeHTLCs so
                        // checkLocalChainActions has an up-to-date view of the
                        // commitments.
                        c.updateActiveHTLCs()
                        htlcs := c.activeHTLCs
                        chainActions, err = c.checkLocalChainActions(
                                triggerHeight, trigger, htlcs, false,
                        )
                        if err != nil {
                                return StateDefault, nil, err
                        }
                } else {
                        chainActions, err = c.constructChainActions(
                                confCommitSet, triggerHeight, trigger,
                        )
                        if err != nil {
                                return StateDefault, nil, err
                        }
                }

                // If there are no actions to be made, then we'll remain in the
                // default state. If this isn't a self initiated event (we're
                // checking due to a chain update), then we'll exit now.
                if len(chainActions) == 0 && trigger == chainTrigger {
                        log.Debugf("ChannelArbitrator(%v): no actions for "+
                                "chain trigger, terminating", c.cfg.ChanPoint)

                        return StateDefault, closeTx, nil
                }

                // Otherwise, we'll log that we checked the HTLC actions as the
                // commitment transaction has already been broadcast.
                log.Tracef("ChannelArbitrator(%v): logging chain_actions=%v",
                        c.cfg.ChanPoint, lnutils.SpewLogClosure(chainActions))

                // Cancel upstream HTLCs for all outgoing dust HTLCs available
                // either on the local or the remote/remote pending commitment
                // transaction.
                dustHTLCs := chainActions[HtlcFailDustAction]
                if len(dustHTLCs) > 0 {
                        log.Debugf("ChannelArbitrator(%v): canceling %v dust "+
                                "HTLCs backwards", c.cfg.ChanPoint,
                                len(dustHTLCs))

                        getIdx := func(htlc channeldb.HTLC) uint64 {
                                return htlc.HtlcIndex
                        }
                        dustHTLCSet := fn.NewSet(fn.Map(dustHTLCs, getIdx)...)
                        err = c.abandonForwards(dustHTLCSet)
                        if err != nil {
                                return StateError, closeTx, err
                        }
                }

                // Depending on the type of trigger, we'll either "tunnel"
                // through to a farther state, or just proceed linearly to the
                // next state.
                switch trigger {

                // If this is a chain trigger, then we'll go straight to the
                // next state, as we still need to broadcast the commitment
                // transaction.
                case chainTrigger:
                        fallthrough
                case userTrigger:
                        nextState = StateBroadcastCommit

                // If the trigger is a cooperative close being confirmed, then
                // we can go straight to StateFullyResolved, as there won't be
                // any contracts to resolve.
                case coopCloseTrigger:
                        nextState = StateFullyResolved

                // Otherwise, if this state advance was triggered by a
                // commitment being confirmed on chain, then we'll jump
                // straight to the state where the contract has already been
                // closed, and we will inspect the set of unresolved contracts.
                case localCloseTrigger:
                        log.Errorf("ChannelArbitrator(%v): unexpected local "+
                                "commitment confirmed while in StateDefault",
                                c.cfg.ChanPoint)
                        fallthrough
                case remoteCloseTrigger:
                        nextState = StateContractClosed

                case breachCloseTrigger:
                        nextContractState, err := c.checkLegacyBreach()
                        if nextContractState == StateError {
                                return nextContractState, nil, err
                        }

                        nextState = nextContractState
                }

        // If we're in this state, then we've decided to broadcast the
        // commitment transaction. We enter this state either due to an outside
        // sub-system, or because an on-chain action has been triggered.
        case StateBroadcastCommit:
                // Under normal operation, we can only enter
                // StateBroadcastCommit via a user or chain trigger. On restart,
                // this state may be reexecuted after closing the channel, but
                // failing to commit to StateContractClosed or
                // StateFullyResolved. In that case, one of the four close
                // triggers will be presented, signifying that we should skip
                // rebroadcasting, and go straight to resolving the on-chain
                // contract or marking the channel resolved.
                switch trigger {
                case localCloseTrigger, remoteCloseTrigger:
                        log.Infof("ChannelArbitrator(%v): detected %s "+
                                "close after closing channel, fast-forwarding "+
                                "to %s to resolve contract",
                                c.cfg.ChanPoint, trigger, StateContractClosed)
                        return StateContractClosed, closeTx, nil

                case breachCloseTrigger:
                        nextContractState, err := c.checkLegacyBreach()
                        if nextContractState == StateError {
                                log.Infof("ChannelArbitrator(%v): unable to "+
                                        "advance breach close resolution: %v",
                                        c.cfg.ChanPoint, nextContractState)
                                return StateError, closeTx, err
                        }

                        log.Infof("ChannelArbitrator(%v): detected %s close "+
                                "after closing channel, fast-forwarding to %s"+
                                " to resolve contract", c.cfg.ChanPoint,
                                trigger, nextContractState)

                        return nextContractState, closeTx, nil

                case coopCloseTrigger:
                        log.Infof("ChannelArbitrator(%v): detected %s "+
                                "close after closing channel, fast-forwarding "+
                                "to %s to resolve contract",
                                c.cfg.ChanPoint, trigger, StateFullyResolved)
                        return StateFullyResolved, closeTx, nil
                }

                log.Infof("ChannelArbitrator(%v): force closing "+
                        "chan", c.cfg.ChanPoint)

                // Now that we have all the actions decided for the set of
                // HTLC's, we'll broadcast the commitment transaction, and
                // signal the link to exit.

                // We'll tell the switch that it should remove the link for
                // this channel, in addition to fetching the force close
                // summary needed to close this channel on chain.
                forceCloseTx, err := c.cfg.Channel.ForceCloseChan()
                if err != nil {
                        log.Errorf("ChannelArbitrator(%v): unable to "+
                                "force close: %v", c.cfg.ChanPoint, err)

                        // We tried to force close (HTLC may be expiring from
                        // our PoV, etc), but we think we've lost data. In this
                        // case, we'll not force close, but terminate the state
                        // machine here to wait to see what confirms on chain.
                        if errors.Is(err, lnwallet.ErrForceCloseLocalDataLoss) {
                                log.Error("ChannelArbitrator(%v): broadcast "+
                                        "failed due to local data loss, "+
                                        "waiting for on chain confimation...",
                                        c.cfg.ChanPoint)

                                return StateBroadcastCommit, nil, nil
                        }

                        return StateError, closeTx, err
                }
                closeTx = forceCloseTx

                // Before publishing the transaction, we store it to the
                // database, such that we can re-publish later in case it
                // didn't propagate. We initiated the force close, so we
                // mark broadcast with local initiator set to true.
                err = c.cfg.MarkCommitmentBroadcasted(closeTx, lntypes.Local)
                if err != nil {
                        log.Errorf("ChannelArbitrator(%v): unable to "+
                                "mark commitment broadcasted: %v",
                                c.cfg.ChanPoint, err)
                        return StateError, closeTx, err
                }

                // With the close transaction in hand, broadcast the
                // transaction to the network, thereby entering the post
                // channel resolution state.
                log.Infof("Broadcasting force close transaction %v, "+
                        "ChannelPoint(%v): %v", closeTx.TxHash(),
                        c.cfg.ChanPoint, lnutils.SpewLogClosure(closeTx))

                // At this point, we'll now broadcast the commitment
                // transaction itself.
                label := labels.MakeLabel(
                        labels.LabelTypeChannelClose, &c.cfg.ShortChanID,
                )
                if err := c.cfg.PublishTx(closeTx, label); err != nil {
                        log.Errorf("ChannelArbitrator(%v): unable to broadcast "+
                                "close tx: %v", c.cfg.ChanPoint, err)

                        // This makes sure we don't fail at startup if the
                        // commitment transaction has too low fees to make it
                        // into mempool. The rebroadcaster makes sure this
                        // transaction is republished regularly until confirmed
                        // or replaced.
                        if !errors.Is(err, lnwallet.ErrDoubleSpend) &&
                                !errors.Is(err, lnwallet.ErrMempoolFee) {

                                return StateError, closeTx, err
                        }
                }

                // We go to the StateCommitmentBroadcasted state, where we'll
                // be waiting for the commitment to be confirmed.
                nextState = StateCommitmentBroadcasted

        // In this state we have broadcasted our own commitment, and will need
        // to wait for a commitment (not necessarily the one we broadcasted!)
        // to be confirmed.
        case StateCommitmentBroadcasted:
                switch trigger {

                // We are waiting for a commitment to be confirmed.
                case chainTrigger, userTrigger:
                        // The commitment transaction has been broadcast, but it
                        // doesn't necessarily need to be the commitment
                        // transaction version that is going to be confirmed. To
                        // be sure that any of those versions can be anchored
                        // down, we now submit all anchor resolutions to the
                        // sweeper. The sweeper will keep trying to sweep all of
                        // them.
                        //
                        // Note that the sweeper is idempotent. If we ever
                        // happen to end up at this point in the code again, no
                        // harm is done by re-offering the anchors to the
                        // sweeper.
                        anchors, err := c.cfg.Channel.NewAnchorResolutions()
                        if err != nil {
                                return StateError, closeTx, err
                        }

                        err = c.sweepAnchors(anchors, triggerHeight)
                        if err != nil {
                                return StateError, closeTx, err
                        }

                        nextState = StateCommitmentBroadcasted

                // If this state advance was triggered by any of the
                // commitments being confirmed, then we'll jump to the state
                // where the contract has been closed.
                case localCloseTrigger, remoteCloseTrigger:
                        nextState = StateContractClosed

                // If a coop close was confirmed, jump straight to the fully
                // resolved state.
                case coopCloseTrigger:
                        nextState = StateFullyResolved

                case breachCloseTrigger:
                        nextContractState, err := c.checkLegacyBreach()
                        if nextContractState == StateError {
                                return nextContractState, closeTx, err
                        }

                        nextState = nextContractState
                }

                log.Infof("ChannelArbitrator(%v): trigger %v moving from "+
                        "state %v to %v", c.cfg.ChanPoint, trigger, c.state,
                        nextState)

        // If we're in this state, then the contract has been fully closed to
        // outside sub-systems, so we'll process the prior set of on-chain
        // contract actions and launch a set of resolvers.
        case StateContractClosed:
                // First, we'll fetch our chain actions, and both sets of
                // resolutions so we can process them.
                contractResolutions, err := c.log.FetchContractResolutions()
                if err != nil {
                        log.Errorf("unable to fetch contract resolutions: %v",
                                err)
                        return StateError, closeTx, err
                }

                // If the resolution is empty, and we have no HTLCs at all to
                // send to, then we're done here. We don't need to launch any
                // resolvers, and can go straight to our final state.
                if contractResolutions.IsEmpty() && confCommitSet.IsEmpty() {
                        log.Infof("ChannelArbitrator(%v): contract "+
                                "resolutions empty, marking channel as fully resolved!",
                                c.cfg.ChanPoint)
                        nextState = StateFullyResolved
                        break
                }

                // First, we'll reconstruct a fresh set of chain actions as the
                // set of actions we need to act on may differ based on if it
                // was our commitment, or they're commitment that hit the chain.
                htlcActions, err := c.constructChainActions(
                        confCommitSet, triggerHeight, trigger,
                )
                if err != nil {
                        return StateError, closeTx, err
                }

                // In case its a breach transaction we fail back all upstream
                // HTLCs for their corresponding outgoing HTLCs on the remote
                // commitment set (remote and remote pending set).
                if contractResolutions.BreachResolution != nil {
                        // cancelBreachedHTLCs is a set which holds HTLCs whose
                        // corresponding incoming HTLCs will be failed back
                        // because the peer broadcasted an old state.
                        cancelBreachedHTLCs := fn.NewSet[uint64]()

                        // We'll use the CommitSet, we'll fail back all
                        // upstream HTLCs for their corresponding outgoing
                        // HTLC that exist on either of the remote commitments.
                        // The map is used to deduplicate any shared HTLC's.
                        for htlcSetKey, htlcs := range confCommitSet.HtlcSets {
                                if !htlcSetKey.IsRemote {
                                        continue
                                }

                                for _, htlc := range htlcs {
                                        // Only outgoing HTLCs have a
                                        // corresponding incoming HTLC.
                                        if htlc.Incoming {
                                                continue
                                        }

                                        cancelBreachedHTLCs.Add(htlc.HtlcIndex)
                                }
                        }

                        err := c.abandonForwards(cancelBreachedHTLCs)
                        if err != nil {
                                return StateError, closeTx, err
                        }
                } else {
                        // If it's not a breach, we resolve all incoming dust
                        // HTLCs immediately after the commitment is confirmed.
                        err = c.failIncomingDust(
                                htlcActions[HtlcIncomingDustFinalAction],
                        )
                        if err != nil {
                                return StateError, closeTx, err
                        }

                        // We fail the upstream HTLCs for all remote pending
                        // outgoing HTLCs as soon as the commitment is
                        // confirmed. The upstream HTLCs for outgoing dust
                        // HTLCs have already been resolved before we reach
                        // this point.
                        getIdx := func(htlc channeldb.HTLC) uint64 {
                                return htlc.HtlcIndex
                        }
                        remoteDangling := fn.NewSet(fn.Map(
                                htlcActions[HtlcFailDanglingAction], getIdx,
                        )...)
                        err := c.abandonForwards(remoteDangling)
                        if err != nil {
                                return StateError, closeTx, err
                        }
                }

                // Now that we know we'll need to act, we'll process all the
                // resolvers, then create the structures we need to resolve all
                // outstanding contracts.
                resolvers, err := c.prepContractResolutions(
                        contractResolutions, triggerHeight, htlcActions,
                )
                if err != nil {
                        log.Errorf("ChannelArbitrator(%v): unable to "+
                                "resolve contracts: %v", c.cfg.ChanPoint, err)
                        return StateError, closeTx, err
                }

                log.Debugf("ChannelArbitrator(%v): inserting %v contract "+
                        "resolvers", c.cfg.ChanPoint, len(resolvers))

                err = c.log.InsertUnresolvedContracts(nil, resolvers...)
                if err != nil {
                        return StateError, closeTx, err
                }

                // Finally, we'll launch all the required contract resolvers.
                // Once they're all resolved, we're no longer needed.
                c.resolveContracts(resolvers)

                nextState = StateWaitingFullResolution

        // This is our terminal state. We'll keep returning this state until
        // all contracts are fully resolved.
        case StateWaitingFullResolution:
                log.Infof("ChannelArbitrator(%v): still awaiting contract "+
                        "resolution", c.cfg.ChanPoint)

                unresolved, err := c.log.FetchUnresolvedContracts()
                if err != nil {
                        return StateError, closeTx, err
                }

                // If we have no unresolved contracts, then we can move to the
                // final state.
                if len(unresolved) == 0 {
                        nextState = StateFullyResolved
                        break
                }

                // Otherwise we still have unresolved contracts, then we'll
                // stay alive to oversee their resolution.
                nextState = StateWaitingFullResolution

                // Add debug logs.
                for _, r := range unresolved {
                        log.Debugf("ChannelArbitrator(%v): still have "+
                                "unresolved contract: %T", c.cfg.ChanPoint, r)
                }

        // If we start as fully resolved, then we'll end as fully resolved.
        case StateFullyResolved:
                // To ensure that the state of the contract in persistent
                // storage is properly reflected, we'll mark the contract as
                // fully resolved now.
                nextState = StateFullyResolved

                log.Infof("ChannelPoint(%v) has been fully resolved "+
                        "on-chain at height=%v", c.cfg.ChanPoint, triggerHeight)

                if err := c.cfg.MarkChannelResolved(); err != nil {
                        log.Errorf("unable to mark channel resolved: %v", err)
                        return StateError, closeTx, err
                }
        }

        log.Tracef("ChannelArbitrator(%v): next_state=%v", c.cfg.ChanPoint,
                nextState)

        return nextState, closeTx, nil
}

// sweepAnchors offers all given anchor resolutions to the sweeper. It requests
// sweeping at the minimum fee rate. This fee rate can be upped manually by the
// user via the BumpFee rpc.
func (c *ChannelArbitrator) sweepAnchors(anchors *lnwallet.AnchorResolutions,
        heightHint uint32) error {

        // Update the set of activeHTLCs so that the sweeping routine has an
        // up-to-date view of the set of commitments.
        c.updateActiveHTLCs()

        // Prepare the sweeping requests for all possible versions of
        // commitments.
        sweepReqs, err := c.prepareAnchorSweeps(heightHint, anchors)
        if err != nil {
                return err
        }

        // Send out the sweeping requests to the sweeper.
        for _, req := range sweepReqs {
                _, err = c.cfg.Sweeper.SweepInput(req.input, req.params)
                if err != nil {
                        return err
                }
        }

        return nil
}

// findCommitmentDeadlineAndValue finds the deadline (relative block height)
// for a commitment transaction by extracting the minimum CLTV from its HTLCs.
// From our PoV, the deadline delta is defined to be the smaller of,
//   - half of the least CLTV from outgoing HTLCs' corresponding incoming
//     HTLCs,  or,
//   - half of the least CLTV from incoming HTLCs if the preimage is available.
//
// We use half of the CTLV value to ensure that we have enough time to sweep
// the second-level HTLCs.
//
// It also finds the total value that are time-sensitive, which is the sum of
// all the outgoing HTLCs plus incoming HTLCs whose preimages are known. It
// then returns the value left after subtracting the budget used for sweeping
// the time-sensitive HTLCs.
//
// NOTE: when the deadline turns out to be 0 blocks, we will replace it with 1
// block because our fee estimator doesn't allow a 0 conf target. This also
// means we've left behind and should increase our fee to make the transaction
// confirmed asap.
func (c *ChannelArbitrator) findCommitmentDeadlineAndValue(heightHint uint32,
        htlcs htlcSet) (fn.Option[int32], btcutil.Amount, error) {

        deadlineMinHeight := uint32(math.MaxUint32)
        totalValue := btcutil.Amount(0)

        // First, iterate through the outgoingHTLCs to find the lowest CLTV
        // value.
        for _, htlc := range htlcs.outgoingHTLCs {
                // Skip if the HTLC is dust.
                if htlc.OutputIndex < 0 {
                        log.Debugf("ChannelArbitrator(%v): skipped deadline "+
                                "for dust htlc=%x",
                                c.cfg.ChanPoint, htlc.RHash[:])

                        continue
                }

                value := htlc.Amt.ToSatoshis()

                // Find the expiry height for this outgoing HTLC's incoming
                // HTLC.
                deadlineOpt := c.cfg.FindOutgoingHTLCDeadline(htlc)

                // The deadline is default to the current deadlineMinHeight,
                // and it's overwritten when it's not none.
                deadline := deadlineMinHeight
                deadlineOpt.WhenSome(func(d int32) {
                        deadline = uint32(d)

                        // We only consider the value is under protection when
                        // it's time-sensitive.
                        totalValue += value
                })

                if deadline < deadlineMinHeight {
                        deadlineMinHeight = deadline

                        log.Tracef("ChannelArbitrator(%v): outgoing HTLC has "+
                                "deadline=%v, value=%v", c.cfg.ChanPoint,
                                deadlineMinHeight, value)
                }
        }

        // Then going through the incomingHTLCs, and update the minHeight when
        // conditions met.
        for _, htlc := range htlcs.incomingHTLCs {
                // Skip if the HTLC is dust.
                if htlc.OutputIndex < 0 {
                        log.Debugf("ChannelArbitrator(%v): skipped deadline "+
                                "for dust htlc=%x",
                                c.cfg.ChanPoint, htlc.RHash[:])

                        continue
                }

                // Since it's an HTLC sent to us, check if we have preimage for
                // this HTLC.
                preimageAvailable, err := c.isPreimageAvailable(htlc.RHash)
                if err != nil {
                        return fn.None[int32](), 0, err
                }

                if !preimageAvailable {
                        continue
                }

                value := htlc.Amt.ToSatoshis()
                totalValue += value

                if htlc.RefundTimeout < deadlineMinHeight {
                        deadlineMinHeight = htlc.RefundTimeout

                        log.Tracef("ChannelArbitrator(%v): incoming HTLC has "+
                                "deadline=%v, amt=%v", c.cfg.ChanPoint,
                                deadlineMinHeight, value)
                }
        }

        // Calculate the deadline. There are two cases to be handled here,
        //   - when the deadlineMinHeight never gets updated, which could
        //     happen when we have no outgoing HTLCs, and, for incoming HTLCs,
        //       * either we have none, or,
        //       * none of the HTLCs are preimageAvailable.
        //   - when our deadlineMinHeight is no greater than the heightHint,
        //     which means we are behind our schedule.
        var deadline uint32
        switch {
        // When we couldn't find a deadline height from our HTLCs, we will fall
        // back to the default value as there's no time pressure here.
        case deadlineMinHeight == math.MaxUint32:
                return fn.None[int32](), 0, nil

        // When the deadline is passed, we will fall back to the smallest conf
        // target (1 block).
        case deadlineMinHeight <= heightHint:
                log.Warnf("ChannelArbitrator(%v): deadline is passed with "+
                        "deadlineMinHeight=%d, heightHint=%d",
                        c.cfg.ChanPoint, deadlineMinHeight, heightHint)
                deadline = 1

        // Use half of the deadline delta, and leave the other half to be used
        // to sweep the HTLCs.
        default:
                deadline = (deadlineMinHeight - heightHint) / 2
        }

        // Calculate the value left after subtracting the budget used for
        // sweeping the time-sensitive HTLCs.
        valueLeft := totalValue - calculateBudget(
                totalValue, c.cfg.Budget.DeadlineHTLCRatio,
                c.cfg.Budget.DeadlineHTLC,
        )

        log.Debugf("ChannelArbitrator(%v): calculated valueLeft=%v, "+
                "deadline=%d, using deadlineMinHeight=%d, heightHint=%d",
                c.cfg.ChanPoint, valueLeft, deadline, deadlineMinHeight,
                heightHint)

        return fn.Some(int32(deadline)), valueLeft, nil
}

// resolveContracts updates the activeResolvers list and starts to resolve each
// contract concurrently, and launches them.
func (c *ChannelArbitrator) resolveContracts(resolvers []ContractResolver) {
        c.activeResolversLock.Lock()
        c.activeResolvers = resolvers
        c.activeResolversLock.Unlock()

        // Launch all resolvers.
        c.launchResolvers()

        for _, contract := range resolvers {
                c.wg.Add(1)
                go c.resolveContract(contract)
        }
}

// launchResolvers launches all the active resolvers concurrently.
func (c *ChannelArbitrator) launchResolvers() {
        c.activeResolversLock.Lock()
        resolvers := c.activeResolvers
        c.activeResolversLock.Unlock()

        // errChans is a map of channels that will be used to receive errors
        // returned from launching the resolvers.
        errChans := make(map[ContractResolver]chan error, len(resolvers))

        // Launch each resolver in goroutines.
        for _, r := range resolvers {
                // If the contract is already resolved, there's no need to
                // launch it again.
                if r.IsResolved() {
                        log.Debugf("ChannelArbitrator(%v): skipping resolver "+
                                "%T as it's already resolved", c.cfg.ChanPoint,
                                r)

                        continue
                }

                // Create a signal chan.
                errChan := make(chan error, 1)
                errChans[r] = errChan

                go func() {
                        err := r.Launch()
                        errChan <- err
                }()
        }

        // Wait for all resolvers to finish launching.
        for r, errChan := range errChans {
                select {
                case err := <-errChan:
                        if err == nil {
                                continue
                        }

                        log.Errorf("ChannelArbitrator(%v): unable to launch "+
                                "contract resolver(%T): %v", c.cfg.ChanPoint, r,
                                err)

                case <-c.quit:
                        log.Debugf("ChannelArbitrator quit signal received, " +
                                "exit launchResolvers")

                        return
                }
        }
}

// advanceState is the main driver of our state machine. This method is an
// iterative function which repeatedly attempts to advance the internal state
// of the channel arbitrator. The state will be advanced until we reach a
// redundant transition, meaning that the state transition is a noop. The final
// param is a callback that allows the caller to execute an arbitrary action
// after each state transition.
func (c *ChannelArbitrator) advanceState(
        triggerHeight uint32, trigger transitionTrigger,
        confCommitSet *CommitSet) (ArbitratorState, *wire.MsgTx, error) {

        var (
                priorState   ArbitratorState
                forceCloseTx *wire.MsgTx
        )

        // We'll continue to advance our state forward until the state we
        // transition to is that same state that we started at.
        for {
                priorState = c.state
                log.Debugf("ChannelArbitrator(%v): attempting state step with "+
                        "trigger=%v from state=%v at height=%v",
                        c.cfg.ChanPoint, trigger, priorState, triggerHeight)

                nextState, closeTx, err := c.stateStep(
                        triggerHeight, trigger, confCommitSet,
                )
                if err != nil {
                        log.Errorf("ChannelArbitrator(%v): unable to advance "+
                                "state: %v", c.cfg.ChanPoint, err)
                        return priorState, nil, err
                }

                if forceCloseTx == nil && closeTx != nil {
                        forceCloseTx = closeTx
                }

                // Our termination transition is a noop transition. If we get
                // our prior state back as the next state, then we'll
                // terminate.
                if nextState == priorState {
                        log.Debugf("ChannelArbitrator(%v): terminating at "+
                                "state=%v", c.cfg.ChanPoint, nextState)
                        return nextState, forceCloseTx, nil
                }

                // As the prior state was successfully executed, we can now
                // commit the next state. This ensures that we will re-execute
                // the prior state if anything fails.
                if err := c.log.CommitState(nextState); err != nil {
                        log.Errorf("ChannelArbitrator(%v): unable to commit "+
                                "next state(%v): %v", c.cfg.ChanPoint,
                                nextState, err)
                        return priorState, nil, err
                }
                c.state = nextState
        }
}

// ChainAction is an enum that encompasses all possible on-chain actions
// we'll take for a set of HTLC's.
type ChainAction uint8

const (
        // NoAction is the min chainAction type, indicating that no action
        // needs to be taken for a given HTLC.
        NoAction ChainAction = 0

        // HtlcTimeoutAction indicates that the HTLC will timeout soon. As a
        // result, we should get ready to sweep it on chain after the timeout.
        HtlcTimeoutAction = 1

        // HtlcClaimAction indicates that we should claim the HTLC on chain
        // before its timeout period.
        HtlcClaimAction = 2

        // HtlcFailDustAction indicates that we should fail the upstream HTLC
        // for an outgoing dust HTLC immediately (even before the commitment
        // transaction is confirmed) because it has no output on the commitment
        // transaction. This also includes remote pending outgoing dust HTLCs.
        HtlcFailDustAction = 3

        // HtlcOutgoingWatchAction indicates that we can't yet timeout this
        // HTLC, but we had to go to chain on order to resolve an existing
        // HTLC.  In this case, we'll either: time it out once it expires, or
        // will learn the pre-image if the remote party claims the output. In
        // this case, well add the pre-image to our global store.
        HtlcOutgoingWatchAction = 4

        // HtlcIncomingWatchAction indicates that we don't yet have the
        // pre-image to claim incoming HTLC, but we had to go to chain in order
        // to resolve and existing HTLC. In this case, we'll either: let the
        // other party time it out, or eventually learn of the pre-image, in
        // which case we'll claim on chain.
        HtlcIncomingWatchAction = 5

        // HtlcIncomingDustFinalAction indicates that we should mark an incoming
        // dust htlc as final because it can't be claimed on-chain.
        HtlcIncomingDustFinalAction = 6

        // HtlcFailDanglingAction indicates that we should fail the upstream
        // HTLC for an outgoing HTLC immediately after the commitment
        // transaction has confirmed because it has no corresponding output on
        // the commitment transaction. This category does NOT include any dust
        // HTLCs which are mapped in the "HtlcFailDustAction" category.
        HtlcFailDanglingAction = 7
)

// String returns a human readable string describing a chain action.
func (c ChainAction) String() string {
        switch c {
        case NoAction:
                return "NoAction"

        case HtlcTimeoutAction:
                return "HtlcTimeoutAction"

        case HtlcClaimAction:
                return "HtlcClaimAction"

        case HtlcFailDustAction:
                return "HtlcFailDustAction"

        case HtlcOutgoingWatchAction:
                return "HtlcOutgoingWatchAction"

        case HtlcIncomingWatchAction:
                return "HtlcIncomingWatchAction"

        case HtlcIncomingDustFinalAction:
                return "HtlcIncomingDustFinalAction"

        case HtlcFailDanglingAction:
                return "HtlcFailDanglingAction"

        default:
                return "<unknown action>"
        }
}

// ChainActionMap is a map of a chain action, to the set of HTLC's that need to
// be acted upon for a given action type. The channel
type ChainActionMap map[ChainAction][]channeldb.HTLC

// Merge merges the passed chain actions with the target chain action map.
func (c ChainActionMap) Merge(actions ChainActionMap) {
        for chainAction, htlcs := range actions {
                c[chainAction] = append(c[chainAction], htlcs...)
        }
}

// shouldGoOnChain takes into account the absolute timeout of the HTLC, if the
// confirmation delta that we need is close, and returns a bool indicating if
// we should go on chain to claim.  We do this rather than waiting up until the
// last minute as we want to ensure that when we *need* (HTLC is timed out) to
// sweep, the commitment is already confirmed.
func (c *ChannelArbitrator) shouldGoOnChain(htlc channeldb.HTLC,
        broadcastDelta, currentHeight uint32) bool {

        // We'll calculate the broadcast cut off for this HTLC. This is the
        // height that (based on our current fee estimation) we should
        // broadcast in order to ensure the commitment transaction is confirmed
        // before the HTLC fully expires.
        broadcastCutOff := htlc.RefundTimeout - broadcastDelta

        log.Tracef("ChannelArbitrator(%v): examining outgoing contract: "+
                "expiry=%v, cutoff=%v, height=%v", c.cfg.ChanPoint, htlc.RefundTimeout,
                broadcastCutOff, currentHeight)

        // TODO(roasbeef): take into account default HTLC delta, don't need to
        // broadcast immediately
        //  * can then batch with SINGLE | ANYONECANPAY

        // We should on-chain for this HTLC, iff we're within out broadcast
        // cutoff window.
        if currentHeight < broadcastCutOff {
                return false
        }

        // In case of incoming htlc we should go to chain.
        if htlc.Incoming {
                return true
        }

        // For htlcs that are result of our initiated payments we give some grace
        // period before force closing the channel. During this time we expect
        // both nodes to connect and give a chance to the other node to send its
        // updates and cancel the htlc.
        // This shouldn't add any security risk as there is no incoming htlc to
        // fulfill at this case and the expectation is that when the channel is
        // active the other node will send update_fail_htlc to remove the htlc
        // without closing the channel. It is up to the user to force close the
        // channel if the peer misbehaves and doesn't send the update_fail_htlc.
        // It is useful when this node is most of the time not online and is
        // likely to miss the time slot where the htlc may be cancelled.
        isForwarded := c.cfg.IsForwardedHTLC(c.cfg.ShortChanID, htlc.HtlcIndex)
        upTime := c.cfg.Clock.Now().Sub(c.startTimestamp)
        return isForwarded || upTime > c.cfg.PaymentsExpirationGracePeriod
}

// checkCommitChainActions is called for each new block connected to the end of
// the main chain. Given the new block height, this new method will examine all
// active HTLC's, and determine if we need to go on-chain to claim any of them.
// A map of action -> []htlc is returned, detailing what action (if any) should
// be performed for each HTLC. For timed out HTLC's, once the commitment has
// been sufficiently confirmed, the HTLC's should be canceled backwards. For
// redeemed HTLC's, we should send the pre-image back to the incoming link.
func (c *ChannelArbitrator) checkCommitChainActions(height uint32,
        trigger transitionTrigger, htlcs htlcSet) (ChainActionMap, error) {

        // TODO(roasbeef): would need to lock channel? channel totem?
        //  * race condition if adding and we broadcast, etc
        //  * or would make each instance sync?

        log.Debugf("ChannelArbitrator(%v): checking commit chain actions at "+
                "height=%v, in_htlc_count=%v, out_htlc_count=%v",
                c.cfg.ChanPoint, height,
                len(htlcs.incomingHTLCs), len(htlcs.outgoingHTLCs))

        actionMap := make(ChainActionMap)

        // First, we'll make an initial pass over the set of incoming and
        // outgoing HTLC's to decide if we need to go on chain at all.
        haveChainActions := false
        for _, htlc := range htlcs.outgoingHTLCs {
                // We'll need to go on-chain for an outgoing HTLC if it was
                // never resolved downstream, and it's "close" to timing out.
                //
                // TODO(yy): If there's no corresponding incoming HTLC, it
                // means we are the first hop, hence the payer. This is a
                // tricky case - unlike a forwarding hop, we don't have an
                // incoming HTLC that will time out, which means as long as we
                // can learn the preimage, we can settle the invoice (before it
                // expires?).
                toChain := c.shouldGoOnChain(
                        htlc, c.cfg.OutgoingBroadcastDelta, height,
                )

                if toChain {
                        // Convert to int64 in case of overflow.
                        remainingBlocks := int64(htlc.RefundTimeout) -
                                int64(height)

                        log.Infof("ChannelArbitrator(%v): go to chain for "+
                                "outgoing htlc %x: timeout=%v, amount=%v, "+
                                "blocks_until_expiry=%v, broadcast_delta=%v",
                                c.cfg.ChanPoint, htlc.RHash[:],
                                htlc.RefundTimeout, htlc.Amt, remainingBlocks,
                                c.cfg.OutgoingBroadcastDelta,
                        )
                }

                haveChainActions = haveChainActions || toChain
        }

        for _, htlc := range htlcs.incomingHTLCs {
                // We'll need to go on-chain to pull an incoming HTLC iff we
                // know the pre-image and it's close to timing out. We need to
                // ensure that we claim the funds that are rightfully ours
                // on-chain.
                preimageAvailable, err := c.isPreimageAvailable(htlc.RHash)
                if err != nil {
                        return nil, err
                }

                if !preimageAvailable {
                        continue
                }

                toChain := c.shouldGoOnChain(
                        htlc, c.cfg.IncomingBroadcastDelta, height,
                )

                if toChain {
                        // Convert to int64 in case of overflow.
                        remainingBlocks := int64(htlc.RefundTimeout) -
                                int64(height)

                        log.Infof("ChannelArbitrator(%v): go to chain for "+
                                "incoming htlc %x: timeout=%v, amount=%v, "+
                                "blocks_until_expiry=%v, broadcast_delta=%v",
                                c.cfg.ChanPoint, htlc.RHash[:],
                                htlc.RefundTimeout, htlc.Amt, remainingBlocks,
                                c.cfg.IncomingBroadcastDelta,
                        )
                }

                haveChainActions = haveChainActions || toChain
        }

        // If we don't have any actions to make, then we'll return an empty
        // action map. We only do this if this was a chain trigger though, as
        // if we're going to broadcast the commitment (or the remote party did)
        // we're *forced* to act on each HTLC.
        if !haveChainActions && trigger == chainTrigger {
                log.Tracef("ChannelArbitrator(%v): no actions to take at "+
                        "height=%v", c.cfg.ChanPoint, height)
                return actionMap, nil
        }

        // Now that we know we'll need to go on-chain, we'll examine all of our
        // active outgoing HTLC's to see if we either need to: sweep them after
        // a timeout (then cancel backwards), cancel them backwards
        // immediately, or watch them as they're still active contracts.
        for _, htlc := range htlcs.outgoingHTLCs {
                switch {
                // If the HTLC is dust, then we can cancel it backwards
                // immediately as there's no matching contract to arbitrate
                // on-chain. We know the HTLC is dust, if the OutputIndex
                // negative.
                case htlc.OutputIndex < 0:
                        log.Tracef("ChannelArbitrator(%v): immediately "+
                                "failing dust htlc=%x", c.cfg.ChanPoint,
                                htlc.RHash[:])

                        actionMap[HtlcFailDustAction] = append(
                                actionMap[HtlcFailDustAction], htlc,
                        )

                // If we don't need to immediately act on this HTLC, then we'll
                // mark it still "live". After we broadcast, we'll monitor it
                // until the HTLC times out to see if we can also redeem it
                // on-chain.
                case !c.shouldGoOnChain(htlc, c.cfg.OutgoingBroadcastDelta,
                        height,
                ):
                        // TODO(roasbeef): also need to be able to query
                        // circuit map to see if HTLC hasn't been fully
                        // resolved
                        //
                        //  * can't fail incoming until if outgoing not yet
                        //  failed

                        log.Tracef("ChannelArbitrator(%v): watching chain to "+
                                "decide action for outgoing htlc=%x",
                                c.cfg.ChanPoint, htlc.RHash[:])

                        actionMap[HtlcOutgoingWatchAction] = append(
                                actionMap[HtlcOutgoingWatchAction], htlc,
                        )

                // Otherwise, we'll update our actionMap to mark that we need
                // to sweep this HTLC on-chain
                default:
                        log.Tracef("ChannelArbitrator(%v): going on-chain to "+
                                "timeout htlc=%x", c.cfg.ChanPoint, htlc.RHash[:])

                        actionMap[HtlcTimeoutAction] = append(
                                actionMap[HtlcTimeoutAction], htlc,
                        )
                }
        }

        // Similarly, for each incoming HTLC, now that we need to go on-chain,
        // we'll either: sweep it immediately if we know the pre-image, or
        // observe the output on-chain if we don't In this last, case we'll
        // either learn of it eventually from the outgoing HTLC, or the sender
        // will timeout the HTLC.
        for _, htlc := range htlcs.incomingHTLCs {
                // If the HTLC is dust, there is no action to be taken.
                if htlc.OutputIndex < 0 {
                        log.Debugf("ChannelArbitrator(%v): no resolution "+
                                "needed for incoming dust htlc=%x",
                                c.cfg.ChanPoint, htlc.RHash[:])

                        actionMap[HtlcIncomingDustFinalAction] = append(
                                actionMap[HtlcIncomingDustFinalAction], htlc,
                        )

                        continue
                }

                log.Tracef("ChannelArbitrator(%v): watching chain to decide "+
                        "action for incoming htlc=%x", c.cfg.ChanPoint,
                        htlc.RHash[:])

                actionMap[HtlcIncomingWatchAction] = append(
                        actionMap[HtlcIncomingWatchAction], htlc,
                )
        }

        return actionMap, nil
}

// isPreimageAvailable returns whether the hash preimage is available in either
// the preimage cache or the invoice database.
func (c *ChannelArbitrator) isPreimageAvailable(hash lntypes.Hash) (bool,
        error) {

        // Start by checking the preimage cache for preimages of
        // forwarded HTLCs.
        _, preimageAvailable := c.cfg.PreimageDB.LookupPreimage(
                hash,
        )
        if preimageAvailable {
                return true, nil
        }

        // Then check if we have an invoice that can be settled by this HTLC.
        //
        // TODO(joostjager): Check that there are still more blocks remaining
        // than the invoice cltv delta. We don't want to go to chain only to
        // have the incoming contest resolver decide that we don't want to
        // settle this invoice.
        invoice, err := c.cfg.Registry.LookupInvoice(context.Background(), hash)
        switch {
        case err == nil:
        case errors.Is(err, invoices.ErrInvoiceNotFound) ||
                errors.Is(err, invoices.ErrNoInvoicesCreated):

                return false, nil
        default:
                return false, err
        }

        preimageAvailable = invoice.Terms.PaymentPreimage != nil

        return preimageAvailable, nil
}

// checkLocalChainActions is similar to checkCommitChainActions, but it also
// examines the set of HTLCs on the remote party's commitment. This allows us
// to ensure we're able to satisfy the HTLC timeout constraints for incoming vs
// outgoing HTLCs.
func (c *ChannelArbitrator) checkLocalChainActions(
        height uint32, trigger transitionTrigger,
        activeHTLCs map[HtlcSetKey]htlcSet,
        commitsConfirmed bool) (ChainActionMap, error) {

        // First, we'll check our local chain actions as normal. This will only
        // examine HTLCs on our local commitment (timeout or settle).
        localCommitActions, err := c.checkCommitChainActions(
                height, trigger, activeHTLCs[LocalHtlcSet],
        )
        if err != nil {
                return nil, err
        }

        // Next, we'll examine the remote commitment (and maybe a dangling one)
        // to see if the set difference of our HTLCs is non-empty. If so, then
        // we may need to cancel back some HTLCs if we decide go to chain.
        remoteDanglingActions := c.checkRemoteDanglingActions(
                height, activeHTLCs, commitsConfirmed,
        )

        // Finally, we'll merge the two set of chain actions.
        localCommitActions.Merge(remoteDanglingActions)

        return localCommitActions, nil
}

// checkRemoteDanglingActions examines the set of remote commitments for any
// HTLCs that are close to timing out. If we find any, then we'll return a set
// of chain actions for HTLCs that are on our commitment, but not theirs to
// cancel immediately.
func (c *ChannelArbitrator) checkRemoteDanglingActions(
        height uint32, activeHTLCs map[HtlcSetKey]htlcSet,
        commitsConfirmed bool) ChainActionMap {

        var (
                pendingRemoteHTLCs []channeldb.HTLC
                localHTLCs         = make(map[uint64]struct{})
                remoteHTLCs        = make(map[uint64]channeldb.HTLC)
                actionMap          = make(ChainActionMap)
        )

        // First, we'll construct two sets of the outgoing HTLCs: those on our
        // local commitment, and those that are on the remote commitment(s).
        for htlcSetKey, htlcs := range activeHTLCs {
                if htlcSetKey.IsRemote {
                        for _, htlc := range htlcs.outgoingHTLCs {
                                remoteHTLCs[htlc.HtlcIndex] = htlc
                        }
                } else {
                        for _, htlc := range htlcs.outgoingHTLCs {
                                localHTLCs[htlc.HtlcIndex] = struct{}{}
                        }
                }
        }

        // With both sets constructed, we'll now compute the set difference of
        // our two sets of HTLCs. This'll give us the HTLCs that exist on the
        // remote commitment transaction, but not on ours.
        for htlcIndex, htlc := range remoteHTLCs {
                if _, ok := localHTLCs[htlcIndex]; ok {
                        continue
                }

                pendingRemoteHTLCs = append(pendingRemoteHTLCs, htlc)
        }

        // Finally, we'll examine all the pending remote HTLCs for those that
        // have expired. If we find any, then we'll recommend that they be
        // failed now so we can free up the incoming HTLC.
        for _, htlc := range pendingRemoteHTLCs {
                // We'll now check if we need to go to chain in order to cancel
                // the incoming HTLC.
                goToChain := c.shouldGoOnChain(htlc, c.cfg.OutgoingBroadcastDelta,
                        height,
                )

                // If we don't need to go to chain, and no commitments have
                // been confirmed, then we can move on. Otherwise, if
                // commitments have been confirmed, then we need to cancel back
                // *all* of the pending remote HTLCS.
                if !goToChain && !commitsConfirmed {
                        continue
                }

                // Dust htlcs can be canceled back even before the commitment
                // transaction confirms. Dust htlcs are not enforceable onchain.
                // If another version of the commit tx would confirm we either
                // gain or lose those dust amounts but there is no other way
                // than cancelling the incoming back because we will never learn
                // the preimage.
                if htlc.OutputIndex < 0 {
                        log.Infof("ChannelArbitrator(%v): fail dangling dust "+
                                "htlc=%x from local/remote commitments diff",
                                c.cfg.ChanPoint, htlc.RHash[:])

                        actionMap[HtlcFailDustAction] = append(
                                actionMap[HtlcFailDustAction], htlc,
                        )

                        continue
                }

                log.Infof("ChannelArbitrator(%v): fail dangling htlc=%x from "+
                        "local/remote commitments diff",
                        c.cfg.ChanPoint, htlc.RHash[:])

                actionMap[HtlcFailDanglingAction] = append(
                        actionMap[HtlcFailDanglingAction], htlc,
                )
        }

        return actionMap
}

// checkRemoteChainActions examines the two possible remote commitment chains
// and returns the set of chain actions we need to carry out if the remote
// commitment (non pending) confirms. The pendingConf indicates if the pending
// remote commitment confirmed. This is similar to checkCommitChainActions, but
// we'll immediately fail any HTLCs on the pending remote commit, but not the
// remote commit (or the other way around).
func (c *ChannelArbitrator) checkRemoteChainActions(
        height uint32, trigger transitionTrigger,
        activeHTLCs map[HtlcSetKey]htlcSet,
        pendingConf bool) (ChainActionMap, error) {

        // First, we'll examine all the normal chain actions on the remote
        // commitment that confirmed.
        confHTLCs := activeHTLCs[RemoteHtlcSet]
        if pendingConf {
                confHTLCs = activeHTLCs[RemotePendingHtlcSet]
        }
        remoteCommitActions, err := c.checkCommitChainActions(
                height, trigger, confHTLCs,
        )
        if err != nil {
                return nil, err
        }

        // With these actions computed, we'll now check the diff of the HTLCs on
        // the commitments, and cancel back any that are on the pending but not
        // the non-pending.
        remoteDiffActions := c.checkRemoteDiffActions(
                activeHTLCs, pendingConf,
        )

        // Finally, we'll merge all the chain actions and the final set of
        // chain actions.
        remoteCommitActions.Merge(remoteDiffActions)
        return remoteCommitActions, nil
}

// checkRemoteDiffActions checks the set difference of the HTLCs on the remote
// confirmed commit and remote pending commit for HTLCS that we need to cancel
// back. If we find any HTLCs on the remote pending but not the remote, then
// we'll mark them to be failed immediately.
func (c *ChannelArbitrator) checkRemoteDiffActions(
        activeHTLCs map[HtlcSetKey]htlcSet,
        pendingConf bool) ChainActionMap {

        // First, we'll partition the HTLCs into those that are present on the
        // confirmed commitment, and those on the dangling commitment.
        confHTLCs := activeHTLCs[RemoteHtlcSet]
        danglingHTLCs := activeHTLCs[RemotePendingHtlcSet]
        if pendingConf {
                confHTLCs = activeHTLCs[RemotePendingHtlcSet]
                danglingHTLCs = activeHTLCs[RemoteHtlcSet]
        }

        // Next, we'll create a set of all the HTLCs confirmed commitment.
        remoteHtlcs := make(map[uint64]struct{})
        for _, htlc := range confHTLCs.outgoingHTLCs {
                remoteHtlcs[htlc.HtlcIndex] = struct{}{}
        }

        // With the remote HTLCs assembled, we'll mark any HTLCs only on the
        // remote pending commitment to be failed asap.
        actionMap := make(ChainActionMap)
        for _, htlc := range danglingHTLCs.outgoingHTLCs {
                if _, ok := remoteHtlcs[htlc.HtlcIndex]; ok {
                        continue
                }

                preimageAvailable, err := c.isPreimageAvailable(htlc.RHash)
                if err != nil {
                        log.Errorf("ChannelArbitrator(%v): failed to query "+
                                "preimage for dangling htlc=%x from remote "+
                                "commitments diff", c.cfg.ChanPoint,
                                htlc.RHash[:])

                        continue
                }

                if preimageAvailable {
                        continue
                }

                // Dust HTLCs on the remote commitment can be failed back.
                if htlc.OutputIndex < 0 {
                        log.Infof("ChannelArbitrator(%v): fail dangling dust "+
                                "htlc=%x from remote commitments diff",
                                c.cfg.ChanPoint, htlc.RHash[:])

                        actionMap[HtlcFailDustAction] = append(
                                actionMap[HtlcFailDustAction], htlc,
                        )

                        continue
                }

                actionMap[HtlcFailDanglingAction] = append(
                        actionMap[HtlcFailDanglingAction], htlc,
                )

                log.Infof("ChannelArbitrator(%v): fail dangling htlc=%x from "+
                        "remote commitments diff",
                        c.cfg.ChanPoint, htlc.RHash[:])
        }

        return actionMap
}

// constructChainActions returns the set of actions that should be taken for
// confirmed HTLCs at the specified height. Our actions will depend on the set
// of HTLCs that were active across all channels at the time of channel
// closure.
func (c *ChannelArbitrator) constructChainActions(confCommitSet *CommitSet,
        height uint32, trigger transitionTrigger) (ChainActionMap, error) {

        // If we've reached this point and have not confirmed commitment set,
        // then this is an older node that had a pending close channel before
        // the CommitSet was introduced. In this case, we'll just return the
        // existing ChainActionMap they had on disk.
        if confCommitSet == nil || confCommitSet.ConfCommitKey.IsNone() {
                return c.log.FetchChainActions()
        }

        // Otherwise, we have the full commitment set written to disk, and can
        // proceed as normal.
        htlcSets := confCommitSet.toActiveHTLCSets()
        confCommitKey, err := confCommitSet.ConfCommitKey.UnwrapOrErr(
                fmt.Errorf("no commitKey available"),
        )
        if err != nil {
                return nil, err
        }

        switch confCommitKey {
        // If the local commitment transaction confirmed, then we'll examine
        // that as well as their commitments to the set of chain actions.
        case LocalHtlcSet:
                return c.checkLocalChainActions(
                        height, trigger, htlcSets, true,
                )

        // If the remote commitment confirmed, then we'll grab all the chain
        // actions for the remote commit, and check the pending commit for any
        // HTLCS we need to handle immediately (dust).
        case RemoteHtlcSet:
                return c.checkRemoteChainActions(
                        height, trigger, htlcSets, false,
                )

        // Otherwise, the remote pending commitment confirmed, so we'll examine
        // the HTLCs on that unrevoked dangling commitment.
        case RemotePendingHtlcSet:
                return c.checkRemoteChainActions(
                        height, trigger, htlcSets, true,
                )
        }

        return nil, fmt.Errorf("unable to locate chain actions")
}

// prepContractResolutions is called either in the case that we decide we need
// to go to chain, or the remote party goes to chain. Given a set of actions we
// need to take for each HTLC, this method will return a set of contract
// resolvers that will resolve the contracts on-chain if needed, and also a set
// of packets to send to the htlcswitch in order to ensure all incoming HTLC's
// are properly resolved.
func (c *ChannelArbitrator) prepContractResolutions(
        contractResolutions *ContractResolutions, height uint32,
        htlcActions ChainActionMap) ([]ContractResolver, error) {

        // We'll also fetch the historical state of this channel, as it should
        // have been marked as closed by now, and supplement it to each resolver
        // such that we can properly resolve our pending contracts.
        var chanState *channeldb.OpenChannel
        chanState, err := c.cfg.FetchHistoricalChannel()
        switch {
        // If we don't find this channel, then it may be the case that it
        // was closed before we started to retain the final state
        // information for open channels.
        case err == channeldb.ErrNoHistoricalBucket:
                fallthrough
        case err == channeldb.ErrChannelNotFound:
                log.Warnf("ChannelArbitrator(%v): unable to fetch historical "+
                        "state", c.cfg.ChanPoint)

        case err != nil:
                return nil, err
        }

        incomingResolutions := contractResolutions.HtlcResolutions.IncomingHTLCs
        outgoingResolutions := contractResolutions.HtlcResolutions.OutgoingHTLCs

        // We'll use these two maps to quickly look up an active HTLC with its
        // matching HTLC resolution.
        outResolutionMap := make(map[wire.OutPoint]lnwallet.OutgoingHtlcResolution)
        inResolutionMap := make(map[wire.OutPoint]lnwallet.IncomingHtlcResolution)
        for i := 0; i < len(incomingResolutions); i++ {
                inRes := incomingResolutions[i]
                inResolutionMap[inRes.HtlcPoint()] = inRes
        }
        for i := 0; i < len(outgoingResolutions); i++ {
                outRes := outgoingResolutions[i]
                outResolutionMap[outRes.HtlcPoint()] = outRes
        }

        // We'll create the resolver kit that we'll be cloning for each
        // resolver so they each can do their duty.
        resolverCfg := ResolverConfig{
                ChannelArbitratorConfig: c.cfg,
                Checkpoint: func(res ContractResolver,
                        reports ...*channeldb.ResolverReport) error {

                        return c.log.InsertUnresolvedContracts(reports, res)
                },
        }

        commitHash := contractResolutions.CommitHash

        var htlcResolvers []ContractResolver

        // We instantiate an anchor resolver if the commitment tx has an
        // anchor.
        if contractResolutions.AnchorResolution != nil {
                anchorResolver := newAnchorResolver(
                        contractResolutions.AnchorResolution.AnchorSignDescriptor,
                        contractResolutions.AnchorResolution.CommitAnchor,
                        height, c.cfg.ChanPoint, resolverCfg,
                )
                anchorResolver.SupplementState(chanState)

                htlcResolvers = append(htlcResolvers, anchorResolver)
        }

        // If this is a breach close, we'll create a breach resolver, determine
        // the htlc's to fail back, and exit. This is done because the other
        // steps taken for non-breach-closes do not matter for breach-closes.
        if contractResolutions.BreachResolution != nil {
                breachResolver := newBreachResolver(resolverCfg)
                htlcResolvers = append(htlcResolvers, breachResolver)

                return htlcResolvers, nil
        }

        // For each HTLC, we'll either act immediately, meaning we'll instantly
        // fail the HTLC, or we'll act only once the transaction has been
        // confirmed, in which case we'll need an HTLC resolver.
        for htlcAction, htlcs := range htlcActions {
                switch htlcAction {
                // If we can claim this HTLC, we'll create an HTLC resolver to
                // claim the HTLC (second-level or directly), then add the pre
                case HtlcClaimAction:
                        for _, htlc := range htlcs {
                                htlc := htlc

                                htlcOp := wire.OutPoint{
                                        Hash:  commitHash,
                                        Index: uint32(htlc.OutputIndex),
                                }

                                resolution, ok := inResolutionMap[htlcOp]
                                if !ok {
                                        // TODO(roasbeef): panic?
                                        log.Errorf("ChannelArbitrator(%v) unable to find "+
                                                "incoming resolution: %v",
                                                c.cfg.ChanPoint, htlcOp)
                                        continue
                                }

                                resolver := newSuccessResolver(
                                        resolution, height, htlc, resolverCfg,
                                )
                                if chanState != nil {
                                        resolver.SupplementState(chanState)
                                }
                                htlcResolvers = append(htlcResolvers, resolver)
                        }

                // If we can timeout the HTLC directly, then we'll create the
                // proper resolver to do so, who will then cancel the packet
                // backwards.
                case HtlcTimeoutAction:
                        for _, htlc := range htlcs {
                                htlc := htlc

                                htlcOp := wire.OutPoint{
                                        Hash:  commitHash,
                                        Index: uint32(htlc.OutputIndex),
                                }

                                resolution, ok := outResolutionMap[htlcOp]
                                if !ok {
                                        log.Errorf("ChannelArbitrator(%v) unable to find "+
                                                "outgoing resolution: %v", c.cfg.ChanPoint, htlcOp)
                                        continue
                                }

                                resolver := newTimeoutResolver(
                                        resolution, height, htlc, resolverCfg,
                                )
                                if chanState != nil {
                                        resolver.SupplementState(chanState)
                                }

                                // For outgoing HTLCs, we will also need to
                                // supplement the resolver with the expiry
                                // block height of its corresponding incoming
                                // HTLC.
                                deadline := c.cfg.FindOutgoingHTLCDeadline(htlc)
                                resolver.SupplementDeadline(deadline)

                                htlcResolvers = append(htlcResolvers, resolver)
                        }

                // If this is an incoming HTLC, but we can't act yet, then
                // we'll create an incoming resolver to redeem the HTLC if we
                // learn of the pre-image, or let the remote party time out.
                case HtlcIncomingWatchAction:
                        for _, htlc := range htlcs {
                                htlc := htlc

                                htlcOp := wire.OutPoint{
                                        Hash:  commitHash,
                                        Index: uint32(htlc.OutputIndex),
                                }

                                // TODO(roasbeef): need to handle incoming dust...

                                // TODO(roasbeef): can't be negative!!!
                                resolution, ok := inResolutionMap[htlcOp]
                                if !ok {
                                        log.Errorf("ChannelArbitrator(%v) unable to find "+
                                                "incoming resolution: %v",
                                                c.cfg.ChanPoint, htlcOp)
                                        continue
                                }

                                resolver := newIncomingContestResolver(
                                        resolution, height, htlc,
                                        resolverCfg,
                                )
                                if chanState != nil {
                                        resolver.SupplementState(chanState)
                                }
                                htlcResolvers = append(htlcResolvers, resolver)
                        }

                // Finally, if this is an outgoing HTLC we've sent, then we'll
                // launch a resolver to watch for the pre-image (and settle
                // backwards), or just timeout.
                case HtlcOutgoingWatchAction:
                        for _, htlc := range htlcs {
                                htlc := htlc

                                htlcOp := wire.OutPoint{
                                        Hash:  commitHash,
                                        Index: uint32(htlc.OutputIndex),
                                }

                                resolution, ok := outResolutionMap[htlcOp]
                                if !ok {
                                        log.Errorf("ChannelArbitrator(%v) "+
                                                "unable to find outgoing "+
                                                "resolution: %v",
                                                c.cfg.ChanPoint, htlcOp)

                                        continue
                                }

                                resolver := newOutgoingContestResolver(
                                        resolution, height, htlc, resolverCfg,
                                )
                                if chanState != nil {
                                        resolver.SupplementState(chanState)
                                }

                                // For outgoing HTLCs, we will also need to
                                // supplement the resolver with the expiry
                                // block height of its corresponding incoming
                                // HTLC.
                                deadline := c.cfg.FindOutgoingHTLCDeadline(htlc)
                                resolver.SupplementDeadline(deadline)

                                htlcResolvers = append(htlcResolvers, resolver)
                        }
                }
        }

        // If this is was an unilateral closure, then we'll also create a
        // resolver to sweep our commitment output (but only if it wasn't
        // trimmed).
        if contractResolutions.CommitResolution != nil {
                resolver := newCommitSweepResolver(
                        *contractResolutions.CommitResolution, height,
                        c.cfg.ChanPoint, resolverCfg,
                )
                if chanState != nil {
                        resolver.SupplementState(chanState)
                }
                htlcResolvers = append(htlcResolvers, resolver)
        }

        return htlcResolvers, nil
}

// replaceResolver replaces a in the list of active resolvers. If the resolver
// to be replaced is not found, it returns an error.
func (c *ChannelArbitrator) replaceResolver(oldResolver,
        newResolver ContractResolver) error {

        c.activeResolversLock.Lock()
        defer c.activeResolversLock.Unlock()

        oldKey := oldResolver.ResolverKey()
        for i, r := range c.activeResolvers {
                if bytes.Equal(r.ResolverKey(), oldKey) {
                        c.activeResolvers[i] = newResolver
                        return nil
                }
        }

        return errors.New("resolver to be replaced not found")
}

// resolveContract is a goroutine tasked with fully resolving an unresolved
// contract. Either the initial contract will be resolved after a single step,
// or the contract will itself create another contract to be resolved. In
// either case, one the contract has been fully resolved, we'll signal back to
// the main goroutine so it can properly keep track of the set of unresolved
// contracts.
//
// NOTE: This MUST be run as a goroutine.
func (c *ChannelArbitrator) resolveContract(currentContract ContractResolver) {
        defer c.wg.Done()

        log.Debugf("ChannelArbitrator(%v): attempting to resolve %T",
                c.cfg.ChanPoint, currentContract)

        // Until the contract is fully resolved, we'll continue to iteratively
        // resolve the contract one step at a time.
        for !currentContract.IsResolved() {
                log.Debugf("ChannelArbitrator(%v): contract %T not yet resolved",
                        c.cfg.ChanPoint, currentContract)

                select {

                // If we've been signalled to quit, then we'll exit early.
                case <-c.quit:
                        return

                default:
                        // Otherwise, we'll attempt to resolve the current
                        // contract.
                        nextContract, err := currentContract.Resolve()
                        if err != nil {
                                if err == errResolverShuttingDown {
                                        return
                                }

                                log.Errorf("ChannelArbitrator(%v): unable to "+
                                        "progress %T: %v",
                                        c.cfg.ChanPoint, currentContract, err)
                                return
                        }

                        switch {
                        // If this contract produced another, then this means
                        // the current contract was only able to be partially
                        // resolved in this step. So we'll do a contract swap
                        // within our logs: the new contract will take the
                        // place of the old one.
                        case nextContract != nil:
                                log.Debugf("ChannelArbitrator(%v): swapping "+
                                        "out contract %T for %T ",
                                        c.cfg.ChanPoint, currentContract,
                                        nextContract)

                                // Swap contract in log.
                                err := c.log.SwapContract(
                                        currentContract, nextContract,
                                )
                                if err != nil {
                                        log.Errorf("unable to add recurse "+
                                                "contract: %v", err)
                                }

                                // Swap contract in resolvers list. This is to
                                // make sure that reports are queried from the
                                // new resolver.
                                err = c.replaceResolver(
                                        currentContract, nextContract,
                                )
                                if err != nil {
                                        log.Errorf("unable to replace "+
                                                "contract: %v", err)
                                }

                                // As this contract produced another, we'll
                                // re-assign, so we can continue our resolution
                                // loop.
                                currentContract = nextContract

                                // Launch the new contract.
                                err = currentContract.Launch()
                                if err != nil {
                                        log.Errorf("Failed to launch %T: %v",
                                                currentContract, err)
                                }

                        // If this contract is actually fully resolved, then
                        // we'll mark it as such within the database.
                        case currentContract.IsResolved():
                                log.Debugf("ChannelArbitrator(%v): marking "+
                                        "contract %T fully resolved",
                                        c.cfg.ChanPoint, currentContract)

                                err := c.log.ResolveContract(currentContract)
                                if err != nil {
                                        log.Errorf("unable to resolve contract: %v",
                                                err)
                                }

                                // Now that the contract has been resolved,
                                // well signal to the main goroutine.
                                select {
                                case c.resolutionSignal <- struct{}{}:
                                case <-c.quit:
                                        return
                                }
                        }

                }
        }
}

// signalUpdateMsg is a struct that carries fresh signals to the
// ChannelArbitrator. We need to receive a message like this each time the
// channel becomes active, as it's internal state may change.
type signalUpdateMsg struct {
        // newSignals is the set of new active signals to be sent to the
        // arbitrator.
        newSignals *ContractSignals

        // doneChan is a channel that will be closed on the arbitrator has
        // attached the new signals.
        doneChan chan struct{}
}

// UpdateContractSignals updates the set of signals the ChannelArbitrator needs
// to receive from a channel in real-time in order to keep in sync with the
// latest state of the contract.
func (c *ChannelArbitrator) UpdateContractSignals(newSignals *ContractSignals) {
        done := make(chan struct{})

        select {
        case c.signalUpdates <- &signalUpdateMsg{
                newSignals: newSignals,
                doneChan:   done,
        }:
        case <-c.quit:
        }

        select {
        case <-done:
        case <-c.quit:
        }
}

// notifyContractUpdate updates the ChannelArbitrator's unmerged mappings such
// that it can later be merged with activeHTLCs when calling
// checkLocalChainActions or sweepAnchors. These are the only two places that
// activeHTLCs is used.
func (c *ChannelArbitrator) notifyContractUpdate(upd *ContractUpdate) {
        c.unmergedMtx.Lock()
        defer c.unmergedMtx.Unlock()

        // Update the mapping.
        c.unmergedSet[upd.HtlcKey] = newHtlcSet(upd.Htlcs)

        log.Tracef("ChannelArbitrator(%v): fresh set of htlcs=%v",
                c.cfg.ChanPoint, lnutils.SpewLogClosure(upd))
}

// updateActiveHTLCs merges the unmerged set of HTLCs from the link with
// activeHTLCs.
func (c *ChannelArbitrator) updateActiveHTLCs() {
        c.unmergedMtx.RLock()
        defer c.unmergedMtx.RUnlock()

        // Update the mapping.
        c.activeHTLCs[LocalHtlcSet] = c.unmergedSet[LocalHtlcSet]
        c.activeHTLCs[RemoteHtlcSet] = c.unmergedSet[RemoteHtlcSet]

        // If the pending set exists, update that as well.
        if _, ok := c.unmergedSet[RemotePendingHtlcSet]; ok {
                pendingSet := c.unmergedSet[RemotePendingHtlcSet]
                c.activeHTLCs[RemotePendingHtlcSet] = pendingSet
        }
}

// channelAttendant is the primary goroutine that acts at the judicial
// arbitrator between our channel state, the remote channel peer, and the
// blockchain (Our judge). This goroutine will ensure that we faithfully execute
// all clauses of our contract in the case that we need to go on-chain for a
// dispute. Currently, two such conditions warrant our intervention: when an
// outgoing HTLC is about to timeout, and when we know the pre-image for an
// incoming HTLC, but it hasn't yet been settled off-chain. In these cases,
// we'll: broadcast our commitment, cancel/settle any HTLC's backwards after
// sufficient confirmation, and finally send our set of outputs to the UTXO
// Nursery for incubation, and ultimate sweeping.
//
// NOTE: This MUST be run as a goroutine.
//
//nolint:funlen
func (c *ChannelArbitrator) channelAttendant(bestHeight int32,
        commitSet *CommitSet) {

        // TODO(roasbeef): tell top chain arb we're done
        defer func() {
                c.wg.Done()
        }()

        err := c.progressStateMachineAfterRestart(bestHeight, commitSet)
        if err != nil {
                // In case of an error, we return early but we do not shutdown
                // LND, because there might be other channels that still can be
                // resolved and we don't want to interfere with that.
                // We continue to run the channel attendant in case the channel
                // closes via other means for example the remote pary force
                // closes the channel. So we log the error and continue.
                log.Errorf("Unable to progress state machine after "+
                        "restart: %v", err)
        }

        for {
                select {

                // A new block has arrived, we'll examine all the active HTLC's
                // to see if any of them have expired, and also update our
                // track of the best current height.
                case beat := <-c.BlockbeatChan:
                        bestHeight = beat.Height()

                        log.Debugf("ChannelArbitrator(%v): new block height=%v",
                                c.cfg.ChanPoint, bestHeight)

                        err := c.handleBlockbeat(beat)
                        if err != nil {
                                log.Errorf("Handle block=%v got err: %v",
                                        bestHeight, err)
                        }

                        // If as a result of this trigger, the contract is
                        // fully resolved, then well exit.
                        if c.state == StateFullyResolved {
                                return
                        }

                // A new signal update was just sent. This indicates that the
                // channel under watch is now live, and may modify its internal
                // state, so we'll get the most up to date signals to we can
                // properly do our job.
                case signalUpdate := <-c.signalUpdates:
                        log.Tracef("ChannelArbitrator(%v): got new signal "+
                                "update!", c.cfg.ChanPoint)

                        // We'll update the ShortChannelID.
                        c.cfg.ShortChanID = signalUpdate.newSignals.ShortChanID

                        // Now that the signal has been updated, we'll now
                        // close the done channel to signal to the caller we've
                        // registered the new ShortChannelID.
                        close(signalUpdate.doneChan)

                // We've cooperatively closed the channel, so we're no longer
                // needed. We'll mark the channel as resolved and exit.
                case closeInfo := <-c.cfg.ChainEvents.CooperativeClosure:
                        log.Infof("ChannelArbitrator(%v) marking channel "+
                                "cooperatively closed", c.cfg.ChanPoint)

                        err := c.cfg.MarkChannelClosed(
                                closeInfo.ChannelCloseSummary,
                                channeldb.ChanStatusCoopBroadcasted,
                        )
                        if err != nil {
                                log.Errorf("Unable to mark channel closed: "+
                                        "%v", err)
                                return
                        }

                        // We'll now advance our state machine until it reaches
                        // a terminal state, and the channel is marked resolved.
                        _, _, err = c.advanceState(
                                closeInfo.CloseHeight, coopCloseTrigger, nil,
                        )
                        if err != nil {
                                log.Errorf("Unable to advance state: %v", err)
                                return
                        }

                // We have broadcasted our commitment, and it is now confirmed
                // on-chain.
                case closeInfo := <-c.cfg.ChainEvents.LocalUnilateralClosure:
                        if c.state != StateCommitmentBroadcasted {
                                log.Errorf("ChannelArbitrator(%v): unexpected "+
                                        "local on-chain channel close",
                                        c.cfg.ChanPoint)
                        }

                        closeTx := closeInfo.CloseTx

                        resolutions, err := closeInfo.ContractResolutions.
                                UnwrapOrErr(
                                        fmt.Errorf("resolutions not found"),
                                )
                        if err != nil {
                                log.Errorf("ChannelArbitrator(%v): unable to "+
                                        "get resolutions: %v", c.cfg.ChanPoint,
                                        err)

                                return
                        }

                        // We make sure that the htlc resolutions are present
                        // otherwise we would panic dereferencing the pointer.
                        //
                        // TODO(ziggie): Refactor ContractResolutions to use
                        // options.
                        if resolutions.HtlcResolutions == nil {
                                log.Errorf("ChannelArbitrator(%v): htlc "+
                                        "resolutions not found",
                                        c.cfg.ChanPoint)

                                return
                        }

                        log.Infof("ChannelArbitrator(%v): local force close "+
                                "tx=%v confirmed", c.cfg.ChanPoint,
                                closeTx.TxHash())

                        contractRes := &ContractResolutions{
                                CommitHash:       closeTx.TxHash(),
                                CommitResolution: resolutions.CommitResolution,
                                HtlcResolutions:  *resolutions.HtlcResolutions,
                                AnchorResolution: resolutions.AnchorResolution,
                        }

                        // When processing a unilateral close event, we'll
                        // transition to the ContractClosed state. We'll log
                        // out the set of resolutions such that they are
                        // available to fetch in that state, we'll also write
                        // the commit set so we can reconstruct our chain
                        // actions on restart.
                        err = c.log.LogContractResolutions(contractRes)
                        if err != nil {
                                log.Errorf("Unable to write resolutions: %v",
                                        err)
                                return
                        }
                        err = c.log.InsertConfirmedCommitSet(
                                &closeInfo.CommitSet,
                        )
                        if err != nil {
                                log.Errorf("Unable to write commit set: %v",
                                        err)
                                return
                        }

                        // After the set of resolutions are successfully
                        // logged, we can safely close the channel. After this
                        // succeeds we won't be getting chain events anymore,
                        // so we must make sure we can recover on restart after
                        // it is marked closed. If the next state transition
                        // fails, we'll start up in the prior state again, and
                        // we won't be longer getting chain events. In this
                        // case we must manually re-trigger the state
                        // transition into StateContractClosed based on the
                        // close status of the channel.
                        err = c.cfg.MarkChannelClosed(
                                closeInfo.ChannelCloseSummary,
                                channeldb.ChanStatusLocalCloseInitiator,
                        )
                        if err != nil {
                                log.Errorf("Unable to mark "+
                                        "channel closed: %v", err)
                                return
                        }

                        // We'll now advance our state machine until it reaches
                        // a terminal state.
                        _, _, err = c.advanceState(
                                uint32(closeInfo.SpendingHeight),
                                localCloseTrigger, &closeInfo.CommitSet,
                        )
                        if err != nil {
                                log.Errorf("Unable to advance state: %v", err)
                        }

                // The remote party has broadcast the commitment on-chain.
                // We'll examine our state to determine if we need to act at
                // all.
                case uniClosure := <-c.cfg.ChainEvents.RemoteUnilateralClosure:
                        log.Infof("ChannelArbitrator(%v): remote party has "+
                                "closed channel out on-chain", c.cfg.ChanPoint)

                        // If we don't have a self output, and there are no
                        // active HTLC's, then we can immediately mark the
                        // contract as fully resolved and exit.
                        contractRes := &ContractResolutions{
                                CommitHash:       *uniClosure.SpenderTxHash,
                                CommitResolution: uniClosure.CommitResolution,
                                HtlcResolutions:  *uniClosure.HtlcResolutions,
                                AnchorResolution: uniClosure.AnchorResolution,
                        }

                        // When processing a unilateral close event, we'll
                        // transition to the ContractClosed state. We'll log
                        // out the set of resolutions such that they are
                        // available to fetch in that state, we'll also write
                        // the commit set so we can reconstruct our chain
                        // actions on restart.
                        err := c.log.LogContractResolutions(contractRes)
                        if err != nil {
                                log.Errorf("Unable to write resolutions: %v",
                                        err)
                                return
                        }
                        err = c.log.InsertConfirmedCommitSet(
                                &uniClosure.CommitSet,
                        )
                        if err != nil {
                                log.Errorf("Unable to write commit set: %v",
                                        err)
                                return
                        }

                        // After the set of resolutions are successfully
                        // logged, we can safely close the channel. After this
                        // succeeds we won't be getting chain events anymore,
                        // so we must make sure we can recover on restart after
                        // it is marked closed. If the next state transition
                        // fails, we'll start up in the prior state again, and
                        // we won't be longer getting chain events. In this
                        // case we must manually re-trigger the state
                        // transition into StateContractClosed based on the
                        // close status of the channel.
                        closeSummary := &uniClosure.ChannelCloseSummary
                        err = c.cfg.MarkChannelClosed(
                                closeSummary,
                                channeldb.ChanStatusRemoteCloseInitiator,
                        )
                        if err != nil {
                                log.Errorf("Unable to mark channel closed: %v",
                                        err)
                                return
                        }

                        // We'll now advance our state machine until it reaches
                        // a terminal state.
                        _, _, err = c.advanceState(
                                uint32(uniClosure.SpendingHeight),
                                remoteCloseTrigger, &uniClosure.CommitSet,
                        )
                        if err != nil {
                                log.Errorf("Unable to advance state: %v", err)
                        }

                // The remote has breached the channel. As this is handled by
                // the ChainWatcher and BreachArbitrator, we don't have to do
                // anything in particular, so just advance our state and
                // gracefully exit.
                case breachInfo := <-c.cfg.ChainEvents.ContractBreach:
                        log.Infof("ChannelArbitrator(%v): remote party has "+
                                "breached channel!", c.cfg.ChanPoint)

                        // In the breach case, we'll only have anchor and
                        // breach resolutions.
                        contractRes := &ContractResolutions{
                                CommitHash:       breachInfo.CommitHash,
                                BreachResolution: breachInfo.BreachResolution,
                                AnchorResolution: breachInfo.AnchorResolution,
                        }

                        // We'll transition to the ContractClosed state and log
                        // the set of resolutions such that they can be turned
                        // into resolvers later on. We'll also insert the
                        // CommitSet of the latest set of commitments.
                        err := c.log.LogContractResolutions(contractRes)
                        if err != nil {
                                log.Errorf("Unable to write resolutions: %v",
                                        err)
                                return
                        }
                        err = c.log.InsertConfirmedCommitSet(
                                &breachInfo.CommitSet,
                        )
                        if err != nil {
                                log.Errorf("Unable to write commit set: %v",
                                        err)
                                return
                        }

                        // The channel is finally marked pending closed here as
                        // the BreachArbitrator and channel arbitrator have
                        // persisted the relevant states.
                        closeSummary := &breachInfo.CloseSummary
                        err = c.cfg.MarkChannelClosed(
                                closeSummary,
                                channeldb.ChanStatusRemoteCloseInitiator,
                        )
                        if err != nil {
                                log.Errorf("Unable to mark channel closed: %v",
                                        err)
                                return
                        }

                        log.Infof("Breached channel=%v marked pending-closed",
                                breachInfo.BreachResolution.FundingOutPoint)

                        // We'll advance our state machine until it reaches a
                        // terminal state.
                        _, _, err = c.advanceState(
                                uint32(bestHeight), breachCloseTrigger,
                                &breachInfo.CommitSet,
                        )
                        if err != nil {
                                log.Errorf("Unable to advance state: %v", err)
                        }

                // A new contract has just been resolved, we'll now check our
                // log to see if all contracts have been resolved. If so, then
                // we can exit as the contract is fully resolved.
                case <-c.resolutionSignal:
                        log.Infof("ChannelArbitrator(%v): a contract has been "+
                                "fully resolved!", c.cfg.ChanPoint)

                        nextState, _, err := c.advanceState(
                                uint32(bestHeight), chainTrigger, nil,
                        )
                        if err != nil {
                                log.Errorf("Unable to advance state: %v", err)
                        }

                        // If we don't have anything further to do after
                        // advancing our state, then we'll exit.
                        if nextState == StateFullyResolved {
                                log.Infof("ChannelArbitrator(%v): all "+
                                        "contracts fully resolved, exiting",
                                        c.cfg.ChanPoint)

                                return
                        }

                // We've just received a request to forcibly close out the
                // channel. We'll
                case closeReq := <-c.forceCloseReqs:
                        log.Infof("ChannelArbitrator(%v): received force "+
                                "close request", c.cfg.ChanPoint)

                        if c.state != StateDefault {
                                select {
                                case closeReq.closeTx <- nil:
                                case <-c.quit:
                                }

                                select {
                                case closeReq.errResp <- errAlreadyForceClosed:
                                case <-c.quit:
                                }

                                continue
                        }

                        nextState, closeTx, err := c.advanceState(
                                uint32(bestHeight), userTrigger, nil,
                        )
                        if err != nil {
                                log.Errorf("Unable to advance state: %v", err)
                        }

                        select {
                        case closeReq.closeTx <- closeTx:
                        case <-c.quit:
                                return
                        }

                        select {
                        case closeReq.errResp <- err:
                        case <-c.quit:
                                return
                        }

                        // If we don't have anything further to do after
                        // advancing our state, then we'll exit.
                        if nextState == StateFullyResolved {
                                log.Infof("ChannelArbitrator(%v): all "+
                                        "contracts resolved, exiting",
                                        c.cfg.ChanPoint)
                                return
                        }

                case <-c.quit:
                        return
                }
        }
}

// handleBlockbeat processes a newly received blockbeat by advancing the
// arbitrator's internal state using the received block height.
func (c *ChannelArbitrator) handleBlockbeat(beat chainio.Blockbeat) error {
        // Notify we've processed the block.
        defer c.NotifyBlockProcessed(beat, nil)

        // Try to advance the state if we are in StateDefault.
        if c.state == StateDefault {
                // Now that a new block has arrived, we'll attempt to advance
                // our state forward.
                _, _, err := c.advanceState(
                        uint32(beat.Height()), chainTrigger, nil,
                )
                if err != nil {
                        return fmt.Errorf("unable to advance state: %w", err)
                }
        }

        // Launch all active resolvers when a new blockbeat is received.
        c.launchResolvers()

        return nil
}

// Name returns a human-readable string for this subsystem.
//
// NOTE: Part of chainio.Consumer interface.
func (c *ChannelArbitrator) Name() string {
        return fmt.Sprintf("ChannelArbitrator(%v)", c.cfg.ChanPoint)
}

// checkLegacyBreach returns StateFullyResolved if the channel was closed with
// a breach transaction before the channel arbitrator launched its own breach
// resolver. StateContractClosed is returned if this is a modern breach close
// with a breach resolver. StateError is returned if the log lookup failed.
func (c *ChannelArbitrator) checkLegacyBreach() (ArbitratorState, error) {
        // A previous version of the channel arbitrator would make the breach
        // close skip to StateFullyResolved. If there are no contract
        // resolutions in the bolt arbitrator log, then this is an older breach
        // close. Otherwise, if there are resolutions, the state should advance
        // to StateContractClosed.
        _, err := c.log.FetchContractResolutions()
        if err == errNoResolutions {
                // This is an older breach close still in the database.
                return StateFullyResolved, nil
        } else if err != nil {
                return StateError, err
        }

        // This is a modern breach close with resolvers.
        return StateContractClosed, nil
}

// sweepRequest wraps the arguments used when calling `SweepInput`.
type sweepRequest struct {
        // input is the input to be swept.
        input input.Input

        // params holds the sweeping parameters.
        params sweep.Params
}

// createSweepRequest creates an anchor sweeping request for a particular
// version (local/remote/remote pending) of the commitment.
func (c *ChannelArbitrator) createSweepRequest(
        anchor *lnwallet.AnchorResolution, htlcs htlcSet, anchorPath string,
        heightHint uint32) (sweepRequest, error) {

        // Use the chan id as the exclusive group. This prevents any of the
        // anchors from being batched together.
        exclusiveGroup := c.cfg.ShortChanID.ToUint64()

        // Find the deadline for this specific anchor.
        deadline, value, err := c.findCommitmentDeadlineAndValue(
                heightHint, htlcs,
        )
        if err != nil {
                return sweepRequest{}, err
        }

        // If we cannot find a deadline, it means there's no HTLCs at stake,
        // which means we can relax our anchor sweeping conditions as we don't
        // have any time sensitive outputs to sweep. However we need to
        // register the anchor output with the sweeper so we are later able to
        // bump the close fee.
        if deadline.IsNone() {
                log.Infof("ChannelArbitrator(%v): no HTLCs at stake, "+
                        "sweeping anchor with default deadline",
                        c.cfg.ChanPoint)
        }

        witnessType := input.CommitmentAnchor

        // For taproot channels, we need to use the proper witness type.
        if txscript.IsPayToTaproot(
                anchor.AnchorSignDescriptor.Output.PkScript,
        ) {

                witnessType = input.TaprootAnchorSweepSpend
        }

        // Prepare anchor output for sweeping.
        anchorInput := input.MakeBaseInput(
                &anchor.CommitAnchor,
                witnessType,
                &anchor.AnchorSignDescriptor,
                heightHint,
                &input.TxInfo{
                        Fee:    anchor.CommitFee,
                        Weight: anchor.CommitWeight,
                },
        )

        // If we have a deadline, we'll use it to calculate the deadline
        // height, otherwise default to none.
        deadlineDesc := "None"
        deadlineHeight := fn.MapOption(func(d int32) int32 {
                deadlineDesc = fmt.Sprintf("%d", d)

                return d + int32(heightHint)
        })(deadline)

        // Calculate the budget based on the value under protection, which is
        // the sum of all HTLCs on this commitment subtracted by their budgets.
        // The anchor output in itself has a small output value of 330 sats so
        // we also include it in the budget to pay for the cpfp transaction.
        budget := calculateBudget(
                value, c.cfg.Budget.AnchorCPFPRatio, c.cfg.Budget.AnchorCPFP,
        ) + AnchorOutputValue

        log.Infof("ChannelArbitrator(%v): offering anchor from %s commitment "+
                "%v to sweeper with deadline=%v, budget=%v", c.cfg.ChanPoint,
                anchorPath, anchor.CommitAnchor, deadlineDesc, budget)

        // Sweep anchor output with a confirmation target fee preference.
        // Because this is a cpfp-operation, the anchor will only be attempted
        // to sweep when the current fee estimate for the confirmation target
        // exceeds the commit fee rate.
        return sweepRequest{
                input: &anchorInput,
                params: sweep.Params{
                        ExclusiveGroup: &exclusiveGroup,
                        Budget:         budget,
                        DeadlineHeight: deadlineHeight,
                },
        }, nil
}

// prepareAnchorSweeps creates a list of requests to be used by the sweeper for
// all possible commitment versions.
func (c *ChannelArbitrator) prepareAnchorSweeps(heightHint uint32,
        anchors *lnwallet.AnchorResolutions) ([]sweepRequest, error) {

        // requests holds all the possible anchor sweep requests. We can have
        // up to 3 different versions of commitments (local/remote/remote
        // dangling) to be CPFPed by the anchors.
        requests := make([]sweepRequest, 0, 3)

        // remotePendingReq holds the request for sweeping the anchor output on
        // the remote pending commitment. It's only set when there's an actual
        // pending remote commitment and it's used to decide whether we need to
        // update the fee budget when sweeping the anchor output on the local
        // commitment.
        remotePendingReq := fn.None[sweepRequest]()

        // First we check on the remote pending commitment and optionally
        // create an anchor sweeping request.
        htlcs, ok := c.activeHTLCs[RemotePendingHtlcSet]
        if ok && anchors.RemotePending != nil {
                req, err := c.createSweepRequest(
                        anchors.RemotePending, htlcs, "remote pending",
                        heightHint,
                )
                if err != nil {
                        return nil, err
                }

                // Save the request.
                requests = append(requests, req)

                // Set the optional variable.
                remotePendingReq = fn.Some(req)
        }

        // Check the local commitment and optionally create an anchor sweeping
        // request. The params used in this request will be influenced by the
        // anchor sweeping request made from the pending remote commitment.
        htlcs, ok = c.activeHTLCs[LocalHtlcSet]
        if ok && anchors.Local != nil {
                req, err := c.createSweepRequest(
                        anchors.Local, htlcs, "local", heightHint,
                )
                if err != nil {
                        return nil, err
                }

                // If there's an anchor sweeping request from the pending
                // remote commitment, we will compare its budget against the
                // budget used here and choose the params that has a larger
                // budget. The deadline when choosing the remote pending budget
                // instead of the local one will always be earlier or equal to
                // the local deadline because outgoing HTLCs are resolved on
                // the local commitment first before they are removed from the
                // remote one.
                remotePendingReq.WhenSome(func(s sweepRequest) {
                        if s.params.Budget <= req.params.Budget {
                                return
                        }

                        log.Infof("ChannelArbitrator(%v): replaced local "+
                                "anchor(%v) sweep params with pending remote "+
                                "anchor sweep params, \nold:[%v], \nnew:[%v]",
                                c.cfg.ChanPoint, anchors.Local.CommitAnchor,
                                req.params, s.params)

                        req.params = s.params
                })

                // Save the request.
                requests = append(requests, req)
        }

        // Check the remote commitment and create an anchor sweeping request if
        // needed.
        htlcs, ok = c.activeHTLCs[RemoteHtlcSet]
        if ok && anchors.Remote != nil {
                req, err := c.createSweepRequest(
                        anchors.Remote, htlcs, "remote", heightHint,
                )
                if err != nil {
                        return nil, err
                }

                requests = append(requests, req)
        }

        return requests, nil
}

// failIncomingDust resolves the incoming dust HTLCs because they do not have
// an output on the commitment transaction and cannot be resolved onchain. We
// mark them as failed here.
func (c *ChannelArbitrator) failIncomingDust(
        incomingDustHTLCs []channeldb.HTLC) error {

        for _, htlc := range incomingDustHTLCs {
                if !htlc.Incoming || htlc.OutputIndex >= 0 {
                        return fmt.Errorf("htlc with index %v is not incoming "+
                                "dust", htlc.OutputIndex)
                }

                key := models.CircuitKey{
                        ChanID: c.cfg.ShortChanID,
                        HtlcID: htlc.HtlcIndex,
                }

                // Mark this dust htlc as final failed.
                chainArbCfg := c.cfg.ChainArbitratorConfig
                err := chainArbCfg.PutFinalHtlcOutcome(
                        key.ChanID, key.HtlcID, false,
                )
                if err != nil {
                        return err
                }

                // Send notification.
                chainArbCfg.HtlcNotifier.NotifyFinalHtlcEvent(
                        key,
                        channeldb.FinalHtlcInfo{
                                Settled:  false,
                                Offchain: false,
                        },
                )
        }

        return nil
}

// abandonForwards cancels back the incoming HTLCs for their corresponding
// outgoing HTLCs. We use a set here to avoid sending duplicate failure messages
// for the same HTLC. This also needs to be done for locally initiated outgoing
// HTLCs they are special cased in the switch.
func (c *ChannelArbitrator) abandonForwards(htlcs fn.Set[uint64]) error {
        log.Debugf("ChannelArbitrator(%v): cancelling back %v incoming "+
                "HTLC(s)", c.cfg.ChanPoint,
                len(htlcs))

        msgsToSend := make([]ResolutionMsg, 0, len(htlcs))
        failureMsg := &lnwire.FailPermanentChannelFailure{}

        for idx := range htlcs {
                failMsg := ResolutionMsg{
                        SourceChan: c.cfg.ShortChanID,
                        HtlcIndex:  idx,
                        Failure:    failureMsg,
                }

                msgsToSend = append(msgsToSend, failMsg)
        }

        // Send the msges to the switch, if there are any.
        if len(msgsToSend) == 0 {
                return nil
        }

        log.Debugf("ChannelArbitrator(%v): sending resolution message=%v",
                c.cfg.ChanPoint, lnutils.SpewLogClosure(msgsToSend))

        err := c.cfg.DeliverResolutionMsg(msgsToSend...)
        if err != nil {
                log.Errorf("Unable to send resolution msges to switch: %v", err)
                return err
        }

        return nil
}

lightningnetwork / lnd / 12343072627

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