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 emergency_recover. It may decode other formats in future.

•

string (string): Value to be decoded:

RETURN VALUE

On success, an object is returned, containing:

• type (string) (one of "bolt12 offer", "bolt12 invoice", "bolt12 invoice_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 except 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 (missing 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, optional): The description of the purpose of the offer. - offer_issuer (string, optional): The description of the creator of the offer. - offer_features (hex, optional): The feature bits of the offer. - offer_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, 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, 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 - offer_node_id (pubkey, optional): Obsolete name for offer_issuer_id. deprecated in v24.08, removed after v24.11 - offer_issuer_id (pubkey, optional): The pubkey associated with the offer (can be a node id). (added v24.08) - offer_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. 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_offer_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_missing_offer_issuer_id: offer_issuer_id is not present and there are no offer_paths (added v24.08) - warning_invalid_offer_description: offer_description is not valid UTF8. - warning_missing_offer_description: offer_description is not present. - warning_invalid_offer_currency: offer_currency_code is not valid UTF8. - warning_invalid_offer_issuer: offer_issuer is not valid UTF8.

If type is "bolt12 invoice_request", and valid is true: - invreq_metadata (hex): The payer-provided blob to derive invreq_payer_id. - invreq_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 identify 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. - 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, optional): The description of the purpose of the offer. - offer_issuer (string, optional): The description of the creator of the offer. - offer_features (hex, optional): The feature bits of the offer. - offer_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, 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, 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 - 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, 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. 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. - invreq_chain (hex, optional) (always 64 characters): 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, optional): A note attached by the payer. - invreq_paths (array of objects, 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): Blinding 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, optional): The name (part before the @). (added v25.02) - domain (string, optional): The domain (part after the @). (added v25.02) - invreq_recurrence_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_invoice_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 possible: - 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 following warnings are possible: - warning_invalid_offer_description: offer_description is not valid UTF8. - warning_missing_offer_description: offer_description is not present. - warning_invalid_offer_currency: offer_currency_code is not valid UTF8. - warning_invalid_offer_issuer: offer_issuer is not valid UTF8. - warning_missing_invreq_metadata: invreq_metadata is not present. - warning_missing_invreq_payer_id: invreq_payer_id is not present. - warning_invalid_invreq_payer_note: invreq_payer_note is not valid UTF8. - warning_invreq_bip_353_name_name_invalid: invreq_bip_353_name name field contains unusual characters. (added v25.02) - warning_invreq_bip_353_name_domain_invalid: invreq_bip_353_name domain field contains unusual characters. (added v25.02) - warning_missing_invoice_request_signature: signature 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. - invreq_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_proportional_millionths (u32): Proportional fee for path. - cltv_expiry_delta (u32): CLTV delta for path. - features (hex): Features allowed for path. - 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, 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 signature of the offer_issuer_id on this invoice. - offer_id (hex, optional) (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) (always 64 characters): 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, optional): The description of the purpose of the offer. - offer_issuer (string, optional): The description of the creator of the offer. - offer_features (hex, optional): The feature bits of the offer. - offer_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, 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, 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 - 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, 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. 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. - invreq_chain (hex, optional) (always 64 characters): 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, optional): A note attached by the payer. - invreq_paths (array of objects, 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): Blinding 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, optional): The name (part before the @). (added v25.02) - domain (string, optional): The domain (part after the @). (added v25.02) - invreq_recurrence_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_relative_expiry (u32, optional): The number of seconds after invoice_created_at when this expires. - invoice_fallbacks (array of objects, optional): 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_basetime (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: - warning_invoice_fallbacks_version_invalid: version is > 16. - the following warnings are possible: - warning_invalid_offer_description: offer_description is not valid UTF8. - warning_missing_offer_description: offer_description is not present. - warning_invalid_offer_currency: offer_currency_code is not valid UTF8. - warning_invalid_offer_issuer: offer_issuer is not valid UTF8. - warning_missing_invreq_metadata: invreq_metadata is not present. - warning_invalid_invreq_payer_note: invreq_payer_note is not valid UTF8. - warning_missing_invoice_paths: invoice_paths is not present. - warning_missing_invoice_blindedpay: invoice_blindedpay is not present. - warning_missing_invoice_created_at: invoice_created_at is not present. - warning_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_basetime is not present. - warning_missing_invoice_node_id: invoice_node_id is not present. - warning_missing_invoice_signature: signature is not present. - warning_invalid_invoice_signature: Incorrect 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 recipient. - 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. - description (string, optional): The description of the purpose of the purchase. - description_hash (hash, optional): The hash of the description, in place of description. - payment_secret (secret, optional): The secret to hand to the payee node. - 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) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH", "P2TR"): The address type (if known). - 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.: - (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_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) (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 (array 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 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.

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), lightning-sendinvoice(7), lightning-commando-rune(7)

RESOURCES

BOLT #11

BOLT #12 (experimental, bolt #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
}