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

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:

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 & GetBlockCountResponse.

Documentation

The documentation for types within {json,bin,other} are omitted, as they can be found in Monero's RPC documentation.

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
2. Remove any suffix extension
3. Add Request/Response suffix

For example:

Endpoint/method	Crate location and name
get_block_count	[json::GetBlockCountRequest] & [json::GetBlockCountResponse]
/get_blocks.bin	[bin::GetBlocksRequest] & [bin::GetBlocksResponse]
/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:

{
  "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::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

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