dig_rpc_types/
lib.rs

1//! # dig-rpc-types
2//!
3//! Pure `serde`-derived wire types for the DIG Network JSON-RPC surface.
4//! This crate is the **single source of truth** for the shape of every
5//! request and response exchanged between a DIG fullnode / validator and
6//! its clients.
7//!
8//! ## What lives here
9//!
10//! - The JSON-RPC 2.0 [envelope](envelope) — `JsonRpcRequest`, `JsonRpcResponse`,
11//!   `JsonRpcError`, `RequestId`, `Version`.
12//! - A stable [error-code enum](errors::ErrorCode) with explicit numeric wire values.
13//! - Shared [domain types](types) — `HashHex`, `PubkeyHex`, `SignatureHex`,
14//!   `Amount`, `BlockSummary`, `ValidatorSummary`, `ValidatorStatus`.
15//! - The [fullnode](fullnode) method catalogue — one `{Method}Request` +
16//!   `{Method}Response` pair per method.
17//! - The [validator](validator) method catalogue — operator-facing RPC.
18//!
19//! ## What does NOT live here
20//!
21//! - **No I/O.** No tokio, no reqwest (except behind the optional `client`
22//!   feature), no Axum. Consumers build their own clients / servers over
23//!   these types.
24//! - **No business logic.** A method's request/response is defined; what
25//!   the server does with it lives in `dig-rpc`, `apps/fullnode`, etc.
26//! - **No validation beyond `serde`.** Length caps, range checks, and
27//!   cross-field invariants are the server's responsibility.
28//!
29//! ## Stability guarantees
30//!
31//! 1. Every enum is `#[non_exhaustive]` — adding variants is additive, not
32//!    breaking.
33//! 2. [`ErrorCode`](errors::ErrorCode) numeric values **never** change once
34//!    assigned. New variants take the next unused integer.
35//! 3. Method names are snake_case and stable.
36//! 4. Hex-encoded fields emit `0x` + lowercase; accept case-insensitive with
37//!    optional `0x` prefix on parse.
38//! 5. Response envelopes are valid JSON-RPC 2.0 — exactly one of `result` or
39//!    `error` per response, never both, never neither.
40//! 6. [`SCHEMA_VERSION`] is bumped on wire-breaking changes.
41//!
42//! ## Versioning policy
43//!
44//! - **Additive changes** (new methods, new optional fields, new enum
45//!   variants): bump the minor version. Clients on an older minor continue
46//!   to work.
47//! - **Removing or reshaping a field**: bump the major version. Servers MAY
48//!   serve multiple majors behind URL prefixes (`/v1/`, `/v2/`).
49//!
50//! ## Feature flags
51//!
52//! | Flag | Default | Effect |
53//! |---|---|---|
54//! | `client` | off | Ships a thin blocking `reqwest`-backed client for CLI tools |
55//! | `schema-export` | off | Generates JSON-Schema dumps for Go/TS codegen via `schemars` |
56//!
57//! ## Example — decode a response envelope
58//!
59//! ```
60//! use dig_rpc_types::{JsonRpcResponse, JsonRpcResponseBody};
61//!
62//! let raw = r#"{"jsonrpc":"2.0","id":1,"result":{"ok":true}}"#;
63//! let resp: JsonRpcResponse<serde_json::Value> = serde_json::from_str(raw).unwrap();
64//! match resp.body {
65//!     JsonRpcResponseBody::Success { result } => {
66//!         assert_eq!(result["ok"], true);
67//!     }
68//!     JsonRpcResponseBody::Error { .. } => unreachable!(),
69//! }
70//! ```
71
72#![deny(unsafe_code)]
73#![warn(missing_docs)]
74
75pub mod envelope;
76pub mod errors;
77pub mod types;
78
79pub mod fullnode;
80pub mod validator;
81
82// Re-export the most-used items at crate root for convenience.
83pub use envelope::{
84    JsonRpcError, JsonRpcRequest, JsonRpcResponse, JsonRpcResponseBody, RequestId, Version,
85};
86pub use errors::ErrorCode;
87pub use types::{
88    Amount, BlockSummary, HashHex, PubkeyHex, SignatureHex, ValidatorStatus, ValidatorSummary,
89};
90
91/// Wire-schema version exposed by `dig-rpc` servers in response headers /
92/// extensions.
93///
94/// Bumped only on breaking changes. Clients can reject unknown majors.
95pub const SCHEMA_VERSION: &str = "1";
dig_rpc_types/lib.rs

dig_rpc_types/
lib.rs
