12986279612

Committed 27 Jan 2025 09:51AM UTC coverage: 57.652% (-1.1%) from 58.788%

Build # 12986279612

Build Type

Pull #9447

github

Committed by

yyforyongyu

Commit Message

sweep: rename methods for clarity

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

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

Run Details

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

19578 existing lines in 256 files now uncovered.

103448 of 179434 relevant lines covered (57.65%)

24884.58 hits per line

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

33.4

/lnwallet/chainfee/estimator.go

package chainfee

import (
        "encoding/json"
        "errors"
        "fmt"
        "io"
        "math"
        prand "math/rand"
        "net"
        "net/http"
        "sync"
        "sync/atomic"
        "time"

        "github.com/btcsuite/btcd/btcutil"
        "github.com/btcsuite/btcd/rpcclient"
        "github.com/lightningnetwork/lnd/lnutils"
)

const (
        // MaxBlockTarget is the highest number of blocks confirmations that
        // a WebAPIEstimator will cache fees for. This number is chosen
        // because it's the highest number of confs bitcoind will return a fee
        // estimate for.
        MaxBlockTarget uint32 = 1008

        // minBlockTarget is the lowest number of blocks confirmations that
        // a WebAPIEstimator will cache fees for. Requesting an estimate for
        // less than this will result in an error.
        minBlockTarget uint32 = 1

        // WebAPIConnectionTimeout specifies the timeout value for connecting
        // to the api source.
        WebAPIConnectionTimeout = 5 * time.Second

        // WebAPIResponseTimeout specifies the timeout value for receiving a
        // fee response from the api source.
        WebAPIResponseTimeout = 10 * time.Second

        // economicalFeeMode is a mode that bitcoind uses to serve
        // non-conservative fee estimates. These fee estimates are less
        // resistant to shocks.
        economicalFeeMode = "ECONOMICAL"

        // filterCapConfTarget is the conf target that will be used to cap our
        // minimum feerate if we used the median of our peers' feefilter
        // values.
        filterCapConfTarget = uint32(1)
)

var (
        // errNoFeeRateFound is used when a given conf target cannot be found
        // from the fee estimator.
        errNoFeeRateFound = errors.New("no fee estimation for block target")

        // errEmptyCache is used when the fee rate cache is empty.
        errEmptyCache = errors.New("fee rate cache is empty")
)

// Estimator provides the ability to estimate on-chain transaction fees for
// various combinations of transaction sizes and desired confirmation time
// (measured by number of blocks).
type Estimator interface {
        // EstimateFeePerKW takes in a target for the number of blocks until an
        // initial confirmation and returns the estimated fee expressed in
        // sat/kw.
        EstimateFeePerKW(numBlocks uint32) (SatPerKWeight, error)

        // Start signals the Estimator to start any processes or goroutines
        // it needs to perform its duty.
        Start() error

        // Stop stops any spawned goroutines and cleans up the resources used
        // by the fee estimator.
        Stop() error

        // RelayFeePerKW returns the minimum fee rate required for transactions
        // to be relayed. This is also the basis for calculation of the dust
        // limit.
        RelayFeePerKW() SatPerKWeight
}

// StaticEstimator will return a static value for all fee calculation requests.
// It is designed to be replaced by a proper fee calculation implementation.
// The fees are not accessible directly, because changing them would not be
// thread safe.
type StaticEstimator struct {
        // feePerKW is the static fee rate in satoshis-per-vbyte that will be
        // returned by this fee estimator.
        feePerKW SatPerKWeight

        // relayFee is the minimum fee rate required for transactions to be
        // relayed.
        relayFee SatPerKWeight
}

// NewStaticEstimator returns a new static fee estimator instance.
func NewStaticEstimator(feePerKW, relayFee SatPerKWeight) *StaticEstimator {
        return &StaticEstimator{
                feePerKW: feePerKW,
                relayFee: relayFee,
        }
}

// EstimateFeePerKW will return a static value for fee calculations.
//
// NOTE: This method is part of the Estimator interface.
func (e StaticEstimator) EstimateFeePerKW(numBlocks uint32) (SatPerKWeight, error) {
        return e.feePerKW, nil
}

// RelayFeePerKW returns the minimum fee rate required for transactions to be
// relayed.
//
// NOTE: This method is part of the Estimator interface.
func (e StaticEstimator) RelayFeePerKW() SatPerKWeight {
        return e.relayFee
}

// Start signals the Estimator to start any processes or goroutines
// it needs to perform its duty.
//
// NOTE: This method is part of the Estimator interface.
func (e StaticEstimator) Start() error {
        return nil
}

