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 <[email protected]> is mainly responsible.

RESOURCES

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