cuprate-hinto-janai/rpc/types/README.md

77 lines
3.2 KiB
Markdown
Raw Normal View History

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:
2024-07-06 00:35:52 +00:00
This crate has 5 modules:
- The root module - miscellaneous items
- [`json`] - JSON types from the `/json_rpc` endpoint
- [`bin`] - Binary types from the binary endpoints
- [`other`] - Misc JSON types from other endpoints
- [`base`] - Base 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).
2024-07-06 00:35:52 +00:00
Miscellaneous types are found in the root module, e.g. [`crate::Status`]. Many of types here are found and used in request/response types, for example, [`crate::BlockHeader`] is used in [`crate::json::GetLastBlockHeaderResponse`].
# 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:
- 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) | [`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`
TODO: fix doc links when types are ready.
# Mixed types
Note that some types within [`other`] 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": "<serialized 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::BinaryString`] instead of [`String`].
- TODO: list the specific types.
- TODO: we need to figure out a type that (de)serializes correctly, `String` errors with `serde_json`
2024-07-02 00:52:57 +00:00
# Feature flags
List of feature flags for `cuprate-rpc-types`.
All are enabled by default.
| Feature flag | Does what |
|--------------|-----------|
2024-07-02 00:58:15 +00:00
| `json` | Enables the `crate::json` module
| `bin` | Enables the `crate::bin` module
| `other` | Enables the `crate::other` module
2024-07-02 00:52:57 +00:00
| `serde` | Implements `serde` on all types
2024-07-02 00:58:15 +00:00
| `epee` | Implements `cuprate_epee_encoding` on all types