From a5e79490afcd2113212ed1221d3b67a6ba1ba195 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Thu, 14 Dec 2023 19:23:05 -0800 Subject: [PATCH] Updated Scripts --- doc/lightning-bkpr-listbalances.7.md | 6 +- doc/lightning-checkrune.7.md | 7 +- doc/lightning-commando.7.md | 3 + doc/lightning-decode.7.md | 7 +- doc/lightning-decodepay.7.md | 5 +- doc/lightning-deldatastore.7.md | 3 + doc/lightning-delpay.7.md | 1 + doc/lightning-emergencyrecover.7.md | 15 +-- doc/lightning-fetchinvoice.7.md | 26 ---- doc/lightning-fundchannel.7.md | 90 +++----------- doc/lightning-funderupdate.7.md | 94 ++++----------- doc/schemas/commando.schema.json | 12 ++ doc/schemas/delforward.request.json | 2 +- doc/schemas/emergencyrecover.schema.json | 2 +- doc/schemas/fetchinvoice.request.json | 14 +-- doc/schemas/fundchannel.request.json | 29 +++-- doc/schemas/funderupdate.request.json | 18 +-- tools/fromschema.py | 79 ++++++------ tools/merge.py | 147 ++++++++++++++++++++--- 19 files changed, 282 insertions(+), 278 deletions(-) create mode 100644 doc/schemas/commando.schema.json diff --git a/doc/lightning-bkpr-listbalances.7.md b/doc/lightning-bkpr-listbalances.7.md index efac73eb456f..835510193881 100644 --- a/doc/lightning-bkpr-listbalances.7.md +++ b/doc/lightning-bkpr-listbalances.7.md @@ -9,11 +9,9 @@ SYNOPSIS DESCRIPTION ----------- -The **bkpr-listbalances** RPC command is a list of all current and historical account balances. An account is either the on-chain *wallet* or a channel balance. -Any funds sent to an *external* account will not be accounted for here. +The **bkpr-listbalances** RPC command is a list of all current and historical account balances. An account is either the on-chain *wallet* or a channel balance. Any funds sent to an *external* account will not be accounted for here. -Note that any channel that was recorded will be listed. Closed channel balances -will be 0msat. +Note that any channel that was recorded will be listed. Closed channel balances will be 0msat. RETURN VALUE ------------ diff --git a/doc/lightning-checkrune.7.md b/doc/lightning-checkrune.7.md index 90cc1e4a30e6..48e6210c0eb9 100644 --- a/doc/lightning-checkrune.7.md +++ b/doc/lightning-checkrune.7.md @@ -25,6 +25,9 @@ On success, an object is returned, containing: [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ + The following error codes may occur: - RUNE\_NOT\_AUTHORIZED (1501): rune is not for this node (or perhaps completely invalid) @@ -34,8 +37,7 @@ The following error codes may occur: AUTHOR ------ -Shahana Farooqui <> is mainly responsible -for consolidating logic from commando. +Shahana Farooqui <> is mainly responsible for consolidating logic from commando. SEE ALSO -------- @@ -46,4 +48,5 @@ RESOURCES --------- Main web site: + [comment]: # ( SHA256STAMP:977acf366f8fde1411f2c78d072b34b38b456e95381a6bce8fe6855a2d91434a) diff --git a/doc/lightning-commando.7.md b/doc/lightning-commando.7.md index 97a90990b69a..450e06abb226 100644 --- a/doc/lightning-commando.7.md +++ b/doc/lightning-commando.7.md @@ -18,8 +18,11 @@ provided you with a *rune* which allows it. RETURN VALUE ------------ +[comment]: # (GENERATE-FROM-SCHEMA-START) On success, the return depends on the *method* invoked. +[comment]: # (GENERATE-FROM-SCHEMA-END) + ERRORS ------ diff --git a/doc/lightning-decode.7.md b/doc/lightning-decode.7.md index e44918a0de3a..1883e6760d08 100644 --- a/doc/lightning-decode.7.md +++ b/doc/lightning-decode.7.md @@ -300,14 +300,13 @@ SEE ALSO lightning-pay(7), lightning-offer(7), lightning-fetchinvoice(7), lightning-sendinvoice(7), lightning-commando-rune(7) +RESOURCES +--------- + [BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) [BOLT #12](https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md) (experimental, [bolt](https://github.com/lightning/bolts) #798) - -RESOURCES ---------- - Main web site: [comment]: # ( SHA256STAMP:d62327dbe56d27e5e82d5ad2599d3d88495cc8360d84ff02fca59d08ab7fa14e) diff --git a/doc/lightning-decodepay.7.md b/doc/lightning-decodepay.7.md index bcc5e18a456a..d6667a3bff75 100644 --- a/doc/lightning-decodepay.7.md +++ b/doc/lightning-decodepay.7.md @@ -63,12 +63,11 @@ SEE ALSO lightning-pay(7), lightning-getroute(7), lightning-sendpay(7). -[BOLT -\#11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md). - RESOURCES --------- +[BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) + Main web site: [comment]: # ( SHA256STAMP:14c7dd565178078d7073e2837ad283a1e811affb5017e72c69e69d9f8c2baabd) diff --git a/doc/lightning-deldatastore.7.md b/doc/lightning-deldatastore.7.md index b6df33e833fb..9d05a846127a 100644 --- a/doc/lightning-deldatastore.7.md +++ b/doc/lightning-deldatastore.7.md @@ -29,6 +29,9 @@ On success, an object is returned, containing: [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ + The following error codes may occur: - 1200: the key does not exist diff --git a/doc/lightning-delpay.7.md b/doc/lightning-delpay.7.md index 13ea67e0fdee..5bfc7b18c7dd 100644 --- a/doc/lightning-delpay.7.md +++ b/doc/lightning-delpay.7.md @@ -32,6 +32,7 @@ EXAMPLE JSON REQUEST } ``` + RETURN VALUE ------------ diff --git a/doc/lightning-emergencyrecover.7.md b/doc/lightning-emergencyrecover.7.md index 31af839ffda3..354f9adf8b87 100644 --- a/doc/lightning-emergencyrecover.7.md +++ b/doc/lightning-emergencyrecover.7.md @@ -9,22 +9,17 @@ SYNOPSIS DESCRIPTION ----------- -The **emergencyrecover** RPC command fetches data from the emergency.recover -file and tries to reconnect to the peer and force him to close the channel. -The data in this file has enough information to reconnect and sweep the funds. +The **emergencyrecover** RPC command fetches data from the emergency.recover file and tries to reconnect to the peer and force him to close the channel. The data in this file has enough information to reconnect and sweep the funds. -This recovery method is not spontaneous and it depends on the peer, so it should -be used as a last resort to recover the funds stored in a channel in case of severe -data loss. +This recovery method is not spontaneous and it depends on the peer, so it should be used as a last resort to recover the funds stored in a channel in case of severe data loss. RETURN VALUE ------------ On success, an object is returned, containing: -- **stubs** (array of hexs): - - Each item is the channel ID of the channel successfully inserted - +- **stubs** (array of strings) + - Channel IDs of channels successfully inserted. AUTHOR ------ @@ -41,4 +36,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:9cfaa9eb4609b36accc3e3b12a352c00ddd402307e4461f4df274146d12f6eb0) +[comment]: # ( SHA256STAMP:678c253c9bbd957d0d7f458d4697a66cad4cd7dc4c64b5f650e0e6a1c32d4c9f) diff --git a/doc/lightning-fetchinvoice.7.md b/doc/lightning-fetchinvoice.7.md index 1dcce81c2257..cc3f00c6beae 100644 --- a/doc/lightning-fetchinvoice.7.md +++ b/doc/lightning-fetchinvoice.7.md @@ -19,32 +19,6 @@ If **fetchinvoice-noconnect** is not specified in the configuation, it will connect to the destination in the (currently common!) case where it cannot find a route which supports `option_onion_messages`. -*amount\_msat* is required if the *offer* does not specify an amount -at all, otherwise it is optional (but presumably if you set it to less -than the offer, you will get an error from the issuer). - -*quantity* is is required if the *offer* specifies -*quantity\_max*, otherwise it is not allowed. - -*recurrence\_counter* is required if the *offer* -specifies *recurrence*, otherwise it is not allowed. -*recurrence\_counter* should first be set to 0, and incremented for -each successive invoice in a given series. - -*recurrence\_start* is required if the *offer* -specifies *recurrence\_base* with *start\_any\_period* set, otherwise it -is not allowed. It indicates what period number to start at. - -*recurrence\_label* is required if *recurrence\_counter* is set, and -otherwise is not allowed. It must be the same as prior fetchinvoice -calls for the same recurrence, as it is used to link them together. - -*timeout* is an optional timeout; if we don't get a reply before this -we fail (default, 60 seconds). - -*payer\_note* is an optional payer note to ask the issuer to include -in the fetched invoice. - RETURN VALUE ------------ diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md index 3493ffd9b5d3..b97a1497378f 100644 --- a/doc/lightning-fundchannel.7.md +++ b/doc/lightning-fundchannel.7.md @@ -4,75 +4,23 @@ lightning-fundchannel -- Command for establishing a lightning channel SYNOPSIS -------- -**fundchannel** *id* *amount* [*feerate*] [*announce*] [*minconf*] -[*utxos*] [*push\_msat*] [*close\_to*] [*request\_amt*] [*compact\_lease*] -[*reserve*] +**fundchannel** *id* *amount* [*feerate*] [*announce*] [*minconf*] [*push_msat*] [*close_to*] [*request_amt*] [*compact_lease*] [*utxos*] [*mindepth*] [*reserve*] DESCRIPTION ----------- -The **fundchannel** RPC command opens a payment channel with a peer by -committing a funding transaction to the blockchain as defined in BOLT -\#2. -If not already connected, **fundchannel** will automatically attempt -to connect if C-lightning knows a way to contact the node (either from -normal gossip, or from a previous **connect** call). -This auto-connection can fail if C-lightning does not know how to contact -the target node; see lightning-connect(7). -Once the -transaction is confirmed, normal channel operations may begin. Readiness -is indicated by **listpeers** reporting a *state* of `CHANNELD_NORMAL` -for the channel. - -*id* is the peer id obtained from **connect**. - -*amount* is the amount in satoshis taken from the internal wallet to -fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). The string *all* can be used to specify all available -funds (or 16777215 satoshi if more is available and large channels were not negotiated with the peer). Otherwise, it is in -satoshi precision; it can be a whole number, a whole number ending in -*sat*, a whole number ending in *000msat*, or a number with 1 to 8 -decimal places ending in *btc*. The value cannot be less than the dust -limit, currently set to 546, nor more than 16777215 satoshi (unless large -channels were negotiated with the peer). - -*feerate* is an optional feerate used for the opening transaction and -(unless *option\_anchors\_zero\_fee\_htlc\_tx* is negotiated), as initial feerate -for commitment and HTLC transactions (see NOTES in lightning-feerates(7)). -The default is *normal*. - -*announce* is an optional flag that triggers whether to announce this -channel or not. Defaults to `true`. An unannounced channel is considered -private. - -*minconf* specifies the minimum number of confirmations that used -outputs should have. Default is 1. - -*utxos* specifies the utxos to be used to fund the channel, as an array -of "txid:vout". - -*push\_msat* is the amount of millisatoshis to push to the channel peer at -open. Note that this is a gift to the peer -- these satoshis are -added to the initial balance of the peer at channel start and are largely -unrecoverable once pushed. - -*close\_to* is a Bitcoin address to which the channel funds should be sent to -on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`. -Returns `close_to` set to closing script iff is negotiated. - -*request\_amt* is an amount of liquidity you'd like to lease from the peer. -If peer supports `option_will_fund`, indicates to them to include this -much liquidity into the channel. Must also pass in *compact\_lease*. - -*compact\_lease* is a compact represenation of the peer's expected -channel lease terms. If the peer's terms don't match this set, we will -fail to open the channel. - -*reserve* is the amount we want the peer to maintain on its side of the channel. -Default is 1% of the funding amount. It can be a whole number, a whole number -ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 -decimal places ending in *btc*. +The **fundchannel** RPC command opens a payment channel with a peer by committing a +funding transaction to the blockchain as defined in BOLT #2. +If not already connected, **fundchannel** will automatically attempt to connect if +Core Lightning knows a way to contact the node (either from normal gossip, or from +a previous **connect** call). +This auto-connection can fail if Core Lightning does not know how to contact the +target node; see lightning-connect(7). + +Once the transaction is confirmed, normal channel operations may begin. Readiness +is indicated by **listpeers** reporting a *state* of `CHANNELD_NORMAL` for the channel. This example shows how to use lightning-cli to open new channel with peer 03f...fc1 from one whole utxo bcc1...39c:0 (you can use **listfunds** command to get txid and vout): @@ -82,17 +30,17 @@ This example shows how to use lightning-cli to open new channel with peer 03f... RETURN VALUE ------------ -[comment]: # (GENERATE-FROM-SCHEMA-START) On success, an object is returned, containing: - **tx** (hex): The raw transaction which funded the channel - **txid** (txid): The txid of the transaction which funded the channel - **outnum** (u32): The 0-based output index showing which output funded the channel -- **channel\_id** (hex): The channel\_id of the resulting channel (always 64 characters) -- **close\_to** (hex, optional): The raw scriptPubkey which mutual close will go to; only present if *close\_to* parameter was specified and peer supports `option_upfront_shutdown_script` +- **channel_id** (hex): The channel_id of the resulting channel (always 64 characters) +- **close_to** (hex, optional): The raw scriptPubkey which mutual close will go to; only present if *close_to* parameter was specified and peer supports `option_upfront_shutdown_script` - **mindepth** (u32, optional): Number of confirmations before we consider the channel active. -[comment]: # (GENERATE-FROM-SCHEMA-END) +ERROR +------ The following error codes may occur: @@ -103,18 +51,16 @@ The following error codes may occur: - 303: Broadcasting of the funding transaction failed, the internal call to bitcoin-cli returned with an error. - 313: The `min-emergency-msat` reserve not be preserved (and we have or are opening anchor channels). -Failure may also occur if **lightningd** and the peer cannot agree on -channel parameters (funding limits, channel reserves, fees, etc.). +Failure may also occur if **lightningd** and the peer cannot agree on channel parameters (funding limits, channel reserves, fees, etc.). SEE ALSO -------- -lightning-connect(7), lightning-listfunds(), lightning-listpeers(7), -lightning-feerates(7), lightning-multifundchannel(7) +lightning-connect(7), lightning-listfunds(), lightning-listpeers(7),lightning-feerates(7), lightning-multifundchannel(7) RESOURCES --------- Main web site: -[comment]: # ( SHA256STAMP:a8329cdb3f13f5bd0047824bed82c2e10516af2735dc59aa2cd71e4cc4f0250a) +[comment]: # ( SHA256STAMP:8f80263a6a56f45168d90a73ed72735ae53dbc7db64729aa38117959d8dfb54c) diff --git a/doc/lightning-funderupdate.7.md b/doc/lightning-funderupdate.7.md index 318d836c3b23..cdb7670e8350 100644 --- a/doc/lightning-funderupdate.7.md +++ b/doc/lightning-funderupdate.7.md @@ -4,7 +4,7 @@ lightning-funderupdate -- Command for adjusting node funding v2 channels SYNOPSIS -------- -**funderupdate** [*policy*] [*policy\_mod*] [*leases\_only*] [*min\_their\_funding\_msat*] [*max\_their\_funding\_msat*] [*per\_channel\_min\_msat*] [*per\_channel\_max\_msat*] [*reserve\_tank\_msat*] [*fuzz\_percent*] [*fund\_probability*] [*lease\_fee\_base\_msat*] [*lease\_fee\_basis*] [*funding\_weight*] [*channel\_fee\_max\_base\_msat*] [*channel\_fee\_max\_proportional\_thousandths*] [*compact\_lease*] +**funderupdate** [*policy*] [*policy_mod*] [*leases_only*] [*min_their_funding_msat*] [*max_their_funding_msat*] [*per_channel_min_msat*] [*per_channel_max_msat*] [*reserve_tank_msat*] [*fuzz_percent*] [*fund_probability*] [*lease_fee_base_msat*] [*lease_fee_basis*] [*funding_weight*] [*channel_fee_max_base_msat*] [*channel_fee_max_proportional_thousandths*] [*compact_lease*] DESCRIPTION ----------- @@ -15,67 +15,19 @@ For channel open requests using dual funding. There are three policy options, detailed below: -* `match` -- Contribute *policy\_mod* percent of their requested funds. - Valid *policy\_mod* values are 0 to 200. If this is a channel lease +* `match` -- Contribute *policy_mod* percent of their requested funds. + Valid *policy_mod* values are 0 to 200. If this is a channel lease request, we match based on their requested funds. If it is not a - channel lease request (and *lease\_only* is false), then we match + channel lease request (and *lease_only* is false), then we match their funding amount. Note: any lease match less than 100 will likely fail, as clients will not accept a lease less than their request. -* `available` -- Contribute *policy\_mod* percent of our available - node wallet funds. Valid *policy\_mod* values are 0 to 100. -* `fixed` -- Contributes a fixed *policy\_mod* sats to v2 channel open requests. +* `available` -- Contribute *policy_mod* percent of our available + node wallet funds. Valid *policy_mod* values are 0 to 100. +* `fixed` -- Contributes a fixed *policy_mod* sats to v2 channel open requests. Note: to maximize channel leases, best policy setting is (match, 100). -*leases\_only* will only contribute funds to `option_will_fund` requests -which pay to lease funds. It will fund any v2 open request -using *policy* even if it's they're not seeking to lease funds. Note that -`option_will_fund` commits funds for 4032 blocks (~1mo). Must also set -*lease\_fee\_base\_msat*, *lease\_fee\_basis*, *funding\_weight*, -*channel\_fee\_max\_base\_msat*, and *channel\_fee\_max\_proportional\_thousandths* -to advertise available channel leases. - -*fuzz\_percent* is a percentage to fuzz the resulting contribution amount by. -Valid values are 0 to 100. Note that turning this on with (match, 100) policy -will randomly fail `option_will_fund` leases, as most clients -expect an exact or greater match of their `requested_funds`. - -*fund\_probability* is the percent of v2 channel open requests to apply our -policy to. Valid values are integers from 0 (fund 0% of all open requests) -to 100 (fund every request). Useful for randomizing opens that receive funds. - -Setting any of the next 5 options will activate channel leases for this node, -and advertise these values via the lightning gossip network. If any one is set, -the other values will be the default. - -*lease\_fee\_base\_msat* is the flat fee for a channel lease. Node will -receive this much extra added to their channel balance, paid by the opening -node. - -*lease\_fee\_basis* is a basis fee that's calculated as 1/10k of the total -requested funds the peer is asking for. Node will receive the total of -*lease\_fee\_basis* times requested funds / 10k satoshis added to their channel -balance, paid by the opening node. - -*funding\_weight* is used to calculate the fee the peer will compensate your -node for its contributing inputs to the funding transaction. The total fee -is calculated as the `open_channel2`.`funding_feerate_perkw` times this -*funding\_weight* divided by 1000. Node will have this funding fee added -to their channel balance, paid by the opening node. - -*channel\_fee\_max\_base\_msat* is a commitment to a maximum -`channel_fee_base_msat` that your node will charge for routing payments -over this leased channel during the lease duration. - -*channel\_fee\_max\_proportional\_thousandths* is a commitment to a maximum -`channel_fee_proportional_millionths` that your node will charge for -routing payments over this leased channel during the lease duration. -Note that it's denominated in 'thousandths'. A setting of `1` is equal -to 1k ppm; `5` is 5k ppm, etc. - -*compact\_lease* is a compact description of the channel lease params. When -opening a channel, passed in to `fundchannel` to indicate the terms we -expect from the peer. +Setting any of the 5 options from *lease_fee_base_msat*, *lease_fee_basis*, *funding_weight*, *channel_fee_max_base_msat* and, *channel_fee_max_proportional_thousandths* will activate channel leases for this node, and advertise these values via the lightning gossip network. If any one is set, the other values will be the default. RETURN VALUE ------------ @@ -85,21 +37,21 @@ On success, an object is returned, containing: - **summary** (string): Summary of the current funding policy e.g. (match 100) - **policy** (string): Policy funder plugin will use to decide how much captial to commit to a v2 open channel request (one of "match", "available", "fixed") -- **policy\_mod** (u32): The *policy\_mod* is the number or 'modification' to apply to the policy. -- **leases\_only** (boolean): Only contribute funds to `option_will_fund` lease requests. -- **min\_their\_funding\_msat** (msat): The minimum funding sats that we require from peer to activate our funding policy. -- **max\_their\_funding\_msat** (msat): The maximum funding sats that we'll allow from peer to activate our funding policy. -- **per\_channel\_min\_msat** (msat): The minimum amount that we will fund a channel open with. -- **per\_channel\_max\_msat** (msat): The maximum amount that we will fund a channel open with. -- **reserve\_tank\_msat** (msat): Amount of sats to leave available in the node wallet. -- **fuzz\_percent** (u32): Percentage to fuzz our funding amount by. -- **fund\_probability** (u32): Percent of opens to consider funding. 100 means we'll consider funding every requested open channel request. -- **lease\_fee\_base\_msat** (msat, optional): Flat fee to charge for a channel lease. -- **lease\_fee\_basis** (u32, optional): Proportional fee to charge for a channel lease, calculated as 1/10,000th of requested funds. -- **funding\_weight** (u32, optional): Transaction weight the channel opener will pay us for a leased funding transaction. -- **channel\_fee\_max\_base\_msat** (msat, optional): Maximum channel\_fee\_base\_msat we'll charge for routing funds leased on this channel. -- **channel\_fee\_max\_proportional\_thousandths** (u32, optional): Maximum channel\_fee\_proportional\_millitionths we'll charge for routing funds leased on this channel, in thousandths. -- **compact\_lease** (hex, optional): Compact description of the channel lease parameters. +- **policy_mod** (u32): The *policy_mod* is the number or 'modification' to apply to the policy. +- **leases_only** (boolean): Only contribute funds to `option_will_fund` lease requests. +- **min_their_funding_msat** (msat): The minimum funding sats that we require from peer to activate our funding policy. +- **max_their_funding_msat** (msat): The maximum funding sats that we'll allow from peer to activate our funding policy. +- **per_channel_min_msat** (msat): The minimum amount that we will fund a channel open with. +- **per_channel_max_msat** (msat): The maximum amount that we will fund a channel open with. +- **reserve_tank_msat** (msat): Amount of sats to leave available in the node wallet. +- **fuzz_percent** (u32): Percentage to fuzz our funding amount by. +- **fund_probability** (u32): Percent of opens to consider funding. 100 means we'll consider funding every requested open channel request. +- **lease_fee_base_msat** (msat, optional): Flat fee to charge for a channel lease. +- **lease_fee_basis** (u32, optional): Proportional fee to charge for a channel lease, calculated as 1/10,000th of requested funds. +- **funding_weight** (u32, optional): Transaction weight the channel opener will pay us for a leased funding transaction. +- **channel_fee_max_base_msat** (msat, optional): Maximum channel_fee_base_msat we'll charge for routing funds leased on this channel. +- **channel_fee_max_proportional_thousandths** (u32, optional): Maximum channel_fee_proportional_millitionths we'll charge for routing funds leased on this channel, in thousandths. +- **compact_lease** (hex, optional): Compact description of the channel lease parameters. [comment]: # (GENERATE-FROM-SCHEMA-END) diff --git a/doc/schemas/commando.schema.json b/doc/schemas/commando.schema.json new file mode 100644 index 000000000000..dd8cbd873345 --- /dev/null +++ b/doc/schemas/commando.schema.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "any": { + "type": "object", + "description": "the return depends on the *method* invoked" + } + } +} diff --git a/doc/schemas/delforward.request.json b/doc/schemas/delforward.request.json index 163c79909af6..265d78195d46 100644 --- a/doc/schemas/delforward.request.json +++ b/doc/schemas/delforward.request.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", - "required": [], + "required": ["in_channel", "in_htlc_id", "status"], "properties": { "in_channel": { "type": "short_channel_id" diff --git a/doc/schemas/emergencyrecover.schema.json b/doc/schemas/emergencyrecover.schema.json index 127dfbc6bf43..17c3e64383c8 100644 --- a/doc/schemas/emergencyrecover.schema.json +++ b/doc/schemas/emergencyrecover.schema.json @@ -9,7 +9,7 @@ "stubs": { "type": "array", "items": { - "type": "string", + "type": "hex", "description": "Channel IDs of channels successfully inserted." } } diff --git a/doc/schemas/fetchinvoice.request.json b/doc/schemas/fetchinvoice.request.json index d3f293d4ab61..5558c0725cf4 100644 --- a/doc/schemas/fetchinvoice.request.json +++ b/doc/schemas/fetchinvoice.request.json @@ -12,31 +12,31 @@ }, "amount_msat": { "type": "msat", - "description": "amount_msat is required if the offer does not specify an amount at all, otherwise it is optional (but presumably if you set it to less than the offer, you will get an error from the issuer)." + "description": "required if the offer does not specify an amount at all, otherwise it is optional (but presumably if you set it to less than the offer, you will get an error from the issuer)" }, "quantity": { "type": "u64", - "description": "quantity is is required if the offer specifies quantity_max, otherwise it is not allowed." + "description": "required if the offer specifies quantity_max, otherwise it is not allowed" }, "recurrence_counter": { "type": "u64", - "description": "recurrence_counter is required if the offer specifies recurrence, otherwise it is not allowed. recurrence_counter should first be set to 0, and incremented for each successive invoice in a given series." + "description": "required if the offer specifies recurrence, otherwise it is not allowed. recurrence_counter should first be set to 0, and incremented for each successive invoice in a given series" }, "recurrence_start": { "type": "number", - "description": "recurrence_start is required if the offer specifies recurrence_base with start_any_period set, otherwise it is not allowed. It indicates what period number to start at." + "description": "required if the offer specifies recurrence_base with start_any_period set, otherwise it is not allowed. It indicates what period number to start at" }, "recurrence_label": { "type": "string", - "description": "recurrence_label is required if recurrence_counter is set, and otherwise is not allowed. It must be the same as prior fetchinvoice calls for the same recurrence, as it is used to link them together." + "description": "required if recurrence_counter is set, and otherwise is not allowed. It must be the same as prior fetchinvoice calls for the same recurrence, as it is used to link them together" }, "timeout": { "type": "number", - "description": "timeout is an optional timeout; if we don't get a reply before this we fail (default, 60 seconds)." + "description": "if we don't get a reply before this we fail (default, 60 seconds)" }, "payer_note": { "type": "string", - "description": "payer_note is an optional payer note to ask the issuer to include in the fetched invoice." + "description": "to ask the issuer to include in the fetched invoice" } } } diff --git a/doc/schemas/fundchannel.request.json b/doc/schemas/fundchannel.request.json index bc4b44a4e152..ff080bac1c5f 100644 --- a/doc/schemas/fundchannel.request.json +++ b/doc/schemas/fundchannel.request.json @@ -9,34 +9,43 @@ "properties": { "id": { "type": "pubkey", - "description": "id is the peer id obtained from connect." + "description": "id is the peer id obtained from connect" }, "amount": { - "type": "msat_or_all" + "type": "msat_or_all", + "description": "the amount in satoshis taken from the internal wallet to fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). The string *all* can be used to specify all available funds (or 16777215 satoshi if more is available and large channels were not negotiated with the peer). Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*. The value cannot be less than the dust limit, currently set to 546, nor more than 16777215 satoshi (unless large channels were negotiated with the peer)" }, "feerate": { - "type": "feerate" + "type": "feerate", + "description": "used for the opening transaction and (unless *option_anchors_zero_fee_htlc_tx* is negotiated), as initial feerate for commitment and HTLC transactions (see NOTES in lightning-feerates(7)). The default is *normal*" }, "announce": { - "type": "boolean" + "type": "boolean", + "description": "whether to announce this channel or not. An unannounced channel is considered private. Defaults to *True*" }, "minconf": { - "type": "u32" + "type": "u32", + "description": "the minimum number of confirmations that used outputs should have. Default is 1" }, "push_msat": { - "type": "msat" + "type": "msat", + "description": "the amount of millisatoshis to push to the channel peer at open. Note that this is a gift to the peer -- these satoshis are added to the initial balance of the peer at channel start and are largely unrecoverable once pushed" }, "close_to": { - "type": "string" + "type": "string", + "description": "a Bitcoin address to which the channel funds should be sent to on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`. Returns `close_to` set to closing script iff is negotiated" }, "request_amt": { - "type": "msat" + "type": "msat", + "description": "an amount of liquidity you'd like to lease from the peer. If peer supports `option_will_fund`, indicates to them to include this much liquidity into the channel. Must also pass in *compact_lease*" }, "compact_lease": { - "type": "string" + "type": "string", + "description": "a compact represenation of the peer's expected channel lease terms. If the peer's terms don't match this set, we will fail to open the channel" }, "utxos": { "type": "array", + "description": "the utxos to be used to fund the channel, as an array of `txid:vout`", "items": { "type": "outpoint" } @@ -47,7 +56,7 @@ }, "reserve": { "type": "msat", - "description": "The amount we want the peer to maintain on its side" + "description": "the amount we want the peer to maintain on its side of the channel. Default is 1% of the funding amount. It can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*" } } } diff --git a/doc/schemas/funderupdate.request.json b/doc/schemas/funderupdate.request.json index ba5b9b8b0162..af7fd904bacd 100644 --- a/doc/schemas/funderupdate.request.json +++ b/doc/schemas/funderupdate.request.json @@ -19,7 +19,7 @@ }, "leases_only": { "type": "boolean", - "description": "only contribute funds to `option_will_fund` lease requests. Defaults to false" + "description": "only contribute funds to `option_will_fund` requests which pay to lease funds. It will fund any v2 open request using *policy* even if it's they're not seeking to lease funds. Note that `option_will_fund` commits funds for 4032 blocks (~1mo). Must also set *lease_fee_base_msat*, *lease_fee_basis*, *funding_weight*, *channel_fee_max_base_msat*, and *channel_fee_max_proportional_thousandths* to advertise available channel leases. Defaults to *False*" }, "min_their_funding_msat": { "type": "msat", @@ -43,35 +43,35 @@ }, "fuzz_percent": { "type": "u32", - "description": "percentage to fuzz our funding amount by. Defaults to 0% (no fuzz)" + "description": "a percentage to fuzz the resulting contribution amount by. Valid values are 0 to 100. Note that turning this on with (match, 100) policy will randomly fail `option_will_fund` leases, as most clients expect an exact or greater match of their `requested_funds`. Defaults to 0% (no fuzz)" }, "fund_probability": { "type": "u32", - "description": "percent of opens to consider funding. 100 means we'll consider funding every requested open channel request. Defaults to 100" + "description": "the percent of v2 channel open requests to apply our policy to. Valid values are integers from 0 (fund 0% of all open requests) to 100 (fund every request). Useful for randomizing opens that receive funds. Useful for randomizing opens that receive funds. Defaults to 100" }, "lease_fee_base_msat": { "type": "msat", - "description": "flat fee to charge for a channel lease. Defaults to 2k sats. Note that the minimum is 1sat." + "description": "flat fee for a channel lease. Node will receive this much extra added to their channel balance, paid by the opening node. Defaults to 2k sats. Note that the minimum is 1sat." }, "lease_fee_basis": { "type": "u32", - "description": "proportional fee to charge for a channel lease, calculated as 1/10,000th of requested funds. Default is 0.65% (65 basis points)" + "description": "a basis fee that's calculated as 1/10k of the total requested funds the peer is asking for. Node will receive the total of *lease_fee_basis* times requested funds / 10k satoshis added to their channel balance, paid by the opening node. Default is 0.65% (65 basis points)" }, "funding_weight": { "type": "u32", - "description": "transaction weight the channel opener will pay us for a leased funding transaction. Default is 2 inputs + 1 P2WPKH output." + "description": "to calculate the fee the peer will compensate your node for its contributing inputs to the funding transaction. The total fee is calculated as the `open_channel2`.`funding_feerate_perkw` times this *funding_weight* divided by 1000. Node will have this funding fee added to their channel balance, paid by the opening node. Default is 2 inputs + 1 P2WPKH output." }, "channel_fee_max_base_msat": { "type": "msat", - "description": "maximum channel_fee_base_msat we'll charge for routing funds leased on this channel. Default is 5k sats" + "description": "a commitment to a maximum `channel_fee_base_msat` that your node will charge for routing payments over this leased channel during the lease duration. Default is 5k sats" }, "channel_fee_max_proportional_thousandths": { "type": "u32", - "description": "maximum channel_fee_proportional_millitionths we'll charge for routing funds leased on this channel, in thousandths. Default is 100 (100k ppm)" + "description": "a commitment to a maximum `channel_fee_proportional_millionths` that your node will charge for routing payments over this leased channel during the lease duration. Note that it's denominated in 'thousandths'. A setting of `1` is equal to 1k ppm; `5` is 5k ppm, etc. Default is 100 (100k ppm)" }, "compact_lease": { "type": "hex", - "description": "compact description of the channel lease parameters" + "description": "a compact description of the channel lease params. When opening a channel, passed in to `fundchannel` to indicate the terms we expect from the peer" } } } \ No newline at end of file diff --git a/tools/fromschema.py b/tools/fromschema.py index 196df561507f..0734611fba0e 100755 --- a/tools/fromschema.py +++ b/tools/fromschema.py @@ -288,37 +288,6 @@ def output_params(schema): output("\n") -def generate_from_request(schema): - props = schema["request"]["properties"] - toplevels = list(props.keys()) - indent="" - - output_title("SYNOPSIS") - output_params(schema) - - if len(schema["request"]["properties"]) > 0: - output_title("METHOD PARAMETERS") - if toplevels == []: - sub = schema["request"] - elif len(toplevels) == 1 and "oneOf" in props[toplevels[0]] and isinstance(props[toplevels[0]]["oneOf"], list): - output("{}".format(fmt_propname(toplevels[0]))) - output_type(props[toplevels[0]], False if toplevels[0] in schema["request"]["required"] else True) - output("\n") - indent = indent + " " - sub = props[toplevels[0]] - elif len(toplevels) == 1 and props[toplevels[0]]["type"] == "object": - output("{}\n".format(fmt_propname(toplevels[0]))) - assert "description" not in toplevels[0] - sub = props[toplevels[0]] - elif len(toplevels) == 1 and props[toplevels[0]]["type"] == "array" and props[toplevels[0]]["items"]["type"] == "object": - output("{}\n".format(fmt_propname(toplevels[0]))) - assert "description" not in toplevels[0] - sub = props[toplevels[0]]["items"] - else: - sub = schema["request"] - output_members(sub, indent) - - def generate_from_response(schema): """This is not general, but works for us""" output_title("RETURN VALUE") @@ -374,20 +343,28 @@ def generate_from_response(schema): outputs(["\n", "The following warnings may also be returned:\n\n"]) for w, desc in warnings: output("- {}: {}".format(fmt_propname(w), desc)) + output("\n") if "post_return_value_notes" in response: if warnings: - output("\n\n") + output("\n") outputs(response["post_return_value_notes"], "\n") + output("\n") def generate_header(schema): output_title("".join(["lightning-", schema["rpc"], " -- ", schema["title"]]), "=", 0, 1) + output_title("SYNOPSIS") + output_params(schema) -def generate_request_details(schema): +def generate_from_request(schema): request = schema["request"] request_key_list = [key for key in list(request.keys()) if key not in ['required', 'properties']] + props = request["properties"] + toplevels = list(props.keys()) + indent="" + for key in request_key_list: output_title(key.replace("_", " ").upper()) if key == "description": @@ -395,17 +372,40 @@ def generate_request_details(schema): output("Command **deprecated, removal in {}**.\n\n".format(deprecated_to_deleted(schema["deprecated"]))) if "added" in schema: output("Command *added* in {}.\n\n".format(schema["added"])) - outputs(request[key], "\n") - # Add single newline after the section - output("\n") + outputs(request[key], "\n") + if len(props) > 0: + output("\n\n") + if toplevels == []: + sub = schema["request"] + elif len(toplevels) == 1 and "oneOf" in props[toplevels[0]] and isinstance(props[toplevels[0]]["oneOf"], list): + output("{}".format(fmt_propname(toplevels[0]))) + output_type(props[toplevels[0]], False if toplevels[0] in schema["request"]["required"] else True) + output("\n") + indent = indent + " " + sub = props[toplevels[0]] + elif len(toplevels) == 1 and props[toplevels[0]]["type"] == "object": + output("{}\n".format(fmt_propname(toplevels[0]))) + assert "description" not in toplevels[0] + sub = props[toplevels[0]] + elif len(toplevels) == 1 and props[toplevels[0]]["type"] == "array" and props[toplevels[0]]["items"]["type"] == "object": + output("{}\n".format(fmt_propname(toplevels[0]))) + assert "description" not in toplevels[0] + sub = props[toplevels[0]]["items"] + else: + sub = schema["request"] + output_members(sub, indent) + else: + output("\n") + else: + outputs(request[key], "\n") def generate_footer(schema): keys = list(schema.keys()) footer_key_list = [key for key in keys if key not in ['$schema', 'type', 'additionalProperties', 'rpc', 'title', 'request', 'response', 'added', 'deprecated']] - for key in footer_key_list: - output_title(key.replace("_", " ").upper(), "-", 2) + for i, key in enumerate(footer_key_list): + output_title(key.replace("_", " ").upper(), "-", 1 if i == 0 else 2) outputs(schema[key], ", " if key in ['categories', 'see_also'] else "\n") - output("Main web site: \n\n") + output("\n\n") def main(schemafile, markdownfile): @@ -413,7 +413,6 @@ def main(schemafile, markdownfile): schema = json.load(f) generate_header(schema) generate_from_request(schema) - generate_request_details(schema) generate_from_response(schema) generate_footer(schema) diff --git a/tools/merge.py b/tools/merge.py index d88b36780032..2a8ccb00e14d 100644 --- a/tools/merge.py +++ b/tools/merge.py @@ -3,23 +3,127 @@ # Input folder containing JSON files input_folder = "/home/shahana/workspace/lightning/doc/" -raw_request_date = { - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "additionalProperties": False, - "required": [], - "properties": {} -} -# Process all files in the input folder -for root, _, files in os.walk(os.path.join(input_folder, "schemas")): - # Group request and schema files with the same name - grouped_files = [] - for file in files: - if file.endswith(".schema.json"): - base_name = file[:-12] - if base_name not in grouped_files: - grouped_files.append(base_name) +# raw_request_date = { +# "$schema": "http://json-schema.org/draft-07/schema#", +# "type": "object", +# "additionalProperties": False, +# "required": [], +# "properties": {} +# } + +# # Process all files in the input folder +# for root, _, files in os.walk(os.path.join(input_folder, "schemas")): +# # Group request and schema files with the same name +# grouped_files = [] +# for file in files: +# if file.endswith(".schema.json"): +# base_name = file[:-12] +# if base_name not in grouped_files: +# grouped_files.append(base_name) + +grouped_files = [ + "close", + "commando", + "datastore", + "datastoreusage", + "decodepay", + "decode", + "deldatastore", + "delexpiredinvoice", + "delforward", + "delinvoice", + "delpay", + "disableinvoicerequest", + "disableoffer", + "disconnect", + "emergencyrecover", + # "feerates", + # "fetchinvoice", + # "fundchannel", + # "fundchannel_start", + # "fundchannel_complete", + # "fundchannel_cancel", + # "funderupdate", + # "addpsbtoutput", + # "fundpsbt", + # "getroute", + # "hsmtool.8", + # "invoice", + # "invoicerequest", + # "keysend", + # "listchannels", + # "listclosedchannels", + # "listdatastore", + # "listforwards", + # "listfunds", + # "listhtlcs", + # "listinvoices", + # "listinvoicerequests", + # "listoffers", + # "listpays", + # "listpeers", + # "listpeerchannels", + # "showrunes", + # "listsendpays", + # "makesecret", + # "multifundchannel", + # "multiwithdraw", + # "newaddr", + # "notifications", + # "offer", + # "openchannel_abort", + # "openchannel_bump", + # "openchannel_init", + # "openchannel_signed", + # "openchannel_update", + # "pay", + # "parsefeerate", + # "plugin", + # "preapproveinvoice", + # "preapprovekeysend", + # "recover", + # "recoverchannel", + # "renepay", + # "renepaystatus", + # "reserveinputs", + # "sendinvoice", + # "sendonion", + # "sendonionmessage", + # "sendpay", + # "setchannel", + # "setconfig", + # "setpsbtversion", + # "sendcustommsg", + # "signinvoice", + # "signmessage", + # "splice_init", + # "splice_update", + # "splice_signed", + # "staticbackup", + # "txprepare", + # "txdiscard", + # "txsend", + # "unreserveinputs", + # "utxopsbt", + # "wait", + # "waitinvoice", + # "waitanyinvoice", + # "waitblockheight", + # "waitsendpay", + # "withdraw", + # "ping", + # "stop", + # "signpsbt", + # "sendpsbt", + # "getinfo", + # "listtransactions", + # "listnodes", + # "listconfigs", + # "help", + # "getlog", + # "reckless.7" +] # Merge and create new JSON files for base_name in grouped_files: @@ -31,7 +135,8 @@ continue elif not os.path.exists(input_folder + "schemas/" + base_name + ".request.json"): with open(input_folder + "schemas/" + base_name + ".request.json", "w") as request_file: - json.dump(raw_request_date, request_file, indent=2) + json.dump("", request_file, indent=2) + # json.dump(raw_request_date, request_file, indent=2) print("REQUEST created for " + base_name) with open(input_folder + "schemas/" + base_name + ".request.json", "r") as request_file, \ @@ -92,10 +197,16 @@ merged_json["response"] = response_json elif title_line.startswith("SEE ALSO"): merged_json["see_also"] = "".join(md_file_contents[i+2:title_line_end]).strip(".").split(", ") + elif title_line.startswith("RESOURCES"): + for j in range(i+2, len(md_file_contents)): + if md_file_contents[j].startswith("[comment]: # ( SHA256STAMP:"): + title_line_end = j - 1 + break + merged_json[title_line.lower()] = md_file_contents[i+2:title_line_end] else: merged_json[title_line.lower().replace(" ", "_")] = md_file_contents[i+2:title_line_end] i = j # Write merged JSON to the new file - output_file = os.path.join(input_folder, "schemas", f"{base_name}.new.json") + output_file = os.path.join(input_folder, "schemas", f"lightning-{base_name}.json") with open(output_file, "w") as outfile: json.dump(merged_json, outfile, indent=2)