docs

rpc/monero-rpc-types/Cargo.toml

@@ -9,12 +9,12 @@ repository  = "https://github.com/Cuprate/cuprate/tree/main/rpc/monero-rpc-types
 keywords    = ["monero", "rpc", "types"]
 
 [features]
-default = ["serde"]
+default = []
 
 [dependencies]
 monero-serai = { workspace = true }
 paste        = { workspace = true }
-serde        = { workspace = true, optional = true }
+serde        = { workspace = true }
 strum        = { workspace = true, features = ["derive"] }
 
 [dev-dependencies]

rpc/monero-rpc-types/README.md

@@ -0,0 +1,61 @@
+Monero RPC types.
+
+# What
+This crate ports the types used in Monero's RPC interface, including:
+- JSON types
+- Binary (epee) types
+- Mixed types
+- Other commonly used RPC types
+
+# Modules
+This crate's types are split in the following manner:
+
+1. This crate has 3 modules:
+    - The root module (`monero_rpc_types`)
+    - [`req`] (request types)
+    - [`resp`] (response types)
+1. Miscellaneous types are found in the root module, e.g. [`Status`]
+1. The `req` and `resp` modules perfectly mirror each-other, and are split into 3 modules:
+    - `json` (JSON types from the `/json_rpc` endpoint)
+    - `bin` (Binary types from the binary endpoints)
+    - `other` (Misc JSON types from other endpoints)
+1. Each type in `req` has a corresponding type in `resp` and vice-versa with an identical name, e.g. [`req::json::GetBlockCount`] and [`resp::json::GetBlockCount`]
+
+# Documentation
+The documentation for types within [`req`] and [`resp`] are omitted,
+as they can be found in [Monero's RPC documentation](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#on_get_block_hash).
+
+However, each type will document:
+- The exact type definition location in `monerod`
+- The Monero RPC documentation link
+
+# Naming
+The naming for types within [`req`] and [`resp`] follow the following scheme:
+- Convert the endpoint or method name into `UpperCamelCase`
+- Remove any suffix extension
+
+For example:
+
+| Endpoint/method | Crate location and name |
+|-----------------|-------------------------|
+| [`get_block_count`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_block_count) | [`req::json::GetBlockCount`] & [`resp::json::GetBlockCount`]
+| [`/get_blocks.bin`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_blockbin) | `req::bin::GetBlocks` & `resp::bin::GetBlocks`
+| [`/get_height`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_height) | `req::other::GetHeight` & `resp::other::GetHeight`
+
+TODO: fix doc links when types are ready.
+
+# Mixed types
+Note that some types within [`resp::other`] mix JSON & binary, i.e.,
+the message overall is JSON, however some fields contain binary
+values, for example:
+
+```json
+{
+  "string": "",
+  "float": 30.0,
+  "integer": 30,
+  "binary": /* serialized binary */
+}
+```
+
+TODO: list the specific types.

rpc/monero-rpc-types/src/json.rs

@@ -32,7 +32,7 @@ define_monero_rpc_struct! {
         // The struct generated and all fields are `pub`.
 
         count: u64,
-        status: crate::misc::Status,
+        status: crate::Status,
         untrusted: bool,
     }
 }

rpc/monero-rpc-types/src/lib.rs

@@ -1,7 +1,4 @@
-//! Monero RPC types.
-//!
-//! TODO.
-
+#![doc = include_str!("../README.md")]
 //---------------------------------------------------------------------------------------------------- Lints
 // Forbid lints.
 // Our code, and code generated (e.g macros) cannot overrule these.
@@ -98,11 +95,16 @@
 )]
 
 //---------------------------------------------------------------------------------------------------- Use
-mod bin;
-mod data;
-mod json;
+// Misc types.
+mod status;
+pub use status::Status;
+
+// Internal modules.
 mod macros;
-pub mod misc;
+
+// Request/response JSON/binary/other types.
+mod bin;
+mod json;
 mod other;
 
 /// TODO
