From 27608da5c21fe070ff3f1b873f8fa706e5e1a85e 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/schemas/commando.schema.json | 12 ++ doc/schemas/delforward.request.json | 2 +- doc/schemas/emergencyrecover.schema.json | 2 +- tools/fromschema.py | 79 ++++++------ tools/merge.py | 147 ++++++++++++++++++++--- 13 files changed, 206 insertions(+), 83 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/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/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)