lnd.xprv/zpay32/invoice.go
Conner Fromknecht 53ab22305d
zpay32: rename to DefaultAssumedFinalCLTVDelta
This renames the paramter to clarify that this value is only used when
no CLTV value was decoded from the payment request
2020-07-24 13:14:03 -07:00

375 lines
12 KiB
Go

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 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)
}
// 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
}