mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 09:54:16 +01:00
b327bd30c3
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>
373 lines
11 KiB
JSON
373 lines
11 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"added": "v23.08",
|
|
"rpc": "wait",
|
|
"title": "Command to wait for creations, changes and deletions",
|
|
"description": [
|
|
"The **wait** RPC command returns once the index given by *indexname* in *subsystem* reaches or exceeds *nextvalue*. All indexes start at 0, when no events have happened (**wait** with a *nextvalue* of 0 is a way of getting the current index, though naturally this is racy!)."
|
|
],
|
|
"request": {
|
|
"required": [
|
|
"subsystem",
|
|
"indexname",
|
|
"nextvalue"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"description": [
|
|
"The subsystem to get the next index value from.",
|
|
" `invoices`: corresponding to `listinvoices` (added in *v23.08*).",
|
|
" `sendpays`: corresponding to `listsendpays` (added in *v23.11*).",
|
|
" `forwards`: corresponding to `listforwards` (added in *v23.11*)."
|
|
],
|
|
"enum": [
|
|
"invoices",
|
|
"forwards",
|
|
"sendpays"
|
|
]
|
|
},
|
|
"indexname": {
|
|
"type": "string",
|
|
"description": [
|
|
"The name of the index to get the next value for.",
|
|
" `created` is incremented by one for every new object.",
|
|
" `updated` is incremented by one every time an object is changed.",
|
|
" `deleted` is incremented by one every time an object is deleted."
|
|
],
|
|
"enum": [
|
|
"created",
|
|
"updated",
|
|
"deleted"
|
|
]
|
|
},
|
|
"nextvalue": {
|
|
"type": "u64",
|
|
"description": [
|
|
"The next value of the index."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"response": {
|
|
"required": [
|
|
"subsystem"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"invoices",
|
|
"forwards",
|
|
"sendpays"
|
|
]
|
|
},
|
|
"created": {
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order entry was created."
|
|
]
|
|
},
|
|
"updated": {
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order entry was updated."
|
|
]
|
|
},
|
|
"deleted": {
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order entry was deleted."
|
|
]
|
|
},
|
|
"details": {}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"invoices"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {},
|
|
"created": {},
|
|
"updated": {},
|
|
"deleted": {},
|
|
"details": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"unpaid",
|
|
"paid",
|
|
"expired"
|
|
],
|
|
"description": [
|
|
"Whether it's paid, unpaid or unpayable."
|
|
]
|
|
},
|
|
"label": {
|
|
"type": "string",
|
|
"description": [
|
|
"Unique label supplied at invoice creation."
|
|
]
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": [
|
|
"Description used in the invoice."
|
|
]
|
|
},
|
|
"bolt11": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT11 string."
|
|
]
|
|
},
|
|
"bolt12": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT12 string."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"forwards"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {},
|
|
"created": {},
|
|
"updated": {},
|
|
"deleted": {},
|
|
"details": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"offered",
|
|
"settled",
|
|
"failed",
|
|
"local_failed"
|
|
],
|
|
"description": [
|
|
"Still ongoing, completed, failed locally, or failed after forwarding."
|
|
]
|
|
},
|
|
"in_channel": {
|
|
"type": "short_channel_id",
|
|
"description": [
|
|
"Unique label supplied at invoice creation."
|
|
]
|
|
},
|
|
"in_htlc_id": {
|
|
"type": "u64",
|
|
"description": [
|
|
"The unique HTLC id the sender gave this (not present if incoming channel was closed before upgrade to v22.11)."
|
|
]
|
|
},
|
|
"in_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The value of the incoming HTLC."
|
|
]
|
|
},
|
|
"out_channel": {
|
|
"type": "short_channel_id",
|
|
"description": [
|
|
"The channel that the HTLC (trying to) forward to."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"sendpays"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {},
|
|
"created": {},
|
|
"updated": {},
|
|
"deleted": {},
|
|
"details": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"failed",
|
|
"complete"
|
|
],
|
|
"description": [
|
|
"Status of the payment."
|
|
]
|
|
},
|
|
"partid": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Part number (for multiple parts to a single payment)."
|
|
]
|
|
},
|
|
"groupid": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash."
|
|
]
|
|
},
|
|
"payment_hash": {
|
|
"type": "hash",
|
|
"description": [
|
|
"The hash of the *payment_preimage* which will prove payment."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"reliability": [
|
|
"Indices can go forward by more than one; in particlar, if multiple objects were created and the one deleted, you could see this effect. Similarly, there are some places (e.g. invoice expiration) where we can update multiple entries at once.",
|
|
"",
|
|
"Indices only monotoncally increase."
|
|
],
|
|
"usage": [
|
|
"The **wait** RPC is used to track changes in the system. Consider tracking invoices being paid or expiring.",
|
|
"",
|
|
"The simplest (and inefficient method) would be:",
|
|
"",
|
|
"1: Call `listinvoices` to get the current state of all invoices, and remember the highest `updated_index`. Say it was 5.",
|
|
"",
|
|
"2: Call `wait invoices updated 6`.",
|
|
"",
|
|
"3: When it returns, call `listinvoices` again to see what changed.",
|
|
"",
|
|
"This is obviously inefficient, so there are two optimizations:",
|
|
"",
|
|
"1: Call `listinvoices` with `index=updated` and `start=6` to only see invoices with `updated_index` greater than or equal to 6.",
|
|
"",
|
|
"2: `wait` itself may also return some limited subset of fields from the list command (it can't do this in all cases); for `invoices` this is `label` and `status`, allowing many callers to avoid the `listinvoices` call."
|
|
],
|
|
"errors": [
|
|
"On error the returned object will contain `code` and `message` properties, with `code` being one of the following:",
|
|
"",
|
|
"- -32602: If the given parameters are wrong."
|
|
],
|
|
"author": [
|
|
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-listinvoices(7)",
|
|
"lightning-listforwards(7)",
|
|
"lightning-listsendpays(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
],
|
|
"examples": [
|
|
{
|
|
"request": {
|
|
"id": "example:wait#1",
|
|
"method": "wait",
|
|
"params": {
|
|
"subsystem": "invoices",
|
|
"indexname": "created",
|
|
"nextvalue": 0
|
|
}
|
|
},
|
|
"response": {
|
|
"subsystem": "invoices",
|
|
"created": 15
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:wait#2",
|
|
"method": "wait",
|
|
"params": {
|
|
"subsystem": "sendpays",
|
|
"indexname": "created",
|
|
"nextvalue": 15
|
|
}
|
|
},
|
|
"response": {
|
|
"subsystem": "sendpays",
|
|
"created": 15,
|
|
"details": {
|
|
"status": "pending",
|
|
"partid": 0,
|
|
"groupid": 1,
|
|
"payment_hash": "4c6f04eaf19dd956b616f1ba8718df40e387c4a56be36cf4e881a009cbf66899"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:wait#3",
|
|
"method": "wait",
|
|
"params": [
|
|
"sendpays",
|
|
"updated",
|
|
15
|
|
]
|
|
},
|
|
"response": {
|
|
"subsystem": "sendpays",
|
|
"updated": 15,
|
|
"details": {
|
|
"status": "complete",
|
|
"partid": 0,
|
|
"groupid": 1,
|
|
"payment_hash": "4c6f04eaf19dd956b616f1ba8718df40e387c4a56be36cf4e881a009cbf66899"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|