loop/liquidity/fees.go

package liquidity

import (
	"errors"
	"fmt"

	"github.com/btcsuite/btcd/btcutil"
	"github.com/lightninglabs/loop"
	"github.com/lightningnetwork/lnd/lnwallet/chainfee"
)

const (
	// defaultSwapFeePPM is the default limit we place on swap fees,
	// expressed as parts per million of swap volume, 0.5%.
	defaultSwapFeePPM = 5000

	// defaultRoutingFeePPM is the default limit we place on routing fees
	// for the swap invoice, expressed as parts per million of swap volume,
	// 1%.
	defaultRoutingFeePPM = 10000

	// defaultRoutingFeePPM is the default limit we place on routing fees
	// for the prepay invoice, expressed as parts per million of prepay
	// volume, 0.5%.
	defaultPrepayRoutingFeePPM = 5000

	// defaultMaximumMinerFee is the default limit we place on miner fees
	// per swap. We apply a multiplier to this default fee to guard against
	// the case where we have broadcast the preimage, then fees spike and
	// we need to sweep the preimage.
	defaultMaximumMinerFee = 15000 * 100

	// defaultMaximumPrepay is the default limit we place on prepay
	// invoices.
	defaultMaximumPrepay = 30000

	// defaultSweepFeeRateLimit is the default limit we place on estimated
	// sweep fees, (750 * 4 /1000 = 3 sat/vByte).
	defaultSweepFeeRateLimit = chainfee.SatPerKWeight(750)

	// minerMultiplier is a multiplier we use to predict the average chain
	// costs towards miner fees.
	minerMultiplier = 2

	// maxMinerMultiplier is the maximum multiplier we use to scale our
	// miner fee to ensure that we will still be able to complete our swap
	// in the case of a severe fee spike.
	maxMinerMultiplier = 50

	// defaultFeePPM is the default percentage of swap amount that we
	// allocate to fees, 2%.
	defaultFeePPM = 20000
)

var (
	// ErrZeroMinerFee is returned if a zero maximum miner fee is set.
	ErrZeroMinerFee = errors.New("maximum miner fee must be non-zero")

	// ErrZeroSwapFeePPM is returned if a zero server fee ppm is set.
	ErrZeroSwapFeePPM = errors.New("swap fee PPM must be non-zero")

	// ErrZeroRoutingPPM is returned if a zero routing fee ppm is set.
	ErrZeroRoutingPPM = errors.New("routing fee PPM must be non-zero")

	// ErrZeroPrepayPPM is returned if a zero prepay routing fee ppm is set.
	ErrZeroPrepayPPM = errors.New("prepay routing fee PPM must be non-zero")

	// ErrZeroPrepay is returned if a zero maximum prepay is set.
	ErrZeroPrepay = errors.New("maximum prepay must be non-zero")

	// ErrInvalidPPM is returned is the parts per million for a fee rate
	// are invalid.
	ErrInvalidPPM = errors.New("invalid ppm")

	// ErrInvalidSweepFeeRateLimit is returned if an invalid sweep fee limit
	// is set.
	ErrInvalidSweepFeeRateLimit = fmt.Errorf("sweep fee rate limit must "+
		"be > %v sat/vByte",
		satPerKwToSatPerVByte(chainfee.AbsoluteFeePerKwFloor))
)

// Compile time assertion that FeeCategoryLimit implements FeeLimit.
var _ FeeLimit = (*FeeCategoryLimit)(nil)

// FeeCategoryLimit is an implementation of the fee limit interface which sets
// a specific fee limit per fee category.
type FeeCategoryLimit struct {
	// MaximumPrepay is the maximum prepay amount we are willing to pay per
	// swap.
	MaximumPrepay btcutil.Amount

	// MaximumSwapFeePPM is the maximum server fee we are willing to pay per
	// swap expressed as parts per million of the swap volume.
	MaximumSwapFeePPM uint64

	// MaximumRoutingFeePPM is the maximum off-chain routing fee we
	// are willing to pay for off chain invoice routing fees per swap,
	// expressed as parts per million of the swap amount.
	MaximumRoutingFeePPM uint64

	// MaximumPrepayRoutingFeePPM is the maximum off-chain routing fee we
	// are willing to pay for off chain prepay routing fees per swap,
	// expressed as parts per million of the prepay amount.
	MaximumPrepayRoutingFeePPM uint64

	// MaximumMinerFee is the maximum on chain fee that we cap our miner
	// fee at in case where we need to claim on chain because we have
	// revealed the preimage, but fees have spiked. We will not initiate a
	// swap if we estimate that the sweep cost will be above our sweep
	// fee limit, and we use fee estimates at time of sweep to set our fees,
	// so this is just a sane cap covering the special case where we need to
	// sweep during a fee spike.
	MaximumMinerFee btcutil.Amount

	// SweepFeeRateLimit is the limit that we place on our estimated sweep
	// fee. A swap will not be suggested if estimated fee rate is above this
	// value.
	SweepFeeRateLimit chainfee.SatPerKWeight
}

