zpay32

README

zpay32

The zpay32 package implements a basic scheme for the encoding of payment requests between two lnd nodes within the Lightning Network. The zpay32 encoding scheme uses the zbase32 scheme along with a checksum to encode a serialized payment request.

The payment request serialized by the package consist of: the destination's public key, the payment hash to use for the payment, and the value of payment to send.

Installation and Updating

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

Documentation

Index

• Constants
• Variables
• func Amount(milliSat lnwire.MilliSatoshi) func(*Invoice)
• func CLTVExpiry(delta uint64) func(*Invoice)
• func Description(description string) func(*Invoice)
• func DescriptionHash(descriptionHash [32]byte) func(*Invoice)
• func Destination(destination *btcec.PublicKey) func(*Invoice)
• func Expiry(expiry time.Duration) func(*Invoice)
• func FallbackAddr(fallbackAddr btcutil.Address) func(*Invoice)
• func Features(features *lnwire.FeatureVector) func(*Invoice)
• func PaymentAddr(addr [32]byte) func(*Invoice)
• func RouteHint(routeHint []HopHint) func(*Invoice)
• type HopHint
  • func (h HopHint) Copy() HopHint
• type Invoice
  • func Decode(invoice string, net *chaincfg.Params) (*Invoice, er.R)
  • func NewInvoice(net *chaincfg.Params, paymentHash [32]byte, timestamp time.Time, ...) (*Invoice, er.R)
  • func (invoice *Invoice) Encode(signer MessageSigner) (string, er.R)
  • func (invoice *Invoice) Expiry() time.Duration
  • func (invoice *Invoice) MinFinalCLTVExpiry() uint64
• type MessageSigner

Constants

const (
	// DefaultAssumedFinalCLTVDelta is the default value to be used as the
	// final CLTV delta for a route if one is unspecified in the payment
	// request.
	DefaultAssumedFinalCLTVDelta = 9
)

const (

	// DefaultInvoiceExpiry is the default expiry duration from the creation
	// timestamp if expiry is set to zero.
	DefaultInvoiceExpiry = time.Hour
)

Variables

var (
	Err = er.NewErrorType("lnd.zpay32")
	// ErrInvoiceTooLarge is returned when an invoice exceeds
	// maxInvoiceLength.
	ErrInvoiceTooLarge = Err.CodeWithDetail("ErrInvoiceTooLarge", "invoice is too large")

	// ErrInvalidFieldLength is returned when a tagged field was specified
	// with a length larger than the left over bytes of the data field.
	ErrInvalidFieldLength = Err.CodeWithDetail("ErrInvalidFieldLength", "invalid field length")

	// ErrBrokenTaggedField is returned when the last tagged field is
	// incorrectly formatted and doesn't have enough bytes to be read.
	ErrBrokenTaggedField = Err.CodeWithDetail("ErrBrokenTaggedField", "last tagged field is broken")
)

Functions

func Amount

func Amount(milliSat lnwire.MilliSatoshi) func(*Invoice)

Amount is a functional option that allows callers of NewInvoice to set the amount in millisatoshis that the Invoice should encode.

func CLTVExpiry

func CLTVExpiry(delta uint64) func(*Invoice)

CLTVExpiry is an optional value which allows the receiver of the payment to specify the delta between the current height and the HTLC extended to the receiver.

func Description

func Description(description string) func(*Invoice)

Description is a functional option that allows callers of NewInvoice to set the payment description of the created Invoice.

NOTE: Must be used if and only if DescriptionHash is not used.

func DescriptionHash

func DescriptionHash(descriptionHash [32]byte) func(*Invoice)

DescriptionHash is a functional option that allows callers of NewInvoice to set the payment description hash of the created Invoice.

NOTE: Must be used if and only if Description is not used.

func Destination

func Destination(destination *btcec.PublicKey) func(*Invoice)

Destination is a functional option that allows callers of NewInvoice to explicitly set the pubkey of the Invoice's destination node.

func Expiry

func Expiry(expiry time.Duration) func(*Invoice)

Expiry is a functional option that allows callers of NewInvoice to set the expiry of the created Invoice. If not set, a default expiry of 60 min will be implied.

func FallbackAddr

func FallbackAddr(fallbackAddr btcutil.Address) func(*Invoice)

FallbackAddr is a functional option that allows callers of NewInvoice to set the Invoice's fallback on-chain address that can be used for payment in case the Lightning payment fails

func Features

func Features(features *lnwire.FeatureVector) func(*Invoice)

Features is a functional option that allows callers of NewInvoice to set the desired feature bits that are advertised on the invoice. If this option is not used, an empty feature vector will automatically be populated.

func PaymentAddr

func PaymentAddr(addr [32]byte) func(*Invoice)

PaymentAddr is a functional option that allows callers of NewInvoice to set the desired payment address tht is advertised on the invoice.

func RouteHint

func RouteHint(routeHint []HopHint) func(*Invoice)

RouteHint is a functional option that allows callers of NewInvoice to add one or more hop hints that represent a private route to the destination.

Types

type HopHint

type HopHint struct {
	// NodeID is the public key of the node at the start of the channel.
	NodeID *btcec.PublicKey

	// ChannelID is the unique identifier of the channel.
	ChannelID uint64

	// FeeBaseMSat is the base fee of the channel in millisatoshis.
	FeeBaseMSat uint32

	// FeeProportionalMillionths is the fee rate, in millionths of a
	// satoshi, for every satoshi sent through the channel.
	FeeProportionalMillionths uint32

	// CLTVExpiryDelta is the time-lock delta of the channel.
	CLTVExpiryDelta uint16
}

HopHint is a routing hint that contains the minimum information of a channel required for an intermediate hop in a route to forward the payment to the next. This should be ideally used for private channels, since they are not publicly advertised to the network for routing.

func (HopHint) Copy

func (h HopHint) Copy() HopHint

Copy returns a deep copy of the hop hint.

type Invoice

type Invoice struct {
	// Net specifies what network this Lightning invoice is meant for.
	Net *chaincfg.Params

	// MilliSat specifies the amount of this invoice in millisatoshi.
	// Optional.
	MilliSat *lnwire.MilliSatoshi

	// Timestamp specifies the time this invoice was created.
	// Mandatory
	Timestamp time.Time

	// PaymentHash is the payment hash to be used for a payment to this
	// invoice.
	PaymentHash *[32]byte

	// PaymentAddr is the payment address to be used by payments to prevent
	// probing of the destination.
	PaymentAddr *[32]byte

	// Destination is the public key of the target node. This will always
	// be set after decoding, and can optionally be set before encoding to
	// include the pubkey as an 'n' field. If this is not set before
	// encoding then the destination pubkey won't be added as an 'n' field,
	// and the pubkey will be extracted from the signature during decoding.
	Destination *btcec.PublicKey

	// Description is a short description of the purpose of this invoice.
	// Optional. Non-nil iff DescriptionHash is nil.
	Description *string

	// DescriptionHash is the SHA256 hash of a description of the purpose of
	// this invoice.
	// Optional. Non-nil iff Description is nil.
	DescriptionHash *[32]byte

	// FallbackAddr is an on-chain address that can be used for payment in
	// case the Lightning payment fails.
	// Optional.
	FallbackAddr btcutil.Address

	// RouteHints represents one or more different route hints. Each route
	// hint can be individually used to reach the destination. These usually
	// represent private routes.
	//
	// NOTE: This is optional.
	RouteHints [][]HopHint

	// Features represents an optional field used to signal optional or
	// required support for features by the receiver.
	Features *lnwire.FeatureVector
	// contains filtered or unexported fields
}

Invoice represents a decoded invoice, or to-be-encoded invoice. Some of the fields are optional, and will only be non-nil if the invoice this was parsed from contains that field. When encoding, only the non-nil fields will be added to the encoded invoice.

func Decode

func Decode(invoice string, net *chaincfg.Params) (*Invoice, er.R)

Decode parses the provided encoded invoice and returns a decoded Invoice if it is valid by BOLT-0011 and matches the provided active network.

func NewInvoice

func NewInvoice(net *chaincfg.Params, paymentHash [32]byte,
	timestamp time.Time, options ...func(*Invoice)) (*Invoice, er.R)

NewInvoice creates a new Invoice object. The last parameter is a set of variadic arguments for setting optional fields of the invoice.

NOTE: Either Description or DescriptionHash must be provided for the Invoice to be considered valid.

func (*Invoice) Encode

func (invoice *Invoice) Encode(signer MessageSigner) (string, er.R)

Encode takes the given MessageSigner and returns a string encoding this invoice signed by the node key of the signer.

func (*Invoice) Expiry

func (invoice *Invoice) Expiry() time.Duration

Expiry returns the expiry time for this invoice. If expiry time is not set explicitly, the default 3600 second expiry will be returned.

func (*Invoice) MinFinalCLTVExpiry

func (invoice *Invoice) MinFinalCLTVExpiry() uint64

MinFinalCLTVExpiry returns the minimum final CLTV expiry delta as specified by the creator of the invoice. This value specifies the delta between the current height and the expiry height of the HTLC extended in the last hop.

type MessageSigner

type MessageSigner struct {
	// SignCompact signs the hash of the passed msg with the node's privkey.
	// The returned signature should be 65 bytes, where the last 64 are the
	// compact signature, and the first one is a header byte. This is the
	// format returned by btcec.SignCompact.
	SignCompact func(msg []byte) ([]byte, er.R)
}

MessageSigner is passed to the Encode method to provide a signature corresponding to the node's pubkey.