dig-rpc-types 0.1.0

JSON-RPC wire types shared by the DIG Network fullnode + validator RPC servers and their clients. Pure types — no I/O, no async, no logic.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

//! # dig-rpc-types
//!
//! Pure `serde`-derived wire types for the DIG Network JSON-RPC surface.
//! This crate is the **single source of truth** for the shape of every
//! request and response exchanged between a DIG fullnode / validator and
//! its clients.
//!
//! ## What lives here
//!
//! - The JSON-RPC 2.0 [envelope](envelope) — `JsonRpcRequest`, `JsonRpcResponse`,
//!   `JsonRpcError`, `RequestId`, `Version`.
//! - A stable [error-code enum](errors::ErrorCode) with explicit numeric wire values.
//! - Shared [domain types](types) — `HashHex`, `PubkeyHex`, `SignatureHex`,
//!   `Amount`, `BlockSummary`, `ValidatorSummary`, `ValidatorStatus`.
//! - The [fullnode](fullnode) method catalogue — one `{Method}Request` +
//!   `{Method}Response` pair per method.
//! - The [validator](validator) method catalogue — operator-facing RPC.
//!
//! ## What does NOT live here
//!
//! - **No I/O.** No tokio, no reqwest (except behind the optional `client`
//!   feature), no Axum. Consumers build their own clients / servers over
//!   these types.
//! - **No business logic.** A method's request/response is defined; what
//!   the server does with it lives in `dig-rpc`, `apps/fullnode`, etc.
//! - **No validation beyond `serde`.** Length caps, range checks, and
//!   cross-field invariants are the server's responsibility.
//!
//! ## Stability guarantees
//!
//! 1. Every enum is `#[non_exhaustive]` — adding variants is additive, not
//!    breaking.
//! 2. [`ErrorCode`](errors::ErrorCode) numeric values **never** change once
//!    assigned. New variants take the next unused integer.
//! 3. Method names are snake_case and stable.
//! 4. Hex-encoded fields emit `0x` + lowercase; accept case-insensitive with
//!    optional `0x` prefix on parse.
//! 5. Response envelopes are valid JSON-RPC 2.0 — exactly one of `result` or
//!    `error` per response, never both, never neither.
//! 6. [`SCHEMA_VERSION`] is bumped on wire-breaking changes.
//!
//! ## Versioning policy
//!
//! - **Additive changes** (new methods, new optional fields, new enum
//!   variants): bump the minor version. Clients on an older minor continue
//!   to work.
//! - **Removing or reshaping a field**: bump the major version. Servers MAY
//!   serve multiple majors behind URL prefixes (`/v1/`, `/v2/`).
//!
//! ## Feature flags
//!
//! | Flag | Default | Effect |
//! |---|---|---|
//! | `client` | off | Ships a thin blocking `reqwest`-backed client for CLI tools |
//! | `schema-export` | off | Generates JSON-Schema dumps for Go/TS codegen via `schemars` |
//!
//! ## Example — decode a response envelope
//!
//! ```
//! use dig_rpc_types::{JsonRpcResponse, JsonRpcResponseBody};
//!
//! let raw = r#"{"jsonrpc":"2.0","id":1,"result":{"ok":true}}"#;
//! let resp: JsonRpcResponse<serde_json::Value> = serde_json::from_str(raw).unwrap();
//! match resp.body {
//!     JsonRpcResponseBody::Success { result } => {
//!         assert_eq!(result["ok"], true);
//!     }
//!     JsonRpcResponseBody::Error { .. } => unreachable!(),
//! }
//! ```

#![deny(unsafe_code)]
#![warn(missing_docs)]

pub mod envelope;
pub mod errors;
pub mod types;

pub mod fullnode;
pub mod validator;

// Re-export the most-used items at crate root for convenience.
pub use envelope::{
    JsonRpcError, JsonRpcRequest, JsonRpcResponse, JsonRpcResponseBody, RequestId, Version,
};
pub use errors::ErrorCode;
pub use types::{
    Amount, BlockSummary, HashHex, PubkeyHex, SignatureHex, ValidatorStatus, ValidatorSummary,
};

/// Wire-schema version exposed by `dig-rpc` servers in response headers /
/// extensions.
///
/// Bumped only on breaking changes. Clients can reject unknown majors.
pub const SCHEMA_VERSION: &str = "1";