// NewFeeCategoryLimit created a new fee limit struct which sets individual
// fee limits per category.
func NewFeeCategoryLimit(swapFeePPM, routingFeePPM, prepayFeePPM uint64,
	minerFee, prepay btcutil.Amount,
	sweepLimit chainfee.SatPerKWeight) *FeeCategoryLimit {

	return &FeeCategoryLimit{
		MaximumPrepay:              prepay,
		MaximumSwapFeePPM:          swapFeePPM,
		MaximumRoutingFeePPM:       routingFeePPM,
		MaximumPrepayRoutingFeePPM: prepayFeePPM,
		MaximumMinerFee:            minerFee,
		SweepFeeRateLimit:          sweepLimit,
	}
}

func defaultFeeCategoryLimit() *FeeCategoryLimit {
	return NewFeeCategoryLimit(defaultSwapFeePPM, defaultRoutingFeePPM,
		defaultPrepayRoutingFeePPM, defaultMaximumMinerFee,
		defaultMaximumPrepay, defaultSweepFeeRateLimit)
}

// String returns the string representation of our fee category limits.
func (f *FeeCategoryLimit) String() string {
	return fmt.Sprintf("fee categories: maximum prepay: %v, maximum "+
		"miner fee: %v, maximum swap fee ppm: %v, maximum "+
		"routing fee ppm: %v, maximum prepay routing fee ppm: %v,"+
		"sweep fee limit: %v", f.MaximumPrepay, f.MaximumMinerFee,
		f.MaximumSwapFeePPM, f.MaximumRoutingFeePPM,
		f.MaximumPrepayRoutingFeePPM, f.SweepFeeRateLimit,
	)
}

func (f *FeeCategoryLimit) validate() error {
	// Check that we have non-zero fee limits.
	if f.MaximumSwapFeePPM == 0 {
		return ErrZeroSwapFeePPM
	}

	if f.MaximumRoutingFeePPM == 0 {
		return ErrZeroRoutingPPM
	}

	if f.MaximumPrepayRoutingFeePPM == 0 {
		return ErrZeroPrepayPPM
	}

	if f.MaximumPrepay == 0 {
		return ErrZeroPrepay
	}

	if f.MaximumMinerFee == 0 {
		return ErrZeroMinerFee
	}

	// Check that our sweep limit is above our minimum fee rate. We use
	// absolute fee floor rather than kw floor because we will allow users
	// to specify fee rate is sat/vByte and want to allow 1 sat/vByte.
	if f.SweepFeeRateLimit < chainfee.AbsoluteFeePerKwFloor {
		return ErrInvalidSweepFeeRateLimit
	}

	return nil
}

// mayLoopOut checks our estimated loop out sweep fee against our sweep limit.
func (f *FeeCategoryLimit) mayLoopOut(estimate chainfee.SatPerKWeight) error {
	if estimate > f.SweepFeeRateLimit {
		log.Debugf("Current fee estimate to sweep: %v sat/vByte "+
			"exceeds limit of: %v sat/vByte",
			satPerKwToSatPerVByte(estimate),
			satPerKwToSatPerVByte(f.SweepFeeRateLimit))

		return newReasonError(ReasonSweepFees)
	}

	return nil
}

// loopOutLimits checks whether the quote provided is within our fee limits.
func (f *FeeCategoryLimit) loopOutLimits(amount btcutil.Amount,
	quote *loop.LoopOutQuote) error {

	maxFee := ppmToSat(amount, f.MaximumSwapFeePPM)

	if quote.SwapFee > maxFee {
		log.Debugf("quoted swap fee: %v > maximum swap fee: %v",
			quote.SwapFee, maxFee)

		return newReasonError(ReasonSwapFee)
	}

	if quote.MinerFee > f.MaximumMinerFee {
		log.Debugf("quoted miner fee: %v > maximum miner "+
			"fee: %v", quote.MinerFee, f.MaximumMinerFee)

		return newReasonError(ReasonMinerFee)
	}

	if quote.PrepayAmount > f.MaximumPrepay {
		log.Debugf("quoted prepay: %v > maximum prepay: %v",
			quote.PrepayAmount, f.MaximumPrepay)

		return newReasonError(ReasonPrepay)
	}

	return nil
}

