mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-03-11 01:27:58 +01:00
doc: add documentation for invoicerequest commands.
As reported on Discord, these are undocumented. And thus, um, hard to find! Reported-by: Aaron Barnard Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell
Alex Myers
parent
df10c62508
commit
5e394ef53f
11 changed files with 394 additions and 0 deletions
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -57,6 +57,7 @@ Core Lightning Documentation
|
|||
lightning-delforward <lightning-delforward.7.md>
|
||||
lightning-delinvoice <lightning-delinvoice.7.md>
|
||||
lightning-delpay <lightning-delpay.7.md>
|
||||
lightning-disableinvoicerequest <lightning-disableinvoicerequest.7.md>
|
||||
lightning-disableoffer <lightning-disableoffer.7.md>
|
||||
lightning-disconnect <lightning-disconnect.7.md>
|
||||
lightning-emergencyrecover <lightning-emergencyrecover.7.md>
|
||||
|
|
@ -74,6 +75,7 @@ Core Lightning Documentation
|
|||
lightning-help <lightning-help.7.md>
|
||||
lightning-hsmtool <lightning-hsmtool.8.md>
|
||||
lightning-invoice <lightning-invoice.7.md>
|
||||
lightning-invoicerequest <lightning-invoicerequest.7.md>
|
||||
lightning-keysend <lightning-keysend.7.md>
|
||||
lightning-listchannels <lightning-listchannels.7.md>
|
||||
lightning-listconfigs <lightning-listconfigs.7.md>
|
||||
|
|
@ -81,6 +83,7 @@ Core Lightning Documentation
|
|||
lightning-listforwards <lightning-listforwards.7.md>
|
||||
lightning-listfunds <lightning-listfunds.7.md>
|
||||
lightning-listhtlcs <lightning-listhtlcs.7.md>
|
||||
lightning-listinvoicerequests <lightning-listinvoicerequests.7.md>
|
||||
lightning-listinvoices <lightning-listinvoices.7.md>
|
||||
lightning-listnodes <lightning-listnodes.7.md>
|
||||
lightning-listoffers <lightning-listoffers.7.md>
|
||||
|
|
|
|||
54
doc/lightning-disableinvoicerequest.7.md
Normal file
54
doc/lightning-disableinvoicerequest.7.md
Normal file
|
|
@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
lightning-invoicerequest(7), lightning-listinvoicerequest(7).
|
||||
|
||||
RESOURCES
|
||||
---------
|
||||
|
||||
Main web site: <https://github.com/ElementsProject/lightning>
|
||||
|
||||
[comment]: # ( SHA256STAMP:a862f4bfdcef7db2b7e331ea64f5d79cbdf7553ea5bfd49775a675b21dc7004c)
|
||||
85
doc/lightning-invoicerequest.7.md
Normal file
85
doc/lightning-invoicerequest.7.md
Normal file
|
|
@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
lightning-listinvoicerequests(7), lightning-disableinvoicerequest(7).
|
||||
|
||||
RESOURCES
|
||||
---------
|
||||
|
||||
Main web site: <https://github.com/ElementsProject/lightning>
|
||||
|
||||
[comment]: # ( SHA256STAMP:fef519902c0eeb8caa1ae0e9f1a0a16fc5fc6eaa4106af6a1d3a83058e5747c1)
|
||||
50
doc/lightning-listinvoicerequests.7.md
Normal file
50
doc/lightning-listinvoicerequests.7.md
Normal file
|
|
@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
lightning-invoicerequests(7), lightning-disableinvoicerequest(7).
|
||||
|
||||
RESOURCES
|
||||
---------
|
||||
|
||||
Main web site: <https://github.com/ElementsProject/lightning>
|
||||
|
||||
[comment]: # ( SHA256STAMP:233e28e40752d6e8db2eb7928a1ced18bf16db1dddfe6c16d0f3a32b5e51ccd4)
|
||||
14
doc/schemas/disableinvoicerequest.request.json
Normal file
14
doc/schemas/disableinvoicerequest.request.json
Normal file
|
|
@ -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": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
42
doc/schemas/disableinvoicerequest.schema.json
Normal file
42
doc/schemas/disableinvoicerequest.schema.json
Normal file
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
32
doc/schemas/invoicerequest.request.json
Normal file
32
doc/schemas/invoicerequest.request.json
Normal file
|
|
@ -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": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
44
doc/schemas/invoicerequest.schema.json
Normal file
44
doc/schemas/invoicerequest.schema.json
Normal file
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
17
doc/schemas/listinvoicerequests.request.json
Normal file
17
doc/schemas/listinvoicerequests.request.json
Normal file
|
|
@ -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": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
50
doc/schemas/listinvoicerequests.schema.json
Normal file
50
doc/schemas/listinvoicerequests.schema.json
Normal file
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Reference in a new issue