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

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

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

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: