route

Documentation

Index

• Constants
• Variables
• type Hop
  • func (h *Hop) Copy() *Hop
  • func (h *Hop) PackHopPayload(w io.Writer, nextChanID uint64) error
  • func (h *Hop) PayloadSize(nextChanID uint64) uint64
• type Route
  • func NewRouteFromHops(amtToSend lnwire.MilliSatoshi, timeLock uint32, sourceVertex Vertex, ...) (*Route, error)
  • func (r *Route) Copy() *Route
  • func (r *Route) FinalHop() *Hop
  • func (r *Route) HopFee(hopIndex int) lnwire.MilliSatoshi
  • func (r *Route) ReceiverAmt() lnwire.MilliSatoshi
  • func (r *Route) String() string
  • func (r *Route) ToSphinxPath() (*sphinx.PaymentPath, error)
  • func (r *Route) TotalFees() lnwire.MilliSatoshi
• type Vertex
  • func NewVertex(pub *btcec.PublicKey) Vertex
  • func NewVertexFromBytes(b []byte) (Vertex, error)
  • func NewVertexFromStr(v string) (Vertex, error)
  • func (v Vertex) String() string

Constants

const VertexSize = 33

VertexSize is the size of the array to store a vertex.

Variables

var (
	// ErrNoRouteHopsProvided is returned when a caller attempts to
	// construct a new sphinx packet, but provides an empty set of hops for
	// each route.
	ErrNoRouteHopsProvided = fmt.Errorf("empty route hops provided")

	// ErrMaxRouteHopsExceeded is returned when a caller attempts to
	// construct a new sphinx packet, but provides too many hops.
	ErrMaxRouteHopsExceeded = fmt.Errorf("route has too many hops")

	// ErrIntermediateMPPHop is returned when a hop tries to deliver an MPP
	// record to an intermediate hop, only final hops can receive MPP
	// records.
	ErrIntermediateMPPHop = errors.New("cannot send MPP to intermediate")

	// ErrAMPMissingMPP is returned when the caller tries to attach an AMP
	// record but no MPP record is presented for the final hop.
	ErrAMPMissingMPP = errors.New("cannot send AMP without MPP record")
)

Types

type Hop

type Hop struct {
	// PubKeyBytes is the raw bytes of the public key of the target node.
	PubKeyBytes Vertex

	// ChannelID is the unique channel ID for the channel. The first 3
	// bytes are the block height, the next 3 the index within the block,
	// and the last 2 bytes are the output index for the channel.
	ChannelID uint64

	// OutgoingTimeLock is the timelock value that should be used when
	// crafting the _outgoing_ HTLC from this hop.
	OutgoingTimeLock uint32

	// 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 lnwire.MilliSatoshi

	// MPP encapsulates the data required for option_mpp. This field should
	// only be set for the final hop.
	MPP *record.MPP

	// AMP encapsulates the data required for option_amp. This field should
	// only be set for the final hop.
	AMP *record.AMP

	// CustomRecords if non-nil are a set of additional TLV records that
	// should be included in the forwarding instructions for this node.
	CustomRecords record.CustomSet

	// LegacyPayload if true, then this signals that this node doesn't
	// understand the new TLV payload, so we must instead use the legacy
	// payload.
	LegacyPayload bool

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

Hop represents an intermediate or final node of the route. This naming is in line with the definition given in BOLT #4: Onion Routing Protocol. The struct houses the channel along which this hop can be reached and the values necessary to create the HTLC that needs to be sent to the next hop. It is also used to encode the per-hop payload included within the Sphinx packet.

func (*Hop) Copy

func (h *Hop) Copy() *Hop

Copy returns a deep copy of the Hop.

func (*Hop) PackHopPayload

func (h *Hop) PackHopPayload(w io.Writer, nextChanID uint64) error

PackHopPayload writes to the passed io.Writer, the series of byes that can be placed directly into the per-hop payload (EOB) for this hop. This will include the required routing fields, as well as serializing any of the passed optional TLVRecords. nextChanID is the unique channel ID that references the _outgoing_ channel ID that follows this hop. This field follows the same semantics as the NextAddress field in the onion: it should be set to zero to indicate the terminal hop.

func (*Hop) PayloadSize

func (h *Hop) PayloadSize(nextChanID uint64) uint64

Size returns the total size this hop's payload would take up in the onion 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

	// 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 lnwire.MilliSatoshi

	// SourcePubKey is the pubkey of the node where this route originates
	// from.
	SourcePubKey Vertex

	// 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.

func NewRouteFromHops

func NewRouteFromHops(amtToSend lnwire.MilliSatoshi, timeLock uint32,
	sourceVertex Vertex, hops []*Hop) (*Route, error)

NewRouteFromHops creates a new Route structure from the minimally required information to perform the payment. It infers fee amounts and populates the node, chan and prev/next hop maps.

func (*Route) Copy

func (r *Route) Copy() *Route

Copy returns a deep copy of the Route.

func (*Route) FinalHop

func (r *Route) FinalHop() *Hop

FinalHop returns the last hop of the route, or nil if the route is empty.

func (*Route) HopFee

func (r *Route) HopFee(hopIndex int) lnwire.MilliSatoshi

HopFee returns the fee charged by the route hop indicated by hopIndex.

func (*Route) ReceiverAmt

func (r *Route) ReceiverAmt() lnwire.MilliSatoshi

ReceiverAmt is the amount received by the final hop of this route.

func (*Route) String

func (r *Route) String() string

String returns a human readable representation of the route.

func (*Route) ToSphinxPath

func (r *Route) ToSphinxPath() (*sphinx.PaymentPath, error)

ToSphinxPath converts a complete route into a sphinx PaymentPath that contains the per-hop paylods used to encoding the HTLC routing data for each hop in the route. This method also accepts an optional EOB payload for the final hop.

func (*Route) TotalFees

func (r *Route) TotalFees() lnwire.MilliSatoshi

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 to ourself.

type Vertex

type Vertex [VertexSize]byte

Vertex is a simple alias for the serialization of a compressed Bitcoin public key.

func NewVertex

func NewVertex(pub *btcec.PublicKey) Vertex

NewVertex returns a new Vertex given a public key.

func NewVertexFromBytes

func NewVertexFromBytes(b []byte) (Vertex, error)

NewVertexFromBytes returns a new Vertex based on a serialized pubkey in a byte slice.

func NewVertexFromStr

func NewVertexFromStr(v string) (Vertex, error)

NewVertexFromStr returns a new Vertex given its hex-encoded string format.

func (Vertex) String

func (v Vertex) String() string

String returns a human readable version of the Vertex which is the hex-encoding of the serialized compressed public key.