routing

package
v0.18.4-beta.rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 21, 2024 License: MIT Imports: 42 Imported by: 0

README

routing

Build Status MIT licensed GoDoc

The routing package implements authentication+validation of channel announcements, pruning of the channel graph, path finding within the network, sending outgoing payments into the network and synchronizing new peers to our channel graph state.

Installation and Updating

$  go get -u github.com/lightningnetwork/lnd/routing

Documentation

Index

Constants

View Source 
const (
	// DefaultPenaltyHalfLife is the default half-life duration. The
	// half-life duration defines after how much time a penalized node or
	// channel is back at 50% probability.
	DefaultPenaltyHalfLife = time.Hour

	// DefaultMaxMcHistory is the default maximum history size.
	DefaultMaxMcHistory = 1000

	// DefaultMcFlushInterval is the default interval we use to flush MC state
	// to the database.
	DefaultMcFlushInterval = time.Second

	// DefaultAprioriWeight is the default a priori weight. See
	// MissionControlConfig for further explanation.
	DefaultAprioriWeight = 0.5

	// DefaultMinFailureRelaxInterval is the default minimum time that must
	// have passed since the previously recorded failure before the failure
	// amount may be raised.
	DefaultMinFailureRelaxInterval = time.Minute

	// DefaultFeeEstimationTimeout is the default value for
	// FeeEstimationTimeout. It defines the maximum duration that the
	// probing fee estimation is allowed to take.
	DefaultFeeEstimationTimeout = time.Minute
)
View Source 
const (

	// DefaultCapacityFraction is the default value for CapacityFraction.
	// It is chosen such that the capacity factor is active but with a small
	// effect. This value together with capacitySmearingFraction leads to a
	// noticeable reduction in probability if the amount starts to come
	// close to 90% of a channel's capacity.
	DefaultCapacityFraction = 0.9999

	// AprioriEstimatorName is used to identify the apriori probability
	// estimator.
	AprioriEstimatorName = "apriori"
)
View Source 
const (
	// DefaultBimodalScaleMsat is the default value for BimodalScaleMsat in
	// BimodalConfig. It describes the distribution of funds in the LN based
	// on empirical findings. We assume an unbalanced network by default.
	DefaultBimodalScaleMsat = lnwire.MilliSatoshi(300_000_000)

	// DefaultBimodalNodeWeight is the default value for the
	// BimodalNodeWeight in BimodalConfig. It is chosen such that past
	// forwardings on other channels of a router are only slightly taken
	// into account.
	DefaultBimodalNodeWeight = 0.2

	// DefaultBimodalDecayTime is the default value for BimodalDecayTime.
	// We will forget about previous learnings about channel liquidity on
	// the timescale of about a week.
	DefaultBimodalDecayTime = 7 * 24 * time.Hour

	// BimodalScaleMsatMax is the maximum value for BimodalScaleMsat. We
	// limit it here to the fakeHopHintCapacity to avoid issues with hop
	// hint probability calculations.
	BimodalScaleMsatMax = lnwire.MilliSatoshi(
		1000 * fakeHopHintCapacity / 4,
	)

	// BimodalEstimatorName is used to identify the bimodal estimator.
	BimodalEstimatorName = "bimodal"
)
View Source 
const (
	// DefaultPayAttemptTimeout is the default payment attempt timeout. The
	// payment attempt timeout defines the duration after which we stop
	// trying more routes for a payment.
	DefaultPayAttemptTimeout = time.Second * 60

	// MinCLTVDelta is the minimum CLTV value accepted by LND for all
	// timelock deltas. This includes both forwarding CLTV deltas set on
	// channel updates, as well as final CLTV deltas used to create BOLT 11
	// payment requests.
	//
	// NOTE: For payment requests, BOLT 11 stipulates that a final CLTV
	// delta of 9 should be used when no value is decoded. This however
	// leads to inflexibility in upgrading this default parameter, since it
	// can create inconsistencies around the assumed value between sender
	// and receiver. Specifically, if the receiver assumes a higher value
	// than the sender, the receiver will always see the received HTLCs as
	// invalid due to their timelock not meeting the required delta.
	//
	// We skirt this by always setting an explicit CLTV delta when creating
	// invoices. This allows LND nodes to freely update the minimum without
	// creating incompatibilities during the upgrade process. For some time
	// LND has used an explicit default final CLTV delta of 40 blocks for
	// bitcoin, though we now clamp the lower end of this
	// range for user-chosen deltas to 18 blocks to be conservative.
	MinCLTVDelta = 18

	// MaxCLTVDelta is the maximum CLTV value accepted by LND for all
	// timelock deltas.
	MaxCLTVDelta = math.MaxUint16
)
View Source 
const BlockPadding uint16 = 3

BlockPadding is used to increment the finalCltvDelta value for the last hop to prevent an HTLC being failed if some blocks are mined while it's in-flight.

View Source 
const (

	// RiskFactorBillionths controls the influence of time lock delta
	// of a channel on route selection. It is expressed as billionths
	// of msat per msat sent through the channel per time lock delta
	// block. See edgeWeight function below for more details.
	// The chosen value is based on the previous incorrect weight function
	// 1 + timelock + fee * fee. In this function, the fee penalty
	// diminishes the time lock penalty for all but the smallest amounts.
	// To not change the behaviour of path finding too drastically, a
	// relatively small value is chosen which is still big enough to give
	// some effect with smaller time lock values. The value may need
	// tweaking and/or be made configurable in the future.
	RiskFactorBillionths = 15
)
View Source 
const Subsystem = "CRTR"

Variables

