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 It also includes some traits for these types. # Modules This crate's types are split in the following manner: | Module | Purpose | |--------|---------| | The root module | Miscellaneous items, e.g. constants. | [`json`] | Contains JSON request/response (some mixed with binary) that all share the common `/json_rpc` endpoint. | | [`bin`] | Contains request/response types that are expected to be fully in binary (`cuprate_epee_encoding`) in `monerod` and `cuprated`'s RPC interface. These are called at a custom endpoint instead of `/json_rpc`, e.g. `/get_blocks.bin`. | | [`other`] | Contains request/response types that are JSON, but aren't called at `/json_rpc` (e.g. [`crate::other::GetHeightRequest`]). | | [`misc`] | Contains miscellaneous types, e.g. [`crate::misc::Status`]. Many of types here are found and used in request/response types, for example, [`crate::misc::BlockHeader`] is used in [`crate::json::GetLastBlockHeaderResponse`]. | | [`base`] | Contains base types flattened into many request/response types. Each type in `{json,bin,other}` come in pairs and have identical names, but are suffixed with either `Request` or `Response`. e.g. [`GetBlockCountRequest`](crate::json::GetBlockCountRequest) & [`GetBlockCountResponse`](crate::json::GetBlockCountResponse). # Documentation The documentation for types within `{json,bin,other}` are omitted, as they can be found in [Monero's RPC documentation](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html). However, each type will document: - **Definition**: the exact type definition location in `monerod` - **Documentation**: the Monero RPC documentation link - **Request/response**: the other side of this type, either the request or response # Naming The naming for types within `{json,bin,other}` follow the following scheme: 1. Convert the endpoint or method name into `UpperCamelCase` 1. Remove any suffix extension 1. Add `Request/Response` suffix For example: | Endpoint/method | Crate location and name | |-----------------|-------------------------| | [`get_block_count`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_block_count) | [`json::GetBlockCountRequest`] & [`json::GetBlockCountResponse`] | [`/get_blocks.bin`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_blockbin) | [`bin::GetBlocksRequest`] & [`bin::GetBlocksResponse`] | [`/get_height`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_height) | [`other::GetHeightRequest`] & [`other::GetHeightResponse`] # Mixed types Note that some types mix JSON & binary together, i.e., the message overall is JSON, however some fields contain binary values inside JSON strings, for example: ```json { "string": "", "float": 30.0, "integer": 30, "binary": "" } ``` `binary` here is (de)serialized as a normal [`String`]. In order to be clear on which fields contain binary data, the struct fields that have them will use [`crate::misc::BinaryString`] instead of [`String`]. These mixed types are: - [`crate::json::GetTransactionPoolBacklogResponse`] - [`crate::json::GetOutputDistributionResponse`] TODO: we need to figure out a type that (de)serializes correctly, `String` errors with `serde_json` # Fixed byte containers TODO # (De)serialization invariants Due to how types are defined in this library internally (all through a single macro), most types implement both `serde` and `epee`. However, some of the types will panic with [`unimplemented`] or will otherwise have undefined implementation in the incorrect context. In other words: - The epee (de)serialization of [`json`] & [`other`] types should **not** be relied upon - The JSON (de)serialization of [`bin`] types should **not** be relied upon The invariants that can be relied upon: - Types in [`json`] & [`other`] will implement `serde` correctly - Types in [`bin`] will implement `epee` correctly - Misc types will implement `serde/epee` correctly as needed # Requests and responses For `enum`s that encapsulate all request/response types, see: - [`crate::json::JsonRpcRequest`] & [`crate::json::JsonRpcResponse`] - [`crate::bin::BinRequest`] & [`crate::bin::BinResponse`] - [`crate::other::OtherRequest`] & [`crate::other::OtherResponse`] # Feature flags List of feature flags for `cuprate-rpc-types`. All are enabled by default. | Feature flag | Does what | |--------------|-----------| | `serde` | Implements `serde` on all types | `epee` | Implements `cuprate_epee_encoding` on all types