lightning-decode -- Command for decoding an invoice string (low-level) ======================================================================= SYNOPSIS -------- **decode** *string* DESCRIPTION ----------- The **decode** RPC command checks and parses: - a *bolt11* or *bolt12* string (optionally prefixed by `lightning:` or `LIGHTNING:`) as specified by the BOLT 11 and BOLT 12 specifications. - a *rune* as created by lightning-commando-rune(7). It may decode other formats in future. RETURN VALUE ------------ [comment]: # (GENERATE-FROM-SCHEMA-START) On success, an object is returned, containing: - **type** (string): what kind of object it decoded to (one of "bolt12 offer", "bolt12 invoice", "bolt12 invoice_request", "bolt11 invoice", "rune") - **valid** (boolean): if this is false, you *MUST* not use the result except for diagnostics! If **type** is "bolt12 offer", and **valid** is *true*: - **offer_id** (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters) - **node_id** (point32): x-only public key of the offering node - **description** (string): the description of the purpose of the offer - **signature** (bip340sig, optional): BIP-340 signature of the *node_id* on this offer - **chains** (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only): - the genesis blockhash (always 64 characters) - **currency** (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters) - **minor_unit** (u32, optional): the number of decimal places to apply to amount (if currency known) - **amount** (u64, optional): the amount in the *currency* adjusted by *minor_unit*, if any - **amount_msat** (msat, optional): the amount in bitcoin (if specified, and no *currency*) - **send_invoice** (boolean, optional): present if this is a send_invoice offer (always *true*) - **refund_for** (hex, optional): the *payment_preimage* of invoice this is a refund for (always 64 characters) - **vendor** (string, optional): the name of the vendor for this offer - **features** (hex, optional): the array of feature bits for this offer - **absolute_expiry** (u64, optional): UNIX timestamp of when this offer expires - **paths** (array of objects, optional): Paths to the destination: - **blinding** (pubkey): blinding factor for this path - **path** (array of objects): an individual path: - **node_id** (pubkey): node_id of the hop - **encrypted_recipient_data** (hex): encrypted TLV entry for this hop - **quantity_min** (u64, optional): the minimum quantity - **quantity_max** (u64, optional): the maximum quantity - **recurrence** (object, optional): how often to this offer should be used: - **time_unit** (u32): the BOLT12 time unit - **period** (u32): how many *time_unit* per payment period - **time_unit_name** (string, optional): the name of *time_unit* (if valid) - **basetime** (u64, optional): period starts at this UNIX timestamp - **start_any_period** (u64, optional): you can start at any period (only if **basetime** present) - **limit** (u32, optional): maximum period number for recurrence - **paywindow** (object, optional): when within a period will payment be accepted (default is prior and during the period): - **seconds_before** (u32): seconds prior to period start - **seconds_after** (u32): seconds after to period start - **proportional_amount** (boolean, optional): amount should be scaled if payed after period start (always *true*) - the following warnings are possible: - **warning_offer_unknown_currency**: The currency code is unknown (so no **minor_unit**) If **type** is "bolt12 offer", and **valid** is *false*: - the following warnings are possible: - **warning_offer_missing_description**: No **description** If **type** is "bolt12 invoice", and **valid** is *true*: - **node_id** (point32): x-only public key of the offering node - **signature** (bip340sig): BIP-340 signature of the *node_id* on this offer - **amount_msat** (msat): the amount in bitcoin - **description** (string): the description of the purpose of the offer - **created_at** (u64): the UNIX timestamp of invoice creation - **payment_hash** (hex): the hash of the *payment_preimage* (always 64 characters) - **relative_expiry** (u32): the number of seconds after *created_at* when this expires - **min_final_cltv_expiry** (u32): the number of blocks required by destination - **offer_id** (hex, optional): the id of this offer (merkle hash of non-signature fields) (always 64 characters) - **chain** (hex, optional): which blockchain this invoice is for (missing implies bitcoin mainnet only) (always 64 characters) - **send_invoice** (boolean, optional): present if this offer was a send_invoice offer (always *true*) - **refund_for** (hex, optional): the *payment_preimage* of invoice this is a refund for (always 64 characters) - **vendor** (string, optional): the name of the vendor for this offer - **features** (hex, optional): the array of feature bits for this offer - **paths** (array of objects, optional): Paths to the destination: - **blinding** (pubkey): blinding factor for this path - **path** (array of objects): an individual path: - **node_id** (pubkey): node_id of the hop - **encrypted_recipient_data** (hex): encrypted TLV entry for this hop - **quantity** (u64, optional): the quantity ordered - **recurrence_counter** (u32, optional): the 0-based counter for a recurring payment - **recurrence_start** (u32, optional): the optional start period for a recurring payment - **recurrence_basetime** (u32, optional): the UNIX timestamp of the first recurrence period start - **payer_key** (point32, optional): the transient key which identifies the payer - **payer_info** (hex, optional): the payer-provided blob to derive payer_key - **fallbacks** (array of objects, optional): onchain addresses: - **version** (u8): Segwit address version - **hex** (hex): Raw encoded segwit address - **address** (string, optional): bech32 segwit address - **refund_signature** (bip340sig, optional): the payer key signature to get a refund If **type** is "bolt12 invoice", and **valid** is *false*: - **fallbacks** (array of objects, optional): - the following warnings are possible: - **warning_invoice_fallbacks_version_invalid**: **version** is > 16 - the following warnings are possible: - **warning_invoice_missing_amount**: **amount_msat* missing - **warning_invoice_missing_description**: No **description** - **warning_invoice_missing_blinded_payinfo**: Has **paths** without payinfo - **warning_invoice_invalid_blinded_payinfo**: Does not have exactly one payinfo for each of **paths** - **warning_invoice_missing_recurrence_basetime**: Has **recurrence_counter** without **recurrence_basetime** - **warning_invoice_missing_created_at**: Missing **created_at** - **warning_invoice_missing_payment_hash**: Missing **payment_hash** - **warning_invoice_refund_signature_missing_payer_key**: Missing **payer_key** for refund_signature - **warning_invoice_refund_signature_invalid**: **refund_signature** incorrect - **warning_invoice_refund_missing_signature**: No **refund_signature** If **type** is "bolt12 invoice_request", and **valid** is *true*: - **offer_id** (hex): the id of the offer this is requesting (merkle hash of non-signature fields) (always 64 characters) - **payer_key** (point32): the transient key which identifies the payer - **chain** (hex, optional): which blockchain this invoice_request is for (missing implies bitcoin mainnet only) (always 64 characters) - **amount_msat** (msat, optional): the amount in bitcoin - **features** (hex, optional): the array of feature bits for this offer - **quantity** (u64, optional): the quantity ordered - **recurrence_counter** (u32, optional): the 0-based counter for a recurring payment - **recurrence_start** (u32, optional): the optional start period for a recurring payment - **payer_info** (hex, optional): the payer-provided blob to derive payer_key - **recurrence_signature** (bip340sig, optional): the payer key signature If **type** is "bolt12 invoice_request", and **valid** is *false*: - the following warnings are possible: - **warning_invoice_request_missing_offer_id**: No **offer_id** - **warning_invoice_request_missing_payer_key**: No **payer_key** - **warning_invoice_request_missing_recurrence_signature**: No **recurrence_signature** - **warning_invoice_request_invalid_recurrence_signature**: **recurrence_signature** incorrect If **type** is "bolt11 invoice", and **valid** is *true*: - **currency** (string): the BIP173 name for the currency - **created_at** (u64): the UNIX-style timestamp of the invoice - **expiry** (u64): the number of seconds this is valid after *timestamp* - **payee** (pubkey): the public key of the recipient - **payment_hash** (hex): the hash of the *payment_preimage* (always 64 characters) - **signature** (signature): signature of the *payee* on this invoice - **min_final_cltv_expiry** (u32): the minimum CLTV delay for the final node - **amount_msat** (msat, optional): Amount the invoice asked for - **description** (string, optional): the description of the purpose of the purchase - **description_hash** (hex, optional): the hash of the description, in place of *description* (always 64 characters) - **payment_secret** (hex, optional): the secret to hand to the payee node (always 64 characters) - **features** (hex, optional): the features bitmap for this invoice - **payment_metadata** (hex, optional): the payment_metadata to put in the payment - **fallbacks** (array of objects, optional): onchain addresses: - **type** (string): the address type (if known) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH") - **hex** (hex): Raw encoded address - **addr** (string, optional): the address in appropriate format for *type* - **routes** (array of arrays, optional): Route hints to the *payee*: - hops in the route: - **pubkey** (pubkey): the public key of the node - **short_channel_id** (short_channel_id): a channel to the next peer - **fee_base_msat** (msat): the base fee for payments - **fee_proportional_millionths** (u32): the parts-per-million fee for payments - **cltv_expiry_delta** (u32): the CLTV delta across this hop - **extra** (array of objects, optional): Any extra fields we didn't know how to parse: - **tag** (string): The bech32 letter which identifies this field (always 1 characters) - **data** (string): The bech32 data for this field If **type** is "rune", and **valid** is *true*: - **valid** (boolean) (always *true*) - **string** (string): the string encoding of the rune - **restrictions** (array of objects): restrictions built into the rune: all must pass: - **alternatives** (array of strings): each way restriction can be met: any can pass: - the alternative of form fieldname condition fieldname - **summary** (string): human-readable summary of this restriction - **unique_id** (string, optional): unique id (always a numeric id on runes we create) - **version** (string, optional): rune version, not currently set on runes we create If **type** is "rune", and **valid** is *false*: - **valid** (boolean) (always *false*) - **hex** (hex, optional): the raw rune in hex - the following warnings are possible: - **warning_rune_invalid_utf8**: the rune contains invalid UTF-8 strings [comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ Rusty Russell <> is mainly responsible. SEE ALSO -------- lightning-pay(7), lightning-offer(7), lightning-offerout(7), lightning-fetchinvoice(7), lightning-sendinvoice(7), lightning-commando-rune(7) [BOLT #11](https://github.com/lightningnetwork/bolts/blob/master/11-payment-encoding.md). [BOLT #12](https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md). RESOURCES --------- Main web site: [comment]: # ( SHA256STAMP:3e522a9788bb79302e4c4386c3937b7dcd8359d1b894364ac3e884bd3f695850)