View Source 
var (
	// ErrNoBlindedPath is returned when the blinded path in a blinded
	// payment is missing.
	ErrNoBlindedPath = errors.New("blinded path required")

	// ErrInsufficientBlindedHops is returned when a blinded path does
	// not have enough blinded hops.
	ErrInsufficientBlindedHops = errors.New("blinded path requires " +
		"at least one hop")

	// ErrHTLCRestrictions is returned when a blinded path has invalid
	// HTLC maximum and minimum values.
	ErrHTLCRestrictions = errors.New("invalid htlc minimum and maximum")
)
View Source 
var (
	// ErrInvalidMcHistory is returned if we get a negative mission control
	// history count.
	ErrInvalidMcHistory = errors.New("mission control history must be " +
		">= 0")

	// ErrInvalidFailureInterval is returned if we get an invalid failure
	// interval.
	ErrInvalidFailureInterval = errors.New("failure interval must be >= 0")
)
View Source 
var (
	// DefaultEstimator is the default estimator used for computing
	// probabilities in pathfinding.
	DefaultEstimator = AprioriEstimatorName

	// DefaultAttemptCost is the default fixed virtual cost in path finding
	// of a failed payment attempt. It is used to trade off potentially
	// better routes against their probability of succeeding.
	DefaultAttemptCost = lnwire.NewMSatFromSatoshis(100)

	// DefaultAttemptCostPPM is the default proportional virtual cost in
	// path finding weight units of executing a payment attempt that fails.
	// It is used to trade off potentially better routes against their
	// probability of succeeding. This parameter is expressed in parts per
	// million of the payment amount.
	//
	// It is impossible to pick a perfect default value. The current value
	// of 0.1% is based on the idea that a transaction fee of 1% is within
	// reasonable territory and that a payment shouldn't need more than 10
	// attempts.
	DefaultAttemptCostPPM = int64(1000)

	// DefaultMinRouteProbability is the default minimum probability for routes
	// returned from findPath.
	DefaultMinRouteProbability = float64(0.01)

	// DefaultAprioriHopProbability is the default a priori probability for
	// a hop.
	DefaultAprioriHopProbability = float64(0.6)
)
View Source 
var (
	// ErrInvalidHalflife is returned when we get an invalid half life.
	ErrInvalidHalflife = errors.New("penalty half life must be >= 0")

	// ErrInvalidHopProbability is returned when we get an invalid hop
	// probability.
	ErrInvalidHopProbability = errors.New("hop probability must be in " +
		"[0, 1]")

	// ErrInvalidAprioriWeight is returned when we get an apriori weight
	// that is out of range.
	ErrInvalidAprioriWeight = errors.New("apriori weight must be in [0, 1]")

	// ErrInvalidCapacityFraction is returned when we get a capacity
	// fraction that is out of range.
	ErrInvalidCapacityFraction = fmt.Errorf("capacity fraction must be in "+
		"[%v, 1]", minCapacityFraction)
)
View Source 
var (
	// ErrInvalidScale is returned when we get a scale below or equal zero.
	ErrInvalidScale = errors.New("scale must be >= 0 and sane")

	// ErrInvalidNodeWeight is returned when we get a node weight that is
	// out of range.
	ErrInvalidNodeWeight = errors.New("node weight must be in [0, 1]")

	// ErrInvalidDecayTime is returned when we get a decay time below zero.
	ErrInvalidDecayTime = errors.New("decay time must be larger than zero")

	// ErrZeroCapacity is returned when we encounter a channel with zero
	// capacity in probability estimation.
	ErrZeroCapacity = errors.New("capacity must be larger than zero")
)
View Source 
var (
	// ErrRouterShuttingDown is returned if the router is in the process of
	// shutting down.
	ErrRouterShuttingDown = fmt.Errorf("router shutting down")

	// ErrSelfIntro is a failure returned when the source node of a
	// route request is also the introduction node. This is not yet
	// supported because LND does not support blinded forwardingg.
	ErrSelfIntro = errors.New("introduction point as own node not " +
		"supported")

	// ErrHintsAndBlinded is returned if a route request has both
	// bolt 11 route hints and a blinded path set.
	ErrHintsAndBlinded = errors.New("bolt 11 route hints and blinded " +
		"paths are mutually exclusive")

	// ErrExpiryAndBlinded is returned if a final cltv and a blinded path
	// are provided, as the cltv should be provided within the blinded
	// path.
	ErrExpiryAndBlinded = errors.New("final cltv delta and blinded " +
		"paths are mutually exclusive")

	// ErrTargetAndBlinded is returned is a target destination and a
	// blinded path are both set (as the target is inferred from the
	// blinded path).
	ErrTargetAndBlinded = errors.New("target node and blinded paths " +
		"are mutually exclusive")

	// ErrNoTarget is returned when the target node for a route is not
	// provided by either a blinded route or a cleartext pubkey.
	ErrNoTarget = errors.New("destination not set in target or blinded " +
		"path")

	// ErrSkipTempErr is returned when a non-MPP is made yet the
	// skipTempErr flag is set.
	ErrSkipTempErr = errors.New("cannot skip temp error for non-MPP")
)
View Source 
var (
	// DefaultShardMinAmt is the default amount beyond which we won't try to
	// further split the payment if no route is found. It is the minimum
	// amount that we use as the shard size when splitting.
	DefaultShardMinAmt = lnwire.NewMSatFromSatoshis(10000)
)
View Source 
var (
	// ErrNoPayLoadSizeFunc is returned when no payload size function is
	// definied.
	ErrNoPayLoadSizeFunc = errors.New("no payloadSizeFunc defined for " +
		"additional edge")
)
View Source 
var ErrPaymentLifecycleExiting = errors.New("payment lifecycle exiting")

ErrPaymentLifecycleExiting is used when waiting for htlc attempt result, but the payment lifecycle is exiting .

Functions

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by by default until UseLogger is called.

func FetchAmountPairCapacity 

func FetchAmountPairCapacity(graph Graph, source, nodeFrom, nodeTo route.Vertex,
	amount lnwire.MilliSatoshi) (btcutil.Amount, error)

FetchAmountPairCapacity determines the maximal public capacity between two nodes depending on the amount we try to send.

func RouteHintsToEdges 

func RouteHintsToEdges(routeHints [][]zpay32.HopHint, target route.Vertex) (
	map[route.Vertex][]AdditionalEdge, error)

RouteHintsToEdges converts a list of invoice route hints to an edge map that can be passed into pathfinding.

func UseLogger 

func UseLogger(logger btclog.Logger)

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 ValidateCLTVLimit 

func ValidateCLTVLimit(limit uint32, delta uint16, includePad bool) error

ValidateCLTVLimit is a helper function that validates that the cltv limit is greater than the final cltv delta parameter, optionally including the BlockPadding in this calculation.

Types

type AMPOptions 

type AMPOptions struct {
	SetID     [32]byte
	RootShare [32]byte
}

AMPOptions houses information that must be known in order to send an AMP payment.

type AdditionalEdge 

type AdditionalEdge interface {
	// IntermediatePayloadSize returns the size of the payload for the
	// additional edge when being an intermediate hop in a route NOT the
	// final hop.
	IntermediatePayloadSize(amount lnwire.MilliSatoshi, expiry uint32,
		channelID uint64) uint64

	// EdgePolicy returns the policy of the additional edge.
	EdgePolicy() *models.CachedEdgePolicy

	// BlindedPayment returns the BlindedPayment that this additional edge
	// info was derived from. It will return nil if this edge was not
	// derived from a blinded route.
	BlindedPayment() *BlindedPayment
}

AdditionalEdge is an interface which specifies additional edges which can be appended to an existing route. Compared to normal edges of a route they provide an explicit payload size function and are introduced because blinded paths differ in their payload structure.

type AprioriConfig 

type AprioriConfig struct {
	// PenaltyHalfLife defines after how much time a penalized node or
	// channel is back at 50% probability.
	PenaltyHalfLife time.Duration

	// AprioriHopProbability is the assumed success probability of a hop in
	// a route when no other information is available.
	AprioriHopProbability float64

	// AprioriWeight is a value in the range [0, 1] that defines to what
	// extent historical results should be extrapolated to untried
	// connections. Setting it to one will completely ignore historical
	// results and always assume the configured a priori probability for
	// untried connections. A value of zero will ignore the a priori
	// probability completely and only base the probability on historical
	// results, unless there are none available.
	AprioriWeight float64

	// CapacityFraction is the fraction of a channel's capacity that we
	// consider to have liquidity. For amounts that come close to or exceed
	// the fraction, an additional penalty is applied. A value of 1.0
	// disables the capacityFactor.
	CapacityFraction float64
}

AprioriConfig contains configuration for our probability estimator.

func DefaultAprioriConfig 

func DefaultAprioriConfig() AprioriConfig

DefaultAprioriConfig returns the default configuration for the estimator.

type AprioriEstimator 

type AprioriEstimator struct {
	// AprioriConfig contains configuration options for our estimator.
	AprioriConfig
	// contains filtered or unexported fields
}

AprioriEstimator returns node and pair probabilities based on historical payment results. It uses a preconfigured success probability value for untried hops (AprioriHopProbability) and returns a high success probability for hops that could previously conduct a payment (prevSuccessProbability). Successful edges are retried until proven otherwise. Recently failed hops are penalized by an exponential time decay (PenaltyHalfLife), after which they are reconsidered for routing. If information was learned about a forwarding node, the information is taken into account to estimate a per node probability that mixes with the a priori probability (AprioriWeight).

func NewAprioriEstimator 

func NewAprioriEstimator(cfg AprioriConfig) (*AprioriEstimator, error)

NewAprioriEstimator creates a new AprioriEstimator.

func (*AprioriEstimator) Config 

func (p *AprioriEstimator) Config() estimatorConfig

Config returns the estimator's configuration.

func (*AprioriEstimator) LocalPairProbability 

func (p *AprioriEstimator) LocalPairProbability(
	now time.Time, results NodeResults, toNode route.Vertex) float64

LocalPairProbability estimates the probability of successfully traversing our own local channels to toNode.

func (*AprioriEstimator) PairProbability 

func (p *AprioriEstimator) PairProbability(now time.Time,
	results NodeResults, toNode route.Vertex, amt lnwire.MilliSatoshi,
	capacity btcutil.Amount) float64

PairProbability estimates the probability of successfully traversing to toNode based on historical payment outcomes for the from node. Those outcomes are passed in via the results parameter.

func (*AprioriEstimator) String 

func (p *AprioriEstimator) String() string

String returns the estimator's configuration as a string representation.

type AuxHtlcModifier 

