mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 09:54:16 +01:00
Code Issues Projects Releases Wiki Activity

doc: Updated parameter descriptions for *.request.json

Browse Source 
Added descriptions for rpc command parameters

This also performs the following fixes:
1. delforward parameters are compulsory (required).
2. disableinvoicerequest request added `added` field.
3. invoice request order fixed (label then description, not vice-versa!).
4. listpeers log levels are a proper enum
5. description parameter documented for sendonion requests.
6. deprecatred amount_msat removed from sendpay request.
7. sendpay request partid type fixed to u64 (was u16!)
8. sendpay request localinvreqid type tightened to hash (was hex)
9. sendpay request payment_metadata and description fields documented.
10. sendpsbt request reserve type fixed to u32 (was boolean)
11. utxopsbt request satoshi type fixed to msat_or_all (was msat)
12. withdraw request parameter satoshi is compulsory (required)
13. fundchannel_start request amount is sat, not msat_or_all.
14. openchannel_init request amount is sat, not msat
15. openchannel_init close_to is a string, not hex.
16: invoice labels can be strings OR numbers.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2024-02-02 15:17:43 +10:30
parent d9dd3a1840
commit d7cc1e4a17
86 changed files with 1552 additions and 1089 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
.msggen.json
View File

@ -235,6 +235,12 @@
"ONCHAIN": 8,
"OPENINGD": 0
},
"ListpeersLevel": {
"debug": 1,
"info": 2,
"io": 0,
"unusual": 3
},
"ListpeersPeersChannelsHtlcsDirection": {
"in": 0,
"out": 1
@ -1566,6 +1572,7 @@
"SendonionRequest": {
"SendOnion.amount_msat": 12,
"SendOnion.bolt11": 7,
"SendOnion.description": 14,
"SendOnion.destination": 9,
"SendOnion.first_hop": 2,
"SendOnion.groupid": 11,
@ -1598,6 +1605,7 @@
"SendpayRequest": {
"SendPay.amount_msat": 10,
"SendPay.bolt11": 5,
"SendPay.description": 13,
"SendPay.groupid": 9,
"SendPay.label": 3,
"SendPay.localinvreqid": 11,
@ -1605,6 +1613,7 @@
"SendPay.msatoshi": 4,
"SendPay.partid": 7,
"SendPay.payment_hash": 2,
"SendPay.payment_metadata": 12,
"SendPay.payment_secret": 6,
"SendPay.route[]": 1
},
@ -5664,6 +5673,10 @@
"added": "v23.11",
"deprecated": false
},
"SendOnion.description": {
"added": "v0.11.0",
"deprecated": false
},
"SendOnion.destination": {
"added": "pre-v0.10.1",
"deprecated": false
@ -5764,6 +5777,10 @@
"added": "v23.11",
"deprecated": false
},
"SendPay.description": {
"added": "v0.11.0",
"deprecated": false
},
"SendPay.destination": {
"added": "pre-v0.10.1",
"deprecated": false
@ -5796,6 +5813,10 @@
"added": "pre-v0.10.1",
"deprecated": false
},
"SendPay.payment_metadata": {
"added": "v0.11.0",
"deprecated": false
},
"SendPay.payment_preimage": {
"added": "pre-v0.10.1",
"deprecated": false

BIN
cln-grpc/proto/node.proto generated
View File

Binary file not shown.

BIN
cln-grpc/src/convert.rs generated
View File

Binary file not shown.

BIN
cln-rpc/src/model.rs generated
View File

Binary file not shown.

838
contrib/msggen/msggen/schema.json
View File

File diff suppressed because it is too large Load Diff

944
contrib/pyln-grpc-proto/pyln/grpc/node_pb2.py
View File

File diff suppressed because one or more lines are too long

2
doc/schemas/addgossip.request.json
View File

@ -8,7 +8,7 @@
"properties": {
"message": {
"type": "hex",
"description": "The raw, hex-encoded, gossip message to add to the local gossip view."
"description": "The raw, hex-encoded, gossip message to add to the local gossip view"
}
}
}

15
doc/schemas/addpsbtoutput.request.json
View File

@ -8,17 +8,20 @@
"added": "v23.11",
"properties": {
"satoshi": {
"type": "msat"
},
"locktime": {
"type": "u32"
"type": "msat",
"description": "the satoshi value of the output. It can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*"
},
"initialpsbt": {
"type": "string",
"description": "the (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically"
"description": "base 64 encoded PSBT to add the output to. If not specified, one will be generated automatically"
},
"locktime": {
"type": "u32",
"description": "if not set, it is set to a recent block height (if no initial psbt is specified)"
},
"destination": {
"type": "string"
"type": "string",
"description": "if it is not set, an internal address is generated"
}
}
}

4
doc/schemas/autoclean-once.request.json
View File

@ -17,11 +17,11 @@
"paidinvoices",
"expiredinvoices"
],
"description": "What subsystem to clean"
"description": "What subsystem to clean. Currently supported subsystems are:\t* `failedforwards`: routed payments which did not succeed (`failed` or `local_failed` in listforwards `status`).\t* `succeededforwards`: routed payments which succeeded (`settled` in listforwards `status`).\t* `failedpays`: payment attempts which did not succeed (`failed` in listpays `status`).\t* `succeededpays`: payment attempts which succeeded (`complete` in listpays `status`).\t* `expiredinvoices`: invoices which were not paid (and cannot be) (`expired` in listinvoices `status`).\t* `paidinvoices`: invoices which were paid (`paid` in listinvoices `status)"
},
"age": {
"type": "u64",
"description": "How many seconds old an entry must be to delete it"
"description": "non-zero number in seconds. How many seconds old an entry must be to delete it"
}
}
}

2
doc/schemas/autoclean-status.request.json
View File

@ -14,7 +14,7 @@
"paidinvoices",
"expiredinvoices"
],
"description": "What subsystem to ask about"
"description": "What subsystem to ask about. Currently supported subsystems are:\t* `failedforwards`: routed payments which did not succeed (`failed` or `local_failed` in listforwards `status`).\t* `succeededforwards`: routed payments which succeeded (`settled` in listforwards `status`).\t* `failedpays`: payment attempts which did not succeed (`failed` in listpays `status`).\t* `succeededpays`: payment attempts which succeeded (`complete` in listpays `status`).\t* `expiredinvoices`: invoices which were not paid (and cannot be) (`expired` in listinvoices `status`).\t* `paidinvoices`: invoices which were paid (`paid` in listinvoices `status)"
}
}
}

2
doc/schemas/batching.request.json
View File

@ -8,7 +8,7 @@
"properties": {
"enable": {
"type": "boolean",
"description": "Whether to enable or disable transaction batching"
"description": "whether to enable or disable transaction batching. Defaults to *False*"
}
}
}

6
doc/schemas/bkpr-listincome.request.json
View File

@ -7,15 +7,15 @@
"properties": {
"consolidate_fees": {
"type": "boolean",
"description": "A brief description about consolidate_fees"
"description": "if true, we emit a single, consolidated event for any onchain-fees for a txid and account. Otherwise, events for every update to the onchain fee calculation for this account and txid will be printed. Defaults to true. Note that this means that the events emitted are non-stable, i.e. calling **listincome** twice may result in different onchain fee events being emitted, depending on how much information we've logged for that transaction"
},
"start_time": {
"type": "u32",
"description": "Filters the events after the time"
"description": "UNIX timestamp (in seconds) that filters events after the provided timestamp. Defaults to zero"
},
"end_time": {
"type": "u32",
"description": "Filters the events up to the timestamp"
"description": "UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. Defaults to max-int"
}
}
}

6
doc/schemas/checkmessage.request.json
View File

@ -9,15 +9,15 @@
"properties": {
"message": {
"type": "string",
"description": "Message to be checked against the signature."
"description": "Message to be checked against the signature"
},
"zbase": {
"type": "string",
"description": "The Zbase32 encoded signature to verify."
"description": "The Zbase32 encoded signature to verify"
},
"pubkey": {
"type": "pubkey",
"description": "The Zbase32 encoded signature to verify."
"description": "The Zbase32 encoded signature to verify"
}
}
}

14
doc/schemas/close.request.json
View File

