LIGHTNING-DECODE(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💅 NAME 💅

okay bestie, welcome to lightning-decode (7) — the low-level command page for decode, aka the "Command for decoding an invoice string (low-level)". think of it as the little decoder ring for your Lightning strings, and yes it's giving main character energy ✨

⭐ SYNOPSIS ⭐

decode string

🎀 DESCRIPTION 🎀

so this command was added in v23.05 — periodt.

the decode RPC command checks and parses bolt11, bolt12, rune or emergency_recover. and lowkey it may decode other formats in future, so stay tuned 💖

string (string) — the value to be decoded, and here's what it can be:
- 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 lightning-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", "bolt12 payer_proof") — what kind of object it decoded to. like, the vibe check of your string 🦋
valid (boolean) — if this is false, you MUST not use the result except for diagnostics!

bestie fr fr, that valid warning is not a drill. if it's false, the result is diagnostics-only, no cap 💀

🌸 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)
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.
- compulsory_field (boolean) — true if this is the offer_recurrence_compulsory field (which means readers which don't understand recurrence cannot use it), false if this is the offer_recurrence_optional field. (added v26.06)
- time_unit_name (string, optional) — the name of time_unit (if valid).
- basetime (u64, optional) — period starts at this UNIX timestamp.
- 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_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)
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.
- limit (u32, optional) — maximum period number for recurrence.
- compulsory_field (boolean, optional) — true if this is the offer_recurrence_compulsory field (which means readers which don't understand recurrence cannot use it), false if this is the offer_recurrence_optional field. (added v26.06)
- 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)
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.
invreq_recurrence_cancel (boolean, optional) (always true) — present to cancel a recurring invoice (added v26.06)
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).

So when type comes back as "bolt12 invoice_request" and valid is false, your girl is basically handing you a lil list of what went wrong 💅 — these are the warnings you might see:

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_invreq_recurrence_cancel_without_counter — invreq_recurrence_cancel is present, but invreq_recurrence_counter isn't. (added v26.06)
warning_invreq_recurrence_cancel_with_zero_counter — invreq_recurrence_cancel is present, but invreq_recurrence_counter is 0. (added v26.06)
warning_missing_invoice_request_signature — signature is not present
warning_invalid_invoice_request_signature — Incorrect signature

Now, when type is "bolt12 invoice" and valid is true, it's giving full breakdown energy 👑 — here's every field you can get back:

invreq_metadata (hex) — the payer-provided blob you use 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
  - htlc_minimum_msat (msat) — minimum amount which can be sent via path. (added v26.04)
  - htlc_maximum_msat (msat) — maximum amount which can be sent via path. (added v26.04)
  - 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_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)
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 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
- limit (u32, optional) — maximum period number for recurrence
- compulsory_field (boolean, optional) — True if this is the offer_recurrence_compulsory field (which means readers which don't understand recurrence cannot use it), false if this is the offer_recurrence_optional field. (added v26.06)
- 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)
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)

And if type is "bolt12 invoice" but valid is false 🙈 — yeah, it didn't pass the vibe check, and these are the warnings that can pop up:

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, you get this whole little treasure chest 💖:

currency (string) — the BIP173 name for the currency, iykyk.
created_at (u64) — the UNIX-style timestamp of the invoice.
expiry (u64) — how many 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) — the payee's signature on this invoice.
min_final_cltv_expiry (u32) — the minimum CLTV delay for the final node.
amount_msat (msat, optional) — the amount the invoice asked for.
description (string, optional) — what the purchase is actually for.
description_hash (hash, optional) — the hash of the description, standing 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, bestie:
- 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 the 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 "bolt12 payer_proof", and valid is true, it's giving proof-of-payment realness ✨:

