FreeBSD Manual Pages
LIGHTNING-DECODE(7) LIGHTNING-DECODE(7) NAME lightning-decode -- Command for decoding an invoice string (low-level) SYNOPSIS decode string DESCRIPTION Command added in v23.05. The decode RPC command checks and parses bolt11, bolt12, rune or emer- gency_recover. It may decode other formats in future. • string (string): Value to be decoded: • a bolt11 or bolt12 string (optionally prefixed by lightning: or LIGHTNING:) as specified by the BOLT 11 and BOLT 12 specifica- tions. • a rune as created by lightning-commando-rune(7). • an emergency_recover string generated by hsmtool like lightning- hsmtool getemergencyrecover <path/to/emergency.recover>. It holds emergency.recover contents and starts with clnemerg1. RETURN VALUE On success, an object is returned, containing: • type (string) (one of "bolt12 offer", "bolt12 invoice", "bolt12 in- voice_request", "bolt11 invoice", "rune", "emergency recover"): What kind of object it decoded to. • valid (boolean): If this is false, you MUST not use the result ex- cept for diagnostics! If type is "bolt12 offer", and valid is true: - offer_id (hex) (always 64 characters): The id we use to identify this offer. - offer_chains (array of hashs, optional): Which blockchains this offer is for (miss- ing implies bitcoin mainnet only).: - (hash, optional): The genesis blockhash. - offer_metadata (hex, optional): Any metadata the creator of the offer includes. - offer_currency (string, optional) (always 3 characters): ISO 4217 code of the currency (missing implies Bitcoin). - currency_minor_unit (u32, optional): The number of decimal places to apply to amount (if currency known). - offer_amount (u64, optional): The amount in the offer_currency adjusted by currency_minor_unit, if any. - offer_amount_msat (msat, optional): The amount in bitcoin (if specified, and no offer_currency). - offer_description (string, op- tional): The description of the purpose of the offer. - offer_issuer (string, optional): The description of the creator of the offer. - of- fer_features (hex, optional): The feature bits of the offer. - of- fer_absolute_expiry (u64, optional): UNIX timestamp of when this offer expires. - offer_quantity_max (u64, optional): The maximum quantity (or, if 0, means any quantity). - offer_paths (array of objects, op- tional): Paths to the destination.: - first_path_key (pubkey): Path key to deliver to first hop on this path. (added v24.11) - path (array of objects): An individual path.: - blinded_node_id (pubkey): Node_id of the hop. - encrypted_recipient_data (hex): Encrypted TLV entry for this hop. - first_node_id (pubkey, optional): The (presumably well- known) public key of the start of the path. - first_scid (short_chan- nel_id, optional): the short channel id of the start of the path (al- ternative to first_node_id) (added v23.05) - first_scid_dir (u32, op- tional): which end of the first_scid is the start of the path (added v23.05) - blinding (pubkey, optional): Blinding factor for this path. deprecated in v24.11, removed after v25.05 - offer_node_id (pubkey, op- tional): Obsolete name for offer_issuer_id. deprecated in v24.08, re- moved after v24.11 - offer_issuer_id (pubkey, optional): The pubkey as- sociated with the offer (can be a node id). (added v24.08) - offer_re- currence (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, op- tional): Maximum period number for recurrence. - paywindow (object, optional): When within a period will payment be accepted. The 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) (always true): Amount should be scaled if paid after period start. - unknown_offer_tlvs (array of objects, optional): Any extra fields we didn't know how to parse.: - type (u64): The type. - length (u64): The length. - value (hex): The value. - the following warnings are possible: - warning_unknown_of- fer_currency: The currency code is unknown (so no currency_minor_unit). - warning_empty_blinded_path: The blinded path has 0 hops. (added v24.08) If type is "bolt12 offer", and valid is false: - the following warnings are possible: - warning_missing_offer_node_id: offer_node_id is not present. deprecated in v24.08, removed after v24.11 - warning_miss- ing_offer_issuer_id: offer_issuer_id is not present and there are no offer_paths (added v24.08) - warning_invalid_offer_description: of- fer_description is not valid UTF8. - warning_missing_offer_descrip- tion: offer_description is not present. - warning_invalid_offer_cur- rency: offer_currency_code is not valid UTF8. - warning_invalid_of- fer_issuer: offer_issuer is not valid UTF8. If type is "bolt12 invoice_request", and valid is true: - invreq_meta- data (hex): The payer-provided blob to derive invreq_payer_id. - in- vreq_payer_id (hex): The payer-provided key. - signature (bip340sig): BIP-340 signature of the invreq_payer_id on this invoice_request. - offer_id (hex, optional) (always 64 characters): The id we use to iden- tify this offer. - offer_chains (array of hexs, optional): Which blockchains this offer is for (missing implies bitcoin mainnet only).: - (hex, optional) (always 64 characters): The genesis blockhash. - of- fer_metadata (hex, optional): Any metadata the creator of the offer in- cludes. - offer_currency (string, optional) (always 3 characters): ISO 4217 code of the currency (missing implies Bitcoin). - currency_mi- nor_unit (u32, optional): The number of decimal places to apply to amount (if currency known). - offer_amount (u64, optional): The amount in the offer_currency adjusted by currency_minor_unit, if any. - of- fer_amount_msat (msat, optional): The amount in bitcoin (if specified, and no offer_currency). - offer_description (string, optional): The description of the purpose of the offer. - offer_issuer (string, op- tional): The description of the creator of the offer. - offer_features (hex, optional): The feature bits of the offer. - offer_absolute_ex- piry (u64, optional): UNIX timestamp of when this offer expires. - of- fer_quantity_max (u64, optional): The maximum quantity (or, if 0, means any quantity). - offer_paths (array of objects, optional): Paths to the destination.: - first_path_key (pubkey): Path key to deliver to first hop on this path. (added v24.11) - path (array of objects): An individual path.: - blinded_node_id (pubkey): Node_id of the hop. - encrypted_recipient_data (hex): Encrypted TLV entry for this hop. - first_node_id (pubkey, optional): The (presumably well-known) public key of the start of the path. - first_scid (short_channel_id, op- tional): the short channel id of the start of the path (alternative to first_node_id) (added v23.05) - first_scid_dir (u32, optional): which end of the first_scid is the start of the path (added v23.05) - blind- ing (pubkey, optional): Blinding factor for this path. deprecated in v24.11, removed after v25.05 - offer_node_id (pubkey, optional): Public key of the offering node. deprecated in v24.08, removed after v24.11 - offer_issuer_id (pubkey, optional): Public key of the offering node (can be a node id). (added v24.08) - offer_recurrence (object, op- tional): 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 time- stamp. - 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. The default is prior and during the period.: - seconds_before (u32): Seconds prior to period start. - sec- onds_after (u32): Seconds after to period start. - proportional_amount (boolean, optional) (always true): Amount should be scaled if paid af- ter period start. - invreq_chain (hex, optional) (always 64 charac- ters): Which blockchain this offer is for (missing implies bitcoin mainnet only). - invreq_amount_msat (msat, optional): The amount the invoice should be for. - invreq_features (hex, optional): The feature bits of the invoice_request. - invreq_quantity (u64, optional): The number of items to invoice for. - invreq_payer_note (string, op- tional): A note attached by the payer. - invreq_paths (array of ob- jects, optional): Paths to the destination. (added v24.08): - first_path_key (pubkey): Path key to deliver to first hop on this path. (added v24.11) - path (array of objects): An individual path. (added v24.08): - blinded_node_id (pubkey): Node_id of the hop. (added v24.08) - encrypted_recipient_data (hex): Encrypted TLV entry for this hop. (added v24.08) - first_node_id (pubkey, optional): The (presumably well-known) public key of the start of the path. (added v24.08) - first_scid (short_channel_id, optional): the short channel id of the start of the path (alternative to first_node_id) (added v24.08) - first_scid_dir (u32, optional): which end of the first_scid is the start of the path (added v24.08) - blinding (pubkey, optional): Blind- ing factor for this path. deprecated in v24.11, removed after v25.05 (added v24.08) - invreq_bip_353_name (object, optional): BIP 353 name which this invoice request is for. (added v25.02): - name (string, op- tional): The name (part before the @). (added v25.02) - domain (string, optional): The domain (part after the @). (added v25.02) - invreq_re- currence_counter (u32, optional): Which number request this is for the same invoice. - invreq_recurrence_start (u32, optional): When we're requesting to start an invoice at a non-zero period. - unknown_in- voice_request_tlvs (array of objects, optional): Any extra fields we didn't know how to parse.: - type (u64): The type. - length (u64): The length. - value (hex): The value. - the following warnings are possi- ble: - warning_unknown_offer_currency: The currency code is unknown (so no currency_minor_unit). If type is "bolt12 invoice_request", and valid is false: - the follow- ing warnings are possible: - warning_invalid_offer_description: of- fer_description is not valid UTF8. - warning_missing_offer_descrip- tion: offer_description is not present. - warning_invalid_offer_cur- rency: offer_currency_code is not valid UTF8. - warning_invalid_of- fer_issuer: offer_issuer is not valid UTF8. - warning_missing_in- vreq_metadata: invreq_metadata is not present. - warning_missing_in- vreq_payer_id: invreq_payer_id is not present. - warning_invalid_in- vreq_payer_note: invreq_payer_note is not valid UTF8. - warning_in- vreq_bip_353_name_name_invalid: invreq_bip_353_name name field contains unusual characters. (added v25.02) - warning_invreq_bip_353_name_do- main_invalid: invreq_bip_353_name domain field contains unusual charac- ters. (added v25.02) - warning_missing_invoice_request_signature: sig- nature is not present. - warning_invalid_invoice_request_signature: Incorrect signature. If type is "bolt12 invoice", and valid is true: - invreq_metadata (hex): The payer-provided blob to derive invreq_payer_id. - in- vreq_payer_id (hex): The payer-provided key. - invoice_paths (array of objects): Paths to pay the destination.: - first_path_key (pubkey): Path key to deliver to first hop on this path. (added v24.11) - payinfo (object): - fee_base_msat (msat): Basefee for path. - fee_propor- tional_millionths (u32): Proportional fee for path. - cltv_ex- piry_delta (u32): CLTV delta for path. - features (hex): Features al- lowed for path. - path (array of objects): An individual path.: - blinded_node_id (pubkey): Node_id of the hop. - encrypted_recipi- ent_data (hex): Encrypted TLV entry for this hop. - first_node_id (pubkey, optional): The (presumably well-known) public key of the start of the path. - first_scid (short_channel_id, optional): the short channel id of the start of the path (alternative to first_node_id) (added v23.05) - first_scid_dir (u32, optional): which end of the first_scid is the start of the path (added v23.05) - blinding (pubkey, optional): Blinding factor for this path. deprecated in v24.11, removed after v25.05 - invoice_created_at (u64): The UNIX timestamp of invoice creation. - invoice_payment_hash (hex) (always 64 characters): The hash of the payment_preimage. - invoice_amount_msat (msat): The amount required to fulfill invoice. - signature (bip340sig): BIP-340 signa- ture of the offer_issuer_id on this invoice. - offer_id (hex, op- tional) (always 64 characters): The id we use to identify this offer. - offer_chains (array of hexs, optional): Which blockchains this offer is for (missing implies bitcoin mainnet only).: - (hex, optional) (al- ways 64 characters): The genesis blockhash. - offer_metadata (hex, op- tional): Any metadata the creator of the offer includes. - offer_cur- rency (string, optional) (always 3 characters): ISO 4217 code of the currency (missing implies Bitcoin). - currency_minor_unit (u32, op- tional): The number of decimal places to apply to amount (if currency known). - offer_amount (u64, optional): The amount in the offer_cur- rency adjusted by currency_minor_unit, if any. - offer_amount_msat (msat, optional): The amount in bitcoin (if specified, and no of- fer_currency). - offer_description (string, optional): The description of the purpose of the offer. - offer_issuer (string, optional): The description of the creator of the offer. - offer_features (hex, op- tional): The feature bits of the offer. - offer_absolute_expiry (u64, optional): UNIX timestamp of when this offer expires. - offer_quan- tity_max (u64, optional): The maximum quantity (or, if 0, means any quantity). - offer_paths (array of objects, optional): Paths to the destination.: - first_path_key (pubkey): Path key to deliver to first hop on this path. (added v24.11) - path (array of objects): An individ- ual path.: - blinded_node_id (pubkey): Node_id of the hop. - en- crypted_recipient_data (hex): Encrypted TLV entry for this hop. - first_node_id (pubkey, optional): The (presumably well-known) public key of the start of the path. - first_scid (short_channel_id, op- tional): the short channel id of the start of the path (alternative to first_node_id) (added v23.05) - first_scid_dir (u32, optional): which end of the first_scid is the start of the path (added v23.05) - blind- ing (pubkey, optional): Blinding factor for this path. deprecated in v24.11, removed after v25.05 - offer_node_id (pubkey, optional): Public key of the offering node. deprecated in v24.08, removed after v24.11 - offer_issuer_id (pubkey, optional): Public key of the offering node (can be a node id). (added v24.08) - offer_recurrence (object, op- tional): 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 time- stamp. - 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. The default is prior and during the period.: - seconds_before (u32): Seconds prior to period start. - sec- onds_after (u32): Seconds after to period start. - proportional_amount (boolean, optional) (always true): Amount should be scaled if paid af- ter period start. - invreq_chain (hex, optional) (always 64 charac- ters): Which blockchain this offer is for (missing implies bitcoin mainnet only). - invreq_amount_msat (msat, optional): The amount the invoice should be for. - invreq_features (hex, optional): The feature bits of the invoice_request. - invreq_quantity (u64, optional): The number of items to invoice for. - invreq_payer_note (string, op- tional): A note attached by the payer. - invreq_paths (array of ob- jects, optional): Paths to the destination. (added v24.08): - first_path_key (pubkey): Path key to deliver to first hop on this path. (added v24.11) - path (array of objects): An individual path. (added v24.08): - blinded_node_id (pubkey): Node_id of the hop. (added v24.08) - encrypted_recipient_data (hex): Encrypted TLV entry for this hop. (added v24.08) - first_node_id (pubkey, optional): The (presumably well-known) public key of the start of the path. (added v24.08) - first_scid (short_channel_id, optional): the short channel id of the start of the path (alternative to first_node_id) (added v24.08) - first_scid_dir (u32, optional): which end of the first_scid is the start of the path (added v24.08) - blinding (pubkey, optional): Blind- ing factor for this path. deprecated in v24.11, removed after v25.05 (added v24.08) - invreq_bip_353_name (object, optional): BIP 353 name which this invoice request is for. (added v25.02): - name (string, op- tional): The name (part before the @). (added v25.02) - domain (string, optional): The domain (part after the @). (added v25.02) - invreq_re- currence_counter (u32, optional): Which number request this is for the same invoice. - invreq_recurrence_start (u32, optional): When we're requesting to start an invoice at a non-zero period. - invoice_rela- tive_expiry (u32, optional): The number of seconds after invoice_cre- ated_at when this expires. - invoice_fallbacks (array of objects, op- tional): Onchain addresses.: - version (u8): Segwit address version. - hex (hex): Raw encoded segwit address. - address (string, optional): Bech32 segwit address. - invoice_features (hex, optional): The feature bits of the invoice. - invoice_node_id (pubkey, optional): The id to pay (usually the same as offer_issuer_id). - invoice_recurrence_base- time (u64, optional): The UNIX timestamp to base the invoice periods on. - unknown_invoice_tlvs (array of objects, optional): Any extra fields we didn't know how to parse.: - type (u64): The type. - length (u64): The length. - value (hex): The value. - the following warnings are possible: - warning_unknown_offer_currency: The currency code is unknown (so no currency_minor_unit). If type is "bolt12 invoice", and valid is false: - fallbacks (array of objects, optional): - the following warnings are possible: - warn- ing_invoice_fallbacks_version_invalid: version is > 16. - the follow- ing warnings are possible: - warning_invalid_offer_description: of- fer_description is not valid UTF8. - warning_missing_offer_descrip- tion: offer_description is not present. - warning_invalid_offer_cur- rency: offer_currency_code is not valid UTF8. - warning_invalid_of- fer_issuer: offer_issuer is not valid UTF8. - warning_missing_in- vreq_metadata: invreq_metadata is not present. - warning_invalid_in- vreq_payer_note: invreq_payer_note is not valid UTF8. - warning_miss- ing_invoice_paths: invoice_paths is not present. - warning_missing_in- voice_blindedpay: invoice_blindedpay is not present. - warning_miss- ing_invoice_created_at: invoice_created_at is not present. - warn- ing_missing_invoice_payment_hash: invoice_payment_hash is not present. - warning_missing_invoice_amount: invoice_amount is not present. - warning_missing_invoice_recurrence_basetime: invoice_recurrence_base- time is not present. - warning_missing_invoice_node_id: in- voice_node_id is not present. - warning_missing_invoice_signature: signature is not present. - warning_invalid_invoice_signature: Incor- rect signature. 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 created_at. - payee (pubkey): The public key of the re- cipient. - payment_hash (hash): The hash of the payment_preimage. - 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. - de- scription (string, optional): The description of the purpose of the purchase. - description_hash (hash, optional): The hash of the de- scription, in place of description. - payment_secret (secret, op- tional): The secret to hand to the payee node. - features (hex, op- tional): The features bitmap for this invoice. - payment_metadata (hex, optional): The payment_metadata to put in the payment. - fall- backs (array of objects, optional): Onchain addresses.: - type (string) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH", "P2TR"): The address type (if known). - hex (hex): Raw encoded address. - addr (string, op- tional): The address in appropriate format for type. - routes (array of arrays, optional): Route hints to the payee.: - (array of objects): 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_propor- tional_millionths (u32): The parts-per-million fee for payments. - cltv_expiry_delta (u32): The CLTV delta across this hop. - extra (ar- ray of objects, optional): Any extra fields we didn't know how to parse.: - tag (string) (always 1 characters): The bech32 letter which identifies this field. - 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 (ar- ray of objects): Restrictions built into the rune: all must pass.: - alternatives (array of strings): Each way restriction can be met: any can pass.: - (string, optional): The alternative of form fieldname con- dition fieldname. - summary (string): Human-readable summary of this restriction. - unique_id (string, optional): Unique id (always a nu- meric id on runes we create). - version (string, optional): Rune ver- sion, 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. If type is "emergency recover", and valid is true: - decrypted (hex): The decrypted value of the provided bech32 of emergency.recover. (added v23.11) AUTHOR Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible. SEE ALSO lightning-pay(7), lightning-offer(7), lightning-fetchinvoice(7), light- ning-sendinvoice(7), lightning-commando-rune(7) RESOURCES BOLT #11 <https://github.com/lightning/bolts/blob/master/11-payment- encoding.md> BOLT #12 <https://github.com/rustyrussell/lightning- rfc/blob/guilt/offers/12-offer-encoding.md> (experimental, bolt <https://github.com/lightning/bolts> #798) Main web site: <https://github.com/ElementsProject/lightning> EXAMPLES Example 1: Request: $ lightning-cli decode "zFMd1fjhrAYxUeFA54TjloZqOt8JrA_i_nYwIgXkag49MA==" { "id": "example:decode#1", "method": "decode", "params": [ "zFMd1fjhrAYxUeFA54TjloZqOt8JrA_i_nYwIgXkag49MA==" ] } Response: { "type": "rune", "unique_id": "0", "string": "cc531dd5f8e1ac063151e140e784e396866a3adf09ac0fe2fe76302205e46a0e:=0", "restrictions": [], "valid": true } Example 2: Request: $ lightning-cli decode "lnbcrt100n1pnt2bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000" { "id": "example:decode#2", "method": "decode", "params": [ "lnbcrt100n1pnt2bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000" ] } Response: { "type": "bolt11 invoice", "currency": "bcrt", "created_at": 1738000000, "expiry": 604800, "payee": "nodeid020202020202020202020202020202020202020202020202020202020202", "amount_msat": 200000, "description": "l22 description", "min_final_cltv_expiry": 5, "payment_secret": "paymentsecretinvl00220002200022000220002200022000220002200022000", "features": "02024100", "routes": [ [ { "pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303", "short_channel_id": "111x1x1", "fee_base_msat": 1, "fee_proportional_millionths": 10, "cltv_expiry_delta": 6 } ] ], "payment_hash": "paymenthashinvl0220022002200220022002200220022002200220022002200", "signature": "dcde30c4bb50bed221009d010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101", "valid": true } Core Lightning v25.02 LIGHTNING-DECODE(7)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | AUTHOR | SEE ALSO | RESOURCES | EXAMPLES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-decode&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>