type AuxHtlcModifier interface {
	// ProduceHtlcExtraData is a function that, based on the previous extra
	// data blob of an HTLC, may produce a different blob or modify the
	// amount of bitcoin this htlc should carry.
	ProduceHtlcExtraData(totalAmount lnwire.MilliSatoshi,
		htlcCustomRecords lnwire.CustomRecords) (lnwire.MilliSatoshi,
		lnwire.CustomRecords, error)
}

AuxHtlcModifier is an interface that allows the sender to modify the outgoing HTLC of a payment by changing the amount or the wire message tlv records.

type BimodalConfig 

type BimodalConfig struct {
	// BimodalNodeWeight defines how strongly other previous forwardings on
	// channels of a router should be taken into account when computing a
	// channel's probability to route. The allowed values are in the range
	// [0, 1], where a value of 0 means that only direct information about a
	// channel is taken into account.
	BimodalNodeWeight float64

	// BimodalScaleMsat describes the scale over which channels
	// statistically have some liquidity left. The value determines how
	// quickly the bimodal distribution drops off from the edges of a
	// channel. A larger value (compared to typical channel capacities)
	// means that the drop off is slow and that channel balances are
	// distributed more uniformly. A small value leads to the assumption of
	// very unbalanced channels.
	BimodalScaleMsat lnwire.MilliSatoshi

	// BimodalDecayTime is the scale for the exponential information decay
	// over time for previous successes or failures.
	BimodalDecayTime time.Duration
}

BimodalConfig contains configuration for our probability estimator.

func DefaultBimodalConfig 

func DefaultBimodalConfig() BimodalConfig

DefaultBimodalConfig returns the default configuration for the estimator.

type BimodalEstimator 

type BimodalEstimator struct {
	// BimodalConfig contains configuration options for our estimator.
	BimodalConfig
}

BimodalEstimator returns node and pair probabilities based on historical payment results based on a liquidity distribution model of the LN. The main function is to estimate the direct channel probability based on a depleted liquidity distribution model, with additional information decay over time. A per-node probability can be mixed with the direct probability, taking into account successes/failures on other channels of the forwarder.

func NewBimodalEstimator 

func NewBimodalEstimator(cfg BimodalConfig) (*BimodalEstimator, error)

NewBimodalEstimator creates a new BimodalEstimator.

func (*BimodalEstimator) Config 

func (p *BimodalEstimator) Config() estimatorConfig

config returns the current configuration of the estimator.

func (*BimodalEstimator) LocalPairProbability 

func (p *BimodalEstimator) LocalPairProbability(now time.Time,
	results NodeResults, toNode route.Vertex) float64

LocalPairProbability computes the probability to reach toNode given a set of previous learnings.

func (*BimodalEstimator) PairProbability 

func (p *BimodalEstimator) PairProbability(now time.Time,
	results NodeResults, toNode route.Vertex, amt lnwire.MilliSatoshi,
	capacity btcutil.Amount) float64

PairProbability estimates the probability of successfully traversing to toNode based on historical payment outcomes for the from node. Those outcomes are passed in via the results parameter.

func (*BimodalEstimator) String 

func (p *BimodalEstimator) String() string

String returns the estimator's configuration as a string representation.

type BlindedEdge 

type BlindedEdge struct {
	// contains filtered or unexported fields
}

BlindedEdge implements the AdditionalEdge interface. Blinded hops are viewed as additional edges because they are appended at the end of a normal route.

func NewBlindedEdge 

func NewBlindedEdge(policy *models.CachedEdgePolicy, payment *BlindedPayment,
	hopIndex int) (*BlindedEdge, error)

NewBlindedEdge constructs a new BlindedEdge which packages the policy info for a specific hop within the given blinded payment path. The hop index should correspond to the hop within the blinded payment that this edge is associated with.

func (*BlindedEdge) BlindedPayment 

func (b *BlindedEdge) BlindedPayment() *BlindedPayment

BlindedPayment returns the blinded payment that this edge is associated with.

func (*BlindedEdge) EdgePolicy 

func (b *BlindedEdge) EdgePolicy() *models.CachedEdgePolicy

EdgePolicy return the policy of the BlindedEdge.

func (*BlindedEdge) IntermediatePayloadSize 

func (b *BlindedEdge) IntermediatePayloadSize(_ lnwire.MilliSatoshi, _ uint32,
	_ uint64) uint64

IntermediatePayloadSize returns the sphinx payload size defined in BOLT04 if this edge were to be included in a route.

type BlindedPathRestrictions 

type BlindedPathRestrictions struct {
	// MinDistanceFromIntroNode is the minimum number of _real_ (non-dummy)
	// hops to include in a blinded path. Since we post-fix dummy hops, this
	// is the minimum distance between our node and the introduction node
	// of the path. This doesn't include our node, so if the minimum is 1,
	// then the path will contain at minimum our node along with an
	// introduction node hop.
	MinDistanceFromIntroNode uint8

	// NumHops is the number of hops that each blinded path should consist
	// of. If paths are found with a number of hops less that NumHops, then
	// dummy hops will be padded on to the route. This value doesn't
	// include our node, so if the maximum is 1, then the path will contain
	// our node along with an introduction node hop.
	NumHops uint8

	// MaxNumPaths is the maximum number of blinded paths to select.
	MaxNumPaths uint8

	// NodeOmissionSet is a set of nodes that should not be used within any
	// of the blinded paths that we generate.
	NodeOmissionSet fn.Set[route.Vertex]
}

BlindedPathRestrictions are a set of constraints to adhere to when choosing a set of blinded paths to this node.

type BlindedPayment 

type BlindedPayment struct {
	// BlindedPath contains the unblinded introduction point and blinded
	// hops for the blinded section of the payment.
	BlindedPath *sphinx.BlindedPath

	// BaseFee is the total base fee to be paid for payments made over the
	// blinded path.
	BaseFee uint32

	// ProportionalFeeRate is the aggregated proportional fee rate for
	// payments made over the blinded path.
	ProportionalFeeRate uint32

	// CltvExpiryDelta is the total expiry delta for the blinded path. This
	// field includes the CLTV for the blinded hops *and* the final cltv
	// delta for the receiver.
	CltvExpiryDelta uint16

	// HtlcMinimum is the highest HLTC minimum supported along the blinded
	// path (while some hops may have lower values, we're effectively
	// bounded by the highest minimum).
	HtlcMinimum uint64

	// HtlcMaximum is the lowest HTLC maximum supported along the blinded
	// path (while some hops may have higher values, we're effectively
	// bounded by the lowest maximum).
	HtlcMaximum uint64

	// Features is the set of relay features available for the payment.
	Features *lnwire.FeatureVector
}

BlindedPayment provides the path and payment parameters required to send a payment along a blinded path.

func (*BlindedPayment) Validate 

func (b *BlindedPayment) Validate() error

Validate performs validation on a blinded payment.

type BlindedPaymentPathSet 

type BlindedPaymentPathSet struct {
	// contains filtered or unexported fields
}

BlindedPaymentPathSet groups the data we need to handle sending to a set of blinded paths provided by the recipient of a payment.

NOTE: for now this only holds a single BlindedPayment. By the end of the PR series, it will handle multiple paths.

func NewBlindedPaymentPathSet 

func NewBlindedPaymentPathSet(paths []*BlindedPayment) (*BlindedPaymentPathSet,
	error)

NewBlindedPaymentPathSet constructs a new BlindedPaymentPathSet from a set of BlindedPayments.

func (*BlindedPaymentPathSet) Features 

func (s *BlindedPaymentPathSet) Features() *lnwire.FeatureVector

Features returns the set of relay features available for the payment.

func (*BlindedPaymentPathSet) FinalCLTVDelta 

func (s *BlindedPaymentPathSet) FinalCLTVDelta() uint16

FinalCLTVDelta is the minimum CLTV delta to use for the final hop on the route. In most cases this will return zero since the value is accounted for in the path's accumulated CLTVExpiryDelta. Only in the edge case of the path set only including a single path which only includes an introduction node will this return a non-zero value.

func (*BlindedPaymentPathSet) IntroNodeOnlyPath 

