diff --git a/doc/lightning-listfunds.7 b/doc/lightning-listfunds.7 index 7d4972294c4a..adf98765f02d 100644 --- a/doc/lightning-listfunds.7 +++ b/doc/lightning-listfunds.7 @@ -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\. +On success, an object is returned, containing: +.RS +.IP \[bu] -Each entry in \fIoutputs\fR will include: +\fBoutputs\fR (array of objects): .RS .IP \[bu] -\fItxid\fR -.IP \[bu] -\fIoutput\fR (the index of the output in the transaction) -.IP \[bu] -\fIvalue\fR (the output value in satoshis) +\fBtxid\fR (txid): the ID of the spendable transaction .IP \[bu] -\fIamount_msat\fR (the same as \fIvalue\fR, but in millisatoshi with \fImsat\fR -appended) +\fBoutput\fR (u32): the index within \fItxid\fR .IP \[bu] -\fIaddress\fR +\fBamount_msat\fR (msat): the amount of the output .IP \[bu] -\fIscriptpubkey\fR (the ScriptPubkey of the output, in hex) +\fBscriptpubkey\fR (hex): the scriptPubkey of the output .IP \[bu] -\fIredeemscript\fR (the redeemscript of the output, in hex, only if it's p2sh-wrapped) +\fBstatus\fR (string) (one of "unconfirmed", "confirmed", "spent") .IP \[bu] -\fIstatus\fR (whether \fIunconfirmed\fR, \fIconfirmed\fR, or \fIspent\fR) +\fBaddress\fR (string, optional): the bitcoin address of the output .IP \[bu] -\fIreserved\fR (whether this is UTXO is currently reserved for an in-flight tx) +\fBredeemscript\fR (hex, optional): the redeemscript, only if it's p2sh-wrapped + +.RE + +If \fBstatus\fR is "confirmed": + +.RS .IP \[bu] -\fIreserved_to_block\fR (when reservation expires, if \fIreserved\fR is true) +\fBblockheight\fR (u32): Block height where it was confirmed .RE -Each entry in \fIchannels\fR will include: +If \fBreserved\fR is "true": .RS .IP \[bu] -\fIpeer_id\fR - the peer with which the channel is opened\. +\fBreserved_to_block\fR (u32): Block height where reservation will expire + +.RE + .IP \[bu] -\fIshort_channel_id\fR - as per BOLT 7 (representing the block, -transaction number and output index of the channel funding -transaction)\. + +\fBchannels\fR (array of objects): + +.RS .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)\. +\fBpeer_id\fR (pubkey): the peer with which the channel is opened .IP \[bu] -\fIour_amount_msat\fR - same as above, but in millisatoshis with -\fImsat\fR appended\. +\fBour_amount_msat\fR (msat): available satoshis on our node’s end of the channel .IP \[bu] -\fIchannel_total_sat\fR - total channel value in satoshi +\fBamount_msat\fR (msat): total channel value .IP \[bu] -\fIamount_msat\fR - same as above, but in millisatoshis with \fImsat\fR -appended\. +\fBfunding_txid\fR (txid): funding transaction id .IP \[bu] -\fIfunding_txid\fR - funding transaction id\. +\fBfunding_output\fR (u32): the 0-based index of the output in the funding transaction .IP \[bu] -\fIfunding_output\fR - the index of the output in the funding -transaction\. +\fBconnected\fR (boolean): whether the channel peer is connected .IP \[bu] -\fIconnected\fR - whether the channel peer is connected\. +\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] -\fIstate\fR - the channel state, in particular \fICHANNELD_NORMAL\fR means the -channel can be used normally\. +\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 is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:d1566362ec4c99ec904f03569ccc99306a42414dc682fd88ca1a3dcb8616de53 +\" SHA256STAMP:499d7e1edccfa0751263e1742c31ca1349922ccc7cd4e6134ff016048be2e0aa diff --git a/doc/lightning-listfunds.7.md b/doc/lightning-listfunds.7.md index 73e788d959f2..5b0903528853 100644 --- a/doc/lightning-listfunds.7.md +++ b/doc/lightning-listfunds.7.md @@ -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. - -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) - -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. +[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 + + If **status** is "confirmed": + - **blockheight** (u32): Block height where it was confirmed + + 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: +[comment]: # ( SHA256STAMP:e8ce919941927237a08bbe84a2e4fbd86d391c6b9d502b85a4c9d1a20a8b2958) diff --git a/doc/schemas/listfunds.schema.json b/doc/schemas/listfunds.schema.json new file mode 100644 index 000000000000..84172c855c95 --- /dev/null +++ b/doc/schemas/listfunds.schema.json @@ -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)" + } + } + } + } + ] + } + } + } +}