darkfid: Improve JSONRPC docs

bin/darkfid/src/rpc/mod.rs

@@ -105,22 +105,23 @@ impl RequestHandler<DefaultRpcHandler> for DarkfiNode {
 
 impl DarkfiNode {
     // RPCAPI:
-    // Returns current system clock as `u64` (String) timestamp.
+    // Returns current system clock as a UNIX timestamp.
     //
     // --> {"jsonrpc": "2.0", "method": "clock", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "result": "1234", "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": 1767015913, "id": 1}
     async fn clock(&self, id: u16, _params: JsonValue) -> JsonResult {
-        JsonResponse::new(JsonValue::String(Timestamp::current_time().inner().to_string()), id)
-            .into()
+        JsonResponse::new((Timestamp::current_time().inner() as f64).into(), id).into()
     }
 
     // RPCAPI:
     // Activate or deactivate dnet in the P2P stack.
     // By sending `true`, dnet will be activated, and by sending `false` dnet
-    // will be deactivated. Returns `true` on success.
+    // will be deactivated.
     //
-    // --> {"jsonrpc": "2.0", "method": "dnet_switch", "params": [true], "id": 42}
-    // <-- {"jsonrpc": "2.0", "result": true, "id": 42}
+    // Returns `true` on success.
+    //
+    // --> {"jsonrpc": "2.0", "method": "dnet.switch", "params": [true], "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": true, "id": 1}
     async fn dnet_switch(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if params.len() != 1 || !params[0].is_bool() {
@@ -139,12 +140,27 @@ impl DarkfiNode {
     }
 
     // RPCAPI:
-    // Initializes a subscription to p2p dnet events.
-    // Once a subscription is established, `darkfid` will send JSON-RPC notifications of
-    // new network events to the subscriber.
+    // Initializes a subscription to P2P dnet events.
+    // Once a subscription is established, `darkfid` will send JSON-RPC
+    // notifications of new network events to the subscriber.
     //
-    // --> {"jsonrpc": "2.0", "method": "dnet.subscribe_events", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "method": "dnet.subscribe_events", "params": [`event`]}
+    // --> {
+    //       "jsonrpc": "2.0",
+    //       "method": "dnet.subscribe_events",
+    //       "params": [],
+    //       "id": 1
+    //     }
+    // <-- {
+    //       "jsonrpc": "2.0",
+    //       "method": "dnet.subscribe_events",
+    //       "params": [
+    //         {
+    //           "chan": {"Channel": "Info"},
+    //           "cmd": "command",
+    //           "time": 1767016282
+    //         }
+    //       ]
+    //     }
     pub async fn dnet_subscribe_events(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if !params.is_empty() {

bin/darkfid/src/rpc/rpc_blockchain.rs

@@ -42,24 +42,26 @@ impl DarkfiNode {
     // Returns a readable block upon success.
     //
     // **Params:**
-    // * `array[0]`: `u64` Block height (as string)
+    // * `array[0]`: `u32` block height
     //
     // **Returns:**
-    // * [`BlockInfo`](https://darkrenaissance.github.io/darkfi/dev/darkfi/blockchain/block_store/struct.BlockInfo.html)
-    //   struct serialized into base64.
+    // * `BlockInfo` serialized into base64.
     //
-    // --> {"jsonrpc": "2.0", "method": "blockchain.get_block", "params": ["0"], "id": 1}
-    // <-- {"jsonrpc": "2.0", "result": {...}, "id": 1}
+    // ```rust,no_run,noplayground
+    // {{#include ../../../src/blockchain/block_store.rs:blockinfo}
+    // ```
+    //
+    // --> {"jsonrpc": "2.0", "method": "blockchain.get_block", "params": [0], "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": "base64encodedblock", "id": 1}
     pub async fn blockchain_get_block(&self, id: u16, params: JsonValue) -> JsonResult {
-        let params = params.get::<Vec<JsonValue>>().unwrap();
-        if params.len() != 1 || !params[0].is_string() {
+        let Some(params) = params.get::<Vec<JsonValue>>() else {
+            return JsonError::new(InvalidParams, None, id).into()
+        };
+        if params.len() != 1 || !params[0].is_number() {
             return JsonError::new(InvalidParams, None, id).into()
         }
 
-        let block_height = match params[0].get::<String>().unwrap().parse::<u32>() {
-            Ok(v) => v,
-            Err(_) => return JsonError::new(ParseError, None, id).into(),
-        };
+        let block_height = *params[0].get::<f64>().unwrap() as u32;
 
         let blocks = match self.validator.blockchain.get_blocks_by_heights(&[block_height]) {
             Ok(v) => v,
@@ -79,17 +81,20 @@ impl DarkfiNode {
 
     // RPCAPI:
     // Queries the blockchain database for a given transaction.
-    // Returns a serialized `Transaction` object.
+    // Returns a base64 encoded `Transaction` object.
     //
     // **Params:**
     // * `array[0]`: Hex-encoded transaction hash string
     //
     // **Returns:**
-    // * Serialized [`Transaction`](https://darkrenaissance.github.io/darkfi/dev/darkfi/tx/struct.Transaction.html)
-    //   object encoded with base64
+    // * `Transaction serialized into base64.
+    //
+    // ```rust,no_run,noplayground
+    // {{#include ../../../src/tx/mod.rs:transaction-struct}}
+    // ```
     //
     // --> {"jsonrpc": "2.0", "method": "blockchain.get_tx", "params": ["TxHash"], "id": 1}
-    // <-- {"jsonrpc": "2.0", "result": "ABCD...", "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": "base64encodedtx", "id": 1}
     pub async fn blockchain_get_tx(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if params.len() != 1 || !params[0].is_string() {
@@ -122,7 +127,7 @@ impl DarkfiNode {
     // Queries the blockchain database to find the last confirmed block.
     //
     // **Params:**
-    // * `None`
+    // * Empty
     //
     // **Returns:**
     // * `f64`   : Height of the last confirmed block
@@ -154,7 +159,7 @@ impl DarkfiNode {
     // Queries the validator to find the current best fork next block height.
     //
     // **Params:**
-    // * `None`
+    // * Empty
     //
     // **Returns:**
     // * `f64`: Current best fork next block height
@@ -182,13 +187,13 @@ impl DarkfiNode {
     // Queries the validator to get the currently configured block target time.
     //
     // **Params:**
-    // * `None`
+    // * Empty
     //
     // **Returns:**
     // * `f64`: Current block target time
     //
     // --> {"jsonrpc": "2.0", "method": "blockchain.block_target", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "result": 1234, "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": 120, "id": 1}
     pub async fn blockchain_block_target(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if !params.is_empty() {
@@ -202,11 +207,18 @@ impl DarkfiNode {
 
     // RPCAPI:
     // Initializes a subscription to new incoming blocks.
+    //
     // Once a subscription is established, `darkfid` will send JSON-RPC notifications of
     // new incoming blocks to the subscriber.
     //
+    // The notifications contain base64-encoded `BlockInfo` structs.
+    //
+    // ```rust,no_run,noplayground
+    // {{#include ../../../src/blockchain/block_store.rs:blockinfo}
+    // ```
+    //
     // --> {"jsonrpc": "2.0", "method": "blockchain.subscribe_blocks", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "method": "blockchain.subscribe_blocks", "params": [`blockinfo`]}
+    // <-- {"jsonrpc": "2.0", "method": "blockchain.subscribe_blocks", "params": ["base64encodedblock"]}
     pub async fn blockchain_subscribe_blocks(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if !params.is_empty() {
@@ -218,11 +230,14 @@ impl DarkfiNode {
 
     // RPCAPI:
     // Initializes a subscription to new incoming transactions.
+    //
     // Once a subscription is established, `darkfid` will send JSON-RPC notifications of
     // new incoming transactions to the subscriber.
     //
+    // The notifications contain hex-encoded transaction hashes.
+    //
     // --> {"jsonrpc": "2.0", "method": "blockchain.subscribe_txs", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "method": "blockchain.subscribe_txs", "params": [`tx_hash`]}
+    // <-- {"jsonrpc": "2.0", "method": "blockchain.subscribe_txs", "params": ["tx_hash"]}
     pub async fn blockchain_subscribe_txs(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if !params.is_empty() {
@@ -236,8 +251,14 @@ impl DarkfiNode {
     // Initializes a subscription to new incoming proposals. Once a subscription is established,
     // `darkfid` will send JSON-RPC notifications of new incoming proposals to the subscriber.
     //
+    // The notifications contain base64-encoded `BlockInfo` structs.
+    //
+    // ```rust,no_run,noplayground
+    // {{#include ../../../src/blockchain/block_store.rs:blockinfo}
+    // ```
+    //
     // --> {"jsonrpc": "2.0", "method": "blockchain.subscribe_proposals", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "method": "blockchain.subscribe_proposals", "params": [`blockinfo`]}
+    // <-- {"jsonrpc": "2.0", "method": "blockchain.subscribe_proposals", "params": ["base64encodedblock"]}
     pub async fn blockchain_subscribe_proposals(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if !params.is_empty() {
@@ -255,9 +276,12 @@ impl DarkfiNode {
     // * `array[0]`: base58-encoded contract ID string
     //
     // **Returns:**
-    // * `array[n]`: Pairs of: `zkas_namespace` string, serialized
-    //   [`ZkBinary`](https://darkrenaissance.github.io/darkfi/dev/darkfi/zkas/decoder/struct.ZkBinary.html)
-    //   object
+    // * `array[n]`: Pairs of: `zkas_namespace` strings and base64-encoded
+    //   `ZkBinary` objects.
+    //
+    // ```rust,no_run,noplayground
+    // {{#include ../../../src/zkas/decoder.rs:zkbinary-struct}}
+    // ```
     //
     // --> {"jsonrpc": "2.0", "method": "blockchain.lookup_zkas", "params": ["BZHKGQ26bzmBithTQYTJtjo2QdCqpkR9tjSBopT4yf4o"], "id": 1}
     // <-- {"jsonrpc": "2.0", "result": [["Foo", "ABCD..."], ["Bar", "EFGH..."]], "id": 1}

bin/darkfid/src/rpc/rpc_stratum.rs

@@ -79,7 +79,7 @@ impl DarkfiNode {
     // * `job`    : The generated mining job
     // * `status` : Response status
     //
-    // The generated mining job consists of the following fields:
+    // The generated mining job map consists of the following fields:
     // * `blob`      : The hex encoded block hashing blob of the job block
     // * `job_id`    : Registry mining job ID
     // * `height`    : The job block height
@@ -88,8 +88,34 @@ impl DarkfiNode {
     // * `seed_hash` : Current RandomX key
     // * `next_seed_hash`: (optional) Next RandomX key if it is known
     //
-    // --> {"jsonrpc":"2.0", "method": "login", "id": 1, "params": {"login": "MINING_CONFIG", "pass": "", "agent": "XMRig", "algo": ["rx/0"]}}
-    // <-- {"jsonrpc":"2.0", "id": 1, "result": {"id": "1be0b7b6-b15a-47be-a17d-46b2911cf7d0", "job": { ... }, "status": "OK"}}
+    // --> {
+    //       "jsonrpc": "2.0",
+    //       "method": "login",
+    //       "params": {
+    //         "login": "MINING_CONFIG",
+    //         "pass": "x",
+    //         "agent": "XMRig",
+    //         "algo": ["rx/0"]
+    //       },
+    //       "id": 1
+    //     }
+    // <-- {
+    //       "jsonrpc": "2.0",
+    //       "result": {
+    //         "id": "unique_connection-id",
+    //         "job": {
+    //           "blob": "abcdef...001234",
+    //           "job_id": "unique_job-id",
+    //           "height": 1234,
+    //           "target": "abcd1234",
+    //           "algo": "rx/0",
+    //           "seed_hash": "deadbeef...0234",
+    //           "next_seed_hash": "c0fefe...1243"
+    //         },
+    //         "status": "OK"
+    //       },
+    //       "id": 1
+    //     }
     pub async fn stratum_login(&self, id: u16, params: JsonValue) -> JsonResult {
         // Check if node is synced before responding
         if !*self.validator.synced.read().await {
@@ -196,8 +222,18 @@ impl DarkfiNode {
     // **Response:**
     // * `status`: Block submit status
     //
-    // --> {"jsonrpc":"2.0", "method": "submit", "id": 1, "params": {"id": "...", "job_id": "...", "nonce": "d0030040", "result": "e1364b8782719d7683e2ccd3d8f724bc59dfa780a9e960e7c0e0046acdb40100"}}
-    // <-- {"jsonrpc":"2.0", "id": 1, "result": {"status": "OK"}}
+    // --> {
+    //       "jsonrpc": "2.0",
+    //       "method": "submit",
+    //       "params": {
+    //         "id": "unique_connection-id",
+    //         "job_id": "unique_job-id",
+    //         "nonce": "d0030040",
+    //         "result": "e1364b8782719d7683e2ccd3d8f724bc59dfa780a9e960e7c0e0046acdb40100"
+    //       },
+    //       "id": 1
+    //     }
+    // <-- {"jsonrpc": "2.0", "result": {"status": "OK"}, "id": 1}
     pub async fn stratum_submit(&self, id: u16, params: JsonValue) -> JsonResult {
         // Check if node is synced before responding
         if !*self.validator.synced.read().await {
@@ -365,8 +401,8 @@ impl DarkfiNode {
     // **Response:**
     // * `status`: Response status
     //
-    // --> {"jsonrpc":"2.0", "method": "keepalived", "id": 1, "params": {"id": "foo"}}
-    // <-- {"jsonrpc":"2.0", "id": 1, "result": {"status": "KEEPALIVED"}}
+    // --> {"jsonrpc": "2.0", "method": "keepalived", "params": {"id": "foo"}, "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": {"status": "KEEPALIVED"}, "id": 1}
     pub async fn stratum_keepalived(&self, id: u16, params: JsonValue) -> JsonResult {
         // Parse request params
         let Some(params) = params.get::<HashMap<String, JsonValue>>() else {

bin/darkfid/src/rpc/rpc_tx.rs

@@ -140,7 +140,7 @@ impl DarkfiNode {
     // Returns a vector of hex-encoded transaction hashes.
     //
     // --> {"jsonrpc": "2.0", "method": "tx.pending", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "result": "[TxHash,...]", "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": ["TxHash" , "..."], "id": 1}
     pub async fn tx_pending(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if !params.is_empty() {
@@ -171,7 +171,7 @@ impl DarkfiNode {
     // Returns a vector of hex-encoded transaction hashes.
     //
     // --> {"jsonrpc": "2.0", "method": "tx.clean_pending", "params": [], "id": 1}
-    // <-- {"jsonrpc": "2.0", "result": "[TxHash,...]", "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": ["TxHash", "..."], "id": 1}
     pub async fn tx_clean_pending(&self, id: u16, params: JsonValue) -> JsonResult {
         let params = params.get::<Vec<JsonValue>>().unwrap();
         if !params.is_empty() {

bin/darkfid/src/rpc/rpc_xmr.rs

@@ -86,8 +86,8 @@ impl DarkfiNode {
     // darkfid will send the hash:
     //  H(genesis_hash || network || hard_fork_height)
     //
-    // --> {"jsonrpc":"2.0", "method": "merge_mining_get_chain_id", "id": 1}
-    // <-- {"jsonrpc":"2.0", "result": {"chain_id": "0f28c...7863"}, "id": 1}
+    // --> {"jsonrpc": "2.0", "method": "merge_mining_get_chain_id", "id": 1}
+    // <-- {"jsonrpc": "2.0", "result": {"chain_id": "0f28c...7863"}, "id": 1}
     pub async fn xmr_merge_mining_get_chain_id(&self, id: u16, params: JsonValue) -> JsonResult {
         // Verify request params
         let Some(params) = params.get::<Vec<JsonValue>>() else {
@@ -138,8 +138,26 @@ impl DarkfiNode {
     // * `aux_diff`: Mining difficulty (decimal number)
     // * `aux_hash`: A 32-byte hex-encoded hash of merge mined block
     //
-    // --> {"jsonrpc":"2.0", "method": "merge_mining_get_aux_block", "params": {"address": "MERGE_MINED_CHAIN_ADDRESS", "aux_hash": "f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f", "height": 3000000, "prev_id":"ad505b0be8a49b89273e307106fa42133cbd804456724c5e7635bd953215d92a"}, "id": 1}
-    // <-- {"jsonrpc":"2.0", "result": {"aux_blob": "", "aux_diff": 123456, "aux_hash":"f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f"}, "id": 1}
+    // --> {
+    //       "jsonrpc": "2.0",
+    //       "method": "merge_mining_get_aux_block",
+    //       "params": {
+    //         "address": "MERGE_MINED_CHAIN_ADDRESS",
+    //         "aux_hash": "f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f",
+    //         "height": 3000000,
+    //         "prev_id":"ad505b0be8a49b89273e307106fa42133cbd804456724c5e7635bd953215d92a"
+    //       },
+    //       "id": 1
+    //     }
+    // <-- {
+    //       "jsonrpc":"2.0",
+    //       "result": {
+    //         "aux_blob": "fad344115...3151531",
+    //         "aux_diff": 123456,
+    //         "aux_hash":"f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f"
+    //       },
+    //       "id": 1
+    //     }
     pub async fn xmr_merge_mining_get_aux_block(&self, id: u16, params: JsonValue) -> JsonResult {
         // Check if node is synced before responding to p2pool
         if !*self.validator.synced.read().await {
@@ -247,7 +265,19 @@ impl DarkfiNode {
     // **Response:**
     // * `status`: Block submit status
     //
-    // --> {"jsonrpc":"2.0", "method": "merge_mining_submit_solution", "params": {"aux_blob": "", "aux_hash": "f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f", "blob": "...", "merkle_proof": ["hash1", "hash2", "hash3"], "path": 3, "seed_hash": "22c3d47c595ae888b5d7fc304235f92f8854644d4fad38c5680a5d4a81009fcd"}, "id": 1}
+    // --> {
+    //       "jsonrpc":"2.0",
+    //       "method": "merge_mining_submit_solution",
+    //       "params": {
+    //         "aux_blob": "124125....35215136",
+    //         "aux_hash": "f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f",
+    //         "blob": "...",
+    //         "merkle_proof": ["hash1", "hash2", "hash3"],
+    //         "path": 3,
+    //         "seed_hash": "22c3d47c595ae888b5d7fc304235f92f8854644d4fad38c5680a5d4a81009fcd"
+    //       },
+    //       "id": 1
+    //     }
     // <-- {"jsonrpc":"2.0", "result": {"status": "accepted"}, "id": 1}
     pub async fn xmr_merge_mining_submit_solution(&self, id: u16, params: JsonValue) -> JsonResult {
         // Check if node is synced before responding to p2pool

src/blockchain/block_store.rs

@@ -77,6 +77,7 @@ impl Block {
 /// to include more information that might be used in different
 /// block versions, without affecting the original struct.
 #[derive(Debug, Clone, SerialEncodable, SerialDecodable)]
+// ANCHOR: blockinfo
 pub struct BlockInfo {
     /// Block header data
     pub header: Header,
@@ -85,6 +86,7 @@ pub struct BlockInfo {
     /// Block producer signature
     pub signature: Signature,
 }
+// ANCHOR_END: blockinfo
 
 impl Default for BlockInfo {
     /// Represents the genesis block on current timestamp

src/tx/mod.rs

@@ -54,6 +54,7 @@ macro_rules! zip {
 ///
 /// `DarkLeaf` is used to map relations between contract calls in the transaction.
 #[derive(Clone, Default, Eq, PartialEq, SerialEncodable, SerialDecodable)]
+// ANCHOR: transaction-struct
 pub struct Transaction {
     /// Calls executed in this transaction
     pub calls: Vec<DarkLeaf<ContractCall>>,
@@ -62,6 +63,7 @@ pub struct Transaction {
     /// Attached Schnorr signatures
     pub signatures: Vec<Vec<Signature>>,
 }
+// ANCHOR_END: transaction-struct
 // ANCHOR_END: transaction
 
 impl Transaction {

src/zkas/decoder.rs

@@ -29,6 +29,7 @@ use crate::{Error::ZkasDecoderError as ZkasErr, Result};
 /// A ZkBinary decoded from compiled zkas code.
 /// This is used by the zkvm.
 #[derive(Clone, Debug)]
+// ANCHOR: zkbinary-struct
 pub struct ZkBinary {
     pub namespace: String,
     pub k: u32,
@@ -37,6 +38,7 @@ pub struct ZkBinary {
     pub witnesses: Vec<VarType>,
     pub opcodes: Vec<(Opcode, Vec<(HeapType, usize)>)>,
 }
+// ANCHOR_END: zkbinary-struct
 
 // https://stackoverflow.com/questions/35901547/how-can-i-find-a-subsequence-in-a-u8-slice
 fn find_subslice(haystack: &[u8], needle: &[u8]) -> Option<usize> {