// Stop stops any spawned goroutines and cleans up the resources used
// by the fee estimator.
//
// NOTE: This method is part of the Estimator interface.
func (e StaticEstimator) Stop() error {
        return nil
}

// A compile-time assertion to ensure that StaticFeeEstimator implements the
// Estimator interface.
var _ Estimator = (*StaticEstimator)(nil)

// BtcdEstimator is an implementation of the Estimator interface backed
// by the RPC interface of an active btcd node. This implementation will proxy
// any fee estimation requests to btcd's RPC interface.
type BtcdEstimator struct {
        // fallbackFeePerKW is the fall back fee rate in sat/kw that is returned
        // if the fee estimator does not yet have enough data to actually
        // produce fee estimates.
        fallbackFeePerKW SatPerKWeight

        // minFeeManager is used to query the current minimum fee, in sat/kw,
        // that we should enforce. This will be used to determine fee rate for
        // a transaction when the estimated fee rate is too low to allow the
        // transaction to propagate through the network.
        minFeeManager *minFeeManager

        btcdConn *rpcclient.Client

        // filterManager uses our peer's feefilter values to determine a
        // suitable feerate to use that will allow successful transaction
        // propagation.
        filterManager *filterManager
}

// NewBtcdEstimator creates a new BtcdEstimator given a fully populated
// rpc config that is able to successfully connect and authenticate with the
// btcd node, and also a fall back fee rate. The fallback fee rate is used in
// the occasion that the estimator has insufficient data, or returns zero for a
// fee estimate.
func NewBtcdEstimator(rpcConfig rpcclient.ConnConfig,
        fallBackFeeRate SatPerKWeight) (*BtcdEstimator, error) {

        rpcConfig.DisableConnectOnNew = true
        rpcConfig.DisableAutoReconnect = false
        chainConn, err := rpcclient.New(&rpcConfig, nil)
        if err != nil {
                return nil, err
        }

        fetchCb := func() ([]SatPerKWeight, error) {
                return fetchBtcdFilters(chainConn)
        }

        return &BtcdEstimator{
                fallbackFeePerKW: fallBackFeeRate,
                btcdConn:         chainConn,
                filterManager:    newFilterManager(fetchCb),
        }, nil
}

// Start signals the Estimator to start any processes or goroutines
// it needs to perform its duty.
//
// NOTE: This method is part of the Estimator interface.
func (b *BtcdEstimator) Start() error {
        if err := b.btcdConn.Connect(20); err != nil {
                return err
        }

        // Once the connection to the backend node has been established, we
        // can initialise the minimum relay fee manager which queries the
        // chain backend for the minimum relay fee on construction.
        minRelayFeeManager, err := newMinFeeManager(
                defaultUpdateInterval, b.fetchMinRelayFee,
        )
        if err != nil {
                return err
        }
        b.minFeeManager = minRelayFeeManager

        b.filterManager.Start()

        return nil
}

// fetchMinRelayFee fetches and returns the minimum relay fee in sat/kb from
// the btcd backend.
func (b *BtcdEstimator) fetchMinRelayFee() (SatPerKWeight, error) {
        info, err := b.btcdConn.GetInfo()
        if err != nil {
                return 0, err
        }

        relayFee, err := btcutil.NewAmount(info.RelayFee)
        if err != nil {
                return 0, err
        }

        // The fee rate is expressed in sat/kb, so we'll manually convert it to
        // our desired sat/kw rate.
        return SatPerKVByte(relayFee).FeePerKWeight(), nil
}

// Stop stops any spawned goroutines and cleans up the resources used
// by the fee estimator.
//
// NOTE: This method is part of the Estimator interface.
func (b *BtcdEstimator) Stop() error {
        b.filterManager.Stop()

        b.btcdConn.Shutdown()
        b.btcdConn.WaitForShutdown()

        return nil
}

// EstimateFeePerKW takes in a target for the number of blocks until an initial
// confirmation and returns the estimated fee expressed in sat/kw.
//
// NOTE: This method is part of the Estimator interface.
func (b *BtcdEstimator) EstimateFeePerKW(numBlocks uint32) (SatPerKWeight, error) {
        feeEstimate, err := b.fetchEstimate(numBlocks)
        switch {
        // If the estimator doesn't have enough data, or returns an error, then
        // to return a proper value, then we'll return the default fall back
        // fee rate.
        case err != nil:
                log.Errorf("unable to query estimator: %v", err)
                fallthrough

        case feeEstimate == 0:
                return b.fallbackFeePerKW, nil
        }

        return feeEstimate, nil
}