func (f *FeeCategoryLimit) loopInLimits(amount btcutil.Amount,
	quote *loop.LoopInQuote) error {

	maxServerFee := ppmToSat(amount, f.MaximumSwapFeePPM)
	if quote.SwapFee > maxServerFee {
		log.Debugf("quoted swap fee: %v > maximum swap fee: %v",
			quote.SwapFee, maxServerFee)

		return newReasonError(ReasonSwapFee)
	}

	if quote.MinerFee > f.MaximumMinerFee {
		log.Debugf("quoted miner fee: %v > maximum miner "+
			"fee: %v", quote.MinerFee, f.MaximumMinerFee)

		return newReasonError(ReasonMinerFee)
	}

	return nil
}

// loopOutFees returns the prepay and routing and miner fees we are willing to
// pay for a loop out swap.
func (f *FeeCategoryLimit) loopOutFees(amount btcutil.Amount,
	quote *loop.LoopOutQuote) (btcutil.Amount, btcutil.Amount,
	btcutil.Amount) {

	prepayMaxFee := ppmToSat(
		quote.PrepayAmount, f.MaximumPrepayRoutingFeePPM,
	)

	routeMaxFee := ppmToSat(amount, f.MaximumRoutingFeePPM)

	return prepayMaxFee, routeMaxFee, f.MaximumMinerFee
}

// Compile time assertion that FeePortion implements FeeLimit interface.
var _ FeeLimit = (*FeePortion)(nil)

// FeePortion is a fee limitation which limits fees to a set portion of
// the swap amount.
type FeePortion struct {
	// PartsPerMillion is the total portion of the swap amount that the
	// swap may consume.
	PartsPerMillion uint64
}

func defaultFeePortion() *FeePortion {
	return &FeePortion{
		PartsPerMillion: defaultFeePPM,
	}
}

// NewFeePortion creates a fee limit based on a flat percentage of swap amount.
func NewFeePortion(ppm uint64) *FeePortion {
	return &FeePortion{
		PartsPerMillion: ppm,
	}
}

// String returns a string representation of the fee limit.
func (f *FeePortion) String() string {
	return fmt.Sprintf("parts per million: %v", f.PartsPerMillion)
}

// validate returns an error if the values provided are invalid.
func (f *FeePortion) validate() error {
	if f.PartsPerMillion <= 0 {
		return ErrInvalidPPM
	}

	return nil
}

// mayLoopOut checks our estimated loop out sweep fee against our sweep limit.
// For fee percentage, we do not check anything because we need the full quote
// to determine whether we can perform a swap.
func (f *FeePortion) mayLoopOut(_ chainfee.SatPerKWeight) error {
	return nil
}

// loopOutLimits checks whether the quote provided is within our fee
// limits for the swap amount.
func (f *FeePortion) loopOutLimits(swapAmt btcutil.Amount,
	quote *loop.LoopOutQuote) error {

	// First, check whether any of the individual fee categories provided
	// by the server are more than our total limit. We do this so that we
	// can provide more specific reasons for not executing swaps.
	feeLimit := ppmToSat(swapAmt, f.PartsPerMillion)
	minerFee := scaleMinerFee(quote.MinerFee)

	if minerFee > feeLimit {
		log.Debugf("miner fee: %v greater than fee limit: %v, at "+
			"%v ppm", minerFee, feeLimit, f.PartsPerMillion)

		return newReasonError(ReasonMinerFee)
	}

	if quote.SwapFee > feeLimit {
		log.Debugf("swap fee: %v greater than fee limit: %v, at "+
			"%v ppm", quote.SwapFee, feeLimit, f.PartsPerMillion)

		return newReasonError(ReasonSwapFee)
	}

	// If our miner and swap fee equal our limit, we will have nothing left
	// for off-chain fees, so we fail out early.
	if minerFee+quote.SwapFee >= feeLimit {
		log.Debugf("no budget for off-chain routing with miner fee: "+
			"%v, swap fee: %v and fee limit: %v, at %v ppm",
			minerFee, quote.SwapFee, feeLimit, f.PartsPerMillion)

		return newReasonError(ReasonFeePPMInsufficient)
	}

	prepay, route, miner := f.loopOutFees(swapAmt, quote)

	// Before checking our fees against our budget we remove the large
	// multiplier from the miner fees. We do this because we want to
	// consider the average case for our budget calculations and not the
	// severe edge-case miner fees.
	miner /= maxMinerMultiplier

	// Calculate the worst case fees that we could pay for this swap,
	// ensuring that we are within our fee limit even if the swap fails.
	fees := worstCaseOutFees(
		prepay, route, quote.SwapFee, miner,
	)

	if fees > feeLimit {
		log.Debugf("total fees for swap: %v > fee limit: %v, at "+
			"%v ppm", fees, feeLimit, f.PartsPerMillion)

		return newReasonError(ReasonFeePPMInsufficient)
	}

	return nil
}

