From 8bdba3261947cdd6542bfdf9fb7bd09a9d58709d Mon Sep 17 00:00:00 2001 From: Alfredo Garcia Date: Tue, 15 Mar 2022 06:13:24 -0300 Subject: [PATCH] refactor method docs according to discussion (#3868) --- zebra-rpc/src/methods.rs | 93 +++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 44 deletions(-) diff --git a/zebra-rpc/src/methods.rs b/zebra-rpc/src/methods.rs index 92ff1436..85ec5c2d 100644 --- a/zebra-rpc/src/methods.rs +++ b/zebra-rpc/src/methods.rs @@ -26,86 +26,79 @@ mod tests; #[rpc(server)] /// RPC method signatures. pub trait Rpc { - /// getinfo + /// Returns software information from the RPC server, as a [`GetInfo`] JSON struct. /// - /// Returns software information from the RPC server running Zebra. + /// zcashd reference: [`getinfo`](https://zcash.github.io/rpc/getinfo.html) /// - /// zcashd reference: + /// # Notes /// - /// Result: - /// { - /// "build": String, // Full application version - /// "subversion", String, // Zebra user agent - /// } + /// [The zcashd reference](https://zcash.github.io/rpc/getinfo.html) might not show some fields + /// in Zebra's [`GetInfo`]. Zebra uses the field names and formats from the + /// [zcashd code](https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L86-L87). /// - /// Note 1: We only expose 2 fields as they are the only ones needed for - /// lightwalletd: - /// - /// Note 2: is outdated so it does not - /// show the fields we are exposing. However, this fields are part of the output - /// as shown in the following zcashd code: - /// - /// Zcash open ticket to add this fields to the docs: + /// Some fields from the zcashd reference are missing from Zebra's [`GetInfo`]. It only contains the fields + /// [required for lightwalletd support.](https://github.com/zcash/lightwalletd/blob/v0.4.9/common/common.go#L91-L95) #[rpc(name = "getinfo")] fn get_info(&self) -> Result; - /// getblockchaininfo + /// Returns blockchain state information, as a [`GetBlockChainInfo`] JSON struct. /// - /// TODO: explain what the method does - /// link to the zcashd RPC reference - /// list the arguments and fields that lightwalletd uses - /// note any other lightwalletd changes + /// zcashd reference: [`getblockchaininfo`](https://zcash.github.io/rpc/getblockchaininfo.html) + /// + /// TODO in the context of https://github.com/ZcashFoundation/zebra/issues/3143: + /// - list the arguments and fields that lightwalletd uses + /// - note any other lightwalletd changes #[rpc(name = "getblockchaininfo")] fn get_blockchain_info(&self) -> Result; - /// sendrawtransaction + /// Sends the raw bytes of a signed transaction to the local node's mempool, if the transaction is valid. + /// Returns the [`SentTransactionHash`] for the transaction, as a JSON string. /// - /// Sends the raw bytes of a signed transaction to the network, if the transaction is valid. + /// zcashd reference: [`sendrawtransaction`](https://zcash.github.io/rpc/sendrawtransaction.html) /// - /// zcashd reference: + /// # Parameters /// - /// Result: a hexadecimal string of the hash of the sent transaction. + /// - `raw_transaction_hex`: (string, required) The hex-encoded raw transaction bytes. /// - /// Note: zcashd provides an extra `allowhighfees` parameter, but we don't yet because - /// lightwalletd doesn't use it. + /// # Notes + /// + /// zcashd accepts an optional `allowhighfees` parameter. Zebra doesn't support this parameter, + /// because lightwalletd doesn't use it. #[rpc(name = "sendrawtransaction")] fn send_raw_transaction( &self, raw_transaction_hex: String, ) -> BoxFuture>; - /// getblock + /// Returns the requested block by height, as a [`GetBlock`] JSON string. /// - /// Returns requested block by height, encoded as hex. + /// zcashd reference: [`getblock`](https://zcash.github.io/rpc/getblock.html) /// - /// zcashd reference: + /// # Parameters /// - /// Result: [`GetBlock`] + /// - `height`: (string, required) The height number for the block to be returned. /// - /// Note 1: We only expose the `data` field as lightwalletd uses the non-verbose + /// # Notes + /// + /// We only expose the `data` field as lightwalletd uses the non-verbose /// mode for all getblock calls: /// - /// Note 2: `lightwalletd` only requests blocks by height, so we don't support - /// getting blocks by hash. + /// `lightwalletd` only requests blocks by height, so we don't support + /// getting blocks by hash but we do need to send the height number as a string. /// - /// Note 3: The `verbosity` parameter is ignored but required in the call. + /// The `verbosity` parameter is ignored but required in the call. #[rpc(name = "getblock")] fn get_block(&self, height: String, verbosity: u8) -> BoxFuture>; - /// getbestblockhash - /// - /// Returns the hash of the current best blockchain tip block. - /// - /// zcashd reference: - /// - /// Result: [`GetBestBlockHash`] + /// Returns the hash of the current best blockchain tip block, as a [`GetBestBlockHash`] JSON string. /// + /// zcashd reference: [`getbestblockhash`](https://zcash.github.io/rpc/getbestblockhash.html) #[rpc(name = "getbestblockhash")] fn get_best_block_hash(&self) -> BoxFuture>; /// Returns all transaction ids in the memory pool, as a JSON array. /// - /// zcashd reference: + /// zcashd reference: [`getrawmempool`](https://zcash.github.io/rpc/getrawmempool.html) #[rpc(name = "getrawmempool")] fn get_raw_mempool(&self) -> BoxFuture>>; } @@ -325,6 +318,8 @@ where #[derive(serde::Serialize, serde::Deserialize)] /// Response to a `getinfo` RPC request. +/// +/// See the notes for the [`Rpc::get_info` method]. pub struct GetInfo { build: String, subversion: String, @@ -332,6 +327,8 @@ pub struct GetInfo { #[derive(serde::Serialize, serde::Deserialize)] /// Response to a `getblockchaininfo` RPC request. +/// +/// See the notes for the [`Rpc::get_blockchain_info` method]. pub struct GetBlockChainInfo { chain: String, // TODO: add other fields used by lightwalletd (#3143) @@ -340,13 +337,21 @@ pub struct GetBlockChainInfo { #[derive(Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize)] /// Response to a `sendrawtransaction` RPC request. /// -/// A JSON string with the transaction hash in hexadecimal. +/// Contains the hex-encoded hash of the sent transaction. +/// +/// See the notes for the [`Rpc::send_raw_transaction` method]. pub struct SentTransactionHash(#[serde(with = "hex")] transaction::Hash); #[derive(serde::Serialize)] /// Response to a `getblock` RPC request. +/// +/// See the notes for the [`Rpc::get_block` method]. pub struct GetBlock(#[serde(with = "hex")] SerializedBlock); #[derive(Debug, PartialEq, serde::Serialize)] /// Response to a `getbestblockhash` RPC request. +/// +/// Contains the hex-encoded hash of the tip block. +/// +/// Also see the notes for the [`Rpc::get_best_block_hash` method]. pub struct GetBestBlockHash(#[serde(with = "hex")] block::Hash);