// RelayFeePerKW returns the minimum fee rate required for transactions to be
// relayed.
//
// NOTE: This method is part of the Estimator interface.
func (b *BtcdEstimator) RelayFeePerKW() SatPerKWeight {
        // Get a suitable minimum feerate to use. This may optionally use the
        // median of our peers' feefilter values.
        feeCapClosure := func() (SatPerKWeight, error) {
                return b.fetchEstimateInner(filterCapConfTarget)
        }

        return chooseMinFee(
                b.minFeeManager.fetchMinFee, b.filterManager.FetchMedianFilter,
                feeCapClosure,
        )
}

// fetchEstimate returns a fee estimate for a transaction to be confirmed in
// confTarget blocks. The estimate is returned in sat/kw.
func (b *BtcdEstimator) fetchEstimate(confTarget uint32) (SatPerKWeight, error) {
        satPerKw, err := b.fetchEstimateInner(confTarget)
        if err != nil {
                return 0, err
        }

        // Finally, we'll enforce our fee floor by choosing the higher of the
        // minimum relay fee and the feerate returned by the filterManager.
        absoluteMinFee := b.RelayFeePerKW()

        if satPerKw < absoluteMinFee {
                log.Debugf("Estimated fee rate of %v sat/kw is too low, "+
                        "using fee floor of %v sat/kw instead", satPerKw,
                        absoluteMinFee)

                satPerKw = absoluteMinFee
        }

        log.Debugf("Returning %v sat/kw for conf target of %v",
                int64(satPerKw), confTarget)

        return satPerKw, nil
}

func (b *BtcdEstimator) fetchEstimateInner(confTarget uint32) (SatPerKWeight,
        error) {

        // First, we'll fetch the estimate for our confirmation target.
        btcPerKB, err := b.btcdConn.EstimateFee(int64(confTarget))
        if err != nil {
                return 0, err
        }

        // Next, we'll convert the returned value to satoshis, as it's
        // currently returned in BTC.
        satPerKB, err := btcutil.NewAmount(btcPerKB)
        if err != nil {
                return 0, err
        }

        // Since we use fee rates in sat/kw internally, we'll convert the
        // estimated fee rate from its sat/kb representation to sat/kw.
        return SatPerKVByte(satPerKB).FeePerKWeight(), nil
}

// A compile-time assertion to ensure that BtcdEstimator implements the
// Estimator interface.
var _ Estimator = (*BtcdEstimator)(nil)

// BitcoindEstimator is an implementation of the Estimator interface backed by
// the RPC interface of an active bitcoind node. This implementation will proxy
// any fee estimation requests to bitcoind's RPC interface.
type BitcoindEstimator struct {
        // fallbackFeePerKW is the fallback fee rate in sat/kw that is returned
        // if the fee estimator does not yet have enough data to actually
        // produce fee estimates.
        fallbackFeePerKW SatPerKWeight

        // minFeeManager is used to keep track of the minimum fee, in sat/kw,
        // that we should enforce. This will be used as the default fee rate
        // for a transaction when the estimated fee rate is too low to allow
        // the transaction to propagate through the network.
        minFeeManager *minFeeManager

        // feeMode is the estimate_mode to use when calling "estimatesmartfee".
        // It can be either "ECONOMICAL" or "CONSERVATIVE", and it's default
        // to "CONSERVATIVE".
        feeMode string

        // TODO(ziggie): introduce an interface for the client to enhance
        // testability of the estimator.
        bitcoindConn *rpcclient.Client

        // filterManager uses our peer's feefilter values to determine a
        // suitable feerate to use that will allow successful transaction
        // propagation.
        filterManager *filterManager
}

// NewBitcoindEstimator creates a new BitcoindEstimator given a fully populated
// rpc config that is able to successfully connect and authenticate with the
// bitcoind node, and also a fall back fee rate. The fallback fee rate is used
// in the occasion that the estimator has insufficient data, or returns zero
// for a fee estimate.
func NewBitcoindEstimator(rpcConfig rpcclient.ConnConfig, feeMode string,
        fallBackFeeRate SatPerKWeight) (*BitcoindEstimator, error) {

        rpcConfig.DisableConnectOnNew = true
        rpcConfig.DisableAutoReconnect = false
        rpcConfig.DisableTLS = true
        rpcConfig.HTTPPostMode = true
        chainConn, err := rpcclient.New(&rpcConfig, nil)
        if err != nil {
                return nil, err
        }

        fetchCb := func() ([]SatPerKWeight, error) {
                return fetchBitcoindFilters(chainConn)
        }

        return &BitcoindEstimator{
                fallbackFeePerKW: fallBackFeeRate,
                bitcoindConn:     chainConn,
                feeMode:          feeMode,
                filterManager:    newFilterManager(fetchCb),
        }, nil
}