@ -8,34 +8,34 @@
"properties": {
"id": {
"type": "string",
"description": "peer id, channel id or short_channel_id"
"description": "peer id, channel id or short_channel_id. If the given *id* is a peer ID (66 hex digits as a string), then it applies to the active channel of the direct peer corresponding to the given peer ID. If the given *id* is a channel ID (64 hex digits as a string, or the short channel ID *blockheight:txindex:outindex* form), then it applies to that channel"
},
"unilateraltimeout": {
"type": "u32",
"description": ""
"description": "if it is not zero, the command will unilaterally close the channel when that number of seconds is reached. If *unilateraltimeout* is zero, then the command will wait indefinitely until the peer is online and can negotiate a mutual close. The default is 2 days (172800 seconds)"
},
"destination": {
"type": "string",
"description": ""
"description": "any Bitcoin bech32 type. If it isn't specified, the default is a Core Lightning wallet address. If the peer hasn't offered the option_shutdown_anysegwit` feature, then taproot addresses (or other v1+ segwit) are not allowed. Tell your friends to upgrade!"
},
"fee_negotiation_step": {
"type": "string",
"description": ""
"description": "it controls how closing fee negotiation is performed assuming the peer proposes a fee that is different than our estimate. (Note that modern peers use the quick-close protocol which does not allow negotiation: see *feerange* instead)\tOn every negotiation step we must give up some amount from our proposal towards the peer's proposal. This parameter can be an integer in which case it is interpreted as number of satoshis to step at a time. Or it can be an integer followed by `%` to designate a percentage of the interval to give up. A few examples, assuming the peer proposes a closing fee of 3000 satoshi and our estimate shows it must be 4000:\t- `10`: our next proposal will be 4000-10=3990.\t- `10%`: our next proposal will be 4000-(10% of (4000-3000))=3900.\t- '1': our next proposal will be 3999. This is the most extreme case when we insist on our fee as much as possible.\t- `100%`: our next proposal will be 3000. This is the most relaxed case when we quickly accept the peer's proposal.\tThe default is `50%`"
},
"wrong_funding": {
"type": "outpoint",
"description": ""
"description": "it can only be specified if both sides have offered the `shutdown_wrong_funding` feature (enabled by the **experimental-shutdown-wrong-funding** option): it must be a transaction id followed by a colon then the output number. Instead of negotiating a shutdown to spend the expected funding transaction, the shutdown transaction will spend this output instead. This is only allowed if this peer opened the channel and the channel is unused: it can rescue openings which have been manually miscreated"
},
"force_lease_closed": {
"type": "boolean",
"description": ""
"description": "if the channel has funds leased to the peer (option_will_fund), we prevent initiation of a mutual close unless this flag is passed in. Defaults to false"
},
"feerange": {
"type": "array",
"items": {
"type": "feerate"
},
"description": ""
"description": "an optional array [ *min*, *max* ], indicating the minimum and maximum feerates to offer: the peer will obey these if it supports the quick-close protocol. *slow* and *unilateral_close* are the defaults.\tNote that the maximum fee will be capped at the final commitment transaction fee (unless the experimental anchor-outputs option is negotiated)"
}
}
}

2
doc/schemas/commando-rune.request.json
View File

@ -29,7 +29,7 @@
"enum": [
"readonly"
],
"description": "readonly string to indicate standard readonly restrictions."
"description": "readonly string to indicate standard readonly restrictions"
}
]
}

6
doc/schemas/connect.request.json
View File

@ -8,15 +8,15 @@
"properties": {
"id": {
"type": "string",
"description": ""
"description": "the target node's public key. As a convenience, *id* may be of the form *id@host* or *id@host:port*. In this case, the *host* and *port* parameters must be omitted. This can fail if your C-lightning node is a fresh install that has not connected to any peers yet (your node has no gossip yet), or if the target *id* is a fresh install that has no channels yet (nobody will gossip about a node until it has one published channel)"
},
"host": {
"type": "string",
"description": "The hostname of the node."
"description": "the peer's hostname or IP address.\tIf *host* is not specified (or doesn't work), the connection will be attempted to an IP belonging to *id* obtained through gossip with other already connected peers.\tIf *host* begins with a `/` it is interpreted as a local path and the connection will be made to that local socket (see **bind-addr** in lightningd-config(5))"
},
"port": {
"type": "u16",
"description": "Port to try connecting to"
"description": "the peer's port number. If not specified, the *port* depends on the current network:\t- bitcoin **mainnet**: 9735.\t- bitcoin **testnet**: 19735.\t- bitcoin **signet**: 39735.\t- bitcoin **regtest**: 19846"
}
}
}

11
doc/schemas/createinvoice.request.json
View File

@ -13,8 +13,15 @@
"description": ""
},
"label": {
"type": "string",
"description": ""
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"description": "a unique string or number (which is treated as a string, so `01` is different from `1`); it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice"
},
"preimage": {
"type": "hex",

16
doc/schemas/createonion.request.json
View File

@ -9,7 +9,7 @@
"properties": {
"hops": {
"type": "array",
"description": "",
"description": "a JSON list of dicts, each specifying a node and the payload destined for that node",
"items": {
"type": "object",
"additionalProperties": false,
@ -19,23 +19,27 @@
],
"properties": {
"pubkey": {
"type": "pubkey"
"type": "pubkey",
"description": "node pubkey"
},
"payload": {
"type": "hex"
"type": "hex",
"description": "payload to be sent to the node"
}
}
}
},
"assocdata": {
"type": "hex",
"description": ""
"description": "the associated data that the onion should commit to. If the onion is to be used to send a payment later it MUST match the `payment_hash` of the payment in order to be valid"
},
"session_key": {
"type": "secret"
"type": "secret",
"description": "can be used to specify a secret that is used to generate the shared secrets used to encrypt the onion for each hop. It should only be used for testing or if a specific shared secret is important. If not specified it will be securely generated internally, and the shared secrets will be returned"
},
"onion_size": {
"type": "u16"
"type": "u16",
"description": "a size different from the default payment onion (1300 bytes). May be used for custom protocols like trampoline routing"
}
}
}

2
doc/schemas/createrune.request.json
View File

@ -26,7 +26,7 @@
"enum": [
"readonly"
],
"description": "readonly string to indicate standard readonly restrictions."
"description": "readonly string to indicate standard readonly restrictions"
}
]
}

13
doc/schemas/datastore.request.json
View File

@ -7,10 +7,11 @@
],
"properties": {
"key": {
"description": "a key can either have children or a value, never both: parents are created and removed automatically",
"oneOf": [
{
"type": "array",
"description": "key is an array of values (though a single value is treated as a one-element array), to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically.",
"description": "an array of values to form a hierarchy (though a single value is treated as a one-element array). Using the first element of the key as the plugin name (e.g. `[ 'summary' ]`) is recommended",
"items": {
"type": "string"
}
@ -22,26 +23,26 @@
},
"string": {
"type": "string",
"description": ""
"description": "data to be saved in string format"
},
"hex": {
"type": "hex",
"description": ""
"description": "data to be saved in hex format"
},
"mode": {
"type": "string",
"description": "\t- `must-create`: fails if it already exists.\t- `must-replace`: fails if it doesn't already exist.\t- `create-or-replace`: never fails.\t- `must-append`: must already exist, append this to what's already there.\t- `create-or-append`: append if anything is there, otherwise create.\tDefault is `must-create`",
"enum": [
"must-create",
"must-replace",
"create-or-replace",
"must-append",
"create-or-append"
],
"description": ""
]
},
"generation": {
"type": "u64",
"description": "If specified, means that the update will fail if the previously-existing data is not exactly that generation. This allows for simple atomicity. This is only legal with mode “must-replace” or “must-append”."
"description": "if specified, means that the update will fail if the previously-existing data is not exactly that generation. This allows for simple atomicity. This is only legal with *mode* `must-replace` or `must-append`"
}
}
}

2
doc/schemas/datastoreusage.request.json
View File

@ -9,7 +9,7 @@
"oneOf": [
{
"type": "array",
"description": "key is an array of values (though a single value is treated as a one-element array). Used as the starting point to traverse the datastore.",
"description": "key is an array of values (though a single value is treated as a one-element array). Used as the starting point to traverse the datastore",
"items": {
"type": "string"
}

3
doc/schemas/decode.request.json
View File

@ -8,7 +8,8 @@
],
"properties": {
"string": {
"type": "string"
"type": "string",
"description": "value to be decoded\t- a *bolt11* or *bolt12* string (optionally prefixed by `lightning:` or `LIGHTNING:`) as specified by the BOLT 11 and BOLT 12 specifications.\t- a *rune* as created by lightning-commando-rune(7).\t- an *emergency_recover* string generated by hsmtool like `lightning-hsmtool getemergencyrecover <path/to/emergency.recover>`. It holds `emergency.recover` contents and starts with `clnemerg1`"
}
}
}

6
doc/schemas/decodepay.request.json
View File

@ -8,10 +8,12 @@
],
"properties": {
"bolt11": {
"type": "string"
"type": "string",
"description": "bolt11 invoice to decode"
},
"description": {
"type": "string"
"type": "string",
"description": "description of the invoice to decode"
}
}
}

4
doc/schemas/deldatastore.request.json
View File

@ -10,7 +10,7 @@
"oneOf": [
{
"type": "array",
"description": "key is an array of values (though a single value is treated as a one-element array), to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically.",
"description": "key is an array of values (though a single value is treated as a one-element array), to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically",
"items": {
"type": "string"
}
@ -22,7 +22,7 @@
},
"generation": {
"type": "u64",
"description": "If specified, means that the update will fail if the previously-existing data is not exactly that generation. This allows for simple atomicity. This is only legal with mode “must-replace” or “must-append”."
"description": "If specified, means that the update will fail if the previously-existing data is not exactly that generation. This allows for simple atomicity. This is only legal with mode “must-replace” or “must-append”"
}
}
}

2
doc/schemas/delexpiredinvoice.request.json
View File

@ -6,7 +6,7 @@
"properties": {
"maxexpirytime": {
"type": "u64",
"description": ""
"description": "invoice expiry time in seconds. If not specified then all expired invoices are deleted"
}
}
}

13
doc/schemas/delforward.request.json
View File

