vincenzopalazzo
/
rgb-cln
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

doc/schemas: listfunds 

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2021-06-16 10:36:17 +09:30
parent 74eeaa8213
commit 2296d4452f
3 changed files with 302 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
doc/lightning-listfunds.7 generated
View File

@ -17,69 +17,85 @@ in addition to the unspent ones\. Default is false\.
.SH RETURN VALUE
On success two arrays will be returned: \fIoutputs\fR with funds currently
locked onchain in UTXOs and \fIchannels\fR with funds readily spendable in
channels\.
Each entry in \fIoutputs\fR will include:
On success, an object is returned, containing:
.RS
.IP \[bu]
\fItxid\fR
\fBoutputs\fR (array of objects):
.RS
.IP \[bu]
\fIoutput\fR (the index of the output in the transaction)
\fBtxid\fR (txid): the ID of the spendable transaction
.IP \[bu]
\fIvalue\fR (the output value in satoshis)
\fBoutput\fR (u32): the index within \fItxid\fR
.IP \[bu]
\fIamount_msat\fR (the same as \fIvalue\fR, but in millisatoshi with \fImsat\fR
appended)
\fBamount_msat\fR (msat): the amount of the output
.IP \[bu]
\fIaddress\fR
\fBscriptpubkey\fR (hex): the scriptPubkey of the output
.IP \[bu]
\fIscriptpubkey\fR (the ScriptPubkey of the output, in hex)
\fBstatus\fR (string) (one of "unconfirmed", "confirmed", "spent")
.IP \[bu]
\fIredeemscript\fR (the redeemscript of the output, in hex, only if it's p2sh-wrapped)
\fBaddress\fR (string, optional): the bitcoin address of the output
.IP \[bu]
\fIstatus\fR (whether \fIunconfirmed\fR, \fIconfirmed\fR, or \fIspent\fR)
.IP \[bu]
\fIreserved\fR (whether this is UTXO is currently reserved for an in-flight tx)
.IP \[bu]
\fIreserved_to_block\fR (when reservation expires, if \fIreserved\fR is true)
\fBredeemscript\fR (hex, optional): the redeemscript, only if it's p2sh-wrapped
.RE
Each entry in \fIchannels\fR will include:
If \fBstatus\fR is "confirmed":
.RS
.IP \[bu]
\fIpeer_id\fR - the peer with which the channel is opened\.
\fBblockheight\fR (u32): Block height where it was confirmed
.RE
If \fBreserved\fR is "true":
.RS
.IP \[bu]
\fIshort_channel_id\fR - as per BOLT 7 (representing the block,
transaction number and output index of the channel funding
transaction)\.
\fBreserved_to_block\fR (u32): Block height where reservation will expire
.RE
.IP \[bu]
\fIchannel_sat\fR - available satoshis on our node’s end of the channel
(values rounded down to satoshis as internal storage is in
millisatoshi)\.
\fBchannels\fR (array of objects):
.RS
.IP \[bu]
\fIour_amount_msat\fR - same as above, but in millisatoshis with
\fImsat\fR appended\.
\fBpeer_id\fR (pubkey): the peer with which the channel is opened
.IP \[bu]
\fIchannel_total_sat\fR - total channel value in satoshi
\fBour_amount_msat\fR (msat): available satoshis on our node’s end of the channel
.IP \[bu]
\fIamount_msat\fR - same as above, but in millisatoshis with \fImsat\fR
appended\.
\fBamount_msat\fR (msat): total channel value
.IP \[bu]
\fIfunding_txid\fR - funding transaction id\.
\fBfunding_txid\fR (txid): funding transaction id
.IP \[bu]
\fIfunding_output\fR - the index of the output in the funding
transaction\.
\fBfunding_output\fR (u32): the 0-based index of the output in the funding transaction
.IP \[bu]
\fIconnected\fR - whether the channel peer is connected\.
\fBconnected\fR (boolean): whether the channel peer is connected
.IP \[bu]
\fIstate\fR - the channel state, in particular \fICHANNELD_NORMAL\fR means the
channel can be used normally\.
\fBstate\fR (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN")
.RE
If \fBstate\fR is "CHANNELD_NORMAL":
.RS
.IP \[bu]
\fBshort_channel_id\fR (short_channel_id): short channel id of channel
.RE
If \fBstate\fR is "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN" or "ONCHAIN":
.RS
.IP \[bu]
\fBshort_channel_id\fR (short_channel_id, optional): short channel id of channel (only if funding reached lockin depth before closing)
.RE
.RE
.SH AUTHOR
@ -94,4 +110,4 @@ Felix \fI<fixone@gmail.com\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:d1566362ec4c99ec904f03569ccc99306a42414dc682fd88ca1a3dcb8616de53
\" SHA256STAMP:499d7e1edccfa0751263e1742c31ca1349922ccc7cd4e6134ff016048be2e0aa

64
doc/lightning-listfunds.7.md
View File

@ -19,42 +19,37 @@ in addition to the unspent ones. Default is false.
RETURN VALUE
------------
On success two arrays will be returned: *outputs* with funds currently
locked onchain in UTXOs and *channels* with funds readily spendable in
channels.
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
- **outputs** (array of objects):
- **txid** (txid): the ID of the spendable transaction
- **output** (u32): the index within *txid*
- **amount_msat** (msat): the amount of the output
- **scriptpubkey** (hex): the scriptPubkey of the output
- **status** (string) (one of "unconfirmed", "confirmed", "spent")
- **address** (string, optional): the bitcoin address of the output
- **redeemscript** (hex, optional): the redeemscript, only if it's p2sh-wrapped
Each entry in *outputs* will include:
- *txid*
- *output* (the index of the output in the transaction)
- *value* (the output value in satoshis)
- *amount\_msat* (the same as *value*, but in millisatoshi with *msat*
appended)
- *address*
- *scriptpubkey* (the ScriptPubkey of the output, in hex)
- *redeemscript* (the redeemscript of the output, in hex, only if it's p2sh-wrapped)
- *status* (whether *unconfirmed*, *confirmed*, or *spent*)
- *reserved* (whether this is UTXO is currently reserved for an in-flight tx)
- *reserved_to_block* (when reservation expires, if *reserved* is true)
If **status** is "confirmed":
- **blockheight** (u32): Block height where it was confirmed
Each entry in *channels* will include:
- *peer\_id* - the peer with which the channel is opened.
- *short\_channel\_id* - as per BOLT 7 (representing the block,
transaction number and output index of the channel funding
transaction).
- *channel\_sat* - available satoshis on our node’s end of the channel
(values rounded down to satoshis as internal storage is in
millisatoshi).
- *our\_amount\_msat* - same as above, but in millisatoshis with
*msat* appended.
- *channel\_total\_sat* - total channel value in satoshi
- *amount\_msat* - same as above, but in millisatoshis with *msat*
appended.
- *funding\_txid* - funding transaction id.
- *funding\_output* - the index of the output in the funding
transaction.
- *connected* - whether the channel peer is connected.
- *state* - the channel state, in particular *CHANNELD_NORMAL* means the
channel can be used normally.
If **reserved** is "true":
- **reserved_to_block** (u32): Block height where reservation will expire
- **channels** (array of objects):
- **peer_id** (pubkey): the peer with which the channel is opened
- **our_amount_msat** (msat): available satoshis on our node’s end of the channel
- **amount_msat** (msat): total channel value
- **funding_txid** (txid): funding transaction id
- **funding_output** (u32): the 0-based index of the output in the funding transaction
- **connected** (boolean): whether the channel peer is connected
- **state** (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN")
If **state** is "CHANNELD_NORMAL":
- **short_channel_id** (short_channel_id): short channel id of channel
If **state** is "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN" or "ONCHAIN":
- **short_channel_id** (short_channel_id, optional): short channel id of channel (only if funding reached lockin depth before closing)
[comment]: # (GENERATE-FROM-SCHEMA-END)
AUTHOR
------
@ -71,3 +66,4 @@ RESOURCES
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:e8ce919941927237a08bbe84a2e4fbd86d391c6b9d502b85a4c9d1a20a8b2958)

217
doc/schemas/listfunds.schema.json Normal file
View File

@ -0,0 +1,217 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": [ "outputs", "channels" ],
"properties": {
"outputs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"required": [ "txid", "output", "amount_msat", "scriptpubkey", "status", "reserved" ],
"properties": {
"txid": {
"type": "txid",
"description": "the ID of the spendable transaction"
},
"output": {
"type": "u32",
"description": "the index within *txid*"
},
"amount_msat": {
"type": "msat",
"description": "the amount of the output"
},
"value": {
"type": "u64",
"deprecated": true
},
"scriptpubkey": {
"type": "hex",
"description": "the scriptPubkey of the output"
},
"address": {
"type": "string",
"description": "the bitcoin address of the output"
},
"redeemscript": {
"type": "hex",
"description": "the redeemscript, only if it's p2sh-wrapped"
},
"status": {
"type": "string",
"enum": [ "unconfirmed", "confirmed", "spent" ]
}
},
"allOf": [
{
"if": {
"properties": {
"status": {
"type": "string",
"enum": [ "confirmed" ]
}
}
},
"then": {
"additionalProperties": false,
"required": [ "blockheight" ],
"properties": {
"txid": { },
"output": { },
"amount_msat": { },
"scriptpubkey": { },
"address": { },
"value": { },
"redeemscript": { },
"status": { },
"reserved": { },
"reserved_to_block": { },
"blockheight": {
"type": "u32",
"description": "Block height where it was confirmed"
}
}
}
},
{
"if": {
"properties": {
"reserved": {
"type": "boolean",
"enum": [ "true" ]
}
}
},
"then": {
"additionalProperties": false,
"required": [ "reserved_to_block" ],
"properties": {
"txid": { },
"output": { },
"amount_msat": { },
"scriptpubkey": { },
"address": { },
"value": { },
"redeemscript": { },
"status": { },
"blockheight": { },
"reserved": { },
"reserved_to_block": {
"type": "u32",
"description": "Block height where reservation will expire"
}
}
}
}
]
}
},
"channels": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"required": [ "peer_id", "our_amount_msat", "amount_msat", "funding_txid", "funding_output", "connected", "state" ],
"properties": {
"peer_id": {
"type": "pubkey",
"description": "the peer with which the channel is opened"
},
"our_amount_msat": {
"type": "msat",
"description": "available satoshis on our node’s end of the channel"
},
"channel_sat": {
"deprecated": true
},
"amount_msat": {
"type": "msat",
"description": "total channel value"
},
"channel_total_sat": {
"deprecated": true
},
"funding_txid": {
"type": "txid",
"description": "funding transaction id"
},
"funding_output": {
"type": "u32",
"description": "the 0-based index of the output in the funding transaction"
},
"connected": {
"type": "boolean",
"description": "whether the channel peer is connected"
},
"state": {
"type": "string",
"enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ],
"description": "the channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally"
}
},
"allOf": [
{
"if": {
"properties": {
"state": {
"type": "string",
"enum": [ "CHANNELD_NORMAL" ]
}
}
},
"then": {
"additionalProperties": false,
"required": [ "short_channel_id" ],
"properties": {
"peer_id": { },
"our_amount_msat": { },
"channel_sat": { },
"amount_msat": { },
"channel_total_sat": { },
"funding_txid": { },
"funding_output": { },
"connected": { },
"state": { },
"short_channel_id": {
"type": "short_channel_id",
"description": "short channel id of channel"
}
}
}
},
{
"if": {
"properties": {
"state": {
"type": "string",
"enum": [ "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN" ]
}
}
},
"then": {
"additionalProperties": false,
"required": [ ],
"properties": {
"peer_id": { },
"our_amount_msat": { },
"channel_sat": { },
"amount_msat": { },
"channel_total_sat": { },
"funding_txid": { },
"funding_output": { },
"connected": { },
"state": { },
"short_channel_id": {
"type": "short_channel_id",
"description": "short channel id of channel (only if funding reached lockin depth before closing)"
}
}
}
}
]
}
}
}
}