// Start signals the Estimator to start any processes or goroutines
// it needs to perform its duty.
//
// NOTE: This method is part of the Estimator interface.
func (b *BitcoindEstimator) Start() error {
        // Once the connection to the backend node has been established, we'll
        // initialise the minimum relay fee manager which will query
        // the backend node for its minimum mempool fee.
        relayFeeManager, err := newMinFeeManager(
                defaultUpdateInterval,
                b.fetchMinMempoolFee,
        )
        if err != nil {
                return err
        }
        b.minFeeManager = relayFeeManager

        b.filterManager.Start()

        return nil
}

// fetchMinMempoolFee is used to fetch the minimum fee that the backend node
// requires for a tx to enter its mempool. The returned fee will be the
// maximum of the minimum relay fee and the minimum mempool fee.
func (b *BitcoindEstimator) fetchMinMempoolFee() (SatPerKWeight, error) {
        resp, err := b.bitcoindConn.RawRequest("getmempoolinfo", nil)
        if err != nil {
                return 0, err
        }

        // Parse the response to retrieve the min mempool fee in sat/KB.
        // mempoolminfee is the maximum of minrelaytxfee and
        // minimum mempool fee
        info := struct {
                MempoolMinFee float64 `json:"mempoolminfee"`
        }{}
        if err := json.Unmarshal(resp, &info); err != nil {
                return 0, err
        }

        minMempoolFee, err := btcutil.NewAmount(info.MempoolMinFee)
        if err != nil {
                return 0, err
        }

        // The fee rate is expressed in sat/kb, so we'll manually convert it to
        // our desired sat/kw rate.
        return SatPerKVByte(minMempoolFee).FeePerKWeight(), nil
}

// Stop stops any spawned goroutines and cleans up the resources used
// by the fee estimator.
//
// NOTE: This method is part of the Estimator interface.
func (b *BitcoindEstimator) Stop() error {
        b.filterManager.Stop()
        return nil
}

// EstimateFeePerKW takes in a target for the number of blocks until an initial
// confirmation and returns the estimated fee expressed in sat/kw.
//
// NOTE: This method is part of the Estimator interface.
func (b *BitcoindEstimator) EstimateFeePerKW(
        numBlocks uint32) (SatPerKWeight, error) {

        if numBlocks > MaxBlockTarget {
                log.Debugf("conf target %d exceeds the max value, "+
                        "use %d instead.", numBlocks, MaxBlockTarget,
                )
                numBlocks = MaxBlockTarget
        }

        feeEstimate, err := b.fetchEstimate(numBlocks, b.feeMode)
        switch {
        // If the estimator doesn't have enough data, or returns an error, then
        // to return a proper value, then we'll return the default fall back
        // fee rate.
        case err != nil:
                log.Errorf("unable to query estimator: %v", err)
                fallthrough

        case feeEstimate == 0:
                return b.fallbackFeePerKW, nil
        }

        return feeEstimate, nil
}

// RelayFeePerKW returns the minimum fee rate required for transactions to be
// relayed.
//
// NOTE: This method is part of the Estimator interface.
func (b *BitcoindEstimator) RelayFeePerKW() SatPerKWeight {
        // Get a suitable minimum feerate to use. This may optionally use the
        // median of our peers' feefilter values.
        feeCapClosure := func() (SatPerKWeight, error) {
                return b.fetchEstimateInner(
                        filterCapConfTarget, economicalFeeMode,
                )
        }

        return chooseMinFee(
                b.minFeeManager.fetchMinFee, b.filterManager.FetchMedianFilter,
                feeCapClosure,
        )
}

// fetchEstimate returns a fee estimate for a transaction to be confirmed in
// confTarget blocks. The estimate is returned in sat/kw.
func (b *BitcoindEstimator) fetchEstimate(confTarget uint32, feeMode string) (
        SatPerKWeight, error) {

        satPerKw, err := b.fetchEstimateInner(confTarget, feeMode)
        if err != nil {
                return 0, err
        }

        // Finally, we'll enforce our fee floor by choosing the higher of the
        // minimum relay fee and the feerate returned by the filterManager.
        absoluteMinFee := b.RelayFeePerKW()

        if satPerKw < absoluteMinFee {
                log.Debugf("Estimated fee rate of %v sat/kw is too low, "+
                        "using fee floor of %v sat/kw instead", satPerKw,
                        absoluteMinFee)

                satPerKw = absoluteMinFee
        }

        log.Debugf("Returning %v sat/kw for conf target of %v",
                int64(satPerKw), confTarget)

        return satPerKw, nil
}

func (b *BitcoindEstimator) fetchEstimateInner(confTarget uint32,
        feeMode string) (SatPerKWeight, error) {

        // First, we'll send an "estimatesmartfee" command as a raw request,
        // since it isn't supported by btcd but is available in bitcoind.
        target, err := json.Marshal(uint64(confTarget))
        if err != nil {
                return 0, err
        }

        // The mode must be either ECONOMICAL or CONSERVATIVE.
        mode, err := json.Marshal(feeMode)
        if err != nil {
                return 0, err
        }

        resp, err := b.bitcoindConn.RawRequest(
                "estimatesmartfee", []json.RawMessage{target, mode},
        )
        if err != nil {
                return 0, err
        }

        // Next, we'll parse the response to get the BTC per KB.
        feeEstimate := struct {
                FeeRate float64 `json:"feerate"`
        }{}
        err = json.Unmarshal(resp, &feeEstimate)
        if err != nil {
                return 0, err
        }

        // Next, we'll convert the returned value to satoshis, as it's currently
        // returned in BTC.
        satPerKB, err := btcutil.NewAmount(feeEstimate.FeeRate)
        if err != nil {
                return 0, err
        }

        // Bitcoind will not report any fee estimation if it has not enough
        // data available hence the fee will remain zero. We return an error
        // here to make sure that we do not use the min relay fee instead.
        if satPerKB == 0 {
                return 0, fmt.Errorf("fee estimation data not available yet")
        }

        // Since we use fee rates in sat/kw internally, we'll convert the
        // estimated fee rate from its sat/kb representation to sat/kw.
        return SatPerKVByte(satPerKB).FeePerKWeight(), nil
}

// chooseMinFee takes the minimum relay fee and the median of our peers'
// feefilter values and takes the higher of the two. It then compares the value
// against a maximum fee and caps it if the value is higher than the maximum
// fee. This function is only called if we have data for our peers' feefilter.
// The returned value will be used as the fee floor for calls to
// RelayFeePerKW.
func chooseMinFee(minRelayFeeFunc func() SatPerKWeight,
        medianFilterFunc func() (SatPerKWeight, error),
        feeCapFunc func() (SatPerKWeight, error)) SatPerKWeight {

        minRelayFee := minRelayFeeFunc()

        medianFilter, err := medianFilterFunc()
        if err != nil {
                // If we don't have feefilter data, we fallback to using our
                // minimum relay fee.
                return minRelayFee
        }

        feeCap, err := feeCapFunc()
        if err != nil {
                // If we encountered an error, don't use the medianFilter and
                // instead fallback to using our minimum relay fee.
                return minRelayFee
        }

        // If the median feefilter is higher than our minimum relay fee, use it
        // instead.
        if medianFilter > minRelayFee {
                // Only apply the cap if the median filter was used. This is
                // to prevent an adversary from taking up the majority of our
                // outbound peer slots and forcing us to use a high median
                // filter value.
                if medianFilter > feeCap {
                        return feeCap
                }

                return medianFilter
        }

        return minRelayFee
}

// A compile-time assertion to ensure that BitcoindEstimator implements the
// Estimator interface.
var _ Estimator = (*BitcoindEstimator)(nil)

// WebAPIFeeSource is an interface allows the WebAPIEstimator to query an
// arbitrary HTTP-based fee estimator. Each new set/network will gain an
// implementation of this interface in order to allow the WebAPIEstimator to
// be fully generic in its logic.
type WebAPIFeeSource interface {
        // GetFeeInfo will query the web API, parse the response into a
        // WebAPIResponse which contains a map of confirmation targets to
        // sat/kw fees and min relay feerate.
        GetFeeInfo() (WebAPIResponse, error)
}

// SparseConfFeeSource is an implementation of the WebAPIFeeSource that utilizes
// a user-specified fee estimation API for Bitcoin. It expects the response
// to be in the JSON format: `fee_by_block_target: { ... }` where the value maps
// block targets to fee estimates (in sat per kilovbyte).
type SparseConfFeeSource struct {
        // URL is the fee estimation API specified by the user.
        URL string
}