@ -1,16 +1,23 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": [],
"required": [
"in_channel",
"in_htlc_id",
"status"
],
"properties": {
"in_channel": {
"type": "short_channel_id"
"type": "short_channel_id",
"description": "only the matching forwards on the given inbound channel are deleted.\tNote: for **listforwards** entries without an *in_htlc_id* entry (no longer created in v22.11, but can exist from older versions), a value of 18446744073709551615 can be used, but then it will delete *all* entries without *in_htlc_id* for this *in_channel* and *status*"
},
"in_htlc_id": {
"type": "u64"
"type": "u64",
"description": "the unique HTLC id the sender gave this (not present if incoming channel was closed before ugprade to v22.11)"
},
"status": {
"type": "string",
"description": "the status of the forward to delete. You cannot delete forwards which have status *offered* (i.e. are currently active)",
"enum": [
"settled",
"local_failed",

13
doc/schemas/delinvoice.request.json
View File

@ -10,17 +10,17 @@
"label": {
"oneOf": [
{
"type": "string",
"description": ""
"type": "string"
},
{
"type": "integer",
"description": ""
"type": "u64"
}
]
],
"description": "label of the invoice to be deleted"
},
"status": {
"type": "string",
"description": "label of the invoice to be deleted. The caller should be particularly aware of the error case caused by the *status* changing just before this command is invoked!",
"enum": [
"paid",
"expired",
@ -28,7 +28,8 @@
]
},
"desconly": {
"type": "boolean"
"type": "boolean",
"description": "if set to True, the invoice is not deleted, but has its description removed (this can save space with very large descriptions, as would be used with lightning-invoice(7) *deschashonly*"
}
}
}

9
doc/schemas/delpay.request.json
View File

@ -9,20 +9,23 @@
"properties": {
"payment_hash": {
"type": "hash",
"description": "the hash of the *payment_preimage* which will prove payment"
"description": "the unique identifier of a payment"
},
"status": {
"type": "string",
"description": "expected status of the payment. Only deletes if the payment status matches. Deleting a `pending` payment will return an error",
"enum": [
"complete",
"failed"
]
},
"partid": {
"type": "u64"
"type": "u64",
"description": "specific partid to delete (must be paired with *groupid*)"
},
"groupid": {
"type": "u64"
"type": "u64",
"description": "specific groupid to delete (must be paired with *partid*)"
}
}
}

3
doc/schemas/disableinvoicerequest.request.json
View File

@ -2,13 +2,14 @@
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"added": "v22.11",
"required": [
"invreq_id"
],
"properties": {
"invreq_id": {
"type": "string",
"description": ""
"description": "a specific invoice can be disabled by providing the `invreq_id`, which is presented by lightning-invoicerequest(7)"
}
}
}

6
doc/schemas/disconnect.request.json
View File

@ -7,10 +7,12 @@
],
"properties": {
"id": {
"type": "pubkey"
"type": "pubkey",
"description": "the public key of the peer to terminate the connection.\tIt can be discovered in the output of the listpeers command, which returns a set of peers:\t{\t\t'peers': [\t\t\t{\t\t\t'id': '0563aea81...',\t\t\t'connected': true,\t\t\t...\t\t}\t\t]\t}"
},
"force": {
"type": "boolean"
"type": "boolean",
"description": "if set to True, it will disconnect even with an active channel"
}
}
}

1
doc/schemas/feerates.request.json
View File