func (s *BlindedPaymentPathSet) IntroNodeOnlyPath() (*BlindedPayment, error)

IntroNodeOnlyPath can be called if it is expected that the path set only contains a single payment path which itself only has one hop. It errors if this is not the case.

func (*BlindedPaymentPathSet) IsIntroNode 

func (s *BlindedPaymentPathSet) IsIntroNode(source route.Vertex) bool

IsIntroNode returns true if the given vertex is an introduction node for one of the paths in the blinded payment path set.

func (*BlindedPaymentPathSet) LargestLastHopPayloadPath 

func (s *BlindedPaymentPathSet) LargestLastHopPayloadPath() *BlindedPayment

LargestLastHopPayloadPath returns the BlindedPayment in the set that has the largest last-hop payload. This is to be used for onion size estimation in path finding.

func (*BlindedPaymentPathSet) TargetPubKey 

func (s *BlindedPaymentPathSet) TargetPubKey() *btcec.PublicKey

TargetPubKey returns the public key to be used as the destination node's public key during pathfinding.

func (*BlindedPaymentPathSet) ToRouteHints 

func (s *BlindedPaymentPathSet) ToRouteHints() (RouteHints, error)

ToRouteHints converts the blinded path payment set into a RouteHints map so that the blinded payment paths can be treated like route hints throughout the code base.

type ChannelPolicy 

type ChannelPolicy struct {
	// FeeSchema holds the fee configuration for a channel.
	FeeSchema

	// TimeLockDelta is the required HTLC timelock delta to be used
	// when forwarding payments.
	TimeLockDelta uint32

	// MaxHTLC is the maximum HTLC size including fees we are allowed to
	// forward over this channel.
	MaxHTLC lnwire.MilliSatoshi

	// MinHTLC is the minimum HTLC size including fees we are allowed to
	// forward over this channel.
	MinHTLC *lnwire.MilliSatoshi
}

ChannelPolicy holds the parameters that determine the policy we enforce when forwarding payments on a channel. These parameters are communicated to the rest of the network in ChannelUpdate messages.

type ChannelRouter 

type ChannelRouter struct {
	// contains filtered or unexported fields
}

ChannelRouter is the layer 3 router within the Lightning stack. Below the ChannelRouter is the HtlcSwitch, and below that is the Bitcoin blockchain itself. The primary role of the ChannelRouter is to respond to queries for potential routes that can support a payment amount, and also general graph reachability questions. The router will prune the channel graph automatically as new blocks are discovered which spend certain known funding outpoints, thereby closing their respective channels.

func New 

func New(cfg Config) (*ChannelRouter, error)

New creates a new instance of the ChannelRouter with the specified configuration parameters. As part of initialization, if the router detects that the channel graph isn't fully in sync with the latest UTXO (since the channel graph is a subset of the UTXO set) set, then the router will proceed to fully sync to the latest state of the UTXO set.

func (*ChannelRouter) BuildRoute 

func (r *ChannelRouter) BuildRoute(amt fn.Option[lnwire.MilliSatoshi],
	hops []route.Vertex, outgoingChan *uint64, finalCltvDelta int32,
	payAddr fn.Option[[32]byte], firstHopBlob fn.Option[[]byte]) (
	*route.Route, error)

BuildRoute returns a fully specified route based on a list of pubkeys. If amount is nil, the minimum routable amount is used. To force a specific outgoing channel, use the outgoingChan parameter.

func (*ChannelRouter) FindBlindedPaths 

func (r *ChannelRouter) FindBlindedPaths(destination route.Vertex,
	amt lnwire.MilliSatoshi, probabilitySrc probabilitySource,
	restrictions *BlindedPathRestrictions) ([]*route.Route, error)

FindBlindedPaths finds a selection of paths to the destination node that can be used in blinded payment paths.

func (*ChannelRouter) FindRoute 

func (r *ChannelRouter) FindRoute(req *RouteRequest) (*route.Route, float64,
	error)

FindRoute attempts to query the ChannelRouter for the optimum path to a particular target destination to which it is able to send `amt` after factoring in channel capacities and cumulative fees along the route.

func (*ChannelRouter) PreparePayment 

func (r *ChannelRouter) PreparePayment(payment *LightningPayment) (
	PaymentSession, shards.ShardTracker, error)

PreparePayment creates the payment session and registers the payment with the control tower.

func (*ChannelRouter) SendPayment 

func (r *ChannelRouter) SendPayment(payment *LightningPayment) ([32]byte,
	*route.Route, error)

SendPayment attempts to send a payment as described within the passed LightningPayment. This function is blocking and will return either: when the payment is successful, or all candidates routes have been attempted and resulted in a failed payment. If the payment succeeds, then a non-nil Route will be returned which describes the path the successful payment traversed within the network to reach the destination. Additionally, the payment preimage will also be returned.

func (*ChannelRouter) SendPaymentAsync 

func (r *ChannelRouter) SendPaymentAsync(ctx context.Context,
	payment *LightningPayment, ps PaymentSession, st shards.ShardTracker)

SendPaymentAsync is the non-blocking version of SendPayment. The payment result needs to be retrieved via the control tower.

func (*ChannelRouter) SendToRoute 

func (r *ChannelRouter) SendToRoute(htlcHash lntypes.Hash, rt *route.Route,
	firstHopCustomRecords lnwire.CustomRecords) (*channeldb.HTLCAttempt,
	error)

SendToRoute sends a payment using the provided route and fails the payment when an error is returned from the attempt.

func (*ChannelRouter) SendToRouteSkipTempErr 

func (r *ChannelRouter) SendToRouteSkipTempErr(htlcHash lntypes.Hash,
	rt *route.Route,
	firstHopCustomRecords lnwire.CustomRecords) (*channeldb.HTLCAttempt,
	error)

SendToRouteSkipTempErr sends a payment using the provided route and fails the payment ONLY when a terminal error is returned from the attempt.

func (*ChannelRouter) Start 

func (r *ChannelRouter) Start() error

Start launches all the goroutines the ChannelRouter requires to carry out its duties. If the router has already been started, then this method is a noop.

func (*ChannelRouter) Stop 

func (r *ChannelRouter) Stop() error

Stop signals the ChannelRouter to gracefully halt all routines. This method will *block* until all goroutines have excited. If the channel router has already stopped then this method will return immediately.

type Config 

type Config struct {
	// SelfNode is the public key of the node that this channel router
	// belongs to.
	SelfNode route.Vertex

	// RoutingGraph is a graph source that will be used for pathfinding.
	RoutingGraph Graph

	// Chain is the router's source to the most up-to-date blockchain data.
	// All incoming advertised channels will be checked against the chain
	// to ensure that the channels advertised are still open.
	Chain lnwallet.BlockChainIO

	// Payer is an instance of a PaymentAttemptDispatcher and is used by
	// the router to send payment attempts onto the network, and receive
	// their results.
	Payer PaymentAttemptDispatcher

	// Control keeps track of the status of ongoing payments, ensuring we
	// can properly resume them across restarts.
	Control ControlTower

	// MissionControl is a shared memory of sorts that executions of
	// payment path finding use in order to remember which vertexes/edges
	// were pruned from prior attempts. During SendPayment execution,
	// errors sent by nodes are mapped into a vertex or edge to be pruned.
	// Each run will then take into account this set of pruned
	// vertexes/edges to reduce route failure and pass on graph information
	// gained to the next execution.
	MissionControl MissionController

	// SessionSource defines a source for the router to retrieve new payment
	// sessions.
	SessionSource PaymentSessionSource

	// GetLink is a method that allows the router to query the lower link
	// layer to determine the up-to-date available bandwidth at a
	// prospective link to be traversed. If the link isn't available, then
	// a value of zero should be returned. Otherwise, the current up-to-
	// date knowledge of the available bandwidth of the link should be
	// returned.
	GetLink getLinkQuery

	// NextPaymentID is a method that guarantees to return a new, unique ID
	// each time it is called. This is used by the router to generate a
	// unique payment ID for each payment it attempts to send, such that
	// the switch can properly handle the HTLC.
	NextPaymentID func() (uint64, error)

	// PathFindingConfig defines global path finding parameters.
	PathFindingConfig PathFindingConfig

	// Clock is mockable time provider.
	Clock clock.Clock

	// ApplyChannelUpdate can be called to apply a new channel update to the
	// graph that we received from a payment failure.
	ApplyChannelUpdate func(msg *lnwire.ChannelUpdate) bool

	// ClosedSCIDs is used by the router to fetch closed channels.
	//
	// TODO(yy): remove it once the root cause of stuck payments is found.
	ClosedSCIDs map[lnwire.ShortChannelID]struct{}

	// TrafficShaper is an optional traffic shaper that can be used to
	// control the outgoing channel of a payment.
	TrafficShaper fn.Option[TlvTrafficShaper]
}

