diff --git a/doc/Makefile b/doc/Makefile index a2e158e3d..66d40dcb4 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -34,6 +34,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-delforward.7 \ doc/lightning-delinvoice.7 \ doc/lightning-delpay.7 \ + doc/lightning-disableinvoicerequest.7 \ doc/lightning-disableoffer.7 \ doc/lightning-disconnect.7 \ doc/lightning-emergencyrecover.7 \ @@ -48,6 +49,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-getroute.7 \ doc/lightning-hsmtool.8 \ doc/lightning-invoice.7 \ + doc/lightning-invoicerequest.7 \ doc/lightning-keysend.7 \ doc/lightning-listchannels.7 \ doc/lightning-listdatastore.7 \ @@ -55,6 +57,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-listfunds.7 \ doc/lightning-listhtlcs.7 \ doc/lightning-listinvoices.7 \ + doc/lightning-listinvoicerequests.7 \ doc/lightning-listoffers.7 \ doc/lightning-listpays.7 \ doc/lightning-listpeers.7 \ diff --git a/doc/index.rst b/doc/index.rst index 1be476a41..428ff8273 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -57,6 +57,7 @@ Core Lightning Documentation lightning-delforward lightning-delinvoice lightning-delpay + lightning-disableinvoicerequest lightning-disableoffer lightning-disconnect lightning-emergencyrecover @@ -74,6 +75,7 @@ Core Lightning Documentation lightning-help lightning-hsmtool lightning-invoice + lightning-invoicerequest lightning-keysend lightning-listchannels lightning-listconfigs @@ -81,6 +83,7 @@ Core Lightning Documentation lightning-listforwards lightning-listfunds lightning-listhtlcs + lightning-listinvoicerequests lightning-listinvoices lightning-listnodes lightning-listoffers diff --git a/doc/lightning-disableinvoicerequest.7.md b/doc/lightning-disableinvoicerequest.7.md new file mode 100644 index 000000000..d350cdcb9 --- /dev/null +++ b/doc/lightning-disableinvoicerequest.7.md @@ -0,0 +1,54 @@ +lightning-disableinvoicerequest -- Command for removing an invoice request +========================================================================== + +SYNOPSIS +-------- +**(WARNING: experimental-offers only)** + +**disableinvoicerequest** *invreq\_id* + +DESCRIPTION +----------- + +The **disableinvoicerequest** RPC command disables an +invoice\_request, so that no further invoices will be accepted (and +thus, no further payments made).. + +We currently don't support deletion of invoice\_requests, so they are +not forgotten entirely (there may be payments which refer to this +invoice\_request). + + +RETURN VALUE +------------ + +Note: the returned object is the same format as **listinvoicerequest**. + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: + +- **invreq\_id** (hash): the SHA256 hash of all invoice\_request fields less than 160 +- **active** (boolean): whether the invoice\_request is currently active (always *false*) +- **single\_use** (boolean): whether the invoice\_request will become inactive after we pay an invoice for it +- **bolt12** (string): the bolt12 string starting with lnr +- **used** (boolean): whether the invoice\_request has already been used +- **label** (string, optional): the label provided when creating the invoice\_request + +[comment]: # (GENERATE-FROM-SCHEMA-END) + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-invoicerequest(7), lightning-listinvoicerequest(7). + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:a862f4bfdcef7db2b7e331ea64f5d79cbdf7553ea5bfd49775a675b21dc7004c) diff --git a/doc/lightning-invoicerequest.7.md b/doc/lightning-invoicerequest.7.md new file mode 100644 index 000000000..4a5023b6c --- /dev/null +++ b/doc/lightning-invoicerequest.7.md @@ -0,0 +1,85 @@ +lightning-invoicerequest -- Command for offering payments +========================================================= + +SYNOPSIS +-------- + +**(WARNING: experimental-offers only)** + +**invoicerequest** *amount* *description* [*issuer*] [*label*] [*absolute\_expiry*] [*single\_use*] + +DESCRIPTION +----------- + +The **invoicerequest** RPC command creates an `invoice_request` to +send payments: it automatically enables the processing of an incoming +invoice, and payment of it. The reader of the resulting +`invoice_request` can use lightning-sendinvoice(7) to collect their +payment. + +The *amount* parameter can be 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*. + +The *description* is 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. + +The *issuer* is another (optional) field exposed in the +`invoice_request`, and reflects who is issuing it (i.e. you) if +appropriate. + +The *label* field is an internal-use name for the offer, which can +be any UTF-8 string. + +The *absolute\_expiry* is optionally 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* (default true) 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). + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: + +- **invreq\_id** (hash): the SHA256 hash of all invoice\_request fields less than 160 +- **active** (boolean): whether the invoice\_request is currently active (always *true*) +- **single\_use** (boolean): whether the invoice\_request will become inactive after we pay an invoice for it +- **bolt12** (string): the bolt12 string starting with lnr +- **used** (boolean): whether the invoice\_request has already been used (always *false*) +- **label** (string, optional): the label provided when creating the invoice\_request + +[comment]: # (GENERATE-FROM-SCHEMA-END) + +On failure, an error is returned and no `invoice_request` is +created. If the lightning process fails before responding, the caller +should use lightning-listinvoicerequests(7) to query whether it was +created or not. + +The following error codes may occur: +- -1: Catchall nonspecific error. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listinvoicerequests(7), lightning-disableinvoicerequest(7). + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:fef519902c0eeb8caa1ae0e9f1a0a16fc5fc6eaa4106af6a1d3a83058e5747c1) diff --git a/doc/lightning-listinvoicerequests.7.md b/doc/lightning-listinvoicerequests.7.md new file mode 100644 index 000000000..9b8ed2e83 --- /dev/null +++ b/doc/lightning-listinvoicerequests.7.md @@ -0,0 +1,50 @@ +lightning-listinvoicerequests -- Command for querying invoice\_request status +============================================================================= + +SYNOPSIS +-------- + +**listinvoicerequests** [*invreq\_id*] [*active\_only*] + +DESCRIPTION +----------- + +The **listinvoicerequests** RPC command gets the status of a specific `invoice_request`, +if it exists, or the status of all `invoice_requests` if given no argument. + +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. If `active_only` is `true` (default is `false`) then +only active invoice\_requests are returned. + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **invoicerequests** is returned. It is an array of objects, where each object contains: + +- **invreq\_id** (hash): the SHA256 hash of all invoice\_request fields less than 160 +- **active** (boolean): whether the invoice\_request is currently active +- **single\_use** (boolean): whether the invoice\_request will become inactive after we pay an invoice for it +- **bolt12** (string): the bolt12 string starting with lnr +- **used** (boolean): whether the invoice\_request has already been used +- **label** (string, optional): the label provided when creating the invoice\_request + +[comment]: # (GENERATE-FROM-SCHEMA-END) + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-invoicerequests(7), lightning-disableinvoicerequest(7). + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:233e28e40752d6e8db2eb7928a1ced18bf16db1dddfe6c16d0f3a32b5e51ccd4) diff --git a/doc/schemas/disableinvoicerequest.request.json b/doc/schemas/disableinvoicerequest.request.json new file mode 100644 index 000000000..08bbe7f7b --- /dev/null +++ b/doc/schemas/disableinvoicerequest.request.json @@ -0,0 +1,14 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "invreq_id" + ], + "properties": { + "invreq_id": { + "type": "string", + "description": "" + } + } +} diff --git a/doc/schemas/disableinvoicerequest.schema.json b/doc/schemas/disableinvoicerequest.schema.json new file mode 100644 index 000000000..713cb2efb --- /dev/null +++ b/doc/schemas/disableinvoicerequest.schema.json @@ -0,0 +1,42 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "invreq_id", + "single_use", + "active", + "bolt12", + "used" + ], + "added": "v22.11", + "properties": { + "invreq_id": { + "type": "hash", + "description": "the SHA256 hash of all invoice_request fields less than 160" + }, + "active": { + "type": "boolean", + "enum": [ + false + ], + "description": "whether the invoice_request is currently active" + }, + "single_use": { + "type": "boolean", + "description": "whether the invoice_request will become inactive after we pay an invoice for it" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 string starting with lnr" + }, + "used": { + "type": "boolean", + "description": "whether the invoice_request has already been used" + }, + "label": { + "type": "string", + "description": "the label provided when creating the invoice_request" + } + } +} diff --git a/doc/schemas/invoicerequest.request.json b/doc/schemas/invoicerequest.request.json new file mode 100644 index 000000000..5ba071da9 --- /dev/null +++ b/doc/schemas/invoicerequest.request.json @@ -0,0 +1,32 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "amount", + "description" + ], + "added": "v22.11", + "properties": { + "amount": { + "type": "msat", + "description": "" + }, + "description": { + "type": "string", + "description": "" + }, + "issuer": { + "type": "string", + "description": "" + }, + "absolute_expiry": { + "type": "u64", + "description": "" + }, + "single_use": { + "type": "boolean", + "description": "" + } + } +} diff --git a/doc/schemas/invoicerequest.schema.json b/doc/schemas/invoicerequest.schema.json new file mode 100644 index 000000000..378a95650 --- /dev/null +++ b/doc/schemas/invoicerequest.schema.json @@ -0,0 +1,44 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "invreq_id", + "single_use", + "active", + "bolt12", + "used" + ], + "properties": { + "invreq_id": { + "type": "hash", + "description": "the SHA256 hash of all invoice_request fields less than 160" + }, + "active": { + "type": "boolean", + "enum": [ + true + ], + "description": "whether the invoice_request is currently active" + }, + "single_use": { + "type": "boolean", + "description": "whether the invoice_request will become inactive after we pay an invoice for it" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 string starting with lnr" + }, + "used": { + "type": "boolean", + "enum": [ + false + ], + "description": "whether the invoice_request has already been used" + }, + "label": { + "type": "string", + "description": "the label provided when creating the invoice_request" + } + } +} diff --git a/doc/schemas/listinvoicerequests.request.json b/doc/schemas/listinvoicerequests.request.json new file mode 100644 index 000000000..01104b40a --- /dev/null +++ b/doc/schemas/listinvoicerequests.request.json @@ -0,0 +1,17 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "added": "v22.11", + "properties": { + "invreq_id": { + "type": "string", + "description": "" + }, + "active_only": { + "type": "boolean", + "description": "" + } + } +} diff --git a/doc/schemas/listinvoicerequests.schema.json b/doc/schemas/listinvoicerequests.schema.json new file mode 100644 index 000000000..a2472c30e --- /dev/null +++ b/doc/schemas/listinvoicerequests.schema.json @@ -0,0 +1,50 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "invoicerequests" + ], + "properties": { + "invoicerequests": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ + "invreq_id", + "single_use", + "active", + "bolt12", + "used" + ], + "properties": { + "invreq_id": { + "type": "hash", + "description": "the SHA256 hash of all invoice_request fields less than 160" + }, + "active": { + "type": "boolean", + "description": "whether the invoice_request is currently active" + }, + "single_use": { + "type": "boolean", + "description": "whether the invoice_request will become inactive after we pay an invoice for it" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 string starting with lnr" + }, + "used": { + "type": "boolean", + "description": "whether the invoice_request has already been used" + }, + "label": { + "type": "string", + "description": "the label provided when creating the invoice_request" + } + } + } + } + } +}