invreq_payer_id (pubkey) — the payer's key.
invoice_payment_hash (hex) (always 64 characters) — the hash of the proof_preimage.
invoice_node_id (pubkey) — the id to pay (usually the same as offer_issuer_id).
signature (bip340sig) — BIP-340 signature of invoice_node_id over the disclosed invoice fields.
proof_preimage (hex) (always 64 characters) — the payment preimage proving payment. (added v26.06)
proof_omitted_tlvs (array of u64s) — TLV type markers for fields omitted from the proof. (added v26.06)
- (u64, optional)
proof_missing_hashes (array of hashs) — Merkle hashes needed to reconstruct omitted subtrees. (added v26.06)
- (hash, optional)
proof_leaf_hashes (array of hashs) — nonce hashes for each disclosed non-signature TLV field. (added v26.06)
- (hash, optional)
proof_signature (bip340sig) — BIP-340 signature of invreq_payer_id over the proof. (added v26.06)
type (string, optional)
valid (boolean, optional)
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)
offer_issuer_id (pubkey, optional) — the pubkey associated with the offer (can be a node id). (added v24.08)
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)
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)
invoice_paths (array of objects, optional) — 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.
  - htlc_minimum_msat (msat) — minimum amount which can be sent via path. (added v26.04)
  - htlc_maximum_msat (msat) — maximum amount which can be sent via path. (added v26.04)
  - 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, optional) — the UNIX timestamp of invoice creation.
invoice_relative_expiry (u32, optional) — the number of seconds after invoice_created_at when this expires.
invoice_amount_msat (msat, optional) — the amount required to fulfill invoice.
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.
proof_note (string, optional) — optional note attached to the proof by the payer. (added v26.06)
unknown_payer_proof_tlvs (array of objects, optional) — any extra fields we didn't know how to parse. (added v26.06)
- type (u64) — the type.
- length (u64) — the length.
- value (hex) — the value.

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.

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

Finally, 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. king behaviour, honestly 👑.

🦋 SEE ALSO 🦋

🌈 RESOURCES 🌈

BOLT #11
BOLT #12 (experimental, bolt #798)
Main web site: https://github.com/ElementsProject/lightning

go read the bolts bestie, they're literally right there 🫶

✨ EXAMPLES ✨

okay bestie, here's where it gets real — two whole worked examples so you can see exactly what goes in and what comes out 💅

🎀 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
}

see how that worked?? 🫶 you handed it a rune, it handed you back the whole vibe — "type" came back as "rune", the "unique_id" is "0", the "string" is "cc531dd5f8e1ac063151e140e784e396866a3adf09ac0fe2fe76302205e46a0e:=0", "restrictions" is an empty list [], and "valid" is true. iconic. no notes. 👑

🦋 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
}

and that's the bolt11 glow-up 🌸 like — "type" is "bolt11 invoice", "currency" is "bcrt", "created_at" is 1738000000, "expiry" is 604800, "payee" is "nodeid020202020202020202020202020202020202020202020202020202020202", "amount_msat" is 200000, "description" is "l22 description", "min_final_cltv_expiry" is 5, "payment_secret" is "paymentsecretinvl00220002200022000220002200022000220002200022000", "features" is "02024100". then the "routes" list — and yes it's a list inside a list, nesting is the moment 💀 — holding one hop with "pubkey" "nodeid030303030303030303030303030303030303030303030303030303030303", "short_channel_id" "111x1x1", "fee_base_msat" 1, "fee_proportional_millionths" 10, and "cltv_expiry_delta" 6. then "payment_hash" is "paymenthashinvl0220022002200220022002200220022002200220022002200", "signature" is "dcde30c4bb50bed221009d010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101", and "valid" is true. slay. 🔥

and that's the whole page, bestie 🧚 go decode something cute. 💜

this lil tour came to you straight out of Core Lightning v26.06.9 — the LIGHTNING-DECODE(7) era, no cap ✨💖

📦 where this page comes from

nixpkgs unstable: clightning 26.06.9
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

LIGHTNING-DECODE(7)

💅 NAME 💅

⭐ SYNOPSIS ⭐

🎀 DESCRIPTION 🎀

🌈 RETURN VALUE 🌈

🌸 if type is "bolt12 offer", and valid is true 🌸

🦋 if type is "bolt12 offer", and valid is false 🦋

🧚 if type is "bolt12 invoice_request", and valid is true 🧚

💅 AUTHOR 💅

🦋 SEE ALSO 🦋

🌈 RESOURCES 🌈

✨ EXAMPLES ✨

🎀 Example 1

🦋 Example 2

🌸 if `type` is `"bolt12 offer"`, and `valid` is `true` 🌸

🦋 if `type` is `"bolt12 offer"`, and `valid` is `false` 🦋

🧚 if `type` is `"bolt12 invoice_request"`, and `valid` is `true` 🧚