// WebAPIResponse is the response returned by the fee estimation API.
type WebAPIResponse struct {
        // FeeByBlockTarget is a map of confirmation targets to sat/kvb fees.
        FeeByBlockTarget map[uint32]uint32 `json:"fee_by_block_target"`

        // MinRelayFeerate is the minimum relay fee in sat/kvb.
        MinRelayFeerate SatPerKVByte `json:"min_relay_feerate"`
}

// parseResponse attempts to parse the body of the response generated by the
// above query URL. Typically this will be JSON, but the specifics are left to
// the WebAPIFeeSource implementation.
func (s SparseConfFeeSource) parseResponse(r io.Reader) (
        WebAPIResponse, error) {

        resp := WebAPIResponse{
                FeeByBlockTarget: make(map[uint32]uint32),
                MinRelayFeerate:  0,
        }
        jsonReader := json.NewDecoder(r)
        if err := jsonReader.Decode(&resp); err != nil {
                return WebAPIResponse{}, err
        }

        if resp.MinRelayFeerate == 0 {
                log.Errorf("No min relay fee rate available, using default %v",
                        FeePerKwFloor)
                resp.MinRelayFeerate = FeePerKwFloor.FeePerKVByte()
        }

        return resp, nil
}

// GetFeeInfo will query the web API, parse the response and return a map of
// confirmation targets to sat/kw fees and min relay feerate in a parsed
// response.
func (s SparseConfFeeSource) GetFeeInfo() (WebAPIResponse, error) {
        // Rather than use the default http.Client, we'll make a custom one
        // which will allow us to control how long we'll wait to read the
        // response from the service. This way, if the service is down or
        // overloaded, we can exit early and use our default fee.
        netTransport := &http.Transport{
                Dial: (&net.Dialer{
                        Timeout: WebAPIConnectionTimeout,
                }).Dial,
                TLSHandshakeTimeout: WebAPIConnectionTimeout,
        }
        netClient := &http.Client{
                Timeout:   WebAPIResponseTimeout,
                Transport: netTransport,
        }

        // With the client created, we'll query the API source to fetch the URL
        // that we should use to query for the fee estimation.
        targetURL := s.URL
        resp, err := netClient.Get(targetURL)
        if err != nil {
                log.Errorf("unable to query web api for fee response: %v",
                        err)
                return WebAPIResponse{}, err
        }
        defer resp.Body.Close()

        // Once we've obtained the response, we'll instruct the WebAPIFeeSource
        // to parse out the body to obtain our final result.
        parsedResp, err := s.parseResponse(resp.Body)
        if err != nil {
                log.Errorf("unable to parse fee api response: %v", err)

                return WebAPIResponse{}, err
        }

        return parsedResp, nil
}

// A compile-time assertion to ensure that SparseConfFeeSource implements the
// WebAPIFeeSource interface.
var _ WebAPIFeeSource = (*SparseConfFeeSource)(nil)

// WebAPIEstimator is an implementation of the Estimator interface that
// queries an HTTP-based fee estimation from an existing web API.
type WebAPIEstimator struct {
        started atomic.Bool
        stopped atomic.Bool

        // apiSource is the backing web API source we'll use for our queries.
        apiSource WebAPIFeeSource

        // updateFeeTicker is the ticker responsible for updating the Estimator's
        // fee estimates every time it fires.
        updateFeeTicker *time.Ticker

        // feeByBlockTarget is our cache for fees pulled from the API. When a
        // fee estimate request comes in, we pull the estimate from this array
        // rather than re-querying the API, to prevent an inadvertent DoS attack.
        feesMtx          sync.Mutex
        feeByBlockTarget map[uint32]uint32
        minRelayFeerate  SatPerKVByte

        // noCache determines whether the web estimator should cache fee
        // estimates.
        noCache bool

        // minFeeUpdateTimeout represents the minimum interval in which the
        // web estimator will request fresh fees from its API.
        minFeeUpdateTimeout time.Duration

        // minFeeUpdateTimeout represents the maximum interval in which the
        // web estimator will request fresh fees from its API.
        maxFeeUpdateTimeout time.Duration

        quit chan struct{}
        wg   sync.WaitGroup
}