Config defines the configuration for the ChannelRouter. ALL elements within the configuration MUST be non-nil for the ChannelRouter to carry out its duties.

type ControlTower 

type ControlTower interface {
	// This method checks that no succeeded payment exist for this payment
	// hash.
	InitPayment(lntypes.Hash, *channeldb.PaymentCreationInfo) error

	// DeleteFailedAttempts removes all failed HTLCs from the db. It should
	// be called for a given payment whenever all inflight htlcs are
	// completed, and the payment has reached a final settled state.
	DeleteFailedAttempts(lntypes.Hash) error

	// RegisterAttempt atomically records the provided HTLCAttemptInfo.
	RegisterAttempt(lntypes.Hash, *channeldb.HTLCAttemptInfo) error

	// SettleAttempt marks the given attempt settled with the preimage. If
	// this is a multi shard payment, this might implicitly mean the the
	// full payment succeeded.
	//
	// After invoking this method, InitPayment should always return an
	// error to prevent us from making duplicate payments to the same
	// payment hash. The provided preimage is atomically saved to the DB
	// for record keeping.
	SettleAttempt(lntypes.Hash, uint64, *channeldb.HTLCSettleInfo) (
		*channeldb.HTLCAttempt, error)

	// FailAttempt marks the given payment attempt failed.
	FailAttempt(lntypes.Hash, uint64, *channeldb.HTLCFailInfo) (
		*channeldb.HTLCAttempt, error)

	// FetchPayment fetches the payment corresponding to the given payment
	// hash.
	FetchPayment(paymentHash lntypes.Hash) (dbMPPayment, error)

	// FailPayment transitions a payment into the Failed state, and records
	// the ultimate reason the payment failed. Note that this should only
	// be called when all active attempts are already failed. After
	// invoking this method, InitPayment should return nil on its next call
	// for this payment hash, allowing the user to make a subsequent
	// payment.
	FailPayment(lntypes.Hash, channeldb.FailureReason) error

	// FetchInFlightPayments returns all payments with status InFlight.
	FetchInFlightPayments() ([]*channeldb.MPPayment, error)

	// SubscribePayment subscribes to updates for the payment with the given
	// hash. A first update with the current state of the payment is always
	// sent out immediately.
	SubscribePayment(paymentHash lntypes.Hash) (ControlTowerSubscriber,
		error)

	// SubscribeAllPayments subscribes to updates for all payments. A first
	// update with the current state of every inflight payment is always
	// sent out immediately.
	SubscribeAllPayments() (ControlTowerSubscriber, error)
}

ControlTower tracks all outgoing payments made, whose primary purpose is to prevent duplicate payments to the same payment hash. In production, a persistent implementation is preferred so that tracking can survive across restarts. Payments are transitioned through various payment states, and the ControlTower interface provides access to driving the state transitions.

func NewControlTower 

func NewControlTower(db *channeldb.PaymentControl) ControlTower

NewControlTower creates a new instance of the controlTower.

type ControlTowerSubscriber 

type ControlTowerSubscriber interface {
	// Updates is the channel over which *channeldb.MPPayment updates can be
	// received.
	Updates() <-chan interface{}

	// Close signals that the subscriber is no longer interested in updates.
	Close()
}

ControlTowerSubscriber contains the state for a payment update subscriber.

type DirectedNodePair 

type DirectedNodePair struct {
	From, To route.Vertex
}

DirectedNodePair stores a directed pair of nodes.

func NewDirectedNodePair 

func NewDirectedNodePair(from, to route.Vertex) DirectedNodePair

NewDirectedNodePair instantiates a new DirectedNodePair struct.

func (DirectedNodePair) Reverse 

func (d DirectedNodePair) Reverse() DirectedNodePair

Reverse returns a reversed copy of the pair.

func (DirectedNodePair) String 

func (d DirectedNodePair) String() string

String converts a node pair to its human readable representation.

type EdgeLocator 

type EdgeLocator struct {
	// ChannelID is the channel of this edge.
	ChannelID uint64

	// Direction takes the value of 0 or 1 and is identical in definition to
	// the channel direction flag. A value of 0 means the direction from the
	// lower node pubkey to the higher.
	Direction uint8
}

EdgeLocator is a struct used to identify a specific edge.

func (*EdgeLocator) String 

func (e *EdgeLocator) String() string

String returns a human-readable version of the edgeLocator values.

type ErrNoChannel 

type ErrNoChannel struct {
	// contains filtered or unexported fields
}

ErrNoChannel is returned when a route cannot be built because there are no channels that satisfy all requirements.

func (ErrNoChannel) Error 

func (e ErrNoChannel) Error() string

Error returns a human-readable string describing the error.

type Estimator 

type Estimator interface {
	// PairProbability estimates the probability of successfully traversing
	// to toNode based on historical payment outcomes for the from node.
	// Those outcomes are passed in via the results parameter.
	PairProbability(now time.Time, results NodeResults,
		toNode route.Vertex, amt lnwire.MilliSatoshi,
		capacity btcutil.Amount) float64

	// LocalPairProbability estimates the probability of successfully
	// traversing our own local channels to toNode.
	LocalPairProbability(now time.Time, results NodeResults,
		toNode route.Vertex) float64

	// Config returns the estimator's configuration.
	Config() estimatorConfig

	// String returns the string representation of the estimator's
	// configuration.
	String() string
}

Estimator estimates the probability to reach a node.

type FeeSchema 

type FeeSchema struct {
	// BaseFee is the base amount of milli-satoshis that will be chained
	// for ANY payment forwarded.
	BaseFee lnwire.MilliSatoshi

	// FeeRate is the rate that will be charged for forwarding payments.
	// This value should be interpreted as the numerator for a fraction
	// (fixed point arithmetic) whose denominator is 1 million. As a result
	// the effective fee rate charged per mSAT will be: (amount *
	// FeeRate/1,000,000).
	FeeRate uint32

	// InboundFee is the inbound fee schedule that applies to forwards
	// coming in through a channel to which this FeeSchema pertains.
	InboundFee fn.Option[models.InboundFee]
}

FeeSchema is the set fee configuration for a Lightning Node on the network. Using the coefficients described within the schema, the required fee to forward outgoing payments can be derived.

type Graph 

type Graph interface {
	// ForEachNodeChannel calls the callback for every channel of the given
	// node.
	ForEachNodeChannel(nodePub route.Vertex,
		cb func(channel *channeldb.DirectedChannel) error) error

	// FetchNodeFeatures returns the features of the given node.
	FetchNodeFeatures(nodePub route.Vertex) (*lnwire.FeatureVector, error)
}

Graph is an abstract interface that provides information about nodes and edges to pathfinding.

type GraphSessionFactory 

type GraphSessionFactory interface {
	// NewGraphSession will produce a new Graph to use for a path-finding
	// session. It returns the Graph along with a call-back that must be
	// called once Graph access is complete. This call-back will close any
	// read-only transaction that was created at Graph construction time.
	NewGraphSession() (Graph, func() error, error)
}

GraphSessionFactory can be used to produce a new Graph instance which can then be used for a path-finding session. Depending on the implementation, the Graph session will represent a DB connection where a read-lock is being held across calls to the backing Graph.

type LightningPayment 

