book: Document cashierd API and add links to source code.

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<Executor<'_>>) -> 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<u16>;
         let tls_port: Option<u16>;

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

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'<br><sup><a href="{ghlink}">[src]</a></sup>')
         print("\n```json")
         print(i[2])
         print(i[3])

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)

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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/cashierd/src/main.rs#L331">[src]</a></sup>
+
+```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/cashierd/src/main.rs#L462">[src]</a></sup>
+
+```json
+--> {"method": "withdraw", "params": [network, token, publickey, amount]}
+<-- {"result": "txID"}
+```
+### `features`
+
+Returns supported cashier features, like network, listening ports, etc.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/cashierd/src/main.rs#L549">[src]</a></sup>
+
+```json
+--> {"method": "features", "params": []}
+<-- {"result": {"network": ["btc", "sol"]}
+```

book/src/clients/darkfid_jsonrpc.md

@@ -20,6 +20,7 @@
 ### `say_hello`
 
 Returns a `helloworld` string.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L151">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L159">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L170">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L183">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L195">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L227">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L272">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L310">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L337">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L382">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L449">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L473">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L544">[src]</a></sup>
 
 ```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.
+<br><sup><a href="https://github.com/darkrenaissance/darkfi/blob/master/bin/darkfid/src/main.rs#L661">[src]</a></sup>
 
 ```json
 --> {"method": "transfer", "params": [network,dToken,address,amount]}