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_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).:
- (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.:
- 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.
- 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)
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).

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_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) (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.:
- 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.
- 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)
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_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_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.:
- 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.
- 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)
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_node_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.:
- 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.
- 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)
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_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) (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 "zm0x_eLgHexaTvZn3Cz7gb_YlvrlYGDo_w4BYlR9SS09MSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5Jm1ldGhvZC9saXN0ZGF0YXN0b3Jl"

{
  "id": "example:decode#1",
  "method": "decode",
  "params": [
    "zm0x_eLgHexaTvZn3Cz7gb_YlvrlYGDo_w4BYlR9SS09MSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5Jm1ldGhvZC9saXN0ZGF0YXN0b3Jl"
  ]
}

Response:

{
  "type": "rune",
  "unique_id": "1",
  "string": "ce6d31fde2e01dec5a4ef667dc2cfb81bfd896fae56060e8ff0e0162547d492d:=1&method^list|method^get|method=summary&method/listdatastore",
  "restrictions": [
    {
      "alternatives": [
        "method^list",
        "method^get",
        "method=summary"
      ],
      "summary": "method (of command) starts with 'list' OR method (of command) starts with 'get' OR method (of command) equal to 'summary'"
    },
    {
      "alternatives": [
        "method/listdatastore"
      ],
      "summary": "method (of command) unequal to 'listdatastore'"
    }
  ],
  "valid": true
}

Example 2: