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
- type Invoice
- type MessageSigner
Constants ¶
const ( // DefaultFinalCLTVDelta is the default value to be used as the final // CLTV delta for a route if one is unspecified. DefaultFinalCLTVDelta = 9 )
const ( // DefaultInvoiceExpiry is the default expiry duration from the creation // timestamp if expiry is set to zero. DefaultInvoiceExpiry = time.Hour )
Variables ¶
var ( // ErrInvoiceTooLarge is returned when an invoice exceeds // maxInvoiceLength. ErrInvoiceTooLarge = errors.New("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 = errors.New("invalid field length") // ErrBrokenTaggedField is returned when the last tagged field is // incorrectly formatted and doesn't have enough bytes to be read. ErrBrokenTaggedField = errors.New("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 ¶
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 ¶
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 ¶
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 ¶
Destination is a functional option that allows callers of NewInvoice to explicitly set the pubkey of the Invoice's destination node.
func Expiry ¶
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 ¶
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 ¶
PaymentAddr is a functional option that allows callers of NewInvoice to set the desired payment address tht is advertised on the invoice.
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.
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 ¶
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, error)
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, error)
Encode takes the given MessageSigner and returns a string encoding this invoice signed by the node key of the signer.
func (*Invoice) Expiry ¶
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 ¶
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 passed hash 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(hash []byte) ([]byte, error) }
MessageSigner is passed to the Encode method to provide a signature corresponding to the node's pubkey.