// loopOutFees return the maximum prepay and invoice routing fees for a swap
// amount and quote. Note that the fee portion implementation just returns
// the quote's miner fee, assuming that this value has already been validated.
// We also assume that the quote's minerfee + swapfee < fee limit, so that we
// have some fees left for off-chain routing.
func (f *FeePortion) loopOutFees(amount btcutil.Amount,
	quote *loop.LoopOutQuote) (btcutil.Amount, btcutil.Amount,
	btcutil.Amount) {

	// Calculate the total amount we can spend in fees, and subtract the
	// amounts provided by the quote to get the total available for
	// off-chain fees.
	feeLimit := ppmToSat(amount, f.PartsPerMillion)

	// Apply the small miner multiplier for the fee budget calculations.
	minerFee := scaleMinerFee(quote.MinerFee)

	available := feeLimit - minerFee - quote.SwapFee

	prepayMaxFee, routeMaxFee := splitOffChain(
		available, quote.PrepayAmount, amount,
	)

	// Apply the big miner multiplier to get the worst case miner fees.
	minerFee = scaleMaxMinerFee(minerFee)

	return prepayMaxFee, routeMaxFee, minerFee
}

// splitOffChain takes an available fee budget and divides it among our prepay
// and swap payments proportional to their volume.
func splitOffChain(available, prepayAmt,
	swapAmt btcutil.Amount) (btcutil.Amount, btcutil.Amount) {

	total := swapAmt + prepayAmt

	prepayMaxFee := available * prepayAmt / total
	routeMaxFee := available * swapAmt / total

	return prepayMaxFee, routeMaxFee
}

// scaleMinerFee scales our miner fee by a smaller multiplier. This scale does
// not represent the worst-case maximum miner fees, but the average expected
// fees.
func scaleMinerFee(estimate btcutil.Amount) btcutil.Amount {
	return estimate * btcutil.Amount(minerMultiplier)
}

// scaleMaxMinerFee scales our miner fee by a big multiplier. The returned value
// represents the maximum amount that we consider spending for miner fees in
// worst-case scenarios (fee-spikes).
func scaleMaxMinerFee(estimate btcutil.Amount) btcutil.Amount {
	return estimate * btcutil.Amount(maxMinerMultiplier)
}

func (f *FeePortion) loopInLimits(amount btcutil.Amount,
	quote *loop.LoopInQuote) error {

	// Calculate the total amount that this swap may spend in fees, as a
	// portion of the swap amount.
	totalFeeSpend := ppmToSat(amount, f.PartsPerMillion)

	// Check individual fee components so that we can give more specific
	// feedback.
	if quote.MinerFee > totalFeeSpend {
		log.Debugf("miner fee: %v greater than fee limit: %v, at "+
			"%v ppm", quote.MinerFee, totalFeeSpend,
			f.PartsPerMillion)

		return newReasonError(ReasonMinerFee)
	}

	if quote.SwapFee > totalFeeSpend {
		log.Debugf("swap fee: %v greater than fee limit: %v, at "+
			"%v ppm", quote.SwapFee, totalFeeSpend,
			f.PartsPerMillion)

		return newReasonError(ReasonSwapFee)
	}

	fees := worstCaseInFees(
		quote.MinerFee, quote.SwapFee, defaultLoopInSweepFee,
	)

	if fees > totalFeeSpend {
		log.Debugf("total fees for swap: %v > fee limit: %v, at "+
			"%v ppm", fees, totalFeeSpend, f.PartsPerMillion)

		return newReasonError(ReasonFeePPMInsufficient)
	}

	return nil
}