doc/schemas: listfunds

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2025-01-18 05:12:45 +01:00 · 2021-06-16 10:36:17 +09:30 · 2021-06-16 10:36:17 +09:30 · 2296d4452f
commit 2296d4452f
parent 74eeaa8213
3 changed files with 302 additions and 73 deletions
--- 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\.
-
-
-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
--- 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.
+[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)
--- a/doc/schemas/listfunds.schema.json
+++ 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)"
+				}
+			    }
+			}
+		    }
+		]
+	    }
+	}
+    }
+}