type LightningPayment struct {
	// Target is the node in which the payment should be routed towards.
	Target route.Vertex

	// Amount is the value of the payment to send through the network in
	// milli-satoshis.
	Amount lnwire.MilliSatoshi

	// FeeLimit is the maximum fee in millisatoshis that the payment should
	// accept when sending it through the network. The payment will fail
	// if there isn't a route with lower fees than this limit.
	FeeLimit lnwire.MilliSatoshi

	// CltvLimit is the maximum time lock that is allowed for attempts to
	// complete this payment.
	CltvLimit uint32

	// FinalCLTVDelta is the CTLV expiry delta to use for the _final_ hop
	// in the route. This means that the final hop will have a CLTV delta
	// of at least: currentHeight + FinalCLTVDelta.
	FinalCLTVDelta uint16

	// PayAttemptTimeout is a timeout value that we'll use to determine
	// when we should should abandon the payment attempt after consecutive
	// payment failure. This prevents us from attempting to send a payment
	// indefinitely. A zero value means the payment will never time out.
	//
	// TODO(halseth): make wallclock time to allow resume after startup.
	PayAttemptTimeout time.Duration

	// RouteHints represents the different routing hints that can be used to
	// assist a payment in reaching its destination successfully. These
	// hints will act as intermediate hops along the route.
	//
	// NOTE: This is optional unless required by the payment. When providing
	// multiple routes, ensure the hop hints within each route are chained
	// together and sorted in forward order in order to reach the
	// destination successfully. This is mutually exclusive to the
	// BlindedPayment field.
	RouteHints [][]zpay32.HopHint

	// BlindedPathSet holds the information about a set of blinded paths to
	// the payment recipient. This is mutually exclusive to the RouteHints
	// field.
	BlindedPathSet *BlindedPaymentPathSet

	// OutgoingChannelIDs is the list of channels that are allowed for the
	// first hop. If nil, any channel may be used.
	OutgoingChannelIDs []uint64

	// LastHop is the pubkey of the last node before the final destination
	// is reached. If nil, any node may be used.
	LastHop *route.Vertex

	// DestFeatures specifies the set of features we assume the final node
	// has for pathfinding. Typically, these will be taken directly from an
	// invoice, but they can also be manually supplied or assumed by the
	// sender. If a nil feature vector is provided, the router will try to
	// fall back to the graph in order to load a feature vector for a node
	// in the public graph.
	DestFeatures *lnwire.FeatureVector

	// PaymentAddr is the payment address specified by the receiver. This
	// field should be a random 32-byte nonce presented in the receiver's
	// invoice to prevent probing of the destination.
	PaymentAddr fn.Option[[32]byte]

	// PaymentRequest is an optional payment request that this payment is
	// attempting to complete.
	PaymentRequest []byte

	// DestCustomRecords are TLV records that are to be sent to the final
	// hop in the new onion payload format. If the destination does not
	// understand this new onion payload format, then the payment will
	// fail.
	DestCustomRecords record.CustomSet

	// FirstHopCustomRecords are the TLV records that are to be sent to the
	// first hop of this payment. These records will be transmitted via the
	// wire message and therefore do not affect the onion payload size.
	FirstHopCustomRecords lnwire.CustomRecords

	// MaxParts is the maximum number of partial payments that may be used
	// to complete the full amount.
	MaxParts uint32

	// MaxShardAmt is the largest shard that we'll attempt to split using.
	// If this field is set, and we need to split, rather than attempting
	// half of the original payment amount, we'll use this value if half
	// the payment amount is greater than it.
	//
	// NOTE: This field is _optional_.
	MaxShardAmt *lnwire.MilliSatoshi

	// TimePref is the time preference for this payment. Set to -1 to
	// optimize for fees only, to 1 to optimize for reliability only or a
	// value in between for a mix.
	TimePref float64

	// Metadata is additional data that is sent along with the payment to
	// the payee.
	Metadata []byte
	// contains filtered or unexported fields
}

LightningPayment describes a payment to be sent through the network to the final destination.

func (*LightningPayment) Identifier 

func (l *LightningPayment) Identifier() [32]byte

Identifier returns a 32-byte slice that uniquely identifies this single payment. For non-AMP payments this will be the payment hash, for AMP payments this will be the used SetID.

func (*LightningPayment) SetAMP 

func (l *LightningPayment) SetAMP(amp *AMPOptions) error

SetAMP sets the given AMP options for the payment.

func (*LightningPayment) SetPaymentHash 

func (l *LightningPayment) SetPaymentHash(hash lntypes.Hash) error

SetPaymentHash sets the given hash as the payment's overall hash. This should only be used for non-AMP payments.

type MissionControl 

type MissionControl struct {
	sync.Mutex
	// contains filtered or unexported fields
}

MissionControl contains state which summarizes the past attempts of HTLC routing by external callers when sending payments throughout the network. It acts as a shared memory during routing attempts with the goal to optimize the payment attempt success rate.

Failed payment attempts are reported to mission control. These reports are used to track the time of the last node or channel level failure. The time since the last failure is used to estimate a success probability that is fed into the path finding process for subsequent payment attempts.

func NewMissionControl 

func NewMissionControl(db kvdb.Backend, self route.Vertex,
	cfg *MissionControlConfig) (*MissionControl, error)

NewMissionControl returns a new instance of missionControl.

func (*MissionControl) GetConfig 

func (m *MissionControl) GetConfig() *MissionControlConfig

GetConfig returns the config that mission control is currently configured with. All fields are copied by value, so we do not need to worry about mutation.

func (*MissionControl) GetHistorySnapshot 

func (m *MissionControl) GetHistorySnapshot() *MissionControlSnapshot

GetHistorySnapshot takes a snapshot from the current mission control state and actual probability estimates.

func (*MissionControl) GetPairHistorySnapshot 

func (m *MissionControl) GetPairHistorySnapshot(
	fromNode, toNode route.Vertex) TimedPairResult

GetPairHistorySnapshot returns the stored history for a given node pair.

func (*MissionControl) GetProbability 

func (m *MissionControl) GetProbability(fromNode, toNode route.Vertex,
	amt lnwire.MilliSatoshi, capacity btcutil.Amount) float64

GetProbability is expected to return the success probability of a payment from fromNode along edge.

func (*MissionControl) ImportHistory 

func (m *MissionControl) ImportHistory(history *MissionControlSnapshot,
	force bool) error

ImportHistory imports the set of mission control results provided to our in-memory state. These results are not persisted, so will not survive restarts.

func (*MissionControl) ReportPaymentFail 

func (m *MissionControl) ReportPaymentFail(paymentID uint64, rt *route.Route,
	failureSourceIdx *int, failure lnwire.FailureMessage) (
	*channeldb.FailureReason, error)

ReportPaymentFail reports a failed payment to mission control as input for future probability estimates. The failureSourceIdx argument indicates the failure source. If it is nil, the failure source is unknown. This function returns a reason if this failure is a final failure. In that case no further payment attempts need to be made.

func (*MissionControl) ReportPaymentSuccess 

func (m *MissionControl) ReportPaymentSuccess(paymentID uint64,
	rt *route.Route) error

ReportPaymentSuccess reports a successful payment to mission control as input for future probability estimates.

func (*MissionControl) ResetHistory 

func (m *MissionControl) ResetHistory() error

ResetHistory resets the history of MissionControl returning it to a state as if no payment attempts have been made.

func (*MissionControl) RunStoreTicker 

func (m *MissionControl) RunStoreTicker()

RunStoreTicker runs the mission control store's ticker.

func (*MissionControl) SetConfig 

func (m *MissionControl) SetConfig(cfg *MissionControlConfig) error

SetConfig validates the config provided and updates mission control's config if it is valid.

func (*MissionControl) StopStoreTicker 

func (m *MissionControl) StopStoreTicker()

StopStoreTicker stops the mission control store's ticker.

type MissionControlConfig 

type MissionControlConfig struct {
	// Estimator gives probability estimates for node pairs.
	Estimator Estimator

	// MaxMcHistory defines the maximum number of payment results that are
	// held on disk.
	MaxMcHistory int

	// McFlushInterval defines the ticker interval when we flush the
	// accumulated state to the DB.
	McFlushInterval time.Duration

	// MinFailureRelaxInterval is the minimum time that must have passed
	// since the previously recorded failure before the failure amount may
	// be raised.
	MinFailureRelaxInterval time.Duration
}

MissionControlConfig defines parameters that control mission control behaviour.

func (*MissionControlConfig) String 

func (c *MissionControlConfig) String() string

String returns a string representation of a mission control config.

type MissionControlPairSnapshot 

type MissionControlPairSnapshot struct {
	// Pair is the node pair of which the state is described.
	Pair DirectedNodePair

	// TimedPairResult contains the data for this pair.
	TimedPairResult
}

MissionControlPairSnapshot contains a snapshot of the current node pair state in mission control.

type MissionControlSnapshot 

type MissionControlSnapshot struct {
	// Pairs is a list of channels for which specific information is
	// logged.
	Pairs []MissionControlPairSnapshot
}

MissionControlSnapshot contains a snapshot of the current state of mission control.

type MissionController 

type MissionController interface {
	// ReportPaymentFail reports a failed payment to mission control as
	// input for future probability estimates. It returns a bool indicating
	// whether this error is a final error and no further payment attempts
	// need to be made.
	ReportPaymentFail(attemptID uint64, rt *route.Route,
		failureSourceIdx *int, failure lnwire.FailureMessage) (
		*channeldb.FailureReason, error)

	// ReportPaymentSuccess reports a successful payment to mission control
	// as input for future probability estimates.
	ReportPaymentSuccess(attemptID uint64, rt *route.Route) error

	// GetProbability is expected to return the success probability of a
	// payment from fromNode along edge.
	GetProbability(fromNode, toNode route.Vertex,
		amt lnwire.MilliSatoshi, capacity btcutil.Amount) float64
}

MissionController is an interface that exposes failure reporting and probability estimation.

type NodeResults 

type NodeResults map[route.Vertex]TimedPairResult

NodeResults contains previous results from a node to its peers.

type PathFindingConfig 

type PathFindingConfig struct {
	// AttemptCost is the fixed virtual cost in path finding of a failed
	// payment attempt. It is used to trade off potentially better routes
	// against their probability of succeeding.
	AttemptCost lnwire.MilliSatoshi

	// AttemptCostPPM is the proportional virtual cost in path finding of a
	// failed payment attempt. It is used to trade off potentially better
	// routes against their probability of succeeding. This parameter is
	// expressed in parts per million of the total payment amount.
	AttemptCostPPM int64

	// MinProbability defines the minimum success probability of the
	// returned route.
	MinProbability float64
}

PathFindingConfig defines global parameters that control the trade-off in path finding between fees and probability.

type PayloadSizeFunc 

type PayloadSizeFunc func(amount lnwire.MilliSatoshi, expiry uint32,
	channelID uint64) uint64

PayloadSizeFunc defines the interface for the payload size function.

type PaymentAttemptDispatcher 

type PaymentAttemptDispatcher interface {
	// SendHTLC is a function that directs a link-layer switch to
	// forward a fully encoded payment to the first hop in the route
	// denoted by its public key. A non-nil error is to be returned if the
	// payment was unsuccessful.
	SendHTLC(firstHop lnwire.ShortChannelID,
		attemptID uint64,
		htlcAdd *lnwire.UpdateAddHTLC) error

	// GetAttemptResult returns the result of the payment attempt with
	// the given attemptID. The paymentHash should be set to the payment's
	// overall hash, or in case of AMP payments the payment's unique
	// identifier.
	//
	// The method returns a channel where the payment result will be sent
	// when available, or an error is encountered during forwarding. When a
	// result is received on the channel, the HTLC is guaranteed to no
	// longer be in flight.  The switch shutting down is signaled by
	// closing the channel. If the attemptID is unknown,
	// ErrPaymentIDNotFound will be returned.
	GetAttemptResult(attemptID uint64, paymentHash lntypes.Hash,
		deobfuscator htlcswitch.ErrorDecrypter) (
		<-chan *htlcswitch.PaymentResult, error)

	// CleanStore calls the underlying result store, telling it is safe to
	// delete all entries except the ones in the keepPids map. This should
	// be called periodically to let the switch clean up payment results
	// that we have handled.
	// NOTE: New payment attempts MUST NOT be made after the keepPids map
	// has been created and this method has returned.
	CleanStore(keepPids map[uint64]struct{}) error

	// HasAttemptResult reads the network result store to fetch the
	// specified attempt. Returns true if the attempt result exists.
	//
	// NOTE: This method is used and should only be used by the router to
	// resume payments during startup. It can be viewed as a subset of
	// `GetAttemptResult` in terms of its functionality, and can be removed
	// once we move the construction of `UpdateAddHTLC` and
	// `ErrorDecrypter` into `htlcswitch`.
	HasAttemptResult(attemptID uint64) (bool, error)
}

PaymentAttemptDispatcher is used by the router to send payment attempts onto the network, and receive their results.

type PaymentSession 

type PaymentSession interface {
	// RequestRoute returns the next route to attempt for routing the
	// specified HTLC payment to the target node. The returned route should
	// carry at most maxAmt to the target node, and pay at most feeLimit in
	// fees. It can carry less if the payment is MPP. The activeShards
	// argument should be set to instruct the payment session about the
	// number of in flight HTLCS for the payment, such that it can choose
	// splitting strategy accordingly.
	//
	// A noRouteError is returned if a non-critical error is encountered
	// during path finding.
	RequestRoute(maxAmt, feeLimit lnwire.MilliSatoshi,
		activeShards, height uint32,
		firstHopCustomRecords lnwire.CustomRecords) (*route.Route,
		error)

	// UpdateAdditionalEdge takes an additional channel edge policy
	// (private channels) and applies the update from the message. Returns
	// a boolean to indicate whether the update has been applied without
	// error.
	UpdateAdditionalEdge(msg *lnwire.ChannelUpdate, pubKey *btcec.PublicKey,
		policy *models.CachedEdgePolicy) bool

	// GetAdditionalEdgePolicy uses the public key and channel ID to query
	// the ephemeral channel edge policy for additional edges. Returns a nil
	// if nothing found.
	GetAdditionalEdgePolicy(pubKey *btcec.PublicKey,
		channelID uint64) *models.CachedEdgePolicy
}

PaymentSession is used during SendPayment attempts to provide routes to attempt. It also defines methods to give the PaymentSession additional information learned during the previous attempts.

type PaymentSessionSource 

type PaymentSessionSource interface {
	// NewPaymentSession creates a new payment session that will produce
	// routes to the given target. An optional set of routing hints can be
	// provided in order to populate additional edges to explore when
	// finding a path to the payment's destination.
	NewPaymentSession(p *LightningPayment,
		firstHopBlob fn.Option[tlv.Blob],
		trafficShaper fn.Option[TlvTrafficShaper]) (PaymentSession,
		error)

	// NewPaymentSessionEmpty creates a new paymentSession instance that is
	// empty, and will be exhausted immediately. Used for failure reporting
	// to missioncontrol for resumed payment we don't want to make more
	// attempts for.
	NewPaymentSessionEmpty() PaymentSession
}

PaymentSessionSource is an interface that defines a source for the router to retrieve new payment sessions.

type PrivateEdge 

type PrivateEdge struct {
	// contains filtered or unexported fields
}

PrivateEdge implements the AdditionalEdge interface. As the name implies it is used for private route hints that the receiver adds for example to an invoice.

func (*PrivateEdge) BlindedPayment 

func (p *PrivateEdge) BlindedPayment() *BlindedPayment

BlindedPayment is a no-op for a PrivateEdge since it is not associated with a blinded payment. This will thus return nil.

func (*PrivateEdge) EdgePolicy 

func (p *PrivateEdge) EdgePolicy() *models.CachedEdgePolicy

EdgePolicy return the policy of the PrivateEdge.

func (*PrivateEdge) IntermediatePayloadSize 

func (p *PrivateEdge) IntermediatePayloadSize(amount lnwire.MilliSatoshi,
	expiry uint32, channelID uint64) uint64

IntermediatePayloadSize returns the sphinx payload size defined in BOLT04 if this edge were to be included in a route.

type RestrictParams 

type RestrictParams struct {
	// ProbabilitySource is a callback that is expected to return the
	// success probability of traversing the channel from the node.
	ProbabilitySource func(route.Vertex, route.Vertex,
		lnwire.MilliSatoshi, btcutil.Amount) float64

	// FeeLimit is a maximum fee amount allowed to be used on the path from
	// the source to the target.
	FeeLimit lnwire.MilliSatoshi

	// OutgoingChannelIDs is the list of channels that are allowed for the
	// first hop. If nil, any channel may be used.
	OutgoingChannelIDs []uint64

	// LastHop is the pubkey of the last node before the final destination
	// is reached. If nil, any node may be used.
	LastHop *route.Vertex

	// CltvLimit is the maximum time lock of the route excluding the final
	// ctlv. After path finding is complete, the caller needs to increase
	// all cltv expiry heights with the required final cltv delta.
	CltvLimit uint32

	// DestCustomRecords contains the custom records to drop off at the
	// final hop, if any.
	DestCustomRecords record.CustomSet

	// DestFeatures is a feature vector describing what the final hop
	// supports. If none are provided, pathfinding will try to inspect any
	// features on the node announcement instead.
	DestFeatures *lnwire.FeatureVector

	// PaymentAddr is a random 32-byte value generated by the receiver to
	// mitigate probing vectors and payment sniping attacks on overpaid
	// invoices.
	PaymentAddr fn.Option[[32]byte]

	// Amp signals to the pathfinder that this payment is an AMP payment
	// and therefore it needs to account for additional AMP data in the
	// final hop payload size calculation.
	Amp *AMPOptions

	// Metadata is additional data that is sent along with the payment to
	// the payee.
	Metadata []byte

	// BlindedPaymentPathSet is necessary to determine the hop size of the
	// last/exit hop.
	BlindedPaymentPathSet *BlindedPaymentPathSet

	// FirstHopCustomRecords includes any records that should be included in
	// the update_add_htlc message towards our peer.
	FirstHopCustomRecords lnwire.CustomRecords
}

RestrictParams wraps the set of restrictions passed to findPath that the found path must adhere to.

type RouteHints 

type RouteHints map[route.Vertex][]AdditionalEdge

RouteHints is an alias type for a set of route hints, with the source node as the map's key and the details of the hint(s) in the edge policy.

type RouteRequest 

type RouteRequest struct {
	// Source is the node that the path originates from.
	Source route.Vertex

	// Target is the node that the path terminates at. If the route
	// includes a blinded path, target will be the blinded node id of the
	// final hop in the blinded route.
	Target route.Vertex

	// Amount is the Amount in millisatoshis to be delivered to the target
	// node.
	Amount lnwire.MilliSatoshi

	// TimePreference expresses the caller's time preference for
	// pathfinding.
	TimePreference float64

	// Restrictions provides a set of additional Restrictions that the
	// route must adhere to.
	Restrictions *RestrictParams

	// CustomRecords is a set of custom tlv records to include for the
	// final hop.
	CustomRecords record.CustomSet

	// RouteHints contains an additional set of edges to include in our
	// view of the graph. This may either be a set of hints for private
	// channels or a "virtual" hop hint that represents a blinded route.
	RouteHints RouteHints

	// FinalExpiry is the cltv delta for the final hop. If paying to a
	// blinded path, this value is a duplicate of the delta provided
	// in blinded payment.
	FinalExpiry uint16

	// BlindedPathSet contains a set of optional blinded paths and
	// parameters used to reach a target node blinded paths. This field is
	// mutually exclusive with the Target field.
	BlindedPathSet *BlindedPaymentPathSet
}

RouteRequest contains the parameters for a pathfinding request. It may describe a request to make a regular payment or one to a blinded path (incdicated by a non-nil BlindedPayment field).

func NewRouteRequest 

func NewRouteRequest(source route.Vertex, target *route.Vertex,
	amount lnwire.MilliSatoshi, timePref float64,
	restrictions *RestrictParams, customRecords record.CustomSet,
	routeHints RouteHints, blindedPathSet *BlindedPaymentPathSet,
	finalExpiry uint16) (*RouteRequest, error)

NewRouteRequest produces a new route request for a regular payment or one to a blinded route, validating that the target, routeHints and finalExpiry parameters are mutually exclusive with the blindedPayment parameter (which contains these values for blinded payments).

type SessionSource 

type SessionSource struct {
	// GraphSessionFactory can be used to gain access to a Graph session.
	// If the backing DB allows it, this will mean that a read transaction
	// is being held during the use of the session.
	GraphSessionFactory GraphSessionFactory

	// SourceNode is the graph's source node.
	SourceNode *channeldb.LightningNode

	// GetLink is a method that allows querying the lower link layer
	// to determine the up to date available bandwidth at a prospective link
	// to be traversed. If the link isn't available, then a value of zero
	// should be returned. Otherwise, the current up to date knowledge of
	// the available bandwidth of the link should be returned.
	GetLink getLinkQuery

	// MissionControl is a shared memory of sorts that executions of payment
	// path finding use in order to remember which vertexes/edges were
	// pruned from prior attempts. During payment execution, errors sent by
	// nodes are mapped into a vertex or edge to be pruned. Each run will
	// then take into account this set of pruned vertexes/edges to reduce
	// route failure and pass on graph information gained to the next
	// execution.
	MissionControl MissionController

	// PathFindingConfig defines global parameters that control the
	// trade-off in path finding between fees and probability.
	PathFindingConfig PathFindingConfig
}

SessionSource defines a source for the router to retrieve new payment sessions.

func (*SessionSource) NewPaymentSession 

func (m *SessionSource) NewPaymentSession(p *LightningPayment,
	firstHopBlob fn.Option[tlv.Blob],
	trafficShaper fn.Option[TlvTrafficShaper]) (PaymentSession, error)

NewPaymentSession creates a new payment session backed by the latest prune view from Mission Control. An optional set of routing hints can be provided in order to populate additional edges to explore when finding a path to the payment's destination.

func (*SessionSource) NewPaymentSessionEmpty 

func (m *SessionSource) NewPaymentSessionEmpty() PaymentSession

NewPaymentSessionEmpty creates a new paymentSession instance that is empty, and will be exhausted immediately. Used for failure reporting to missioncontrol for resumed payment we don't want to make more attempts for.

type TimedPairResult 

type TimedPairResult struct {
	// FailTime is the time of the last failure.
	FailTime time.Time

	// FailAmt is the amount of the last failure. This amount may be pushed
	// up if a later success is higher than the last failed amount.
	FailAmt lnwire.MilliSatoshi

	// SuccessTime is the time of the last success.
	SuccessTime time.Time

	// SuccessAmt is the highest amount that successfully forwarded. This
	// isn't necessarily the last success amount. The value of this field
	// may also be pushed down if a later failure is lower than the highest
	// success amount. Because of this, SuccessAmt may not match
	// SuccessTime.
	SuccessAmt lnwire.MilliSatoshi
}

TimedPairResult describes a timestamped pair result.

type TlvTrafficShaper 

type TlvTrafficShaper interface {
	AuxHtlcModifier

	// ShouldHandleTraffic is called in order to check if the channel
	// identified by the provided channel ID may have external mechanisms
	// that would allow it to carry out the payment.
	ShouldHandleTraffic(cid lnwire.ShortChannelID,
		fundingBlob fn.Option[tlv.Blob]) (bool, error)

	// PaymentBandwidth returns the available bandwidth for a custom channel
	// decided by the given channel aux blob and HTLC blob. A return value
	// of 0 means there is no bandwidth available. To find out if a channel
	// is a custom channel that should be handled by the traffic shaper, the
	// HandleTraffic method should be called first.
	PaymentBandwidth(htlcBlob, commitmentBlob fn.Option[tlv.Blob],
		linkBandwidth,
		htlcAmt lnwire.MilliSatoshi) (lnwire.MilliSatoshi, error)
}

TlvTrafficShaper is an interface that allows the sender to determine if a payment should be carried by a channel based on the TLV records that may be present in the `update_add_htlc` message or the channel commitment itself.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.