// NewWebAPIEstimator creates a new WebAPIEstimator from a given URL and a
// fallback default fee. The fees are updated whenever a new block is mined.
func NewWebAPIEstimator(api WebAPIFeeSource, noCache bool,
        minFeeUpdateTimeout time.Duration,
        maxFeeUpdateTimeout time.Duration) (*WebAPIEstimator, error) {

        if minFeeUpdateTimeout == 0 || maxFeeUpdateTimeout == 0 {
                return nil, fmt.Errorf("minFeeUpdateTimeout and " +
                        "maxFeeUpdateTimeout must be greater than 0")
        }

        if minFeeUpdateTimeout >= maxFeeUpdateTimeout {
                return nil, fmt.Errorf("minFeeUpdateTimeout target of %v "+
                        "cannot be greater than maxFeeUpdateTimeout of %v",
                        minFeeUpdateTimeout, maxFeeUpdateTimeout)
        }

        return &WebAPIEstimator{
                apiSource:           api,
                feeByBlockTarget:    make(map[uint32]uint32),
                noCache:             noCache,
                quit:                make(chan struct{}),
                minFeeUpdateTimeout: minFeeUpdateTimeout,
                maxFeeUpdateTimeout: maxFeeUpdateTimeout,
        }, nil
}

// EstimateFeePerKW takes in a target for the number of blocks until an initial
// confirmation and returns the estimated fee expressed in sat/kw.
//
// NOTE: This method is part of the Estimator interface.
func (w *WebAPIEstimator) EstimateFeePerKW(numBlocks uint32) (
        SatPerKWeight, error) {

        // If the estimator hasn't been started yet, we'll return an error as
        // we can't provide a fee estimate.
        if !w.started.Load() {
                return 0, fmt.Errorf("estimator not started")
        }

        if numBlocks > MaxBlockTarget {
                numBlocks = MaxBlockTarget
        } else if numBlocks < minBlockTarget {
                return 0, fmt.Errorf("conf target of %v is too low, minimum "+
                        "accepted is %v", numBlocks, minBlockTarget)
        }

        // Get fee estimates now if we don't refresh periodically.
        if w.noCache {
                w.updateFeeEstimates()
        }

        feePerKb, err := w.getCachedFee(numBlocks)

        // If the estimator returns an error, a zero value fee rate will be
        // returned. We will log the error and return the fall back fee rate
        // instead.
        if err != nil {
                log.Errorf("Unable to query estimator: %v", err)
        }

        // If the result is too low, then we'll clamp it to our current fee
        // floor.
        satPerKw := SatPerKVByte(feePerKb).FeePerKWeight()
        if satPerKw < FeePerKwFloor {
                satPerKw = FeePerKwFloor
        }

        log.Debugf("Web API returning %v sat/kw for conf target of %v",
                int64(satPerKw), numBlocks)

        return satPerKw, nil
}

// Start signals the Estimator to start any processes or goroutines it needs
// to perform its duty.
//
// NOTE: This method is part of the Estimator interface.
func (w *WebAPIEstimator) Start() error {
        log.Infof("Starting Web API fee estimator...")

        // Return an error if it's already been started.
        if w.started.Load() {
                return fmt.Errorf("web API fee estimator already started")
        }
        defer w.started.Store(true)

        // During startup we'll query the API to initialize the fee map.
        w.updateFeeEstimates()

        // No update loop is needed when we don't cache.
        if w.noCache {
                return nil
        }

        feeUpdateTimeout := w.randomFeeUpdateTimeout()

        log.Infof("Web API fee estimator using update timeout of %v",
                feeUpdateTimeout)

        w.updateFeeTicker = time.NewTicker(feeUpdateTimeout)

        w.wg.Add(1)
        go w.feeUpdateManager()

        return nil
}

// Stop stops any spawned goroutines and cleans up the resources used by the
// fee estimator.
//
// NOTE: This method is part of the Estimator interface.
func (w *WebAPIEstimator) Stop() error {
        log.Infof("Stopping web API fee estimator")

        if w.stopped.Swap(true) {
                return fmt.Errorf("web API fee estimator already stopped")
        }

        // Update loop is not running when we don't cache.
        if w.noCache {
                return nil
        }

        if w.updateFeeTicker != nil {
                w.updateFeeTicker.Stop()
        }

        close(w.quit)
        w.wg.Wait()

        return nil
}

// RelayFeePerKW returns the minimum fee rate required for transactions to be
// relayed.
//
// NOTE: This method is part of the Estimator interface.
func (w *WebAPIEstimator) RelayFeePerKW() SatPerKWeight {
        if !w.started.Load() {
                log.Error("WebAPIEstimator not started")
        }

        // Get fee estimates now if we don't refresh periodically.
        if w.noCache {
                w.updateFeeEstimates()
        }

        log.Infof("Web API returning %v for min relay feerate",
                w.minRelayFeerate)

        return w.minRelayFeerate.FeePerKWeight()
}

