add package sweeper

The package contains logic of determining sweep's conf target and fee rate.

Author: starius

sweeper/log.go

@@ -0,0 +1,26 @@
+package sweeper
+
+import (
+	"github.com/btcsuite/btclog"
+	"github.com/lightningnetwork/lnd/build"
+)
+
+// Subsystem defines the sub system name of this package.
+const Subsystem = "SWPR"
+
+// log is a logger that is initialized with no output filters. This means the
+// package will not perform any logging by default until the caller requests
+// it.
+var log btclog.Logger
+
+// The default amount of logging is none.
+func init() {
+	UseLogger(build.NewSubLogger(Subsystem, nil))
+}
+
+// UseLogger uses a specified Logger to output package logging info. This
+// should be used in preference to SetLogWriter if the caller is also using
+// btclog.
+func UseLogger(logger btclog.Logger) {
+	log = logger
+}

sweeper/sweep_fee_provider.go

@@ -0,0 +1,266 @@
+package sweeper
+
+import (
+	"context"
+	"errors"
+
+	"github.com/btcsuite/btcd/btcutil"
+	"github.com/lightningnetwork/lnd/input"
+	"github.com/lightningnetwork/lnd/lntypes"
+	"github.com/lightningnetwork/lnd/lnwallet/chainfee"
+)
+
+// Sweeper provides fee, fee rate and weight by confTarget.
+type Sweeper interface {
+	// GetSweepFeeDetails calculates the required tx fee to spend to
+	// destAddr. It takes a function that is expected to add the weight of
+	// the input to the weight estimator. It also takes a label used for
+	// logging. It returns also the fee rate and transaction weight.
+	GetSweepFeeDetails(ctx context.Context,
+		addInputEstimate func(*input.TxWeightEstimator) error,
+		destAddr btcutil.Address, sweepConfTarget int32, label string) (
+		btcutil.Amount, chainfee.SatPerKWeight, lntypes.WeightUnit,
+		error)
+}
+
+// SweepFeeProvider provides fee rate and fee for a loop sweep transaction.
+type SweepFeeProvider struct {
+	// Sweeper returns fee rate by confTarget.
+	Sweeper Sweeper
+
+	// DefaultSweepConfTargetDelta defines a safe distance in blocks until
+	// the sweep's expiration height. If the distance is less than or equal
+	// to this value, then more aggressive fee is used to make sure that
+	// HTLC is swept before the sweep expires and the counterparty can
+	// collect refund.
+	DefaultSweepConfTargetDelta int32
+
+	// UrgentSweepConfTarget is the block confirmation target that is used
+	// for fee calculation of the on-chain htlc sweep if we are close to
+	// expiry.
+	UrgentSweepConfTarget int32
+
+	// DefaultSweepConfTargetFactor is the default factor by which the fee
+	// calculation increases the calculated fee.
+	DefaultSweepConfTargetFactor float32
+
+	// UrgentSweepConfTargetFactor is the factor by which the fee
+	// calculation increases the fee which resulted from the
+	// UrgentSweepConfTarget confirmation target. This aims to ensure that
+	// the sweep transaction will be confirmed asap in times when there is
+	// elevated block space demand in the top fee band.
+	UrgentSweepConfTargetFactor float32
+
+	// HighPrioSweepAmount is a threshold at which a sweep is prioritized to
+	// be swept with a fee that is related to its size. The fee amount is
+	// determined by HighPrioFeePPM.
+	HighPrioSweepAmount btcutil.Amount
+
+	// HighPrioFeePPM expresses the fraction of the sweep amount that is
+	// paid towards sweeping fees. This fee is only supposed to be paid for
+	// sweeps greater or equal the size of HighPrioSweepAmount to expedite
+	// the availability of on-chain funds to generate revenue on loop-out
+	// operations.
+	// Example: Given HighPrioSweepAmount is 1.2 BTC, sweep amount is
+	// 1.3 BTC and HighPrioFeePPM is 100ppm, then we allocate 13k for the
+	// sweep fee, but at most UrgentSweepConfTarget fees.
+	HighPrioFeePPM int32
+}
+
+// getSweepConfTarget calculates a dynamic block confirmation target for the
+// loop-in sweep transaction.
+func (p *SweepFeeProvider) getSweepConfTarget(cltvExpiry, height int32) (int32,
+	float32) {
+
+	// blocksUntilExpiry is the number of blocks until the htlc timeout path
+	// opens for the client to sweep.
+	blocksUntilExpiry := cltvExpiry - height
+
+	// As we are approaching the expiry of the on-chain htlc we reduce the
+	// block confirmation target to the number of blocks until expiry. If we
+	// are within the DefaultSweepConfTargetDelta we return
+	// UrgentSweepConfTarget and an adjusted fee factor.
+	switch {
+	case blocksUntilExpiry > p.DefaultSweepConfTargetDelta:
+		return blocksUntilExpiry, p.DefaultSweepConfTargetFactor
+
+	// If we still have more than UrgentSweepConfTarget blocks to go,
+	// use UrgentSweepConfTarget.
+	case blocksUntilExpiry > p.UrgentSweepConfTarget:
+		return p.UrgentSweepConfTarget, p.UrgentSweepConfTargetFactor
+
+	// If we are below UrgentSweepConfTarget, but still have more than 1
+	// block to go, use the number of remaining blocks as target.
+	case blocksUntilExpiry >= 1:
+		return blocksUntilExpiry, p.UrgentSweepConfTargetFactor
+
+	// The sweep has expired. Use confTarget=1. We should not be here.
+	default:
+		return 1, p.UrgentSweepConfTargetFactor
+	}
+}
+
+// getHighPriorityFee returns a sweep amount adjusted sweep fee that does not
+// exceed the fee we assign for sweeps close to expiry.
+func (p *SweepFeeProvider) getHighPriorityFee(ctx context.Context,
+	addInputToEstimator func(e *input.TxWeightEstimator) error,
+	destAddr btcutil.Address, amt btcutil.Amount,
+	baseLabel string) (btcutil.Amount, chainfee.SatPerKWeight,
+	lntypes.WeightUnit, error) {
+
+	log.Infof("High priority sweep amount: %v", amt)
+
+	label := baseLabel + "-urgent"
+
+	urgentConfTargetFee, urgentConfTargetFeeRate, weight, err :=
+		p.Sweeper.GetSweepFeeDetails(
+			ctx, addInputToEstimator, destAddr,
+			p.UrgentSweepConfTarget, label,
+		)
+	if err != nil {
+		log.Warnf("Failed to estimate urgent fee: %v", err)
+
+		return 0, 0, 0, err
+	}
+
+	urgentFee := btcutil.Amount(float32(urgentConfTargetFee) *
+		p.UrgentSweepConfTargetFactor)
+
+	urgentFeeRate := chainfee.SatPerKWeight(
+		float32(urgentConfTargetFeeRate) *
+			p.UrgentSweepConfTargetFactor,
+	)
+	log.Infof("Urgent close to expiry fee: %v, fee rate: %v", urgentFee,
+		urgentFeeRate)
+
+	highPrioFee := btcutil.Amount(
+		float32(amt) / 1_000_000.0 * float32(p.HighPrioFeePPM),
+	)
+	if highPrioFee > urgentFee {
+		log.Infof("High priority fee (%v) exceeding close-to-expiry "+
+			"fee (%v). Using close-to-expiry fee for sweep: %v, "+
+			"fee rate: %v", highPrioFee, urgentFee, urgentFee,
+			urgentFeeRate)
+
+		return urgentFee, urgentFeeRate, weight, nil
+	}
+
+	// Find the fee rate for size-relative high priority fee from weight.
+	highPrioFeeRate := chainfee.NewSatPerKWeight(highPrioFee, weight)
+
+	log.Infof("Applying size-relative high priority fee: %v, "+
+		"fee rate: %v", highPrioFee, highPrioFeeRate)
+
+	return highPrioFee, highPrioFeeRate, weight, nil
+}
+
+// SweepFeeRate calculates sweep's confTarget and fee in sats.
+// It takes high priority case into account.
+func (p *SweepFeeProvider) SweepFeeRate(ctx context.Context, amt btcutil.Amount,
+	addInputToEstimator func(e *input.TxWeightEstimator) error,
+	destAddr btcutil.Address, cltvExpiry, height int32,
+	label string) (int32, btcutil.Amount, chainfee.SatPerKWeight,
+	lntypes.WeightUnit, error) {
+
+	// Make sure all the numeric fields of the struct are filled.
+	// If a new field is added, old code might not fill it.
+	if err := p.Validate(); err != nil {
+		return 0, 0, 0, 0, err
+	}
+
+	// Get the dynamic sweep confirmation target
+	confTarget, feeFactor := p.getSweepConfTarget(cltvExpiry, height)
+
+	// Make sure fee factor is sane.
+	if feeFactor == 0 {
+		return 0, 0, 0, 0, errors.New("fee factor is 0")
+	}
+
+	var (
+		fee     btcutil.Amount
+		feeRate chainfee.SatPerKWeight
+		weight  lntypes.WeightUnit
+		err     error
+	)
+
+	// If the sweep has significant economical size we apply a size-relative
+	// fee unless the sweep is close to expiry which is reflected in the
+	// UrgentSweepConfTarget.
+	if amt >= p.HighPrioSweepAmount &&
+		confTarget > p.UrgentSweepConfTarget {
+
+		fee, feeRate, weight, err = p.getHighPriorityFee(
+			ctx, addInputToEstimator, destAddr, amt, label,
+		)
+		if err != nil {
+			return 0, 0, 0, 0, err
+		}
+		// FIXME: confTarget variable is irrelevant by this point, but
+		// it is returned and used for logging. getHighPriorityFee uses
+		// UrgentSweepConfTarget instead of confTarget or uses the
+		// proportional approach to fees, not relying on confTarget.
+	} else {
+		// If the sweep size is below a significant economical size or
+		// the sweep expires in <=UrgentSweepConfTarget blocks, we'll
+		// obtain the fee we should use for the sweep based on our
+		// current best weight estimates as well as the confirmation
+		// target.
+		fee, feeRate, weight, err = p.Sweeper.GetSweepFeeDetails(
+			ctx, addInputToEstimator, destAddr, confTarget, label,
+		)
+		if err != nil {
+			log.Warnf("Failed to estimate fee MuSig2 sweep "+
+				"txn: %v", err)
+
+			return 0, 0, 0, 0, err
+		}
+
+		// Adjust the fee amount and fee rate by the feeFactor which was
+		// determined in the confirmation target calculation.
+		fee = btcutil.Amount(float32(fee) * feeFactor)
+		feeRate = chainfee.SatPerKWeight(float32(feeRate) * feeFactor)
+
+		log.Infof("Using fee for a regular priority sweep: %v, "+
+			"fee rate: %v.", fee, feeRate)
+	}
+
+	// Sanity check. Make sure fee rate is not too low.
+	const minFeeRate = chainfee.AbsoluteFeePerKwFloor
+	if feeRate < minFeeRate {
+		log.Infof("Got too low fee rate for the sweep: %v. "+
+			"Increasing it to %v.", feeRate, minFeeRate)
+
+		feeRate = minFeeRate
+
+		if fee < feeRate.FeeForWeight(weight) {
+			fee = feeRate.FeeForWeight(weight)
+		}
+	}
+
+	return confTarget, fee, feeRate, weight, nil
+}
+
+// Validate checks that all the numeric fields of the struct are filled.
+// If a new field is added, old code might not fill it.
+func (p *SweepFeeProvider) Validate() error {
+	if p.DefaultSweepConfTargetDelta == 0 {
+		return errors.New("DefaultSweepConfTargetDelta is 0")
+	}
+	if p.UrgentSweepConfTarget == 0 {
+		return errors.New("UrgentSweepConfTarget is 0")
+	}
+	if p.DefaultSweepConfTargetFactor == 0 {
+		return errors.New("DefaultSweepConfTargetFactor is 0")
+	}
+	if p.UrgentSweepConfTargetFactor == 0 {
+		return errors.New("UrgentSweepConfTargetFactor is 0")
+	}
+	if p.HighPrioSweepAmount == 0 {
+		return errors.New("HighPrioSweepAmount is 0")
+	}
+	if p.HighPrioFeePPM == 0 {
+		return errors.New("HighPrioFeePPM is 0")
+	}
+
+	return nil
+}