zpay32

package
v0.18.3-beta Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2024 License: MIT Imports: 17 Imported by: 0

README

zpay32

Build Status MIT licensed GoDoc

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

View Source 
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.
	// We adhere to the recommendation in BOLT 02 for terminal payments.
	// See also:
	// https://github.com/lightning/bolts/blob/master/02-peer-protocol.md
	DefaultAssumedFinalCLTVDelta = 18
)
View Source 
const (

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

Variables

View Source 
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 

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 DecodeBlindedHop 

func DecodeBlindedHop(r io.Reader) (*sphinx.BlindedHopInfo, error)

DecodeBlindedHop reads a sphinx.BlindedHopInfo from the passed reader.

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 EncodeBlindedHop 

func EncodeBlindedHop(w io.Writer, hop *sphinx.BlindedHopInfo) error

EncodeBlindedHop writes the passed BlindedHopInfo to the given writer.

1) Blinded node pub key: 33 bytes 2) Cipher text length: BigSize 3) Cipher text.

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 Metadata 

func Metadata(metadata []byte) func(*Invoice)

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

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

func WithBlindedPaymentPath 

func WithBlindedPaymentPath(p *BlindedPaymentPath) func(*Invoice)

WithBlindedPaymentPath is a functional option that allows a caller of NewInvoice to attach a blinded payment path to the invoice. The option can be used multiple times to attach multiple paths.

Types

type BlindedPaymentPath 

type BlindedPaymentPath struct {
	// FeeBaseMsat is the total base fee for the path in milli-satoshis.
	FeeBaseMsat uint32

	// FeeRate is the total fee rate for the path in parts per million.
	FeeRate uint32

	// CltvExpiryDelta is the total CLTV delta to apply to the path.
	CltvExpiryDelta uint16

	// HTLCMinMsat is the minimum number of milli-satoshis that any hop in
	// the path will route.
	HTLCMinMsat uint64

	// HTLCMaxMsat is the maximum number of milli-satoshis that a hop in the
	// path will route.
	HTLCMaxMsat uint64

	// Features is the feature bit vector for the path.
	Features *lnwire.FeatureVector

	// FirstEphemeralBlindingPoint is the blinding point to send to the
	// introduction node. It will be used by the introduction node to derive
	// a shared secret with the receiver which can then be used to decode
	// the encrypted payload from the receiver.
	FirstEphemeralBlindingPoint *btcec.PublicKey

	// Hops is the blinded path. The first hop is the introduction node and
	// so the BlindedNodeID of this hop will be the real node ID.
	Hops []*sphinx.BlindedHopInfo
}

BlindedPaymentPath holds all the information a payer needs to know about a blinded path to a receiver of a payment.

func DecodeBlindedPayment 

func DecodeBlindedPayment(r io.Reader) (*BlindedPaymentPath, error)

DecodeBlindedPayment attempts to parse a BlindedPaymentPath from the passed reader.

func (*BlindedPaymentPath) Encode 

func (p *BlindedPaymentPath) Encode(w io.Writer) error

Encode serialises the BlindedPaymentPath and writes the bytes to the passed writer. 1) The first 26 bytes contain the relay info:

  • Base Fee in msat: uint32 (4 bytes).
  • Proportional Fee in PPM: uint32 (4 bytes).
  • CLTV expiry delta: uint16 (2 bytes).
  • HTLC min msat: uint64 (8 bytes).
  • HTLC max msat: uint64 (8 bytes).

2) Feature bit vector length (2 bytes). 3) Feature bit vector (can be zero length). 4) First blinding point: 33 bytes. 5) Number of hops: 1 byte. 6) Encoded BlindedHops.

type DecodeOption 

type DecodeOption func(*decodeOptions)

DecodeOption is a type that can be used to supply functional options to the Decode function.

func WithErrorOnUnknownFeatureBit 

func WithErrorOnUnknownFeatureBit() DecodeOption

WithErrorOnUnknownFeatureBit is a functional option that will cause the Decode function to return an error if the decoded invoice contains an unknown feature bit.

func WithKnownFeatureBits 

func WithKnownFeatureBits(features map[lnwire.FeatureBit]string) DecodeOption

WithKnownFeatureBits is a functional option that overwrites the set of known feature bits. If not set, then LND's lnwire.Features variable will be used by default.

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.

func (HopHint) HopFee 

func (h HopHint) HopFee(amt lnwire.MilliSatoshi) lnwire.MilliSatoshi

HopFee calculates the fee for a given amount that is forwarded over a hop. The amount has to be denoted in milli satoshi. The returned fee is also denoted in milli satoshi.

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 and should not be set at the same time as
	// BlindedPaymentPaths.
	RouteHints [][]HopHint

	// BlindedPaymentPaths is a set of blinded payment paths that can be
	// used to find the payment receiver.
	//
	// NOTE: This is optional and should not be set at the same time as
	// RouteHints.
	BlindedPaymentPaths []*BlindedPaymentPath

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

	// Metadata is additional data that is sent along with the payment to
	// the payee.
	Metadata []byte
	// 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, opts ...DecodeOption) (
	*Invoice, error)

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 

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 ecdsa.SignCompact.
	SignCompact func(msg []byte) ([]byte, error)
}

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

Source Files

View all Source files

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.