lightning-decode

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_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).:
    • (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_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): t
      h
      e

s
h
o
r
t

c
h
a
n
n
e
l

i
d

o
f

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h

(
a
l
t
e
r
n
a
t
i
v
e

t
o

f
i
r
s
t
_
n

o
d
e
_
i
d
) (added v23.05)
- first_scid_dir (u32, optional): w
h
i
c
h

e
n
d

o
f

t
h
e

f
i
r
s
t
_
s
c
i
d

i
s

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h (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_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) (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_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): t
      h
      e

s
h
o
r
t

c
h
a
n
n
e
l

i
d

o
f

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h

(
a
l
t
e
r
n
a
t
i
v
e

t
o

f
i
r
s
t
_
n

o
d
e
_
i
d
) (added v23.05)
- first_scid_dir (u32, optional): w
h
i
c
h

e
n
d

o
f

t
h
e

f
i
r
s
t
_
s
c
i
d

i
s

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h (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_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.:
    • 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): t
      h
      e

s
h
o
r
t

c
h
a
n
n
e
l

i
d

o
f

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h

(
a
l
t
e
r
n
a
t
i
v
e

t
o

f
i
r
s
t
_
n

o
d
e
_
i
d
) (added v23.05)
- first_scid_dir (u32, optional): w
h
i
c
h

e
n
d

o
f

t
h
e

f
i
r
s
t
_
s
c
i
d

i
s

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h (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_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): t
      h
      e

s
h
o
r
t

c
h
a
n
n
e
l

i
d

o
f

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h

(
a
l
t
e
r
n
a
t
i
v
e

t
o

f
i
r
s
t
_
n

o
d
e
_
i
d
) (added v23.05)
- first_scid_dir (u32, optional): w
h
i
c
h

e
n
d

o
f

t
h
e

f
i
r
s
t
_
s
c
i
d

i
s

t
h
e

s
t
a
r
t

o
f

t
h
e

p
a
t
h (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)

JSON EXAMPLE

Example 1:

Request:

{
  "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:

Request:

{
  "id": "example:decode#2",
  "method": "decode",
  "params": [
    "lnbcrt1m1pja0f2hsp5xyssdvdsu24dmmesrt6x84wfrm4mscsnzq7hl2suzeu90wy6g53qpp5zyyu3anwfsfl64pewe0tg7j28map2wwnhvaam5nt70rlwxa0cegqdqjv3jhxcmjd9c8g6t0dcxqyjw5qcqp9rzjqgkjyd3q5dv6gllh77kygly9c3kfy0d9xwyjyxsq2nq3c83u5vw4jqqqvuqqqqgqqqqqqqlgqqqq86qqqc9qxpqysgq7u4f99u4kepagme27t5c3gdl7czlnjaw7kxryxgm87w2j02j3g94r2vrukhpgedhcdkcdec27m7jrl2lvcr6uh3rdv9lgpz0vc0zcfcqnugjdw"
  ]
}

Response:

{
  "type": "bolt11 invoice",
  "currency": "bcrt",
  "created_at": 1708631383,
  "expiry": 604800,
  "payee": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
  "amount_msat": 100000000,
  "description": "description",
  "min_final_cltv_expiry": 5,
  "payment_secret": "312106b1b0e2aaddef301af463d5c91eebb86213103d7faa1c167857b89a4522",
  "features": "02024100",
  "routes": [
    [
      {
        "pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
        "short_channel_id": "103x1x0",
        "fee_base_msat": 1000,
        "fee_proportional_millionths": 1000,
        "cltv_expiry_delta": 6
      }
    ]
  ],
  "payment_hash": "1109c8f66e4c13fd5439765eb47a4a3efa1539d3bb3bddd26bf3c7f71bafc650",
  "signature": "3045022100f72a929795b643d46f2af2e988a1bff605f9cbaef58c32191b3f9ca93d528a0b022051a983e5ae1465b7c36d86e70af6fd21fd5f6607ae5e236b0bf4044f661e2c27",
  "valid": true
}

AUTHOR

Rusty Russell <[email protected]> is mainly responsible.

SEE ALSO

lightning-pay(7), lightning-offer(7), lightning-fetchinvoice(7), lightning-sendinvoice(7), lightning-commando-rune(7)

RESOURCES

BOLT #11

BOLT #12
(experimental, bolt #798)

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