// randomFeeUpdateTimeout returns a random timeout between minFeeUpdateTimeout
// and maxFeeUpdateTimeout that will be used to determine how often the Estimator
// should retrieve fresh fees from its API.
func (w *WebAPIEstimator) randomFeeUpdateTimeout() time.Duration {
        lower := int64(w.minFeeUpdateTimeout)
        upper := int64(w.maxFeeUpdateTimeout)
        return time.Duration(
                prand.Int63n(upper-lower) + lower, //nolint:gosec
        ).Round(time.Second)
}

// getCachedFee takes a conf target and returns the cached fee rate. When the
// fee rate cannot be found, it will search the cache by decrementing the conf
// target until a fee rate is found. If still not found, it will return the fee
// rate of the minimum conf target cached, in other words, the most expensive
// fee rate it knows of.
func (w *WebAPIEstimator) getCachedFee(numBlocks uint32) (uint32, error) {
        w.feesMtx.Lock()
        defer w.feesMtx.Unlock()

        // If the cache is empty, return an error.
        if len(w.feeByBlockTarget) == 0 {
                return 0, fmt.Errorf("web API error: %w", errEmptyCache)
        }

        // Search the conf target from the cache. We expect a query to the web
        // API has been made and the result has been cached at this point.
        fee, ok := w.feeByBlockTarget[numBlocks]

        // If the conf target can be found, exit early.
        if ok {
                return fee, nil
        }

        // The conf target cannot be found. We will first search the cache
        // using a lower conf target. This is a conservative approach as the
        // fee rate returned will be larger than what's requested.
        for target := numBlocks; target >= minBlockTarget; target-- {
                fee, ok := w.feeByBlockTarget[target]
                if !ok {
                        continue
                }

                log.Warnf("Web API does not have a fee rate for target=%d, "+
                        "using the fee rate for target=%d instead",
                        numBlocks, target)

                // Return the fee rate found, which will be more expensive than
                // requested. We will not cache the fee rate here in the hope
                // that the web API will later populate this value.
                return fee, nil
        }

        // There are no lower conf targets cached, which is likely when the
        // requested conf target is 1. We will search the cache using a higher
        // conf target, which gives a fee rate that's cheaper than requested.
        //
        // NOTE: we can only get here iff the requested conf target is smaller
        // than the minimum conf target cached, so we return the minimum conf
        // target from the cache.
        minTargetCached := uint32(math.MaxUint32)
        for target := range w.feeByBlockTarget {
                if target < minTargetCached {
                        minTargetCached = target
                }
        }

        fee, ok = w.feeByBlockTarget[minTargetCached]
        if !ok {
                // We should never get here, just a vanity check.
                return 0, fmt.Errorf("web API error: %w, conf target: %d",
                        errNoFeeRateFound, numBlocks)
        }

        // Log an error instead of a warning as a cheaper fee rate may delay
        // the confirmation for some important transactions.
        log.Errorf("Web API does not have a fee rate for target=%d, "+
                "using the fee rate for target=%d instead",
                numBlocks, minTargetCached)

        return fee, nil
}

// updateFeeEstimates re-queries the API for fresh fees and caches them.
func (w *WebAPIEstimator) updateFeeEstimates() {
        // Once we've obtained the response, we'll instruct the WebAPIFeeSource
        // to parse out the body to obtain our final result.
        resp, err := w.apiSource.GetFeeInfo()
        if err != nil {
                log.Errorf("unable to get fee response: %v", err)
                return
        }

        log.Debugf("Received response from source: %s", lnutils.NewLogClosure(
                func() string {
                        resp, _ := json.Marshal(resp)
                        return string(resp)
                }))

        w.feesMtx.Lock()
        w.feeByBlockTarget = resp.FeeByBlockTarget
        w.minRelayFeerate = resp.MinRelayFeerate
        w.feesMtx.Unlock()
}

// feeUpdateManager updates the fee estimates whenever a new block comes in.
func (w *WebAPIEstimator) feeUpdateManager() {
        defer w.wg.Done()

        for {
                select {
                case <-w.updateFeeTicker.C:
                        w.updateFeeEstimates()
                case <-w.quit:
                        return
                }
        }
}

// A compile-time assertion to ensure that WebAPIEstimator implements the
// Estimator interface.
var _ Estimator = (*WebAPIEstimator)(nil)

lightningnetwork / lnd / 12986279612

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