.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] \fBdescription\fR (string): the description of the purpose of the offer .IP \[bu] \fBsignature\fR (bip340sig, optional): BIP-340 signature of the \fInode_id\fR on this 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 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:cd54af7c631f06b3db72848cdf90951ceb14d89b8bca981dba69244cd2ddbae5