@ -8,6 +8,7 @@
"properties": {
"style": {
"type": "string",
"description": "\t*perkw* - provide feerate in units of satoshis per 1000 weight (e.g. the minimum fee is usually `253perkw`)\t*perkb* - provide feerate in units of satoshis per 1000 virtual bytes (eg. the minimum fee is usually `1000perkb`)",
"enum": [
"perkb",
"perkw"

16
doc/schemas/fetchinvoice.request.json
View File

@ -8,35 +8,35 @@
"properties": {
"offer": {
"type": "string",
"description": ""
"description": "offer string to get an actual invoice that can be paid"
},
"amount_msat": {
"type": "msat",
"description": "amount_msat is required if the offer does not specify an amount at all, otherwise it is optional (but presumably if you set it to less than the offer, you will get an error from the issuer)."
"description": "required if the offer does not specify an amount at all, otherwise it is optional (but presumably if you set it to less than the offer, you will get an error from the issuer)"
},
"quantity": {
"type": "u64",
"description": "quantity is is required if the offer specifies quantity_max, otherwise it is not allowed."
"description": "required if the offer specifies quantity_max, otherwise it is not allowed"
},
"recurrence_counter": {
"type": "u64",
"description": "recurrence_counter is required if the offer specifies recurrence, otherwise it is not allowed. recurrence_counter should first be set to 0, and incremented for each successive invoice in a given series."
"description": "required if the offer specifies recurrence, otherwise it is not allowed. recurrence_counter should first be set to 0, and incremented for each successive invoice in a given series"
},
"recurrence_start": {
"type": "number",
"description": "recurrence_start is required if the offer specifies recurrence_base with start_any_period set, otherwise it is not allowed. It indicates what period number to start at."
"description": "required if the offer specifies recurrence_base with start_any_period set, otherwise it is not allowed. It indicates what period number to start at"
},
"recurrence_label": {
"type": "string",
"description": "recurrence_label is required if recurrence_counter is set, and otherwise is not allowed. It must be the same as prior fetchinvoice calls for the same recurrence, as it is used to link them together."
"description": "required if recurrence_counter is set, and otherwise is not allowed. It must be the same as prior fetchinvoice calls for the same recurrence, as it is used to link them together"
},
"timeout": {
"type": "number",
"description": "timeout is an optional timeout; if we don't get a reply before this we fail (default, 60 seconds)."
"description": "if we don't get a reply before this we fail (default, 60 seconds)"
},
"payer_note": {
"type": "string",
"description": "payer_note is an optional payer note to ask the issuer to include in the fetched invoice."
"description": "to ask the issuer to include in the fetched invoice"
}
}
}

29
doc/schemas/fundchannel.request.json
View File

@ -9,34 +9,43 @@
"properties": {
"id": {
"type": "pubkey",
"description": "id is the peer id obtained from connect."
"description": "id is the peer id obtained from connect"
},
"amount": {
"type": "msat_or_all"
"type": "msat_or_all",
"description": "the amount in satoshis taken from the internal wallet to fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). The string *all* can be used to specify all available funds (or 16777215 satoshi if more is available and large channels were not negotiated with the peer). Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*. The value cannot be less than the dust limit, currently set to 546, nor more than 16777215 satoshi (unless large channels were negotiated with the peer)"
},
"feerate": {
"type": "feerate"
"type": "feerate",
"description": "used for the opening transaction and (unless *option_anchors_zero_fee_htlc_tx* is negotiated), as initial feerate for commitment and HTLC transactions (see NOTES in lightning-feerates(7)). The default is *normal*"
},
"announce": {
"type": "boolean"
"type": "boolean",
"description": "whether to announce this channel or not. An unannounced channel is considered private. Defaults to *True*"
},
"minconf": {
"type": "u32"
"type": "u32",
"description": "the minimum number of confirmations that used outputs should have. Default is 1"
},
"push_msat": {
"type": "msat"
"type": "msat",
"description": "the amount of millisatoshis to push to the channel peer at open. Note that this is a gift to the peer -- these satoshis are added to the initial balance of the peer at channel start and are largely unrecoverable once pushed"
},
"close_to": {
"type": "string"
"type": "string",
"description": "a Bitcoin address to which the channel funds should be sent to on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`. Returns `close_to` set to closing script iff is negotiated"
},
"request_amt": {
"type": "msat"
"type": "msat",
"description": "an amount of liquidity you'd like to lease from the peer. If peer supports `option_will_fund`, indicates to them to include this much liquidity into the channel. Must also pass in *compact_lease*"
},
"compact_lease": {
"type": "string"
"type": "string",
"description": "a compact represenation of the peer's expected channel lease terms. If the peer's terms don't match this set, we will fail to open the channel"
},
"utxos": {
"type": "array",
"description": "the utxos to be used to fund the channel, as an array of `txid:vout`",
"items": {
"type": "outpoint"
}
@ -47,7 +56,7 @@
},
"reserve": {
"type": "msat",
"description": "The amount we want the peer to maintain on its side"
"description": "the amount we want the peer to maintain on its side of the channel. Default is 1% of the funding amount. It can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*"
},
"channel_type": {
"added": "v24.02",

2
doc/schemas/fundchannel_cancel.request.json
View File

@ -8,7 +8,7 @@
"properties": {
"id": {
"type": "pubkey",
"description": "the node id of the remote peer with which to cancel"
"description": "node id of the remote peer with which to cancel"
}
}
}

4
doc/schemas/fundchannel_complete.request.json
View File

@ -9,11 +9,11 @@
"properties": {
"id": {
"type": "pubkey",
"description": "id is the node id of the remote peer."
"description": "node id of the remote peer"
},
"psbt": {
"type": "string",
"description": "the transaction to use for funding (does not need to be signed but must be otherwise complete)"
"description": "transaction to use for funding (does not need to be signed but must be otherwise complete)"
}
}
}

14
doc/schemas/fundchannel_start.request.json
View File

@ -9,27 +9,27 @@
"properties": {
"id": {
"type": "pubkey",
"description": "id is the peer id obtained from connect."
"description": "node id of the remote peer"
},
"amount": {
"type": "msat_or_all",
"description": "The amount that the channel will be funded."
"type": "sat",
"description": "satoshi value that the channel will be funded at. This value MUST be accurate, otherwise the negotiated commitment transactions will not encompass the correct channel value"
},
"feerate": {
"type": "feerate",
"description": "Sets the feerate for the subsequent commitment transaction."
"description": "feerate for subsequent commitment transactions: see **fundchannel**. Note that this is ignored for channels with *option_anchors_zero_fee_htlc_tx* (we always use a low commitment fee for these)"
},
"announce": {
"type": "boolean",
"description": "Whether or not to announce the channel."
"description": "whether or not to announce this channel"
},
"close_to": {
"type": "string",
"description": "A bitcoin address to which the channel funds should be sent to on close."
"description": "bitcoin address to which the channel funds should be sent to on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`. Returns `close_to` set to closing script iff is negotiated"
},
"push_msat": {
"type": "msat",
"description": "The amount of millisatoshis to push to the channel at open. This is a gift to the peer."
"description": "amount of millisatoshis to push to the channel peer at open. Note that this is a gift to the peer -- these satoshis are added to the initial balance of the peer at channel start and are largely unrecoverable once pushed"
},
"mindepth": {
"type": "u32",

29
doc/schemas/fundpsbt.request.json
View File

@ -9,37 +9,46 @@
],
"properties": {
"satoshi": {
"type": "msat_or_all"
"type": "msat_or_all",
"description": "the minimum satoshi value of the output(s) needed (or the string `all` meaning use all unreserved inputs). If a value, it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*"
},
"feerate": {
"type": "feerate"
"type": "feerate",
"description": "used for the transaction as initial feerate. The default is *normal*"
},
"startweight": {
"type": "u32"
"type": "u32",
"description": "the weight of the transaction before *fundpsbt* has added any inputs"
},
"minconf": {
"type": "u32"
"type": "u32",
"description": "the minimum number of confirmations that used outputs should have. Default is 1"
},
"reserve": {
"type": "u32",
"description": "reserve is a number: if non-zero number then reserveinputs is called (successfully, with exclusive true) on the returned PSBT for this number of blocks (default: 72)."
"description": "if not zero, then *reserveinputs* is called (successfully, with *exclusive* true) on the returned PSBT for this number of blocks. Defaults to 72 blocks if unspecified"
},
"locktime": {
"type": "u32"
"type": "u32",
"description": "the locktime of the transaction. if not set, it is set to a recent block height"
},
"min_witness_weight": {
"type": "u32"
"type": "u32",
"description": "minimum weight to use for a UTXO's witness. If the actual witness weight is greater than the provided minimum, the actual witness weight will be used"
},
"excess_as_change": {
"type": "boolean"
"type": "boolean",
"description": "flag to add a change output for the excess sats"
},
"nonwrapped": {
"added": "v23.02",
"type": "boolean"
"type": "boolean",
"description": "to signal to filter out any p2sh-wrapped inputs from funding this PSBT"
},
"opening_anchor_channel": {
"added": "v23.08",
"type": "boolean"
"type": "boolean",
"description": "to signel that it needs emergency reserve for anchors so that we can lowball our commitment tx fees, and min-emergency-msat for reserving some sats for closing anchor channels"
}
}
}

16
doc/schemas/getroute.request.json
View File

@ -9,38 +9,38 @@
"properties": {
"id": {
"type": "pubkey",
"description": ""
"description": "node pubkey to find the best route for the payment"
},
"amount_msat": {
"type": "msat",
"description": ""
"description": "amount to send. It can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*. The 0 value is special: it ignores any *htlc_minimum_msat* setting on channels, and simply returns a possible route (if any) which is useful for simple probing"
},
"riskfactor": {
"type": "u64",
"description": ""
"description": "a non-negative floating-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage).\tFor example, if you thought the convenience of keeping your funds liquid (not stuck) was worth 20% per annum interest, *riskfactor* would be 20.\tIf you didn't care about risk, *riskfactor* would be zero"
},
"cltv": {
"type": "u32",
"description": ""
"description": "cltv-blocks to spare. Default is 9"
},
"fromid": {
"type": "pubkey",
"description": ""
"description": "the node to start the route from. Default is this node"
},
"fuzzpercent": {
"type": "u32",
"description": ""
"description": "used to distort fees to provide some randomization to the route generated, but it was not properly implemented and is ignored"
},
"exclude": {
"type": "array",
"description": "",
"description": "a JSON array of short-channel-id/direction (e.g. ['564334x877x1/0', '564195x1292x0/1' ]) or node-id which should be excluded from consideration for routing. The default is not to exclude any channels or nodes. Note if the source or destination is excluded, the command result is undefined",
"items": {
"type": "string"
}
},
"maxhops": {
"type": "u32",
"description": ""
"description": "the maximum number of channels to return. Default is 20"
}
}
}

36
doc/schemas/invoice.request.json
View File

@ -10,63 +10,65 @@
"properties": {
"amount_msat": {
"type": "msat_or_any",
"description": ""
},
"description": {
"type": "string",
"description": ""
"description": "the string `any`, which creates an invoice that can be paid with any amount. Otherwise it is a positive value in millisatoshi precision; it can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*"
},
"label": {
"oneOf": [
{
"type": "string",
"description": ""
"type": "string"
},
{
"type": "integer",
"description": ""
"type": "integer"
}
]
],
"description": "a unique string or number (which is treated as a string, so `01` is different from `1`); it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice"
},
"description": {
"type": "string",
"description": "a short description of purpose of payment, e.g. *1 cup of coffee*. This value is encoded into the BOLT11 invoice and is viewable by any node you send this invoice to (unless *deschashonly* is true as described below). It must be UTF-8, and cannot use *\\u* JSON escape codes"
},
"expiry": {
"type": "u64",
"description": ""
"description": "the time the invoice is valid for, in seconds. If no value is provided the default of 604800 (1 week) is used"
},
"fallbacks": {
"type": "array",
"description": "",
"description": "one or more fallback addresses to include in the invoice (in order from most-preferred to least): note that these arrays are not currently tracked to fulfill the invoice",
"items": {
"type": "string"
}
},
"preimage": {
"type": "hex",
"description": ""
"description": "a 64-digit hex string to be used as payment preimage for the created invoice. By default, if unspecified, lightningd will generate a secure pseudorandom preimage seeded from an appropriate entropy source on your system. **IMPORTANT**: if you specify the *preimage*, you are responsible, to ensure appropriate care for generating using a secure pseudorandom generator seeded with sufficient entropy, and keeping the preimage secret. This parameter is an advanced feature intended for use with cutting-edge cryptographic protocols and should not be used unless explicitly needed"
},
"exposeprivatechannels": {
"description": "if specified, it overrides the default route hint logic, which will use unpublished channels only if there are no published channels",
"oneOf": [
{
"type": "boolean",
"description": ""
"description": "if *True* unpublished channels are always considered as a route hint candidate; if *False*, never"
},
{
"type": "array",
"description": "array of short channel ids (or a remote alias), only those specific channels will be considered candidates, even if they are public or dead-ends",
"items": {
"type": "short_channel_id"
}
},
{
"type": "short_channel_id"
"type": "short_channel_id",
"description": "if it is a short channel id (e.g. *1x1x3*), only this specific channel will be considered candidate, even if it is public or dead-end"
}
]
},
"cltv": {
"type": "u32",
"description": ""
"description": "if specified, sets the *min_final_cltv_expiry* for the invoice. Otherwise, it's set to the parameter **cltv-final**"
},
"deschashonly": {
"type": "boolean",
"description": ""
"description": "if True, then the bolt11 returned contains a hash of the *description*, rather than the *description* itself: this allows much longer descriptions, but they must be communicated via some other mechanism. Defaults to False"
}
}
}

12
doc/schemas/invoicerequest.request.json
View File

@ -10,27 +10,27 @@
"properties": {
"amount": {
"type": "msat",
"description": ""
"description": "a positive value in millisatoshi precision; it can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*"
},
"description": {
"type": "string",
"description": ""
"description": "a short description of purpose of the payment, e.g. *ATM withdrawl*. This value is encoded into the resulting `invoice_request` and is viewable by anyone you expose it to. It must be UTF-8, and cannot use *\\u* JSON escape codes"
},
"issuer": {
"type": "string",
"description": ""
"description": "who is issuing it (i.e. you) if appropriate"
},
"label": {
"type": "string",
"description": ""
"description": "an internal-use name for the offer, which can be any UTF-8 string"
},
"absolute_expiry": {
"type": "u64",
"description": ""
"description": "the time the offer is valid until, in seconds since the first day of 1970 UTC. If not set, the `invoice_request` remains valid (though it can be deactivated by the issuer of course). This is encoded in the `invoice_request`"
},
"single_use": {
"type": "boolean",
"description": ""
"description": "indicates that the `invoice_request` is only valid once; we may attempt multiple payments, but as soon as one is successful no more invoices are accepted (i.e. only one person can take the money). Defaults to True"
}
}
}

24
doc/schemas/keysend.request.json
View File

@ -8,25 +8,32 @@
],
"properties": {
"destination": {
"type": "pubkey"
"type": "pubkey",
"description": "the 33 byte, hex-encoded, node ID of the node that the payment should go to"
},
"amount_msat": {
"type": "msat"
"type": "msat",
"description": "a whole number, or a whole number with suffix `msat` or `sat`, or a three decimal point number with suffix `sat`, or an 1 to 11 decimal point number suffixed by `btc`"
},
"label": {
"type": "string"
"type": "string",
"description": "used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7)"
},
"maxfeepercent": {
"type": "number"
"type": "number",
"description": "limits the money paid in fees as percentage of the total amount that is to be transferred, and defaults to *0.5*"
},
"retry_for": {
"type": "u32"
"type": "u32",
"description": "until *retry_for* seconds passes, the command will keep finding routes and retrying the payment. However, a payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case. Defaults to 60 seconds"
},
"maxdelay": {
"type": "u32"
"type": "u32",
"description": "number of blocks the payment may be delayed"
},
"exemptfee": {
"type": "msat"
"type": "msat",
"description": "used for tiny payments which would be dominated by the fee leveraged by forwarding nodes. Setting `exemptfee` allows the `maxfeepercent` check to be skipped on fees that are smaller than *exemptfee*. Defaults to 5000 millisatoshi"
},
"routehints": {
"type": "array",
@ -65,7 +72,8 @@
"extratlvs": {
"type": "object",
"additionalProperties": true,
"required": []
"required": [],
"description": "dictionary of additional fields to insert into the final tlv. The format is 'fieldnumber': 'hexstring'"
}
}
}