@@ -130,23 +132,23 @@ macro_rules! re_export_request_and_response_types {
 			)*
 		}
 	) => { paste::paste! {
-		/// TODO
+		/// RPC request types.
 		pub mod req {
-			/// TODO
+			/// JSON types from the [`/json_rpc`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#json-rpc-methods) endpoint.
 			pub mod json {
 				$(
 					pub use $crate::json::[<Request $json_type>] as $json_type;
 				)*
 			}
 
-			/// TODO
+			/// Binary types from [binary](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_blocksbin) endpoints.
 			pub mod bin {
 				$(
 					pub use $crate::bin::[<Request $binary_type>] as $binary_type;
 				)*
 			}
 
-			/// TODO
+			/// JSON types from the [`other`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#other-daemon-rpc-calls) endpoints.
 			pub mod other {
 				$(
 					pub use $crate::other::[<Request $other_type>] as $other_type;
@@ -154,23 +156,23 @@ macro_rules! re_export_request_and_response_types {
 			}
 		}
 
-		/// TODO
+		/// RPC response types.
 		pub mod resp {
-			/// TODO
+			/// JSON types from the [`/json_rpc`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#json-rpc-methods) endpoint.
 			pub mod json {
 				$(
 					pub use $crate::json::[<Response $json_type>] as $json_type;
 				)*
 			}
 
-			/// TODO
+			/// Binary types from [binary](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_blocksbin) endpoints.
 			pub mod bin {
 				$(
 					pub use $crate::bin::[<Response $binary_type>] as $binary_type;
 				)*
 			}
 
-			/// TODO
+			/// JSON types from the [`other`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#other-daemon-rpc-calls) endpoints.
 			pub mod other {
 				$(
 					pub use $crate::other::[<Response $other_type>] as $other_type;

rpc/monero-rpc-types/src/macros.rs

@@ -43,7 +43,7 @@ macro_rules! define_monero_rpc_struct {
     ) => { paste::paste! {
         #[allow(dead_code)]
         #[allow(missing_docs)]
-        #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+        #[derive(serde::Serialize, serde::Deserialize)]
         #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
         $( #[$request_type_attr] )*
         #[doc = concat!(
@@ -81,7 +81,7 @@ macro_rules! define_monero_rpc_struct {
 
         #[allow(dead_code)]
         #[allow(missing_docs)]
-        #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+        #[derive(serde::Serialize, serde::Deserialize)]
         #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
         $( #[$response_type_attr] )*
         #[doc = concat!(

rpc/monero-rpc-types/src/other.rs

@@ -13,7 +13,7 @@ define_monero_rpc_struct! {
     #[derive(Copy)]
     Request {},
     Response {
-        status: crate::misc::Status,
+        status: crate::Status,
         untrusted: bool,
     }
 }

rpc/monero-rpc-types/src/status.rs

@@ -1,19 +1,24 @@
-//! TODO.
+//! RPC response status type.
 
 //---------------------------------------------------------------------------------------------------- Import
+use serde::{Deserialize, Serialize};
 use strum::{
     AsRefStr, Display, EnumCount, EnumIs, EnumIter, EnumMessage, EnumProperty, EnumString,
     EnumTryAs, FromRepr, IntoStaticStr, VariantArray, VariantNames,
 };
 
 //---------------------------------------------------------------------------------------------------- TODO
-/// TODO
+/// RPC response status.
 ///
-/// <https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454/src/rpc/message.cpp#L40-L44>.
+/// This type represents `monerod`'s frequently appearing string field, `status`.
 ///
-/// ## String formatting
+/// This field appears within RPC [JSON response](crate::resp::json) types.
+///
+/// Reference: <https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454/src/rpc/message.cpp#L40-L44>.
+///
+/// ## Serialization and string formatting
 /// ```rust
-/// # use monero_rpc_types::misc::*;
+/// # use monero_rpc_types::*;
 /// use serde_json::to_string;
 /// use strum::AsRefStr;
 ///
@@ -70,30 +75,49 @@ use strum::{
     IntoStaticStr,
     VariantArray,
     VariantNames,
+    Serialize,
+    Deserialize,
 )]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Status {
-    /// TODO
+    /// Successful RPC response, everything is OK.
     #[strum(serialize = "OK")]
-    #[cfg_attr(feature = "serde", serde(rename = "OK"))]
+    #[serde(rename = "OK", alias = "Ok", alias = "ok")]
     #[default]
     Ok,
 
-    /// TODO
+    #[serde(alias = "Retry", alias = "RETRY", alias = "retry")]
+    /// The RPC call failed and should be retried.
+    ///
+    /// TODO: confirm this.
     Retry,
 
-    /// TODO
+    #[serde(alias = "failed", alias = "FAILED")]
+    /// The RPC call failed.
     Failed,
 
-    /// TODO
+    /// The RPC call contained bad input, unknown method, unknown params, etc.
     #[strum(serialize = "Invalid request type")]
-    #[cfg_attr(feature = "serde", serde(rename = "Invalid request type"))]
+    #[serde(
+        rename = "Invalid request type",
+        alias = "invalid request type",
+        alias = "INVALID REQUEST TYPE"
+    )]
     BadRequest,
 
-    /// TODO
+    /// The RPC call contained malformed JSON.
     #[strum(serialize = "Malformed json")]
-    #[cfg_attr(feature = "serde", serde(rename = "Malformed json"))]
+    #[serde(
+        rename = "Malformed json",
+        alias = "malformed json",
+        alias = "MALFORMED JSON",
+        alias = "Malformed JSON",
+        alias = "malformed JSON"
+    )]
     BadJson,
+    // TODO:
+    // This may not be all the string `monerod` uses.
+    // We could use an `Other(String)` here just in case,
+    // otherwise deserialization would fail.
 }
 
 //---------------------------------------------------------------------------------------------------- Tests