mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 01:43:36 +01:00
Code Issues Projects Releases Wiki Activity
master
core-lightning/doc/schemas/lightning-decode.json
Rusty Russell b327bd30c3 doc: fix all JSON schemas to enforce no additional properties. 
Without this, we have hardly any enforcement.  This is why the schema
mistake fixed in the previous patches weren't spotted immediately.

The hard work was done by:

```
$ for f in lightning-*.json; do grep -v '^  "additionalProperties": false,' $f | bagto $f; done
$ for f in lightning-*.json; do sed 's/"properties": {/"additionalProperties": false, "properties": {/' $f | bagto $f; done
$ make fmt-schemas
```

Then checking where 'additionalProperties: true' had been turned to
false (we deliberately use it in some places where there are if
statements in the schema, or occasionally where there can be arbitrary
fields).

[Including doc/rpc-schema-draft.json update by Shahana]
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-10-30 15:39:12 +10:30

2415 lines
75 KiB
JSON
Raw Permalink Blame History

{
"$schema": "../rpc-schema-draft.json",
"type": "object",
"added": "v23.05",
"rpc": "decode",
"title": "Command for decoding an invoice string (low-level)",
"description": [
"The **decode** RPC command checks and parses `bolt11`, `bolt12`, `rune` or `emergency_recover`. It may decode other formats in future."
],
"request": {
"required": [
"string"
],
"additionalProperties": false,
"properties": {
"string": {
"type": "string",
"description": [
"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`."
]
}
}
},
"response": {
"required": [
"type",
"valid"
],
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt12 offer",
"bolt12 invoice",
"bolt12 invoice_request",
"bolt11 invoice",
"rune",
"emergency recover"
],
"description": [
"What kind of object it decoded to."
]
},
"valid": {
"type": "boolean",
"description": [
"If this is false, you *MUST* not use the result except for diagnostics!"
]
}
},
"allOf": [
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt12 offer"
]
},
"valid": {
"type": "boolean",
"enum": [
true
]
}
}
},
"then": {
"required": [
"offer_id"
],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"offer_id": {
"type": "hex",
"description": [
"The id we use to identify this offer."
],
"maxLength": 64,
"minLength": 64
},
"offer_chains": {
"type": "array",
"description": [
"Which blockchains this offer is for (missing implies bitcoin mainnet only)."
],
"items": {
"type": "hash",
"description": [
"The genesis blockhash."
]
}
},
"offer_metadata": {
"type": "hex",
"description": [
"Any metadata the creator of the offer includes."
]
},
"offer_currency": {
"type": "string",
"description": [
"ISO 4217 code of the currency (missing implies Bitcoin)."
],
"maxLength": 3,
"minLength": 3
},
"warning_unknown_offer_currency": {
"type": "string",
"description": [
"The currency code is unknown (so no `currency_minor_unit`)."
]
},
"currency_minor_unit": {
"type": "u32",
"description": [
"The number of decimal places to apply to amount (if currency known)."
]
},
"offer_amount": {
"type": "u64",
"description": [
"The amount in the `offer_currency` adjusted by `currency_minor_unit`, if any."
]
},
"offer_amount_msat": {
"type": "msat",
"description": [
"The amount in bitcoin (if specified, and no `offer_currency`)."
]
},
"offer_description": {
"type": "string",
"description": [
"The description of the purpose of the offer."
]
},
"offer_issuer": {
"type": "string",
"description": [
"The description of the creator of the offer."
]
},
"offer_features": {
"type": "hex",
"description": [
"The feature bits of the offer."
]
},
"offer_absolute_expiry": {
"type": "u64",
"description": [
"UNIX timestamp of when this offer expires."
]
},
"offer_quantity_max": {
"type": "u64",
"description": [
"The maximum quantity (or, if 0, means any quantity)."
]
},
"offer_paths": {
"type": "array",
"description": [
"Paths to the destination."
],
"items": {
"type": "object",
"required": [
"first_path_key",
"path"
],
"additionalProperties": false,
"properties": {
"first_node_id": {
"type": "pubkey",
"description": [
"The (presumably well-known) public key of the start of the path."
]
},
"first_scid": {
"added": "v23.05",
"type": "short_channel_id",
"description": [
"the short channel id of the start of the path (alternative to first_node_id)"
]
},
"first_scid_dir": {
"added": "v23.05",
"type": "u32",
"description": [
"which end of the first_scid is the start of the path"
]
},
"blinding": {
"deprecated": [
"v24.11",
"v25.05"
],
"type": "pubkey",
"description": [
"Blinding factor for this path."
]
},
"first_path_key": {
"added": "v24.11",
"type": "pubkey",
"description": [
"Path key to deliver to first hop on this path."
]
},
"path": {
"type": "array",
"description": [
"An individual path."
],
"items": {
"type": "object",
"required": [
"blinded_node_id",
"encrypted_recipient_data"
],
"additionalProperties": false,
"properties": {
"blinded_node_id": {
"type": "pubkey",
"description": [
"Node_id of the hop."
]
},
"encrypted_recipient_data": {
"type": "hex",
"description": [
"Encrypted TLV entry for this hop."
]
}
}
}
}
}
}
},
"warning_empty_blinded_path": {
"added": "v24.08",
"type": "string",
"description": [
"The blinded path has 0 hops."
]
},
"offer_node_id": {
"type": "pubkey",
"deprecated": [
"v24.08",
"v24.11"
],
"description": [
"Obsolete name for offer_issuer_id."
]
},
"offer_issuer_id": {
"type": "pubkey",
"added": "v24.08",
"description": [
"The pubkey associated with the offer (can be a node id)."
]
},
"offer_recurrence": {
"type": "object",
"description": [
"How often to this offer should be used."
],
"required": [
"period",
"time_unit"
],
"additionalProperties": false,
"properties": {
"time_unit": {
"type": "u32",
"description": [
"The BOLT12 time unit."
]
},
"time_unit_name": {
"type": "string",
"description": [
"The name of `time_unit` (if valid)."
]
},
"period": {
"type": "u32",
"description": [
"How many `time_unit` per payment period."
]
},
"basetime": {
"type": "u64",
"description": [
"Period starts at this UNIX timestamp."
]
},
"start_any_period": {
"type": "u64",
"description": [
"You can start at any period (only if `basetime` present)."
]
},
"limit": {
"type": "u32",
"description": [
"Maximum period number for recurrence."
]
},
"paywindow": {
"type": "object",
"description": [
"When within a period will payment be accepted."
],
"default": "prior and during the period",
"required": [
"seconds_before",
"seconds_after"
],
"additionalProperties": false,
"properties": {
"seconds_before": {
"type": "u32",
"description": [
"Seconds prior to period start."
]
},
"seconds_after": {
"type": "u32",
"description": [
"Seconds after to period start."
]
},
"proportional_amount": {
"type": "boolean",
"enum": [
true
],
"description": [
"Amount should be scaled if paid after period start."
]
}
}
}
}
},
"unknown_offer_tlvs": {
"type": "array",
"description": [
"Any extra fields we didn't know how to parse."
],
"items": {
"type": "object",
"required": [
"type",
"length",
"value"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "u64",
"description": [
"The type."
]
},
"length": {
"type": "u64",
"description": [
"The length."
]
},
"value": {
"type": "hex",
"description": [
"The value."
]
}
}
}
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt12 offer"
]
},
"valid": {
"type": "boolean",
"enum": [
false
]
}
}
},
"then": {
"required": [],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"offer_id": {},
"node_id": {},
"signature": {},
"chains": {},
"currency": {},
"minor_unit": {},
"warning_unknown_offer_currency": {},
"amount": {},
"amount_msat": {},
"send_invoice": {},
"description": {},
"vendor": {},
"features": {},
"absolute_expiry": {},
"paths": {},
"quantity_max": {},
"unknown_offer_tlvs": {},
"recurrence": {},
"warning_missing_offer_node_id": {
"type": "string",
"deprecated": [
"v24.08",
"v24.11"
],
"description": [
"`offer_node_id` is not present."
]
},
"warning_missing_offer_issuer_id": {
"type": "string",
"added": "v24.08",
"description": [
"`offer_issuer_id` is not present and there are no offer_paths"
]
},
"warning_invalid_offer_description": {
"type": "string",
"description": [
"`offer_description` is not valid UTF8."
]
},
"warning_missing_offer_description": {
"type": "string",
"description": [
"`offer_description` is not present."
]
},
"warning_invalid_offer_currency": {
"type": "string",
"description": [
"`offer_currency_code` is not valid UTF8."
]
},
"warning_invalid_offer_issuer": {
"type": "string",
"description": [
"`offer_issuer` is not valid UTF8."
]
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt12 invoice_request"
]
},
"valid": {
"type": "boolean",
"enum": [
true
]
}
}
},
"then": {
"required": [
"invreq_metadata",
"invreq_payer_id",
"signature"
],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"offer_id": {
"type": "hex",
"description": [
"The id we use to identify this offer."
],
"maxLength": 64,
"minLength": 64
},
"offer_chains": {
"type": "array",
"description": [
"Which blockchains this offer is for (missing implies bitcoin mainnet only)."
],
"items": {
"type": "hex",
"description": [
"The genesis blockhash."
],
"maxLength": 64,
"minLength": 64
}
},
"offer_metadata": {
"type": "hex",
"description": [
"Any metadata the creator of the offer includes."
]
},
"offer_currency": {
"type": "string",
"description": [
"ISO 4217 code of the currency (missing implies Bitcoin)."
],
"maxLength": 3,
"minLength": 3
},
"warning_unknown_offer_currency": {
"type": "string",
"description": [
"The currency code is unknown (so no `currency_minor_unit`)."
]
},
"currency_minor_unit": {
"type": "u32",
"description": [
"The number of decimal places to apply to amount (if currency known)."
]
},
"offer_amount": {
"type": "u64",
"description": [
"The amount in the `offer_currency` adjusted by `currency_minor_unit`, if any."
]
},
"offer_amount_msat": {
"type": "msat",
"description": [
"The amount in bitcoin (if specified, and no `offer_currency`)."
]
},
"offer_description": {
"type": "string",
"description": [
"The description of the purpose of the offer."
]
},
"offer_issuer": {
"type": "string",
"description": [
"The description of the creator of the offer."
]
},
"offer_features": {
"type": "hex",
"description": [
"The feature bits of the offer."
]
},
"offer_absolute_expiry": {
"type": "u64",
"description": [
"UNIX timestamp of when this offer expires."
]
},
"offer_quantity_max": {
"type": "u64",
"description": [
"The maximum quantity (or, if 0, means any quantity)."
]
},
"offer_paths": {
"type": "array",
"description": [
"Paths to the destination."
],
"items": {
"type": "object",
"required": [
"first_path_key",
"path"
],
"additionalProperties": false,
"properties": {
"first_node_id": {
"type": "pubkey",
"description": [
"The (presumably well-known) public key of the start of the path."
]
},
"first_scid": {
"added": "v23.05",
"type": "short_channel_id",
"description": [
"the short channel id of the start of the path (alternative to first_node_id)"
]
},
"first_scid_dir": {
"added": "v23.05",
"type": "u32",
"description": [
"which end of the first_scid is the start of the path"
]
},
"first_path_key": {
"added": "v24.11",
"type": "pubkey",
"description": [
"Path key to deliver to first hop on this path."
]
},
"blinding": {
"deprecated": [
"v24.11",
"v25.05"
],
"type": "pubkey",
"description": [
"Blinding factor for this path."
]
},
"path": {
"type": "array",
"description": [
"An individual path."
],
"items": {
"type": "object",
"required": [
"blinded_node_id",
"encrypted_recipient_data"
],
"additionalProperties": false,
"properties": {
"blinded_node_id": {
"type": "pubkey",
"description": [
"Node_id of the hop."
]
},
"encrypted_recipient_data": {
"type": "hex",
"description": [
"Encrypted TLV entry for this hop."
]
}
}
}
}
}
}
},
"offer_node_id": {
"type": "pubkey",
"deprecated": [
"v24.08",
"v24.11"
],
"description": [
"Public key of the offering node."
]
},
"offer_issuer_id": {
"type": "pubkey",
"added": "v24.08",
"description": [
"Public key of the offering node (can be a node id)."
]
},
"offer_recurrence": {
"type": "object",
"description": [
"How often to this offer should be used."
],
"required": [
"period",
"time_unit"
],
"additionalProperties": false,
"properties": {
"time_unit": {
"type": "u32",
"description": [
"The BOLT12 time unit."
]
},
"time_unit_name": {
"type": "string",
"description": [
"The name of `time_unit` (if valid)."
]
},
"period": {
"type": "u32",
"description": [
"How many `time_unit` per payment period."
]
},
"basetime": {
"type": "u64",
"description": [
"Period starts at this UNIX timestamp."
]
},
"start_any_period": {
"type": "u64",
"description": [
"You can start at any period (only if `basetime` present)."
]
},
"limit": {
"type": "u32",
"description": [
"Maximum period number for recurrence."
]
},
"paywindow": {
"type": "object",
"description": [
"When within a period will payment be accepted."
],
"default": "prior and during the period",
"required": [
"seconds_before",
"seconds_after"
],
"additionalProperties": false,
"properties": {
"seconds_before": {
"type": "u32",
"description": [
"Seconds prior to period start."
]
},
"seconds_after": {
"type": "u32",
"description": [
"Seconds after to period start."
]
},
"proportional_amount": {
"type": "boolean",
"enum": [
true
],
"description": [
"Amount should be scaled if paid after period start."
]
}
}
}
}
},
"invreq_metadata": {
"type": "hex",
"description": [
"The payer-provided blob to derive invreq_payer_id."
]
},
"invreq_payer_id": {
"type": "hex",
"description": [
"The payer-provided key."
]
},
"invreq_chain": {
"type": "hex",
"description": [
"Which blockchain this offer is for (missing implies bitcoin mainnet only)."
],
"maxLength": 64,
"minLength": 64
},
"invreq_amount_msat": {
"type": "msat",
"description": [
"The amount the invoice should be for."
]
},
"invreq_features": {
"type": "hex",
"description": [
"The feature bits of the invoice_request."
]
},
"invreq_quantity": {
"type": "u64",
"description": [
"The number of items to invoice for."
]
},
"invreq_payer_note": {
"type": "string",
"description": [
"A note attached by the payer."
]
},
"invreq_paths": {
"type": "array",
"added": "v24.08",
"description": [
"Paths to the destination."
],
"items": {
"type": "object",
"required": [
"first_path_key",
"path"
],
"additionalProperties": false,
"properties": {
"first_node_id": {
"added": "v24.08",
"type": "pubkey",
"description": [
"The (presumably well-known) public key of the start of the path."
]
},
"first_scid": {
"added": "v24.08",
"type": "short_channel_id",
"description": [
"the short channel id of the start of the path (alternative to first_node_id)"
]
},
"first_scid_dir": {
"added": "v24.08",
"type": "u32",
"description": [
"which end of the first_scid is the start of the path"
]
},
"blinding": {
"added": "v24.08",
"deprecated": [
"v24.11",
"v25.05"
],
"type": "pubkey",
"description": [
"Blinding factor for this path."
]
},
"first_path_key": {
"added": "v24.11",
"type": "pubkey",
"description": [
"Path key to deliver to first hop on this path."
]
},
"path": {
"type": "array",
"added": "v24.08",
"description": [
"An individual path."
],
"items": {
"type": "object",
"required": [
"blinded_node_id",
"encrypted_recipient_data"
],
"additionalProperties": false,
"properties": {
"blinded_node_id": {
"added": "v24.08",
"type": "pubkey",
"description": [
"Node_id of the hop."
]
},
"encrypted_recipient_data": {
"added": "v24.08",
"type": "hex",
"description": [
"Encrypted TLV entry for this hop."
]
}
}
}
}
}
}
},
"invreq_recurrence_counter": {
"type": "u32",
"description": [
"Which number request this is for the same invoice."
]
},
"invreq_recurrence_start": {
"type": "u32",
"description": [
"When we're requesting to start an invoice at a non-zero period."
]
},
"signature": {
"type": "bip340sig",
"description": [
"BIP-340 signature of the `invreq_payer_id` on this invoice_request."
]
},
"unknown_invoice_request_tlvs": {
"type": "array",
"description": [
"Any extra fields we didn't know how to parse."
],
"items": {
"type": "object",
"required": [
"type",
"length",
"value"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "u64",
"description": [
"The type."
]
},
"length": {
"type": "u64",
"description": [
"The length."
]
},
"value": {
"type": "hex",
"description": [
"The value."
]
}
}
}
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt12 invoice_request"
]
},
"valid": {
"type": "boolean",
"enum": [
false
]
}
}
},
"then": {
"required": [],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"offer_id": {},
"offer_chains": {},
"offer_metadata": {},
"offer_currency": {},
"warning_unknown_offer_currency": {},
"currency_minor_unit": {},
"offer_amount": {},
"offer_amount_msat": {},
"offer_description": {},
"offer_issuer": {},
"offer_features": {},
"offer_absolute_expiry": {},
"offer_quantity_max": {},
"offer_paths": {},
"offer_node_id": {},
"offer_issuer_id": {},
"offer_recurrence": {},
"invreq_metadata": {},
"invreq_payer_id": {},
"invreq_chain": {},
"invreq_amount_msat": {},
"invreq_features": {},
"invreq_quantity": {},
"invreq_payer_note": {},
"invreq_paths": {},
"invreq_recurrence_counter": {},
"invreq_recurrence_start": {},
"warning_invalid_offer_description": {
"type": "string",
"description": [
"`offer_description` is not valid UTF8."
]
},
"warning_missing_offer_description": {
"type": "string",
"description": [
"`offer_description` is not present."
]
},
"warning_invalid_offer_currency": {
"type": "string",
"description": [
"`offer_currency_code` is not valid UTF8."
]
},
"warning_invalid_offer_issuer": {
"type": "string",
"description": [
"`offer_issuer` is not valid UTF8."
]
},
"warning_missing_invreq_metadata": {
"type": "string",
"description": [
"`invreq_metadata` is not present."
]
},
"warning_missing_invreq_payer_id": {
"type": "string",
"description": [
"`invreq_payer_id` is not present."
]
},
"warning_invalid_invreq_payer_note": {
"type": "string",
"description": [
"`invreq_payer_note` is not valid UTF8."
]
},
"warning_missing_invoice_request_signature": {
"type": "string",
"description": [
"`signature` is not present."
]
},
"warning_invalid_invoice_request_signature": {
"type": "string",
"description": [
"Incorrect `signature`."
]
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt12 invoice"
]
},
"valid": {
"type": "boolean",
"enum": [
true
]
}
}
},
"then": {
"required": [
"invreq_metadata",
"invreq_payer_id",
"invoice_paths",
"invoice_created_at",
"invoice_payment_hash",
"invoice_amount_msat",
"signature"
],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"offer_id": {
"type": "hex",
"description": [
"The id we use to identify this offer."
],
"maxLength": 64,
"minLength": 64
},
"offer_chains": {
"type": "array",
"description": [
"Which blockchains this offer is for (missing implies bitcoin mainnet only)."
],
"items": {
"type": "hex",
"description": [
"The genesis blockhash."
],
"maxLength": 64,
"minLength": 64
}
},
"offer_metadata": {
"type": "hex",
"description": [
"Any metadata the creator of the offer includes."
]
},
"offer_currency": {
"type": "string",
"description": [
"ISO 4217 code of the currency (missing implies Bitcoin)."
],
"maxLength": 3,
"minLength": 3
},
"warning_unknown_offer_currency": {
"type": "string",
"description": [
"The currency code is unknown (so no `currency_minor_unit`)."
]
},
"currency_minor_unit": {
"type": "u32",
"description": [
"The number of decimal places to apply to amount (if currency known)."
]
},
"offer_amount": {
"type": "u64",
"description": [
"The amount in the `offer_currency` adjusted by `currency_minor_unit`, if any."
]
},
"offer_amount_msat": {
"type": "msat",
"description": [
"The amount in bitcoin (if specified, and no `offer_currency`)."
]
},
"offer_description": {
"type": "string",
"description": [
"The description of the purpose of the offer."
]
},
"offer_issuer": {
"type": "string",
"description": [
"The description of the creator of the offer."
]
},
"offer_features": {
"type": "hex",
"description": [
"The feature bits of the offer."
]
},
"offer_absolute_expiry": {
"type": "u64",
"description": [
"UNIX timestamp of when this offer expires."
]
},
"offer_quantity_max": {
"type": "u64",
"description": [
"The maximum quantity (or, if 0, means any quantity)."
]
},
"offer_paths": {
"type": "array",
"description": [
"Paths to the destination."
],
"items": {
"type": "object",
"required": [
"first_path_key",
"path"
],
"additionalProperties": false,
"properties": {
"first_node_id": {
"type": "pubkey",
"description": [
"The (presumably well-known) public key of the start of the path."
]
},
"first_scid": {
"added": "v23.05",
"type": "short_channel_id",
"description": [
"the short channel id of the start of the path (alternative to first_node_id)"
]
},
"first_scid_dir": {
"added": "v23.05",
"type": "u32",
"description": [
"which end of the first_scid is the start of the path"
]
},
"blinding": {
"deprecated": [
"v24.11",
"v25.05"
],
"type": "pubkey",
"description": [
"Blinding factor for this path."
]
},
"first_path_key": {
"added": "v24.11",
"type": "pubkey",
"description": [
"Path key to deliver to first hop on this path."
]
},
"path": {
"type": "array",
"description": [
"An individual path."
],
"items": {
"type": "object",
"required": [
"blinded_node_id",
"encrypted_recipient_data"
],
"additionalProperties": false,
"properties": {
"blinded_node_id": {
"type": "pubkey",
"description": [
"Node_id of the hop."
]
},
"encrypted_recipient_data": {
"type": "hex",
"description": [
"Encrypted TLV entry for this hop."
]
}
}
}
}
}
}
},
"offer_node_id": {
"type": "pubkey",
"deprecated": [
"v24.08",
"v24.11"
],
"description": [
"Public key of the offering node."
]
},
"offer_issuer_id": {
"type": "pubkey",
"added": "v24.08",
"description": [
"Public key of the offering node (can be a node id)."
]
},
"offer_recurrence": {
"type": "object",
"description": [
"How often to this offer should be used."
],
"required": [
"period",
"time_unit"
],
"additionalProperties": false,
"properties": {
"time_unit": {
"type": "u32",
"description": [
"The BOLT12 time unit."
]
},
"time_unit_name": {
"type": "string",
"description": [
"The name of `time_unit` (if valid)."
]
},
"period": {
"type": "u32",
"description": [
"How many `time_unit` per payment period."
]
},
"basetime": {
"type": "u64",
"description": [
"Period starts at this UNIX timestamp."
]
},
"start_any_period": {
"type": "u64",
"description": [
"You can start at any period (only if `basetime` present)."
]
},
"limit": {
"type": "u32",
"description": [
"Maximum period number for recurrence."
]
},
"paywindow": {
"type": "object",
"description": [
"When within a period will payment be accepted."
],
"default": "prior and during the period",
"required": [
"seconds_before",
"seconds_after"
],
"additionalProperties": false,
"properties": {
"seconds_before": {
"type": "u32",
"description": [
"Seconds prior to period start."
]
},
"seconds_after": {
"type": "u32",
"description": [
"Seconds after to period start."
]
},
"proportional_amount": {
"type": "boolean",
"enum": [
true
],
"description": [
"Amount should be scaled if paid after period start."
]
}
}
}
}
},
"invreq_metadata": {
"type": "hex",
"description": [
"The payer-provided blob to derive invreq_payer_id."
]
},
"invreq_payer_id": {
"type": "hex",
"description": [
"The payer-provided key."
]
},
"invreq_chain": {
"type": "hex",
"description": [
"Which blockchain this offer is for (missing implies bitcoin mainnet only)."
],
"maxLength": 64,
"minLength": 64
},
"invreq_amount_msat": {
"type": "msat",
"description": [
"The amount the invoice should be for."
]
},
"invreq_features": {
"type": "hex",
"description": [
"The feature bits of the invoice_request."
]
},
"invreq_quantity": {
"type": "u64",
"description": [
"The number of items to invoice for."
]
},
"invreq_payer_note": {
"type": "string",
"description": [
"A note attached by the payer."
]
},
"invreq_paths": {
"type": "array",
"added": "v24.08",
"description": [
"Paths to the destination."
],
"items": {
"type": "object",
"required": [
"first_path_key",
"path"
],
"additionalProperties": false,
"properties": {
"first_node_id": {
"added": "v24.08",
"type": "pubkey",
"description": [
"The (presumably well-known) public key of the start of the path."
]
},
"first_scid": {
"added": "v24.08",
"type": "short_channel_id",
"description": [
"the short channel id of the start of the path (alternative to first_node_id)"
]
},
"first_scid_dir": {
"added": "v24.08",
"type": "u32",
"description": [
"which end of the first_scid is the start of the path"
]
},
"blinding": {
"added": "v24.08",
"deprecated": [
"v24.11",
"v25.05"
],
"type": "pubkey",
"description": [
"Blinding factor for this path."
]
},
"first_path_key": {
"added": "v24.11",
"type": "pubkey",
"description": [
"Path key to deliver to first hop on this path."
]
},
"path": {
"type": "array",
"added": "v24.08",
"description": [
"An individual path."
],
"items": {
"type": "object",
"required": [
"blinded_node_id",
"encrypted_recipient_data"
],
"additionalProperties": false,
"properties": {
"blinded_node_id": {
"added": "v24.08",
"type": "pubkey",
"description": [
"Node_id of the hop."
]
},
"encrypted_recipient_data": {
"added": "v24.08",
"type": "hex",
"description": [
"Encrypted TLV entry for this hop."
]
}
}
}
}
}
}
},
"invreq_recurrence_counter": {
"type": "u32",
"description": [
"Which number request this is for the same invoice."
]
},
"invreq_recurrence_start": {
"type": "u32",
"description": [
"When we're requesting to start an invoice at a non-zero period."
]
},
"invoice_paths": {
"type": "array",
"description": [
"Paths to pay the destination."
],
"items": {
"type": "object",
"required": [
"first_path_key",
"payinfo",
"path"
],
"additionalProperties": false,
"properties": {
"first_node_id": {
"type": "pubkey",
"description": [
"The (presumably well-known) public key of the start of the path."
]
},
"first_scid": {
"added": "v23.05",
"type": "short_channel_id",
"description": [
"the short channel id of the start of the path (alternative to first_node_id)"
]
},
"first_scid_dir": {
"added": "v23.05",
"type": "u32",
"description": [
"which end of the first_scid is the start of the path"
]
},
"blinding": {
"type": "pubkey",
"deprecated": [
"v24.11",
"v25.05"
],
"description": [
"Blinding factor for this path."
]
},
"first_path_key": {
"added": "v24.11",
"type": "pubkey",
"description": [
"Path key to deliver to first hop on this path."
]
},
"payinfo": {
"type": "object",
"required": [
"fee_base_msat",
"fee_proportional_millionths",
"cltv_expiry_delta",
"features"
],
"additionalProperties": false,
"properties": {
"fee_base_msat": {
"type": "msat",
"description": [
"Basefee for path."
]
},
"fee_proportional_millionths": {
"type": "u32",
"description": [
"Proportional fee for path."
]
},
"cltv_expiry_delta": {
"type": "u32",
"description": [
"CLTV delta for path."
]
},
"features": {
"type": "hex",
"description": [
"Features allowed for path."
]
}
}
},
"path": {
"type": "array",
"description": [
"An individual path."
],
"items": {
"type": "object",
"required": [
"blinded_node_id",
"encrypted_recipient_data"
],
"additionalProperties": false,
"properties": {
"blinded_node_id": {
"type": "pubkey",
"description": [
"Node_id of the hop."
]
},
"encrypted_recipient_data": {
"type": "hex",
"description": [
"Encrypted TLV entry for this hop."
]
}
}
}
}
}
}
},
"invoice_created_at": {
"type": "u64",
"description": [
"The UNIX timestamp of invoice creation."
]
},
"invoice_relative_expiry": {
"type": "u32",
"description": [
"The number of seconds after *invoice_created_at* when this expires."
]
},
"invoice_payment_hash": {
"type": "hex",
"description": [
"The hash of the *payment_preimage*."
],
"maxLength": 64,
"minLength": 64
},
"invoice_amount_msat": {
"type": "msat",
"description": [
"The amount required to fulfill invoice."
]
},
"invoice_fallbacks": {
"type": "array",
"description": [
"Onchain addresses."
],
"items": {
"type": "object",
"required": [
"version",
"hex"
],
"additionalProperties": false,
"properties": {
"version": {
"type": "u8",
"description": [
"Segwit address version."
]
},
"hex": {
"type": "hex",
"description": [
"Raw encoded segwit address."
]
},
"address": {
"type": "string",
"description": [
"Bech32 segwit address."
]
}
}
}
},
"invoice_features": {
"type": "hex",
"description": [
"The feature bits of the invoice."
]
},
"invoice_node_id": {
"type": "pubkey",
"description": [
"The id to pay (usually the same as offer_issuer_id)."
]
},
"invoice_recurrence_basetime": {
"type": "u64",
"description": [
"The UNIX timestamp to base the invoice periods on."
]
},
"signature": {
"type": "bip340sig",
"description": [
"BIP-340 signature of the `offer_issuer_id` on this invoice."
]
},
"unknown_invoice_tlvs": {
"type": "array",
"description": [
"Any extra fields we didn't know how to parse."
],
"items": {
"type": "object",
"required": [
"type",
"length",
"value"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "u64",
"description": [
"The type."
]
},
"length": {
"type": "u64",
"description": [
"The length."
]
},
"value": {
"type": "hex",
"description": [
"The value."
]
}
}
}
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt12 invoice"
]
},
"valid": {
"type": "boolean",
"enum": [
false
]
}
}
},
"then": {
"required": [],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"offer_id": {},
"offer_chains": {},
"offer_metadata": {},
"offer_currency": {},
"warning_unknown_offer_currency": {},
"currency_minor_unit": {},
"offer_amount": {},
"offer_amount_msat": {},
"offer_description": {},
"offer_issuer": {},
"offer_features": {},
"offer_absolute_expiry": {},
"offer_quantity_max": {},
"offer_paths": {},
"offer_node_id": {},
"offer_issuer_id": {},
"offer_recurrence": {},
"invreq_metadata": {},
"invreq_payer_id": {},
"invreq_chain": {},
"invreq_amount_msat": {},
"invreq_features": {},
"invreq_quantity": {},
"invreq_payer_note": {},
"invreq_paths": {},
"invreq_node_id": {},
"invreq_recurrence_counter": {},
"invreq_recurrence_start": {},
"warning_invalid_offer_description": {
"type": "string",
"description": [
"`offer_description` is not valid UTF8."
]
},
"warning_missing_offer_description": {
"type": "string",
"description": [
"`offer_description` is not present."
]
},
"warning_invalid_offer_currency": {
"type": "string",
"description": [
"`offer_currency_code` is not valid UTF8."
]
},
"warning_invalid_offer_issuer": {
"type": "string",
"description": [
"`offer_issuer` is not valid UTF8."
]
},
"warning_missing_invreq_metadata": {
"type": "string",
"description": [
"`invreq_metadata` is not present."
]
},
"warning_invalid_invreq_payer_note": {
"type": "string",
"description": [
"`invreq_payer_note` is not valid UTF8."
]
},
"warning_missing_invoice_paths": {
"type": "string",
"description": [
"`invoice_paths` is not present."
]
},
"warning_missing_invoice_blindedpay": {
"type": "string",
"description": [
"`invoice_blindedpay` is not present."
]
},
"warning_missing_invoice_created_at": {
"type": "string",
"description": [
"`invoice_created_at` is not present."
]
},
"warning_missing_invoice_payment_hash": {
"type": "string",
"description": [
"`invoice_payment_hash` is not present."
]
},
"warning_missing_invoice_amount": {
"type": "string",
"description": [
"`invoice_amount` is not present."
]
},
"warning_missing_invoice_recurrence_basetime": {
"type": "string",
"description": [
"`invoice_recurrence_basetime` is not present."
]
},
"warning_missing_invoice_node_id": {
"type": "string",
"description": [
"`invoice_node_id` is not present."
]
},
"warning_missing_invoice_signature": {
"type": "string",
"description": [
"`signature` is not present."
]
},
"warning_invalid_invoice_signature": {
"type": "string",
"description": [
"Incorrect `signature`."
]
},
"fallbacks": {
"type": "array",
"items": {
"type": "object",
"required": [
"version",
"hex"
],
"additionalProperties": false,
"properties": {
"version": {},
"hex": {},
"address": {},
"warning_invoice_fallbacks_version_invalid": {
"type": "string",
"description": [
"`version` is > 16."
]
}
}
}
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"bolt11 invoice"
]
},
"valid": {
"type": "boolean",
"enum": [
true
]
}
}
},
"then": {
"required": [
"currency",
"created_at",
"expiry",
"payee",
"min_final_cltv_expiry",
"payment_hash",
"signature"
],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"currency": {
"type": "string",
"description": [
"The BIP173 name for the currency."
]
},
"created_at": {
"type": "u64",
"description": [
"The UNIX-style timestamp of the invoice."
]
},
"expiry": {
"type": "u64",
"description": [
"The number of seconds this is valid after `created_at`."
]
},
"payee": {
"type": "pubkey",
"description": [
"The public key of the recipient."
]
},
"amount_msat": {
"type": "msat",
"description": [
"Amount the invoice asked for."
]
},
"payment_hash": {
"type": "hash",
"description": [
"The hash of the *payment_preimage*."
]
},
"signature": {
"type": "signature",
"description": [
"Signature of the *payee* on this invoice."
]
},
"description": {
"type": "string",
"description": [
"The description of the purpose of the purchase."
]
},
"description_hash": {
"type": "hash",
"description": [
"The hash of the description, in place of *description*."
]
},
"min_final_cltv_expiry": {
"type": "u32",
"description": [
"The minimum CLTV delay for the final node."
]
},
"payment_secret": {
"type": "secret",
"description": [
"The secret to hand to the payee node."
]
},
"features": {
"type": "hex",
"description": [
"The features bitmap for this invoice."
]
},
"payment_metadata": {
"type": "hex",
"description": [
"The payment_metadata to put in the payment."
]
},
"fallbacks": {
"type": "array",
"description": [
"Onchain addresses."
],
"items": {
"type": "object",
"required": [
"type",
"hex"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": [
"The address type (if known)."
],
"enum": [
"P2PKH",
"P2SH",
"P2WPKH",
"P2WSH",
"P2TR"
]
},
"addr": {
"type": "string",
"description": [
"The address in appropriate format for *type*."
]
},
"hex": {
"type": "hex",
"description": [
"Raw encoded address."
]
}
}
}
},
"routes": {
"type": "array",
"description": [
"Route hints to the *payee*."
],
"items": {
"type": "array",
"description": [
"Hops in the route."
],
"items": {
"type": "object",
"required": [
"pubkey",
"short_channel_id",
"fee_base_msat",
"fee_proportional_millionths",
"cltv_expiry_delta"
],
"additionalProperties": false,
"properties": {
"pubkey": {
"type": "pubkey",
"description": [
"The public key of the node."
]
},
"short_channel_id": {
"type": "short_channel_id",
"description": [
"A channel to the next peer."
]
},
"fee_base_msat": {
"type": "msat",
"description": [
"The base fee for payments."
]
},
"fee_proportional_millionths": {
"type": "u32",
"description": [
"The parts-per-million fee for payments."
]
},
"cltv_expiry_delta": {
"type": "u32",
"description": [
"The CLTV delta across this hop."
]
}
}
}
}
},
"extra": {
"type": "array",
"description": [
"Any extra fields we didn't know how to parse."
],
"items": {
"type": "object",
"required": [
"tag",
"data"
],
"additionalProperties": false,
"properties": {
"tag": {
"type": "string",
"description": [
"The bech32 letter which identifies this field."
],
"maxLength": 1,
"minLength": 1
},
"data": {
"type": "string",
"description": [
"The bech32 data for this field."
]
}
}
}
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"rune"
]
},
"valid": {
"type": "boolean",
"enum": [
true
]
}
}
},
"then": {
"required": [
"string",
"restrictions",
"valid"
],
"additionalProperties": false,
"properties": {
"unique_id": {
"type": "string",
"description": [
"Unique id (always a numeric id on runes we create)."
]
},
"version": {
"type": "string",
"description": [
"Rune version, not currently set on runes we create."
]
},
"valid": {
"type": "boolean",
"enum": [
true
]
},
"type": {},
"string": {
"type": "string",
"description": [
"The string encoding of the rune."
]
},
"restrictions": {
"type": "array",
"description": [
"Restrictions built into the rune: all must pass."
],
"items": {
"type": "object",
"required": [
"alternatives",
"summary"
],
"additionalProperties": false,
"properties": {
"alternatives": {
"type": "array",
"description": [
"Each way restriction can be met: any can pass."
],
"items": {
"type": "string",
"description": [
"The alternative of form fieldname condition fieldname."
]
}
},
"summary": {
"type": "string",
"description": [
"Human-readable summary of this restriction."
]
}
}
}
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"rune"
]
},
"valid": {
"type": "boolean",
"enum": [
false
]
}
}
},
"then": {
"required": [
"valid"
],
"additionalProperties": false,
"properties": {
"valid": {
"type": "boolean",
"enum": [
false
]
},
"type": {},
"warning_rune_invalid_utf8": {
"type": "string",
"description": [
"The rune contains invalid UTF-8 strings."
]
},
"hex": {
"type": "hex",
"description": [
"The raw rune in hex."
]
}
}
}
},
{
"if": {
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"emergency recover"
]
},
"valid": {
"type": "boolean",
"enum": [
true
]
}
}
},
"then": {
"required": [
"decrypted"
],
"additionalProperties": false,
"properties": {
"type": {},
"valid": {},
"decrypted": {
"type": "hex",
"description": [
"The decrypted value of the provided bech32 of emergency.recover."
],
"added": "v23.11"
}
}
}
}
]
},
"author": [
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
],
"see_also": [
"lightning-pay(7)",
"lightning-offer(7)",
"lightning-fetchinvoice(7)",
"lightning-sendinvoice(7)",
"lightning-commando-rune(7)"
],
"resources": [
"[BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)",
"",
"[BOLT #12](https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md)",
"(experimental, [bolt](https://github.com/lightning/bolts) #798)",
"",
"Main web site: <https://github.com/ElementsProject/lightning>"
],
"examples": [
{
"request": {
"id": "example:decode#1",
"method": "decode",
"params": [
"zFMd1fjhrAYxUeFA54TjloZqOt8JrA_i_nYwIgXkag49MA=="
]
},
"response": {
"type": "rune",
"unique_id": "0",
"string": "cc531dd5f8e1ac063151e140e784e396866a3adf09ac0fe2fe76302205e46a0e:=0",
"restrictions": [],
"valid": true
}
},
{
"request": {
"id": "example:decode#2",
"method": "decode",
"params": [
"lnbcrt2u1pn2s3xxsp5cpcdj2cy5wpd2nphp2evrp9kqymxf9434zftkmdd6dlgmy8cu78qpp58yq5qf3h0694xwymzjs5e8eejce83vjmxv6cpwqv8cs9e05dxe4qdqcdserygryv4ekxunfwp6xjmmwxqyjw5qcqp9rzjqdwjkyvjm7apxnssu4qgwhfkd67ghs6n6k48v6uqczgt88p6tky96qqqduqqqqgqqqqqqqqpqqqqqzsqqc9qxpqysgq9wlpxf8ur0q798646w94tduf6wfkaw7m0ecmxepgatd4utvsyvcy0pku9t8m39rlsjzhe8x53mup5jkn0f84clfj3ctc6qj09t35wxspycpup2"
]
},
"response": {
"type": "bolt11 invoice",
"currency": "bcrt",
"created_at": 1722303686,
"expiry": 604800,
"payee": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
"amount_msat": 200000,
"description": "l22 description",
"min_final_cltv_expiry": 5,
"payment_secret": "c070d92b04a382d54c370ab2c184b601366496b1a892bb6dadd37e8d90f8e78e",
"features": "02024100",
"routes": [
[
{
"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
"short_channel_id": "111x1x0",
"fee_base_msat": 1,
"fee_proportional_millionths": 10,
"cltv_expiry_delta": 6
}
]
],
"payment_hash": "39014026377e8b53389b14a14c9f39963278b25b333580b80c3e205cbe8d366a",
"signature": "304402202bbe1324fc1bc1e29f55d38b55b789d3936ebbdb7e71b36428eadb5e2d90233002204786dc2acfb8947f84857c9cd48ef81a4ad37a4f5c7d328e178d024f2ae3471a",
"valid": true
}
}
]
}
Reference in New Issue View Git Blame Copy Permalink