6
doc/schemas/listchannels.request.json
View File

@ -6,15 +6,15 @@
"properties": {
"short_channel_id": {
"type": "short_channel_id",
"description": "If short_channel_id is a short channel id, then only known channels with a matching short_channel_id are returned. Otherwise, it must be null."
"description": "if short_channel_id is a short channel id, then only known channels with a matching short_channel_id are returned. Otherwise, it must be null"
},
"source": {
"type": "pubkey",
"description": "If source is a node id, then only channels leading from that node id are returned."
"description": "if source is a node id, then only channels leading from that node id are returned"
},
"destination": {
"type": "pubkey",
"description": "If destination is a node id, then only channels leading to that node id are returned."
"description": "if destination is a node id, then only channels leading to that node id are returned"
}
}
}

2
doc/schemas/listclosedchannels.request.json
View File

@ -7,7 +7,7 @@
"properties": {
"id": {
"type": "pubkey",
"description": "If supplied, limits the channels to just the peer with the given ID, if it exists."
"description": "if no *id* is supplied, then channel data on all historical channels are given. Supplying *id* will filter the results to only match channels to that peer. Note that prior to v23.05, old peers were forgotten"
}
}
}

5
doc/schemas/listdatastore.request.json
View File

@ -8,14 +8,13 @@
"oneOf": [
{
"type": "array",
"description": "key is an array of values (though a single value is treated as a one-element array), to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically.",
"description": "all immediate children of the *key* (or root children) are returned.\t\tUsing the first element of the key as the plugin name (e.g. `[ 'summary' ]`) is recommended.\t\tAn array of values to form a hierarchy (though a single value is treated as a one-element array)",
"items": {
"type": "string"
}
},
{
"type": "string",
"description": ""
"type": "string"
}
]
}

13
doc/schemas/listforwards.request.json
View File

@ -5,6 +5,7 @@
"properties": {
"status": {
"type": "string",
"description": "if specified, then only the forwards with the given status are returned",
"enum": [
"offered",
"settled",
@ -13,10 +14,12 @@
]
},
"in_channel": {
"type": "short_channel_id"
"type": "short_channel_id",
"description": "only the matching forwards on the given inbound channel are returned"
},
"out_channel": {
"type": "short_channel_id"
"type": "short_channel_id",
"description": "only the matching forwards on the given outbount channel are returned"
},
"index": {
"type": "string",
@ -25,17 +28,17 @@
"created",
"updated"
],
"description": ""
"description": "if neither *in_channel* nor *out_channel* is specified, it controls ordering. Defaults to `created`"
},
"start": {
"type": "u64",
"added": "v23.11",
"description": ""
"description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)"
},
"limit": {
"type": "u32",
"added": "v23.11",
"description": ""
"description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return"
}
}
}

2
doc/schemas/listfunds.request.json
View File

@ -6,7 +6,7 @@
"properties": {
"spent": {
"type": "boolean",
"description": "Should outputs that are already spent be included in the result?"
"description": "if True, then the *outputs* will include spent outputs in addition to the unspent ones. Default is False"
}
}
}

2
doc/schemas/listhtlcs.request.json
View File

@ -5,7 +5,7 @@
"properties": {
"id": {
"type": "string",
"description": "channel id or short_channel_id"
"description": "a short channel id (e.g. 1x2x3) or full 64-byte hex channel id, it will only list htlcs for that channel (which must be known)"
}
}
}

4
doc/schemas/listinvoicerequests.request.json
View File

@ -7,11 +7,11 @@
"properties": {
"invreq_id": {
"type": "string",
"description": ""
"description": "a specific invoice can be queried by providing the `invreq_id`, which is presented by lightning-invoicerequest(7), or can be calculated from a bolt12 invoice"
},
"active_only": {
"type": "boolean",
"description": ""
"description": "if it is *True* then only active invoice requests are returned. Default is *False*"
}
}
}

21
doc/schemas/listinvoices.request.json
View File

@ -7,26 +7,25 @@
"label": {
"oneOf": [
{
"type": "string",
"description": ""
"type": "string"
},
{
"type": "integer",
"description": ""
"type": "integer"
}
]
],
"description": "a label used a the creation of the invoice to get a specific invoice"
},
"invstring": {
"type": "string",
"description": ""
"description": "the string value to query a specific invoice"
},
"payment_hash": {
"type": "hex",
"description": ""
"description": "a payment_hash of the invoice to get the details of a specific invoice"
},
"offer_id": {
"type": "string",
"description": ""
"description": "a local `offer_id` the invoice was issued for a specific invoice details"
},
"index": {
"type": "string",
@ -35,17 +34,17 @@
"created",
"updated"
],
"description": ""
"description": "if neither *in_channel* nor *out_channel* is specified, it controls ordering. Defaults to `created`"
},
"start": {
"type": "u64",
"added": "v23.08",
"description": ""
"description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)"
},
"limit": {
"type": "u32",
"added": "v23.08",
"description": ""
"description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return"
}
}
}

3
doc/schemas/listnodes.request.json
View File

@ -5,7 +5,8 @@
"additionalProperties": false,
"properties": {
"id": {
"type": "pubkey"
"type": "pubkey",
"description": "The public key of the node to list"
}
}
}

7
doc/schemas/listpays.request.json
View File

@ -5,13 +5,16 @@
"additionalProperties": false,
"properties": {
"bolt11": {
"type": "string"
"type": "string",
"description": "bolt11 string to get the payment details"
},
"payment_hash": {
"type": "hash"
"type": "hash",
"description": "payment hash to get the payment details"
},
"status": {
"type": "string",
"description": "to filter the payment by status",
"enum": [
"pending",
"complete",

2
doc/schemas/listpeerchannels.request.json
View File

@ -7,7 +7,7 @@
"properties": {
"id": {
"type": "pubkey",
"description": "If supplied, limits the channels to just the peer with the given ID, if it exists."
"description": "If supplied, limits the channels to just the peer with the given ID, if it exists"
}
}
}

10
doc/schemas/listpeers.request.json
View File

@ -6,11 +6,17 @@
"properties": {
"id": {
"type": "pubkey",
"description": "If supplied, limits the result to just the peer with the given ID, if it exists."
"description": "if supplied, limits the result to just the peer with the given ID, if it exists"
},
"level": {
"type": "string",
"description": "Supplying level will show log entries related to that peer at the given log level. Valid log levels are “io”, “debug”, “info”, and “unusual”."
"description": "supplying level will show log entries related to that peer at the given log level",
"enum": [
"io",
"debug",
"info",
"unusual"
]
}
}
}

15
doc/schemas/listsendpays.request.json
View File

@ -5,10 +5,12 @@
"additionalProperties": false,
"properties": {
"bolt11": {
"type": "string"
"type": "string",
"description": "bolt11 invoice"
},
"payment_hash": {
"type": "hash"
"type": "hash",
"description": "the hash of the payment_preimage"
},
"status": {
"type": "string",
@ -16,7 +18,8 @@
"pending",
"complete",
"failed"
]
],
"description": "Whether the invoice has been paid, pending, or failed"
},
"index": {
"type": "string",
@ -25,17 +28,17 @@
"created",
"updated"
],
"description": ""
"description": "if neither bolt11 or payment_hash is specified, `index` controls ordering, by `created` (default) or `updated`"
},
"start": {
"type": "u64",
"added": "v23.11",
"description": ""
"description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)"
},
"limit": {
"type": "u32",
"added": "v23.11",
"description": ""
"description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return"
}
}
}

4
doc/schemas/makesecret.request.json
View File

@ -6,11 +6,11 @@
"properties": {
"hex": {
"type": "hex",
"description": "This will be used for deriving the secret"
"description": "One of `hex` or `string` must be specified: `hex` can be any hex data"
},
"string": {
"type": "string",
"description": "This will be used for deriving the secret"
"description": "One of `hex` or `string` must be specified: `string` is a UTF-8 string interpreted literally"
}
}
}

50
doc/schemas/multifundchannel.request.json
View File

