cuprate/rpc/types
hinto-janai a2bca1b889
Some checks are pending
Audit / audit (push) Waiting to run
CI / fmt (push) Waiting to run
CI / typo (push) Waiting to run
CI / ci (macos-latest, stable, bash) (push) Waiting to run
CI / ci (ubuntu-latest, stable, bash) (push) Waiting to run
CI / ci (windows-latest, stable-x86_64-pc-windows-gnu, msys2 {0}) (push) Waiting to run
Deny / audit (push) Waiting to run
Doc / build (push) Waiting to run
Doc / deploy (push) Blocked by required conditions
rpc: add JSON doc-tests (#232)
* fixed-bytes: add `serde`, document feature flags

* fixed-bytes: add derives

* rpc: add `as _` syntax to macro

* rpc: use `ByteArrayVec` and `ContainerAsBlob` for binary types

* fixed-bytes: re-add derives

* rpc-types: dedup default value within macro

* readme: fixed bytes section

* types: custom epee - `BlockCompleteEntry`

* types: custom epee - `KeyImageSpentStatus`

* types: custom epee - `PoolInfoExtent`

* types: add `Status::Other(String)` variant

* types: custom epee - `TxEntry`, add `read_epee_field` macro

* bin: custom epee - `GetBlocks`

* types: add `serde.rs`

* misc: make `TxEntry` an `enum`, impl serde

* misc: `unimplemented!()` for `TxEntry`'s epee

* types: add `BlockCompleteEntry`

* rpc: replace `BlockCompleteEntry` with `cuprate-types`

* types: document `BlockCompleteEntry`

* bin: fix `number_of_fields` for `GetBlocksResponse`

* misc: add `Distribution`

* distribution: add todo

* misc fixes

* readme: add `(De)serialization invariants`

* distribution: compress variants

* types: add `block_complete_entry.rs`

* net: fix imports

* p2p: fix imports

* turn off default-features

* p2p: fix imports

* misc fixes

* Update net/wire/Cargo.toml

Co-authored-by: Boog900 <boog900@tutanota.com>

* distribution: module doc

* wire: re-export types

* test-utils: add `crate::rpc::types` module

* test-utils: conditional json doc-tests

* bin: use enum for `GetBlocksResponse`

* misc: use lowercase for stringify

* json: add test data, fix macro doc tests

* json: add all data

* other: add all data

* bin: add skeleton

* docs

* move type to correct file

* remove duplicated fields for custom epee

* rpc: `client/{client,constants}.rs` -> `client.rs`

* lib.rs: remove `clippy::module_inception`

* macros: add json doc test macro

* json: add some tests

* json: add doc-test for all types

* add all other JSON doc-tests

* move doc-test macros to files

* base: add doc-tests

* json: TODO distribution test

---------

Co-authored-by: Boog900 <boog900@tutanota.com>
2024-07-28 21:43:16 +01:00
..
src rpc: add JSON doc-tests (#232) 2024-07-28 21:43:16 +01:00
Cargo.toml rpc: add JSON doc-tests (#232) 2024-07-28 21:43:16 +01:00
README.md rpc: custom epee for misc/bin types (#229) 2024-07-25 16:46:41 +01:00

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