LIGHTNING-DECODE(7)

NAME

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).

•   an emergency_recover string generated by hsmtool like lightning-hsmtool getemergencyrecover <path/to/emergency.recover>. It holds emergency.recover contents and starts with clnemerg1.

It may decode other formats in future.

RETURN VALUE

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", "emergency recover")

•   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 we use to identify this offer (always 64 characters)

•   offer_description (string): the description of the purpose of the offer

•   offer_node_id (pubkey): public key of the offering node

•   offer_chains (array of hashs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):

    •   the genesis blockhash

•   offer_metadata (hex, optional): any metadata the creator of the offer includes

•   offer_currency (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)

•   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_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_node_id (pubkey): the (presumably well-known) public key of the start of the path

    •   blinding (pubkey): blinding factor for this 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

•   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 (boolean, 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 paid after period start (always true)

•   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)

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

    •   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:

•   offer_description (string): the description of the purpose of the offer

•   offer_node_id (pubkey): public key of the offering node

•   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): the id we use to identify this offer (always 64 characters)

•   offer_chains (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):

    •   the genesis blockhash (always 64 characters)

•   offer_metadata (hex, optional): any metadata the creator of the offer includes

•   offer_currency (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)

•   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_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_node_id (pubkey): the (presumably well-known) public key of the start of the path

    •   blinding (pubkey): blinding factor for this 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

•   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 (boolean, 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 paid after period start (always true)

•   invreq_chain (hex, optional): which blockchain this offer is for (missing implies bitcoin mainnet only) (always 64 characters)

•   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_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_missing_invoice_request_signature: signature is not present

    •   warning_invalid_invoice_request_signature: Incorrect signature

If type is "bolt12 invoice", and valid is true:

•   offer_description (string): the description of the purpose of the offer

•   offer_node_id (pubkey): public key of the offering node

•   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_node_id (pubkey): the (presumably well-known) public key of the start of the path

    •   blinding (pubkey): blinding factor for this path

    •   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

•   invoice_created_at (u64): the UNIX timestamp of invoice creation

•   invoice_payment_hash (hex): the hash of the payment_preimage (always 64 characters)

•   invoice_amount_msat (msat): the amount required to fulfill invoice

•   signature (bip340sig): BIP-340 signature of the offer_node_id on this invoice

•   offer_id (hex, optional): the id we use to identify this offer (always 64 characters)

•   offer_chains (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):

    •   the genesis blockhash (always 64 characters)

•   offer_metadata (hex, optional): any metadata the creator of the offer includes

•   offer_currency (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)

•   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_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_node_id (pubkey): the (presumably well-known) public key of the start of the path

    •   blinding (pubkey): blinding factor for this 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

•   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 (boolean, 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 paid after period start (always true)

•   invreq_chain (hex, optional): which blockchain this offer is for (missing implies bitcoin mainnet only) (always 64 characters)

•   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_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_node_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): the address type (if known) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH", "P2TR")

    •   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

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)

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)

RESOURCES

Main web site: https://github.com/ElementsProject/lightning