@ -8,6 +8,7 @@
"properties": {
"destinations": {
"type": "array",
"description": "there must be at least one entry in *destinations*; it cannot be an empty array",
"items": {
"type": "object",
"additionalProperties": false,
@ -17,60 +18,67 @@
],
"properties": {
"id": {
"type": "string"
"type": "string",
"description": "node ID, with an optional *@host:port* appended to it in a manner understood by **connect**; see lightning-connect(7). Each entry in the *destinations* array must have a unique node *id*. If not already connected, **multifundchannel** will automatically attempt to connect to the node"
},
"amount": {
"type": "msat_or_all"
"type": "msat",
"description": "amount in satoshis taken from the internal wallet to fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). The string *all* can be used to specify all available funds (or 16,777,215 satoshi if more is available and large channels were not negotiated with the peer). Otherwise it is in satoshi precision; it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*. The value cannot be less than the dust limit, currently 546 satoshi as of this writing, nor more than 16,777,215 satoshi (unless large channels were negotiated with the peer)"
},
"announce": {
"type": "boolean"
"type": "boolean",
"description": "flag that indicates whether to announce the channel with this, default `true`. If set to `false`, the channel is unpublished"
},
"push_msat": {
"type": "msat"
"type": "msat",
"description": "amount of millisatoshis to outright give to the node. This is a gift to the peer, and you do not get a proof-of-payment out of this"
},
"close_to": {
"type": "string"
"type": "string",
"description": "bitcoin address to which the channel funds should be sent to on close. Only valid if both peers have negotiated `option_upfront_shutdown_script` Returns `close_to` set to closing script iff is negotiated"
},
"request_amt": {
"type": "msat"
"type": "msat",
"description": "amount of liquidity you'd like to lease from peer. If peer supports `option_will_fund`, indicates to them to include this much liquidity into the channel. Must also pass in *compact_lease*"
},
"compact_lease": {
"type": "string"
"type": "string",
"description": "compact represenation of the peer's expected channel lease terms. If the peer's terms don't match this set, we will fail to open the channel to this destination"
},
"mindepth": {
"description": "Number of confirmations required before we consider the channel active",
"type": "u32"
"type": "u32",
"description": "number of confirmations before we consider the channel active"
},
"reserve": {
"type": "msat",
"description": "The amount we want the peer to maintain on its side"
},
"channel_type": {
"type": "array",
"items": {
"type": "u32"
}
"description": "amount we want the peer to maintain on its side of the channel. Default is 1% of the funding amount. It can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*"
}
}
}
},
"feerate": {
"type": "feerate"
"type": "feerate",
"description": "feerate used for the opening transaction, and if *commitment_feerate* is not set, as initial feerate for commitment and HTLC transactions. See NOTES in lightning-feerates(7) for possible values. The default is *normal*"
},
"minconf": {
"type": "u32"
"type": "integer",
"description": "minimum number of confirmations that used outputs should have. Default is 1",
"default": 1
},
"utxos": {
"type": "array",
"items": {
"type": "outpoint"
"type": "outpoint",
"description": "utxos to be used to fund the channel, as an array of `txid:vout`"
}
},
"minchannels": {
"type": "u32"
"type": "integer",
"description": "re-attempt funding as long as at least this many peers remain (must not be zero). The **multifundchannel** command will only fail if too many peers fail the funding process"
},
"commitment_feerate": {
"type": "feerate"
"type": "feerate",
"description": "initial feerate for commitment and HTLC transactions. See *feerate* for valid values"
}
}
}

1
doc/schemas/newaddr.request.json
View File

@ -6,6 +6,7 @@
"properties": {
"addresstype": {
"type": "string",
"description": "it specifies the type of address wanted; currently *bech32* (e.g. `tb1qu9j4lg5f9rgjyfhvfd905vw46eg39czmktxqgg` on bitcoin testnet or `bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej` on bitcoin mainnet), or *p2tr* taproot addresses. The special value *all* generates all known address types for the same underlying key. Defaults to *bech32* address",
"enum": [
"bech32",
"p2tr",

27
doc/schemas/openchannel_init.request.json
View File

@ -9,31 +9,40 @@
],
"properties": {
"id": {
"type": "pubkey"
"type": "pubkey",
"description": "node id of the remote peer"
},
"amount": {
"type": "msat"
"type": "sat",
"description": "satoshi value that we will contribute to the channel. This value will be _added_ to the provided PSBT in the output which is encumbered by the 2-of-2 script for this channel"
},
"initialpsbt": {
"type": "string"
"type": "string",
"description": "funded, incomplete PSBT that specifies the UTXOs and change output for our channel contribution. It can be updated, see `openchannel_update`; *initialpsbt* must have at least one input. Must have the Non-Witness UTXO (PSBT_IN_NON_WITNESS_UTXO) set for every input. An error (code 309) will be returned if this requirement is not met"
},
"commitment_feerate": {
"type": "feerate"
"type": "feerate",
"description": "feerate for commitment transactions for non-anchor channels: see **fundchannel**. For anchor channels, it is ignored"
},
"funding_feerate": {
"type": "feerate"
"type": "feerate",
"description": "feerate for the funding transaction. Defaults to 'opening' feerate"
},
"announce": {
"type": "boolean"
"type": "boolean",
"description": "whether or not to announce this channel"
},
"close_to": {
"type": "hex"
"type": "string",
"description": "bitcoin address to which the channel funds should be sent on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`"
},
"request_amt": {
"type": "msat"
"type": "msat",
"description": "an amount of liquidity you'd like to lease from the peer. If peer supports `option_will_fund`, indicates to them to include this much liquidity into the channel. Must also pass in *compact_lease*"
},
"compact_lease": {
"type": "hex"
"type": "hex",
"description": "a compact represenation of the peer's expected channel lease terms. If the peer's terms don't match this set, we will fail to open the channel"
},
"channel_type": {
"type": "array",

34
doc/schemas/pay.request.json
View File

@ -7,34 +7,44 @@
],
"properties": {
"bolt11": {
"type": "string"
"type": "string",
"description": "bolt11 invoice, if **experimental-offers** is enabled, it can actually be a bolt12 invoice, such as one received from lightningd-fetchinvoice(7). If it does not contain an amount, *amount_msat* is required, otherwise if it is specified it must be *null*"
},
"amount_msat": {
"type": "msat"
"type": "msat",
"description": "*amount_msat* is in millisatoshi precision; it can be a whole number, or a whole number with suffix *msat* or *sat*, or a three decimal point number with suffix *sat*, or an 1 to 11 decimal point number suffixed by *btc*"
},
"label": {
"type": "string"
"type": "string",
"description": "it is used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7)"
},
"riskfactor": {
"type": "number"
"type": "number",
"description": "the *riskfactor* is described in detail in lightning-getroute(7), and defaults to 10"
},
"maxfeepercent": {
"type": "number"
"type": "number",
"description": "percentage of the amount that is to be paid. Defaults to 0.5"
},
"retry_for": {
"type": "u16"
"type": "u16",
"description": "until *retry_for* seconds passes, the command will keep finding routes and retrying the payment. Defaults to 60 seconds"
},
"maxdelay": {
"type": "u16"
"type": "u16",
"description": "a payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case"
},
"exemptfee": {
"type": "msat"
"type": "msat",
"description": "this option can be used for tiny payments which would be dominated by the fee leveraged by forwarding nodes. Setting `exemptfee` allows the `maxfeepercent` check to be skipped on fees that are smaller than `exemptfee`. Defaults to 5000 millisatoshi"
},
"localinvreqid": {
"type": "hex"
"type": "hex",
"description": "`localinvreqid` is used by offers to link a payment attempt to a local `invoice_request` offer created by lightningd-invoicerequest(7). This ensures that we only make a single payment for an offer, and that the offer is marked `used` once paid"
},
"exclude": {
"type": "array",
"description": "*exclude* is a JSON array of short-channel-id/direction (e.g. [ '564334x877x1/0', '564195x1292x0/1' ]) or pubkey which should be excluded from consideration for routing. The default is not to exclude any channels or nodes",
"items": {
"oneOf": [
{
@ -47,10 +57,12 @@
}
},
"maxfee": {
"type": "msat"
"type": "msat",
"description": "*maxfee* overrides both *maxfeepercent* and *exemptfee* defaults (and if you specify *maxfee* you cannot specify either of those), and creates an absolute limit on what fee we will pay. This allows you to implement your own heuristics rather than the primitive ones used here"
},
"description": {
"type": "string"
"type": "string",
"description": "it is only required for bolt11 invoices which do not contain a description themselves, but contain a description hash: in this case *description* is required. *description* is then checked against the hash inside the invoice before it will be paid"
}
}
}

9
doc/schemas/ping.request.json
View File

@ -7,13 +7,16 @@
"additionalProperties": false,
"properties": {
"id": {
"type": "pubkey"
"type": "pubkey",
"description": "The pubkey of the node to ping"
},
"len": {
"type": "u16"
"type": "u16",
"description": "the length of the ping. Defaults to 128"
},
"pongbytes": {
"type": "u16"
"type": "u16",
"description": "the length of the reply. A value of 65532 to 65535 means `don't reply`. Defaults to 128"
}
}
}

1
doc/schemas/preapproveinvoice.request.json
View File

@ -9,6 +9,7 @@
"properties": {
"bolt11": {
"type": "string",
"description": "bolt11 invoice to submit to the HSM to check",
"added": "v23.02"
}
}

4
doc/schemas/preapprovekeysend.request.json
View File

@ -11,17 +11,19 @@
"properties": {
"destination": {
"type": "pubkey",
"description": "it is a 33 byte, hex-encoded, node ID of the node that the payment should go to",
"added": "v23.02"
},
"payment_hash": {
"type": "hex",
"added": "v23.02",
"description": "the hash of the *payment_preimage* which will prove payment",
"description": "it is the unique identifier of a payment",
"maxLength": 64,
"minLength": 64
},
"amount_msat": {
"type": "msat",
"description": "the amount to send in millisatoshi precision; it can be a whole number, or a whole number with suffix `msat` or `sat`, or a three decimal point number with suffix `sat`, or an 1 to 11 decimal point number suffixed by `btc`",
"added": "v23.02"
}
}

12
doc/schemas/recoverchannel.request.json
View File

@ -5,11 +5,13 @@
"required": [
"scb"
],
"scb": {
"type": "array",
"description": "SCB of the channels in an array",
"items": {
"type": "hexstr"
"properties": {
"scb": {
"type": "array",
"description": "SCB of the channels in an array",
"items": {
"type": "hexstr"
}
}
}
}

6
doc/schemas/sendcustommsg.request.json
View File

@ -9,10 +9,12 @@
"additionalProperties": false,
"properties": {
"node_id": {
"type": "pubkey"
"type": "pubkey",
"description": "the node specified by `node_id` must be a peer, i.e., it must have a direct connection with the node receiving the RPC call, and the connection must be established. For a method to send arbitrary messages over multiple hops, including hops that do not understand the custom message, see the `createonion` and `sendonion` RPC methods. Messages can only be injected if the connection is handled by `openingd` or `channeld`. Messages cannot be injected when the peer is handled by `onchaind` or `closingd` since these do not have a connection, or are synchronous daemons that do not handle spontaneous messages"
},
"msg": {
"type": "hex"
"type": "hex",
"description": "must be a hex encoded well-formed message, including the 2-byte type prefix, but excluding the length prefix which will be added by the RPC method. The message types may not be one of the internally handled types, since that may cause issues with the internal state tracking of Core Lightning. We do (as of *v23.11*) allow sending of even types, but note that peers (as per the spec) will disconnect on receiving unknown even types"
}
}
}

43
doc/schemas/sendonion.request.json
View File

@ -9,10 +9,12 @@
],
"properties": {
"onion": {
"type": "hex"
"type": "hex",
"description": "hex-encoded 1366 bytes long blob that was returned by either of the tools that can generate onions. It contains the payloads destined for each hop and some metadata. Please refer to [BOLT 04][bolt04] for further details. If is specific to the route that is being used and the *payment_hash* used to construct, and therefore cannot be reused for other payments or to attempt a separate route. The custom onion can generally be created using the `devtools/onion` CLI tool, or the **createonion** RPC command"
},
"first_hop": {
"type": "object",
"description": "instructs Core Lightning which peer to send the onion to. It is a JSON dictionary that corresponds to the first element of the route array returned by *getroute*",
"required": [
"id",
"amount_msat",
@ -20,45 +22,62 @@
],
"properties": {
"id": {
"type": "pubkey"
"type": "pubkey",
"description": "node id for the peer. Use any available channel available to this peer"
},
"amount_msat": {
"type": "msat"
"type": "msat",
"description": "the amount to add an HTLC for millisatoshis"
},
"delay": {
"type": "u16"
"type": "u16",
"description": "the number of blocks delay of blocks on top of the current blockheight"
}
}
},
"payment_hash": {
"type": "hash"
"type": "hash",
"description": "specifies the 32 byte hex-encoded hash to use as a challenge to the HTLC that we are sending. It is specific to the onion and has to match the one the onion was created with"
},
"label": {
"type": "string"
"type": "string",
"description": "can be used to provide a human readable reference to retrieve the payment at a later time"
},
"shared_secrets": {
"type": "array",
"description": "a JSON list of 32 byte hex-encoded secrets that were used when creating the onion. Core Lightning can send a payment with a custom onion without the knowledge of these secrets, however it will not be able to parse an eventual error message since that is encrypted with the shared secrets used in the onion. If *shared_secrets* is provided Core Lightning will decrypt the error, act accordingly, e.g., add a `channel_update` included in the error to its network view, and set the details in *listsendpays* correctly. If it is not provided Core Lightning will store the encrypted onion, and expose it in *listsendpays* allowing the caller to decrypt it externally. If it is not provided the Core Lightning node does not know how long the route is, which channels or nodes are involved, and what an eventual error could have been. It can therefore be used for oblivious payments",
"items": {
"type": "secret"
}
},
"partid": {
"type": "u16"
"type": "u16",
"description": "if provided and non-zero, allows for multiple parallel partial payments with the same *payment_hash*"
},
"bolt11": {
"type": "string"
"type": "string",
"description": "if provided, it will be returned in *waitsendpay* and *listsendpays* results"
},
"amount_msat": {
"type": "msat"
"type": "msat",
"description": "used to annotate the payment, and is returned by *waitsendpay* and *listsendpays*"
},
"destination": {
"type": "pubkey"
"type": "pubkey",
"description": "if provided, it will be returned in **listpays** result"
},
"localinvreqid": {
"type": "hash"
"type": "hash",
"description": "`localinvreqid` is used by offers to link a payment attempt to a local `invoice_request` offer created by lightningd-invoicerequest(7)"
},
"groupid": {
"type": "u64"
"type": "u64",
"description": "grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash"
},
"description": {
"added": "v0.11.0",
"type": "string",
"description": "if provided, it will be returned in *waitsendpay* and *listsendpays* results"
}
}
}

2
doc/schemas/sendonionmessage.request.json
View File

@ -33,7 +33,7 @@
},
"tlv": {
"type": "u8",
"description": "contains a hexidecimal TLV to include"
"description": "contains a hexadecimal TLV to include"
}
}
}

