You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
374 lines
12 KiB
374 lines
12 KiB
package zpay32 |
|
|
|
import ( |
|
"errors" |
|
"fmt" |
|
"time" |
|
|
|
"github.com/btcsuite/btcd/btcec" |
|
"github.com/btcsuite/btcd/chaincfg" |
|
"github.com/btcsuite/btcutil" |
|
"github.com/lightningnetwork/lnd/lnwire" |
|
) |
|
|
|
const ( |
|
// mSatPerBtc is the number of millisatoshis in 1 BTC. |
|
mSatPerBtc = 100000000000 |
|
|
|
// signatureBase32Len is the number of 5-bit groups needed to encode |
|
// the 512 bit signature + 8 bit recovery ID. |
|
signatureBase32Len = 104 |
|
|
|
// timestampBase32Len is the number of 5-bit groups needed to encode |
|
// the 35-bit timestamp. |
|
timestampBase32Len = 7 |
|
|
|
// hashBase32Len is the number of 5-bit groups needed to encode a |
|
// 256-bit hash. Note that the last group will be padded with zeroes. |
|
hashBase32Len = 52 |
|
|
|
// pubKeyBase32Len is the number of 5-bit groups needed to encode a |
|
// 33-byte compressed pubkey. Note that the last group will be padded |
|
// with zeroes. |
|
pubKeyBase32Len = 53 |
|
|
|
// hopHintLen is the number of bytes needed to encode the hop hint of a |
|
// single private route. |
|
hopHintLen = 51 |
|
|
|
// The following byte values correspond to the supported field types. |
|
// The field name is the character representing that 5-bit value in the |
|
// bech32 string. |
|
|
|
// fieldTypeP is the field containing the payment hash. |
|
fieldTypeP = 1 |
|
|
|
// fieldTypeD contains a short description of the payment. |
|
fieldTypeD = 13 |
|
|
|
// fieldTypeN contains the pubkey of the target node. |
|
fieldTypeN = 19 |
|
|
|
// fieldTypeH contains the hash of a description of the payment. |
|
fieldTypeH = 23 |
|
|
|
// fieldTypeX contains the expiry in seconds of the invoice. |
|
fieldTypeX = 6 |
|
|
|
// fieldTypeF contains a fallback on-chain address. |
|
fieldTypeF = 9 |
|
|
|
// fieldTypeR contains extra routing information. |
|
fieldTypeR = 3 |
|
|
|
// fieldTypeC contains an optional requested final CLTV delta. |
|
fieldTypeC = 24 |
|
|
|
// fieldType9 contains one or more bytes for signaling features |
|
// supported or required by the receiver. |
|
fieldType9 = 5 |
|
|
|
// fieldTypeS contains a 32-byte payment address, which is a nonce |
|
// included in the final hop's payload to prevent intermediaries from |
|
// probing the recipient. |
|
fieldTypeS = 16 |
|
|
|
// maxInvoiceLength is the maximum total length an invoice can have. |
|
// This is chosen to be the maximum number of bytes that can fit into a |
|
// single QR code: https://en.wikipedia.org/wiki/QR_code#Storage |
|
maxInvoiceLength = 7089 |
|
|
|
// DefaultInvoiceExpiry is the default expiry duration from the creation |
|
// timestamp if expiry is set to zero. |
|
DefaultInvoiceExpiry = time.Hour |
|
) |
|
|
|
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") |
|
) |
|
|
|
// MessageSigner is passed to the Encode method to provide a signature |
|
// corresponding to the node's pubkey. |
|
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, error) |
|
} |
|
|
|
// 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. |
|
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 |
|
|
|
// minFinalCLTVExpiry is the value that the creator of the invoice |
|
// expects to be used for the CLTV expiry of the HTLC extended to it in |
|
// the last hop. |
|
// |
|
// NOTE: This value is optional, and should be set to nil if the |
|
// invoice creator doesn't have a strong requirement on the CLTV expiry |
|
// of the final HTLC extended to it. |
|
// |
|
// This field is un-exported and can only be read by the |
|
// MinFinalCLTVExpiry() method. By forcing callers to read via this |
|
// method, we can easily enforce the default if not specified. |
|
minFinalCLTVExpiry *uint64 |
|
|
|
// 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 |
|
|
|
// expiry specifies the timespan this invoice will be valid. |
|
// Optional. If not set, a default expiry of 60 min will be implied. |
|
// |
|
// This field is unexported and can be read by the Expiry() method. This |
|
// method makes sure the default expiry time is returned in case the |
|
// field is not set. |
|
expiry *time.Duration |
|
|
|
// 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 |
|
} |
|
|
|
// Amount is a functional option that allows callers of NewInvoice to set the |
|
// amount in millisatoshis that the Invoice should encode. |
|
func Amount(milliSat lnwire.MilliSatoshi) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.MilliSat = &milliSat |
|
} |
|
} |
|
|
|
// Destination is a functional option that allows callers of NewInvoice to |
|
// explicitly set the pubkey of the Invoice's destination node. |
|
func Destination(destination *btcec.PublicKey) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.Destination = destination |
|
} |
|
} |
|
|
|
// 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 Description(description string) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.Description = &description |
|
} |
|
} |
|
|
|
// 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 CLTVExpiry(delta uint64) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.minFinalCLTVExpiry = &delta |
|
} |
|
} |
|
|
|
// 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 DescriptionHash(descriptionHash [32]byte) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.DescriptionHash = &descriptionHash |
|
} |
|
} |
|
|
|
// 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 Expiry(expiry time.Duration) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.expiry = &expiry |
|
} |
|
} |
|
|
|
// 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 FallbackAddr(fallbackAddr btcutil.Address) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.FallbackAddr = fallbackAddr |
|
} |
|
} |
|
|
|
// 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 RouteHint(routeHint []HopHint) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.RouteHints = append(i.RouteHints, routeHint) |
|
} |
|
} |
|
|
|
// 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 Features(features *lnwire.FeatureVector) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.Features = features |
|
} |
|
} |
|
|
|
// PaymentAddr is a functional option that allows callers of NewInvoice to set |
|
// the desired payment address tht is advertised on the invoice. |
|
func PaymentAddr(addr [32]byte) func(*Invoice) { |
|
return func(i *Invoice) { |
|
i.PaymentAddr = &addr |
|
} |
|
} |
|
|
|
// 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 NewInvoice(net *chaincfg.Params, paymentHash [32]byte, |
|
timestamp time.Time, options ...func(*Invoice)) (*Invoice, error) { |
|
|
|
invoice := &Invoice{ |
|
Net: net, |
|
PaymentHash: &paymentHash, |
|
Timestamp: timestamp, |
|
} |
|
|
|
for _, option := range options { |
|
option(invoice) |
|
} |
|
|
|
// If no features were set, we'll populate an empty feature vector. |
|
if invoice.Features == nil { |
|
invoice.Features = lnwire.NewFeatureVector( |
|
nil, lnwire.Features, |
|
) |
|
} |
|
|
|
if err := validateInvoice(invoice); err != nil { |
|
return nil, err |
|
} |
|
|
|
return invoice, nil |
|
} |
|
|
|
// 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 *Invoice) Expiry() time.Duration { |
|
if invoice.expiry != nil { |
|
return *invoice.expiry |
|
} |
|
|
|
// If no expiry is set for this invoice, default is 3600 seconds. |
|
return DefaultInvoiceExpiry |
|
} |
|
|
|
// 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. |
|
func (invoice *Invoice) MinFinalCLTVExpiry() uint64 { |
|
if invoice.minFinalCLTVExpiry != nil { |
|
return *invoice.minFinalCLTVExpiry |
|
} |
|
|
|
return DefaultAssumedFinalCLTVDelta |
|
} |
|
|
|
// validateInvoice does a sanity check of the provided Invoice, making sure it |
|
// has all the necessary fields set for it to be considered valid by BOLT-0011. |
|
func validateInvoice(invoice *Invoice) error { |
|
// The net must be set. |
|
if invoice.Net == nil { |
|
return fmt.Errorf("net params not set") |
|
} |
|
|
|
// The invoice must contain a payment hash. |
|
if invoice.PaymentHash == nil { |
|
return fmt.Errorf("no payment hash found") |
|
} |
|
|
|
// Either Description or DescriptionHash must be set, not both. |
|
if invoice.Description != nil && invoice.DescriptionHash != nil { |
|
return fmt.Errorf("both description and description hash set") |
|
} |
|
if invoice.Description == nil && invoice.DescriptionHash == nil { |
|
return fmt.Errorf("neither description nor description hash set") |
|
} |
|
|
|
// Check that we support the field lengths. |
|
if len(invoice.PaymentHash) != 32 { |
|
return fmt.Errorf("unsupported payment hash length: %d", |
|
len(invoice.PaymentHash)) |
|
} |
|
|
|
if invoice.DescriptionHash != nil && len(invoice.DescriptionHash) != 32 { |
|
return fmt.Errorf("unsupported description hash length: %d", |
|
len(invoice.DescriptionHash)) |
|
} |
|
|
|
if invoice.Destination != nil && |
|
len(invoice.Destination.SerializeCompressed()) != 33 { |
|
return fmt.Errorf("unsupported pubkey length: %d", |
|
len(invoice.Destination.SerializeCompressed())) |
|
} |
|
|
|
// Ensure that all invoices have feature vectors. |
|
if invoice.Features == nil { |
|
return fmt.Errorf("missing feature vector") |
|
} |
|
|
|
return nil |
|
}
|
|
|