Crate cuprate_rpc_types

Source
Expand description

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:

ModulePurpose
The root moduleMiscellaneous items, e.g. constants.
jsonContains JSON request/response (some mixed with binary) that all share the common /json_rpc endpoint.
binContains 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.
otherContains request/response types that are JSON, but aren’t called at /json_rpc (e.g. crate::other::GetHeightRequest).
miscContains 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.
baseContains 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:

§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:

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 enums that encapsulate all request/response types, see:

§Feature flags

List of feature flags for cuprate-rpc-types.

All are enabled by default.

Feature flagDoes what
serdeImplements serde on all types
epeeImplements cuprate_epee_encoding on all types

Modules§

Constants§

Traits§