54
doc/schemas/sendpay.request.json
View File

@ -18,44 +18,66 @@
"channel"
],
"properties": {
"amount_msat": {
"type": "msat"
},
"id": {
"type": "pubkey"
},
"delay": {
"type": "u16"
"type": "pubkey",
"description": "The node at the end of this hop"
},
"channel": {
"type": "short_channel_id"
"type": "short_channel_id",
"description": "The channel joining these nodes"
},
"delay": {
"type": "u32",
"description": "The total CLTV expected by the node at the end of this hop"
},
"amount_msat": {
"type": "msat",
"description": "The amount expected by the node at the end of this hop"
}
}
}
},
"payment_hash": {
"type": "hash"
"type": "hash",
"description": "the hash of the payment_preimage"
},
"label": {
"type": "string"
"type": "string",
"description": "the label provided when creating the invoice_request"
},
"amount_msat": {
"type": "msat"
"type": "msat",
"description": "amount must be provided if *partid* is non-zero, or the payment is to-self, otherwise it must be equal to the final amount to the destination. By default it is in millisatoshi precision; it can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*"
},
"bolt11": {
"type": "string"
"type": "string",
"description": "bolt11 invoice to pay. If provided, will be returned in *waitsendpay* and *listsendpays* results"
},
"payment_secret": {
"type": "secret"
"type": "secret",
"description": "value that the final recipient requires to accept the payment, as defined by the `payment_data` field in BOLT 4 and the `s` field in the BOLT 11 invoice format. It is required if *partid* is non-zero"
},
"partid": {
"type": "u16"
"type": "u64",
"description": "must not be provided for self-payments. If provided and non-zero, allows for multiple parallel partial payments with the same *payment_hash*. The *amount_msat* amount (which must be provided) for each **sendpay** with matching *payment_hash* must be equal, and **sendpay** will fail if there are differing values given"
},
"localinvreqid": {
"type": "hex"
"type": "hex",
"description": "indicates that this payment is being made for a local invoice_request. This ensures that we only send a payment for a single-use invoice_request once"
},
"groupid": {
"type": "u64"
"type": "u64",
"description": "allows you to attach a number which appears in **listsendpays** so payments can be identified as part of a logical group. The *pay* plugin uses this to identify one attempt at a MPP payment, for example"
},
"payment_metadata": {
"added": "v0.11.0",
"type": "hex",
"description": "placed in the final onion hop TLV"
},
"description": {
"added": "v0.11.0",
"type": "string",
"description": "description used in the invoice"
}
}
}

6
doc/schemas/sendpsbt.request.json
View File

@ -7,10 +7,12 @@
],
"properties": {
"psbt": {
"type": "string"
"type": "string",
"description": "the fully signed psbt to be sent"
},
"reserve": {
"type": "boolean"
"type": "u32",
"description": "number of blocks to increase reservation of any of our inputs by. Default is 72"
}
}
}

21
doc/schemas/setchannel.request.json
View File

@ -7,26 +7,33 @@
],
"properties": {
"id": {
"type": "string"
"type": "string",
"description": "should contain a scid (short channel ID), channel id or peerid (pubkey) of the channel to be modified. If *id* is set to `all`, the updates are applied to all channels in states CHANNELD_NORMAL CHANNELD_AWAITING_LOCKIN or DUALOPEND_AWAITING_LOCKIN. If *id* is a peerid, all channels with the +peer in those states are changed"
},
"feebase": {
"type": "msat"
"type": "msat",
"description": "value in millisatoshi that is added as base fee to any routed payment: if omitted, it is unchanged. It can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*"
},
"feeppm": {
"type": "u32"
"type": "u32",
"description": "value that is added proportionally per-millionths to any routed payment volume in satoshi. For example, if ppm is 1,000 and 1,000,000 satoshi is being routed through the channel, an proportional fee of 1,000 satoshi is added, resulting in a 0.1% fee"
},
"htlcmin": {
"type": "msat"
"type": "msat",
"description": "value that limits how small an HTLC we will forward: if omitted, it is unchanged (the default is no lower limit). It can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*. Note that the peer also enforces a minimum for the channel: setting it below that will simply set it to that value with a warning. Also note that *htlcmin* only applies to forwarded HTLCs: we can still send smaller payments ourselves"
},
"htlcmax": {
"type": "msat"
"type": "msat",
"description": "value that limits how large an HTLC we will forward: if omitted, it is unchanged (the default is no effective limit). It can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*. Note that *htlcmax* only applies to forwarded HTLCs: we can still send larger payments ourselves"
},
"enforcedelay": {
"type": "u32"
"type": "u32",
"description": "number of seconds to delay before enforcing the new fees/htlc max (default 600, which is ten minutes). This gives the network a chance to catch up with the new rates and avoids rejecting HTLCs before they do. This only has an effect if rates are increased (we always allow users to overpay fees) or *htlcmax* is decreased, and only applied to a single rate increase per channel (we don't remember an arbitrary number of prior feerates) and if the node is restarted the updated configuration is enforced immediately"
},
"ignorefeelimits": {
"added": "v23.08",
"type": "boolean"
"type": "boolean",
"description": "if set to True means to allow the peer to set the commitment transaction fees (or closing transaction fees) to any value they want. This is dangerous: they could set an exorbitant fee (so HTLCs are unenforcable), or a tiny fee (so that commitment transactions cannot be relayed), but avoids channel breakage in case of feerate disagreements. (Note: the global `ignore_fee_limits` setting overrides this)"
}
}
}

