routing

README

routing

[] (https://travis-ci.org/lightningnetwork/lnd) [] (https://github.com/lightningnetwork/lnd/blob/master/LICENSE) [] (http://godoc.org/github.com/lightningnetwork/lnd/routing)

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
• Variables
• func DisableLog()
• func SetLogWriter(w io.Writer, level string) error
• func UseLogger(logger btclog.Logger)
• type ChannelRouter
  • func New(cfg Config) (*ChannelRouter, error)
  • func (r *ChannelRouter) FindRoute(target *btcec.PublicKey, amt btcutil.Amount) (*Route, error)
  • func (r *ChannelRouter) ProcessRoutingMessage(msg lnwire.Message, src *btcec.PublicKey)
  • func (r *ChannelRouter) SendPayment() error
  • func (r *ChannelRouter) Start() error
  • func (r *ChannelRouter) Stop() error
  • func (r *ChannelRouter) SubscribeTopology() (*TopologyClient, error)
  • func (r *ChannelRouter) SynchronizeNode(pub *btcec.PublicKey)
• type Config
• type FeeSchema
• type Hop
• type Route
• type TopologyChange
• type TopologyClient

Constants

const (
	// HopLimit is the maximum number hops that is permissible as a route.
	// Any potential paths found that lie above this limit will be rejected
	// with an error. This value is computed using the current fixed-size
	// packet length of the Sphinx construction.
	HopLimit = 20
)

Variables

var (
	// ErrNoPathFound is returned when a path to the target destination
	// does not exist in the graph.
	ErrNoPathFound = errors.New("unable to find a path to " +
		"destination")

	// ErrInsufficientCapacity is returned when a path if found, yet the
	// capacity of one of the channels in the path is insufficient to carry
	// the payment.
	ErrInsufficientCapacity = errors.New("channel graph has " +
		"insufficient capacity for the payment")

	// ErrMaxHopsExceeded is returned when a candidate path is found, but
	// the length of that path exceeds HopLimit.
	ErrMaxHopsExceeded = errors.New("potential path has too many hops")

	// ErrTargetNotInNetwork is returned when a
	ErrTargetNotInNetwork = errors.New("target not found")
)

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func SetLogWriter

func SetLogWriter(w io.Writer, level string) error

SetLogWriter uses a specified io.Writer to output package logging info. This allows a caller to direct package logging output without needing a dependency on seelog. If the caller is also using btclog, UseLogger should be used instead.

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.

Types

type ChannelRouter

type ChannelRouter struct {
	sync.RWMutex
	// 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. Additionally, it's the duty of the router to sync up newly connected peers with the latest state of the channel graph.

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) FindRoute

func (r *ChannelRouter) FindRoute(target *btcec.PublicKey, amt btcutil.Amount) (*Route, error)

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

func (*ChannelRouter) ProcessRoutingMessage

func (r *ChannelRouter) ProcessRoutingMessage(msg lnwire.Message, src *btcec.PublicKey)

ProcessRoutingMessags sends a new routing message along with the peer that sent the routing message to the ChannelRouter. The announcement will be processed then added to a queue for batched tickled announcement to all connected peers.

TODO(roasbeef): need to move to discovery package

func (*ChannelRouter) SendPayment

func (r *ChannelRouter) SendPayment() error

SendPayment...

TODO(roasbeef): pipe through the htlcSwitch, move the payment storage info to the router, add interface for payment storage TODO(roasbeef): add version that takes a route object

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.

func (*ChannelRouter) SubscribeTopology

func (r *ChannelRouter) SubscribeTopology() (*TopologyClient, error)

SubscribeTopology....

func (*ChannelRouter) SynchronizeNode

func (r *ChannelRouter) SynchronizeNode(pub *btcec.PublicKey)

SynchronizeNode sends a message to the ChannelRouter indicating it should synchronize routing state with the target node. This method is to be utilized when a node connections for the first time to provide it with the latest channel graph state.

type Config

type Config struct {
	// Graph is the channel graph that the ChannelRouter will use to gather
	// metrics from and also to carry out path finding queries.
	// TODO(roasbeef): make into an interface
	Graph *channeldb.ChannelGraph

	// 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.
	// TODO(roasbeef): remove after discovery service is in
	Chain lnwallet.BlockChainIO

	// Notifier is an instance of the ChainNotifier that the router uses to
	// received notifications of incoming blocks. With each new incoming
	// block found, the router may be able to partially prune the channel
	// graph as channels may have been pruned.
	// TODO(roasbeef): could possibly just replace this with an epoch
	// channel.
	Notifier chainntnfs.ChainNotifier

	// FeeSchema is the set fee schema that will be announced on to the
	// network.
	// TODO(roasbeef): should either be in discovery or switch
	FeeSchema *FeeSchema

	// Broadcast is a function that is used to broadcast a particular set
	// of messages to all peers that the daemon is connected to. If
	// supplied, the exclude parameter indicates that the target peer should
	// be excluded from the broadcast.
	Broadcast func(exclude *btcec.PublicKey, msg ...lnwire.Message) error

	// SendMessages is a function which allows the ChannelRouter to send a
	// set of messages to a particular peer identified by the target public
	// key.
	SendMessages func(target *btcec.PublicKey, msg ...lnwire.Message) error
}

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 FeeSchema

type FeeSchema struct {

	// BaseFee is the base amount that will be chained for ANY payment
	// forwarded.
	BaseFee btcutil.Amount

	// FeeRate is the rate that will be charged for forwarding payments.
	// The fee rate has a granularity of 1/1000 th of a mili-satoshi, or a
	// millionth of a satoshi.
	FeeRate btcutil.Amount
}

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

TODO(roasbeef): should be in switch instead?

type Hop

type Hop struct {
	// Channels is the active payment channel that this hop will travel
	// along.
	Channel *channeldb.ChannelEdge

	// TimeLockDelta is the delta that this hop will subtract from the HTLC
	// before extending it to the next hop in the route.
	TimeLockDelta uint16

	// AmtToForward is the amount that this hop will forward to the next
	// hop. This value is less than the value that the incoming HTLC
	// carries as a fee will be subtracted by the hop.
	AmtToForward btcutil.Amount

	// Fee is the total fee that this hop will subtract from the incoming
	// payment, this difference nets the hop fees for forwarding the
	// payment.
	Fee btcutil.Amount
}

Hop represents the forwarding details at a particular position within the final route. This struct houses the values necessary to create the HTLC which will travel along this hop, and also encode the per-hop payload included within the Sphinx packet.

type Route

type Route struct {
	// TotalTimeLock is the cumulative (final) time lock across the entire
	// route. This is the CLTV value that should be extended to the first
	// hop in the route. All other hops will decrement the time-lock as
	// advertised, leaving enough time for all hops to wait for or present
	// the payment preimage to complete the payment.
	TotalTimeLock uint32

	// TotalFees is the sum of the fees paid at each hop within the final
	// route. In the case of a one-hop payment, this value will be zero as
	// we don't need to pay a fee it ourself.
	TotalFees btcutil.Amount

	// TotalAmount is the total amount of funds required to complete a
	// payment over this route. This value includes the cumulative fees at
	// each hop. As a result, the HTLC extended to the first-hop in the
	// route will need to have at least this many satoshis, otherwise the
	// route will fail at an intermediate node due to an insufficient
	// amount of fees.
	TotalAmount btcutil.Amount

	// Hops contains details concerning the specific forwarding details at
	// each hop.
	Hops []*Hop
}

Route represents a path through the channel graph which runs over one or more channels in succession. This struct carries all the information required to craft the Sphinx onion packet, and send the payment along the first hop in the path. A route is only selected as valid if all the channels have sufficient capacity to carry the initial payment amount after fees are accounted for.

type TopologyChange

type TopologyChange struct {
	NewNodes    []*channeldb.LinkNode
	NewChannels []*channeldb.ChannelEdge
}

TopologyChange...

type TopologyClient

type TopologyClient struct {
}

TopologyClient... TODO(roasbeef): put in discovery package?