From 844dddf3088d1002c67740eaf1b905a378cb240e Mon Sep 17 00:00:00 2001 From: parazyd Date: Thu, 13 Jan 2022 21:32:19 +0100 Subject: [PATCH] book: Document cashierd API and add links to source code. --- bin/cashierd/src/main.rs | 15 +++++++++++ book/Makefile | 5 ++++ book/build_jsonrpc.py | 11 ++++++-- book/src/SUMMARY.md | 1 + book/src/clients/cashierd_jsonrpc.md | 38 ++++++++++++++++++++++++++++ book/src/clients/darkfid_jsonrpc.md | 14 ++++++++++ 6 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 book/src/clients/cashierd_jsonrpc.md diff --git a/bin/cashierd/src/main.rs b/bin/cashierd/src/main.rs index 1e6b7377d..233dcc416 100644 --- a/bin/cashierd/src/main.rs +++ b/bin/cashierd/src/main.rs @@ -323,6 +323,11 @@ impl Cashierd { } } + // RPCAPI: + // Executes a deposit request given `network` and `token_id`. + // Returns the address where the deposit shall be transferred to. + // --> {"method": "deposit", "params": [network, token, publickey]} + // <-- {"result": "Ht5G1RhkcKnpLVLMhqJc5aqZ4wYUEbxbtZwGCVbgU7DL"} async fn deposit(&self, id: Value, params: Value, executor: Arc>) -> JsonResult { info!(target: "CASHIER DAEMON", "Received deposit request"); @@ -448,6 +453,12 @@ impl Cashierd { } } + // RPCAPI: + // Executes a withdraw request given `network`, `token_id`, `publickey` + // and `amount`. `publickey` is supposed to correspond to `network`. + // Returns the transaction ID of the processed withdraw. + // --> {"method": "withdraw", "params": [network, token, publickey, amount]} + // <-- {"result": "txID"} async fn withdraw(&self, id: Value, params: Value) -> JsonResult { info!(target: "CASHIER DAEMON", "Received withdraw request"); @@ -531,6 +542,10 @@ impl Cashierd { } } + // RPCAPI: + // Returns supported cashier features, like network, listening ports, etc. + // --> {"method": "features", "params": []} + // <-- {"result": {"network": ["btc", "sol"]} async fn features(&self, id: Value, _params: Value) -> JsonResult { let tcp_port: Option; let tls_port: Option; diff --git a/book/Makefile b/book/Makefile index 8233af668..506239abc 100644 --- a/book/Makefile +++ b/book/Makefile @@ -4,6 +4,11 @@ all: echo "# darkfid JSON-RPC API" > src/clients/darkfid_jsonrpc.md ./build_jsonrpc.py ../bin/darkfid/src/main.rs \ >> src/clients/darkfid_jsonrpc.md + + echo "# cashierd JSON-RPC API" > src/clients/cashierd_jsonrpc.md + ./build_jsonrpc.py ../bin/cashierd/src/main.rs \ + >> src/clients/cashierd_jsonrpc.md + mdbook build github: all diff --git a/book/build_jsonrpc.py b/book/build_jsonrpc.py index 8bbd0a2ff..7b28e33ec 100755 --- a/book/build_jsonrpc.py +++ b/book/build_jsonrpc.py @@ -18,7 +18,7 @@ def main(path): send = "" recv = "" - for i in lines: + for (idx, i) in enumerate(lines): if not i.startswith("//"): continue @@ -35,7 +35,7 @@ def main(path): if i.startswith("// <-- "): send = i[3:] parsing_method = False - methods.append((method, comment.strip(), recv, send)) + methods.append((method, comment.strip(), recv, send, idx + 2)) comment = "" continue @@ -49,6 +49,13 @@ def main(path): for i in methods: print(f"### `{i[0]}`\n") print(f"{i[1]}") + ghlink = "%s%s%s%d" % ( + "https://github.com/darkrenaissance/darkfi/blob/master/", + path.replace("../", ""), + "#L", + i[4], + ) + print(f'
[src]') print("\n```json") print(i[2]) print(i[3]) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 44895d2d5..bbb9b8930 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -6,6 +6,7 @@ - [Tutorial](tutorial.md) - [Client](clients/clients.md) - [darkfid JSON-RPC API](clients/darkfid_jsonrpc.md) + - [cashierd JSON-RPC API](clients/cashierd_jsonrpc.md) - [zkas](zkas/zkas.md) - [Bincode](zkas/bincode.md) - [Examples](zkas/examples.md) diff --git a/book/src/clients/cashierd_jsonrpc.md b/book/src/clients/cashierd_jsonrpc.md new file mode 100644 index 000000000..2f81823a4 --- /dev/null +++ b/book/src/clients/cashierd_jsonrpc.md @@ -0,0 +1,38 @@ +# cashierd JSON-RPC API + +## Methods +* [`deposit`](#deposit) +* [`withdraw`](#withdraw) +* [`features`](#features) + + +### `deposit` + +Executes a deposit request given `network` and `token_id`. +Returns the address where the deposit shall be transferred to. +
[src] + +```json +--> {"method": "deposit", "params": [network, token, publickey]} +<-- {"result": "Ht5G1RhkcKnpLVLMhqJc5aqZ4wYUEbxbtZwGCVbgU7DL"} +``` +### `withdraw` + +Executes a withdraw request given `network`, `token_id`, `publickey` +and `amount`. `publickey` is supposed to correspond to `network`. +Returns the transaction ID of the processed withdraw. +
[src] + +```json +--> {"method": "withdraw", "params": [network, token, publickey, amount]} +<-- {"result": "txID"} +``` +### `features` + +Returns supported cashier features, like network, listening ports, etc. +
[src] + +```json +--> {"method": "features", "params": []} +<-- {"result": {"network": ["btc", "sol"]} +``` diff --git a/book/src/clients/darkfid_jsonrpc.md b/book/src/clients/darkfid_jsonrpc.md index 8e35542cf..e3e57b4d3 100644 --- a/book/src/clients/darkfid_jsonrpc.md +++ b/book/src/clients/darkfid_jsonrpc.md @@ -20,6 +20,7 @@ ### `say_hello` Returns a `helloworld` string. +
[src] ```json --> {"method": "say_hello", "params": []} @@ -28,6 +29,7 @@ Returns a `helloworld` string. ### `create_wallet` Attempts to initialize a wallet, and returns `true` upon success. +
[src] ```json --> {"method": "create_wallet", "params": []} @@ -36,6 +38,7 @@ Attempts to initialize a wallet, and returns `true` upon success. ### `key_gen` Attempts to generate a new keypair and returns `true` upon success. +
[src] ```json --> {"method": "key_gen", "params": []} @@ -45,6 +48,7 @@ Attempts to generate a new keypair and returns `true` upon success. Fetches the main keypair from the wallet and returns it in an encoded format. +
[src] ```json --> {"method": "get_key", "params": []} @@ -55,6 +59,7 @@ in an encoded format. Fetches all keypairs from the wallet and returns a list of them in an encoded format. The first one in the list is the default selected keypair. +
[src] ```json --> {"method": "get_keys", "params": []} @@ -64,6 +69,7 @@ The first one in the list is the default selected keypair. Imports a keypair into the wallet with a given path on the filesystem. Returns `true` upon success. +
[src] ```json --> {"method": "import_keypair", "params": [path]} @@ -73,6 +79,7 @@ Returns `true` upon success. Exports the default selected keypair to a given path on the filesystem. Returns `true` upon success. +
[src] ```json --> {"method": "export_keypair", "params": [path]} @@ -82,6 +89,7 @@ Returns `true` upon success. Sets the default wallet address to the given parameter. Returns true upon success. +
[src] ```json --> {"method": "set_default_address", "params": [vdNS7oBj7KvsMWWmo9r96SV4SqATLrGsH2a3PGpCfJC]} @@ -91,6 +99,7 @@ Returns true upon success. Fetches the known balances from the wallet. Returns a map of balances, indexed by `network`, and token ID. +
[src] ```json --> {"method": "get_balances", "params": []} @@ -100,6 +109,7 @@ Returns a map of balances, indexed by `network`, and token ID. Generates the internal token ID for a given `network` and token ticker or address. Returns the internal representation of the token ID. +
[src] ```json --> {"method": "get_token_id", "params": [network,token]} @@ -109,6 +119,7 @@ Returns the internal representation of the token ID. Asks the configured cashier for their supported features. Returns a map of features received from the requested cashier. +
[src] ```json --> {"method": "features", "params": []} @@ -121,6 +132,7 @@ and `publickey`. The public key send here is used so the cashier can know where to send the newly minted tokens once the deposit is received. Returns an address to which the caller is supposed to deposit funds. +
[src] ```json --> {"method": "deposit", "params": [network,token,publickey]} @@ -136,6 +148,7 @@ On request, sends a request to a cashier to get a deposit address, and then transfers wrapped DarkFitokens to the cashier's wallet. Following that, the cashier should return a transaction ID of them sending the funds that are requested for withdrawal. +
[src] ```json --> {"method": "withdraw", "params": [network,token,publickey,amount]} @@ -145,6 +158,7 @@ are requested for withdrawal. Transfer a given wrapped DarkFi token amount to the given address. Returns the transaction ID of the transfer. +
[src] ```json --> {"method": "transfer", "params": [network,dToken,address,amount]}