418 lines
12 KiB
Groff
418 lines
12 KiB
Groff
.TH "LIGHTNING-DECODE" "7" "" "" "lightning-decode"
|
|
.SH NAME
|
|
lightning-decode - Command for decoding an invoice string (low-level)
|
|
.SH SYNOPSIS
|
|
|
|
\fB(WARNING: experimental-offers only)\fR
|
|
|
|
|
|
\fBdecode\fR \fIstring\fR
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The \fBdecode\fR RPC command checks and parses a \fIbolt11\fR or \fIbolt12\fR
|
|
string (optionally prefixed by \fBlightning:\fR or \fBLIGHTNING:\fR) as
|
|
specified by the BOLT 11 and BOLT 12 specifications\. It may decode
|
|
other formats in future\.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, an object is returned, containing:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBtype\fR (string): what kind of object it decoded to (one of "bolt12 offer", "bolt12 invoice", "bolt12 invoice_request", "bolt11 invoice")
|
|
.IP \[bu]
|
|
\fBvalid\fR (boolean): if this is false, you \fIMUST\fR not use the result except for diagnostics!
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "bolt12 offer", and \fBvalid\fR is \fItrue\fR:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
|
|
.IP \[bu]
|
|
\fBnode_id\fR (pubkey32): x-only public key of the offering node
|
|
.IP \[bu]
|
|
\fBsignature\fR (bip340sig): BIP-340 signature of the \fInode_id\fR on this offer
|
|
.IP \[bu]
|
|
\fBdescription\fR (string): the description of the purpose of the offer
|
|
.IP \[bu]
|
|
\fBchains\fR (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
|
|
.RS
|
|
.IP \[bu]
|
|
the genesis blockhash (always 64 characters)
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBcurrency\fR (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)
|
|
.IP \[bu]
|
|
\fBminor_unit\fR (u32, optional): the number of decimal places to apply to amount (if currency known)
|
|
.IP \[bu]
|
|
\fBamount\fR (u64, optional): the amount in the \fIcurrency\fR adjusted by \fIminor_unit\fR, if any
|
|
.IP \[bu]
|
|
\fBamount_msat\fR (msat, optional): the amount in bitcoin (if specified, and no \fIcurrency\fR)
|
|
.IP \[bu]
|
|
\fBsend_invoice\fR (boolean, optional): present if this is a send_invoice offer (always \fItrue\fR)
|
|
.IP \[bu]
|
|
\fBrefund_for\fR (hex, optional): the \fIpayment_preimage\fR of invoice this is a refund for (always 64 characters)
|
|
.IP \[bu]
|
|
\fBvendor\fR (string, optional): the name of the vendor for this offer
|
|
.IP \[bu]
|
|
\fBfeatures\fR (hex, optional): the array of feature bits for this offer
|
|
.IP \[bu]
|
|
\fBabsolute_expiry\fR (u64, optional): UNIX timestamp of when this offer expires
|
|
.IP \[bu]
|
|
\fBpaths\fR (array of objects, optional): Paths to the destination:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBblinding\fR (pubkey): blinding factor for this path
|
|
.IP \[bu]
|
|
\fBpath\fR (array of objects): an individual path:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBnode_id\fR (pubkey): node_id of the hop
|
|
.IP \[bu]
|
|
\fBenctlv\fR (hex): encrypted TLV entry for this hop
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBquantity_min\fR (u64, optional): the minimum quantity
|
|
.IP \[bu]
|
|
\fBquantity_max\fR (u64, optional): the maximum quantity
|
|
.IP \[bu]
|
|
\fBrecurrence\fR (object, optional): how often to this offer should be used:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBtime_unit\fR (u32): the BOLT12 time unit
|
|
.IP \[bu]
|
|
\fBperiod\fR (u32): how many \fItime_unit\fR per payment period
|
|
.IP \[bu]
|
|
\fBtime_unit_name\fR (string, optional): the name of \fItime_unit\fR (if valid)
|
|
.IP \[bu]
|
|
\fBbasetime\fR (u64, optional): period starts at this UNIX timestamp
|
|
.IP \[bu]
|
|
\fBstart_any_period\fR (u64, optional): you can start at any period (only if \fBbasetime\fR present)
|
|
.IP \[bu]
|
|
\fBlimit\fR (u32, optional): maximum period number for recurrence
|
|
.IP \[bu]
|
|
\fBpaywindow\fR (object, optional): when within a period will payment be accepted (default is prior and during the period):
|
|
.RS
|
|
.IP \[bu]
|
|
\fBseconds_before\fR (u32): seconds prior to period start
|
|
.IP \[bu]
|
|
\fBseconds_after\fR (u32): seconds after to period start
|
|
.IP \[bu]
|
|
\fBproportional_amount\fR (boolean, optional): amount should be scaled if payed after period start (always \fItrue\fR)
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
the following warnings are possible:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBwarning_offer_unknown_currency\fR: The currency code is unknown (so no \fBminor_unit\fR)
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "bolt12 offer", and \fBvalid\fR is \fIfalse\fR:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
the following warnings are possible:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBwarning_offer_missing_description\fR: No \fBdescription\fR
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "bolt12 invoice", and \fBvalid\fR is \fItrue\fR:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBnode_id\fR (pubkey32): x-only public key of the offering node
|
|
.IP \[bu]
|
|
\fBsignature\fR (bip340sig): BIP-340 signature of the \fInode_id\fR on this offer
|
|
.IP \[bu]
|
|
\fBamount_msat\fR (msat): the amount in bitcoin
|
|
.IP \[bu]
|
|
\fBdescription\fR (string): the description of the purpose of the offer
|
|
.IP \[bu]
|
|
\fBtimestamp\fR (u64): the UNIX timestamp of the invoice
|
|
.IP \[bu]
|
|
\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR (always 64 characters)
|
|
.IP \[bu]
|
|
\fBrelative_expiry\fR (u32): the number of seconds after \fItimestamp\fR when this expires
|
|
.IP \[bu]
|
|
\fBmin_final_cltv_expiry\fR (u32): the number of blocks required by destination
|
|
.IP \[bu]
|
|
\fBoffer_id\fR (hex, optional): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
|
|
.IP \[bu]
|
|
\fBchains\fR (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
|
|
.RS
|
|
.IP \[bu]
|
|
the genesis blockhash (always 64 characters)
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBsend_invoice\fR (boolean, optional): present if this offer was a send_invoice offer (always \fItrue\fR)
|
|
.IP \[bu]
|
|
\fBrefund_for\fR (hex, optional): the \fIpayment_preimage\fR of invoice this is a refund for (always 64 characters)
|
|
.IP \[bu]
|
|
\fBvendor\fR (string, optional): the name of the vendor for this offer
|
|
.IP \[bu]
|
|
\fBfeatures\fR (hex, optional): the array of feature bits for this offer
|
|
.IP \[bu]
|
|
\fBpaths\fR (array of objects, optional): Paths to the destination:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBblinding\fR (pubkey): blinding factor for this path
|
|
.IP \[bu]
|
|
\fBpath\fR (array of objects): an individual path:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBnode_id\fR (pubkey): node_id of the hop
|
|
.IP \[bu]
|
|
\fBenctlv\fR (hex): encrypted TLV entry for this hop
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBquantity\fR (u64, optional): the quantity ordered
|
|
.IP \[bu]
|
|
\fBrecurrence_counter\fR (u32, optional): the 0-based counter for a recurring payment
|
|
.IP \[bu]
|
|
\fBrecurrence_start\fR (u32, optional): the optional start period for a recurring payment
|
|
.IP \[bu]
|
|
\fBrecurrence_basetime\fR (u32, optional): the UNIX timestamp of the first recurrence period start
|
|
.IP \[bu]
|
|
\fBpayer_key\fR (pubkey32, optional): the transient key which identifies the payer
|
|
.IP \[bu]
|
|
\fBpayer_info\fR (hex, optional): the payer-provided blob to derive payer_key
|
|
.IP \[bu]
|
|
\fBfallbacks\fR (array of objects, optional): onchain addresses:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBversion\fR (u8): Segwit address version
|
|
.IP \[bu]
|
|
\fBhex\fR (hex): Raw encoded segwit address
|
|
.IP \[bu]
|
|
\fBaddress\fR (string, optional): bech32 segwit address
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBrefund_signature\fR (bip340sig, optional): the payer key signature to get a refund
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "bolt12 invoice", and \fBvalid\fR is \fIfalse\fR:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBfallbacks\fR (array of objects, optional):
|
|
.RS
|
|
.IP \[bu]
|
|
the following warnings are possible:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBwarning_invoice_fallbacks_version_invalid\fR: \fBversion\fR is > 16
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
the following warnings are possible:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBwarning_invoice_missing_amount\fR: *\fIamount_msat\fR missing
|
|
.IP \[bu]
|
|
\fBwarning_invoice_missing_description\fR: No \fBdescription\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_missing_blinded_payinfo\fR: Has \fBpaths\fR without payinfo
|
|
.IP \[bu]
|
|
\fBwarning_invoice_invalid_blinded_payinfo\fR: Does not have exactly one payinfo for each of \fBpaths\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_missing_recurrence_basetime\fR: Has \fBrecurrence_counter\fR without \fBrecurrence_basetime\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_missing_timestamp\fR: Missing \fBtimestamp\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_missing_payment_hash\fR: Missing \fBpayment_hash\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_refund_signature_missing_payer_key\fR: Missing \fBpayer_key\fR for refund_signature
|
|
.IP \[bu]
|
|
\fBwarning_invoice_refund_signature_invalid\fR: \fBrefund_signature\fR incorrect
|
|
.IP \[bu]
|
|
\fBwarning_invoice_refund_missing_signature\fR: No \fBrefund_signature\fR
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "bolt12 invoice_request", and \fBvalid\fR is \fItrue\fR:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
|
|
.IP \[bu]
|
|
\fBpayer_key\fR (pubkey32): the transient key which identifies the payer
|
|
.IP \[bu]
|
|
\fBchains\fR (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
|
|
.RS
|
|
.IP \[bu]
|
|
the genesis blockhash (always 64 characters)
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBamount_msat\fR (msat, optional): the amount in bitcoin
|
|
.IP \[bu]
|
|
\fBfeatures\fR (hex, optional): the array of feature bits for this offer
|
|
.IP \[bu]
|
|
\fBquantity\fR (u64, optional): the quantity ordered
|
|
.IP \[bu]
|
|
\fBrecurrence_counter\fR (u32, optional): the 0-based counter for a recurring payment
|
|
.IP \[bu]
|
|
\fBrecurrence_start\fR (u32, optional): the optional start period for a recurring payment
|
|
.IP \[bu]
|
|
\fBpayer_info\fR (hex, optional): the payer-provided blob to derive payer_key
|
|
.IP \[bu]
|
|
\fBrecurrence_signature\fR (bip340sig, optional): the payer key signature
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "bolt12 invoice_request", and \fBvalid\fR is \fIfalse\fR:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
the following warnings are possible:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBwarning_invoice_request_missing_offer_id\fR: No \fBoffer_id\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_request_missing_payer_key\fR: No \fBpayer_key\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_request_missing_recurrence_signature\fR: No \fBrecurrence_signature\fR
|
|
.IP \[bu]
|
|
\fBwarning_invoice_request_invalid_recurrence_signature\fR: \fBrecurrence_signature\fR incorrect
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "bolt11 invoice", and \fBvalid\fR is \fItrue\fR:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBcurrency\fR (string): the BIP173 name for the currency
|
|
.IP \[bu]
|
|
\fBcreated_at\fR (u64): the UNIX-style timestamp of the invoice
|
|
.IP \[bu]
|
|
\fBexpiry\fR (u64): the number of seconds this is valid after \fItimestamp\fR
|
|
.IP \[bu]
|
|
\fBpayee\fR (pubkey): the public key of the recipient
|
|
.IP \[bu]
|
|
\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR (always 64 characters)
|
|
.IP \[bu]
|
|
\fBsignature\fR (signature): signature of the \fIpayee\fR on this invoice
|
|
.IP \[bu]
|
|
\fBmin_final_cltv_expiry\fR (u32): the minimum CLTV delay for the final node
|
|
.IP \[bu]
|
|
\fBamount_msat\fR (msat, optional): Amount the invoice asked for
|
|
.IP \[bu]
|
|
\fBdescription\fR (string, optional): the description of the purpose of the purchase
|
|
.IP \[bu]
|
|
\fBdescription_hash\fR (hex, optional): the hash of the description, in place of \fIdescription\fR (always 64 characters)
|
|
.IP \[bu]
|
|
\fBpayment_secret\fR (hex, optional): the secret to hand to the payee node (always 64 characters)
|
|
.IP \[bu]
|
|
\fBfeatures\fR (hex, optional): the features bitmap for this invoice
|
|
.IP \[bu]
|
|
\fBfallbacks\fR (array of objects, optional): onchain addresses:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBtype\fR (string): the address type (if known) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH")
|
|
.IP \[bu]
|
|
\fBhex\fR (hex): Raw encoded address
|
|
.IP \[bu]
|
|
\fBaddr\fR (string, optional): the address in appropriate format for \fItype\fR
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBroutes\fR (array of arrays, optional): Route hints to the \fIpayee\fR:
|
|
.RS
|
|
.IP \[bu]
|
|
hops in the route:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBpubkey\fR (pubkey): the public key of the node
|
|
.IP \[bu]
|
|
\fBshort_channel_id\fR (short_channel_id): a channel to the next peer
|
|
.IP \[bu]
|
|
\fBfee_base_msat\fR (u32): the base fee for payments
|
|
.IP \[bu]
|
|
\fBfee_proportional_millionths\fR (u32): the parts-per-million fee for payments
|
|
.IP \[bu]
|
|
\fBcltv_expiry_delta\fR (u32): the CLTV delta across this hop
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBextra\fR (array of objects, optional): Any extra fields we didn't know how to parse:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBtag\fR (string): The bech32 letter which identifies this field (always 1 characters)
|
|
.IP \[bu]
|
|
\fBdata\fR (string): The bech32 data for this field
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
.SH AUTHOR
|
|
|
|
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBlightning-pay\fR(7), \fBlightning-offer\fR(7), \fBlightning-offerout\fR(7), \fBlightning-fetchinvoice\fR(7), \fBlightning-sendinvoice\fR(7)
|
|
|
|
|
|
\fBBOLT #11\fR (\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md\fR)\.
|
|
|
|
|
|
\fBBOLT #12\fR (\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/12-offer-encoding.md\fR)\.
|
|
|
|
.SH RESOURCES
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
\" SHA256STAMP:403b7cf3cadd8b260b8b2b02746c76d7d21a8319fe386b4174f4f58b3e5dcdbd
|