18
doc/schemas/setconfig.request.json
View File

@ -8,8 +8,22 @@
"added": "v23.08",
"properties": {
"config": {
"type": "string"
"type": "string",
"description": "name of the config variable which should be set to the value of the variable"
},
"val": {}
"val": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "boolean"
}
],
"description": "value of the config variable to be set or updated"
}
}
}

2
doc/schemas/showrunes.request.json
View File

@ -7,7 +7,7 @@
"properties": {
"rune": {
"type": "string",
"description": "optional rune to list"
"description": "if specified, only details of that rune will be returned"
}
}
}

2
doc/schemas/signinvoice.request.json
View File

@ -9,7 +9,7 @@
"properties": {
"invstring": {
"type": "string",
"description": ""
"description": "bolt11 form, but the final signature is ignored. Minimal sanity checks are done"
}
}
}

3
doc/schemas/signmessage.request.json
View File

@ -7,7 +7,8 @@
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
"type": "string",
"description": "less that 65536 characters long message to be signed by the node"
}
}
}

4
doc/schemas/signpsbt.request.json
View File

@ -7,10 +7,12 @@
],
"properties": {
"psbt": {
"type": "string"
"type": "string",
"description": "the psbt to be signed"
},
"signonly": {
"type": "array",
"description": "input numbers to sign",
"items": {
"type": "u32"
}

2
doc/schemas/splice_init.request.json
View File

@ -26,7 +26,7 @@
},
"force_feerate": {
"type": "boolean",
"description": "By default splices will fail if the fee provided looks too high. This is to protect against accidentally setting your fee higher than intended. Set `force_feerate` to true to skip this saftey check"
"description": "by default splices will fail if the fee provided looks too high. This is to protect against accidentally setting your fee higher than intended. Set `force_feerate` to true to skip this saftey check"
}
}
}

2
doc/schemas/splice_update.request.json
View File

@ -14,7 +14,7 @@
},
"psbt": {
"type": "string",
"description": "the (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically"
"description": "the base 64 encoded PSBT returned from `splice_init` with any changes added by the user"
}
}
}

3
doc/schemas/txdiscard.request.json
View File

@ -7,7 +7,8 @@
],
"properties": {
"txid": {
"type": "txid"
"type": "txid",
"description": "the transaction id, inputs should be unreseverd from"
}
}
}

8
doc/schemas/txprepare.request.json
View File

@ -8,18 +8,22 @@
"properties": {
"outputs": {
"type": "array",
"description": "format is like: [{destination1: amount1}, {destination2: amount2}] or [{destination: *all*}]. It supports any number of **confirmed** outputs",
"items": {
"type": "outputdesc"
}
},
"feerate": {
"type": "feerate"
"type": "feerate",
"description": "used for the transaction as initial feerate. The default is *normal*"
},
"minconf": {
"type": "u32"
"type": "u32",
"description": "the minimum number of confirmations that used outputs should have. Default is 1"
},
"utxos": {
"type": "array",
"description": "to be used to fund the transaction, as an array of `txid:vout`. These must be drawn from the node's available UTXO set",
"items": {
"type": "outpoint"
}

3
doc/schemas/txsend.request.json
View File

@ -7,7 +7,8 @@
],
"properties": {
"txid": {
"type": "txid"
"type": "txid",
"description": "The transaction id of the transaction created by **txprepare**"
}
}
}

27
doc/schemas/utxopsbt.request.json
View File

@ -10,39 +10,48 @@
],
"properties": {
"satoshi": {
"type": "msat"
"type": "msat_or_all",
"description": "the minimum satoshi value of the output(s) needed (or the string `all` meaning use all unreserved inputs). If a value, it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*"
},
"feerate": {
"type": "feerate"
"type": "feerate",
"description": "used for the transaction as initial feerate. The default is *normal*"
},
"startweight": {
"type": "u32"
"type": "u32",
"description": "the weight of the transaction before *fundpsbt* has added any inputs"
},
"utxos": {
"type": "array",
"description": "an array of `txid:vout`, each of which must be reserved or available",
"items": {
"type": "outpoint"
}
},
"reserve": {
"type": "u32",
"description": "reserve is a number: if non-zero number then reserveinputs is called (successfully, with exclusive true) on the returned PSBT for this number of blocks (default: 72)."
"description": "if not zero, then *reserveinputs* is called (successfully, with *exclusive* true) on the returned PSBT for this number of blocks. Defaults to 72 blocks if unspecified"
},
"reservedok": {
"type": "boolean"
"type": "boolean",
"description": "if set to true, it will also fail if any of the *utxos* are already reserved. Default is false"
},
"locktime": {
"type": "u32"
"type": "u32",
"description": "if not set, it is set to a recent block height"
},
"min_witness_weight": {
"type": "u32"
"type": "u32",
"description": "minimum weight to use for a UTXO's witness. If the actual witness weight is greater than the provided minimum, the actual witness weight will be used"
},
"excess_as_change": {
"type": "boolean"
"type": "boolean",
"description": "flag to add a change output for the excess sats"
},
"opening_anchor_channel": {
"added": "v23.08",
"type": "boolean"
"type": "boolean",
"description": "to signel that it needs emergency reserve for anchors so that we can lowball our commitment tx fees, and min-emergency-msat for reserving some sats for closing anchor channels"
}
}
}

5
doc/schemas/wait.request.json
View File

@ -11,6 +11,7 @@
"properties": {
"subsystem": {
"type": "string",
"description": "the subsystem to get the next index value from",
"enum": [
"invoices",
"forwards",
@ -19,6 +20,7 @@
},
"indexname": {
"type": "string",
"description": "the name of the index to get the next value for",
"enum": [
"created",
"updated",
@ -26,7 +28,8 @@
]
},
"nextvalue": {
"type": "u64"
"type": "u64",
"description": "the next value of the index"
}
}
}

6
doc/schemas/waitanyinvoice.request.json
View File

@ -5,10 +5,12 @@
"required": [],
"properties": {
"lastpay_index": {
"type": "u64"
"type": "u64",
"description": "ignores any invoices paid prior to or including this index. 0 is equivalent to not specifying and negative value is invalid"
},
"timeout": {
"type": "u64"
"type": "u64",
"description": "if specified, wait at most that number of seconds, which must be an integer. If the specified *timeout* is reached, this command will return with an error. You can specify this to 0 so that **waitanyinvoice** will return immediately with an error if no pending invoice is available yet. If unspecified, this command will wait indefinitely"
}
}
}

4
doc/schemas/waitblockheight.request.json
View File

@ -8,11 +8,11 @@
"properties": {
"blockheight": {
"type": "u32",
"description": "The current block height (>= blockheight parameter)"
"description": "current blockheight of the blockchain if the value is greater than this number. If it is a present or past block height, then the command returns immediately"
},
"timeout": {
"type": "u32",
"description": "If timeout seconds is reached without the specified blockheight being reached, this command will fail with a code of 2000."
"description": "only wait up to specified seconds. Defaults to 60 seconds"
}
}
}

10
doc/schemas/waitinvoice.request.json
View File

@ -7,7 +7,15 @@
],
"properties": {
"label": {
"type": "string"
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"description": "unique label of the invoice waiting to be paid"
}
}
}

12
doc/schemas/waitsendpay.request.json
View File

@ -7,16 +7,20 @@
],
"properties": {
"payment_hash": {
"type": "hash"
"type": "hash",
"description": "the hash of the *payment_preimage*"
},
"timeout": {
"type": "u32"
"type": "u32",
"description": "a timeout in seconds, for this RPC command to return. If the *timeout* is provided and the given amount of time passes without the payment definitely succeeding or definitely failing, this command returns with a 200 error code (payment still in progress). If *timeout* is not provided this call will wait indefinitely. Indicating a *timeout* of 0 effectively makes this call a pollable query of the status of the payment"
},
"partid": {
"type": "u64"
"type": "u64",
"description": "unique ID within this (multi-part) payment. It must match that of the **sendpay** command"
},
"groupid": {
"type": "u64"
"type": "u64",
"description": "grouping key to disambiguate multiple attempts to pay the same payment_hash"
}
}
}

16
doc/schemas/withdraw.request.json
View File

@ -3,23 +3,29 @@
"type": "object",
"additionalProperties": false,
"required": [
"destination"
"destination",
"satoshi"
],
"properties": {
"destination": {
"type": "string"
"type": "string",
"description": "any Bitcoin accepted type, including bech32"
},
"satoshi": {
"type": "msat_or_all"
"type": "msat_or_all",
"description": "the amount to be withdrawn from the internal wallet (expressed, as name suggests, in satoshi). The string *all* can be used to specify withdrawal of all available funds (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*"
},
"feerate": {
"type": "feerate"
"type": "feerate",
"description": "used for the withdrawal as initial feerate. The default is *normal*"
},
"minconf": {
"type": "u16"
"type": "u16",
"description": "minimum number of confirmations that used outputs should have. Default is 1"
},
"utxos": {
"type": "array",
"description": "specifies the utxos to be used to be withdrawn from, as an array of `txid:vout`. These must be drawn from the node's available UTXO set",
"items": {
"type": "outpoint"
}