ant_protocol/lib.rs
1//! # ant-protocol
2//!
3//! Wire protocol for the Autonomi decentralized network (`WithAutonomi` fork).
4//!
5//! This crate is the contract between `ant-client` and `ant-node`:
6//! wire message types, serialization, content addressing, and the
7//! pure-verification halves of the post-quantum signing scheme. Both
8//! crates depend on `ant-protocol` and on nothing else from each other.
9//!
10//! ## Scope
11//!
12//! - [`chunk`] — chunk request/response messages, protocol constants,
13//! `ProtocolError`, close-group sizing, proof-type tag bytes.
14//! - [`data_types`] — pure helpers on 32-byte addresses (`compute_address`,
15//! `xor_distance`, `peer_id_to_xor_name`) and `DataChunk`.
16//! - [`chunk_protocol`] — a shared "subscribe → send → poll" helper
17//! [`chunk_protocol::send_and_await_chunk_response`] that both the
18//! client and node test harness use to exchange chunk messages on
19//! a `saorsa-core::P2PNode`.
20//! - [`payment`] — on-wire payment artifacts: `PaymentProof`,
21//! `SingleNodePayment` (with `pay` and `verify` co-located), and
22//! ML-DSA-65 verification of quotes and merkle candidates.
23//!
24//! ## What is **not** here
25//!
26//! - Quote generation and node-side signing keys (stay in `ant-node`).
27//! - On-chain verification cache and payment verifier state machine
28//! (stay in `ant-node`).
29//! - `LocalDevnet` and node process management (stay in `ant-client`
30//! and `ant-node` respectively).
31//!
32//! ## Logging
33//!
34//! The `logging` feature re-exports [`tracing`] macros. When disabled
35//! the macros become no-ops with zero runtime cost.
36
37#![deny(unsafe_code)]
38#![warn(missing_docs)]
39#![warn(clippy::all)]
40#![warn(clippy::pedantic)]
41// Variables used only inside log macros become unused when `logging` is off.
42#![cfg_attr(not(feature = "logging"), allow(unused_variables, unused_assignments))]
43
44pub mod chunk;
45#[cfg(feature = "native")]
46pub mod chunk_protocol;
47pub mod data_types;
48pub mod devnet_manifest;
49pub mod error;
50pub mod logging;
51pub mod payment;
52
53// =============================================================================
54// Public surface re-exports
55// =============================================================================
56
57pub use chunk::{
58 client_update_required_message, settlement_compatibility, ChunkGetRequest, ChunkGetResponse,
59 ChunkMessage, ChunkMessageBody, ChunkPutRequest, ChunkPutResponse, ChunkQuoteRequest,
60 ChunkQuoteRequestV2, ChunkQuoteResponse, MerkleCandidateQuoteRequest,
61 MerkleCandidateQuoteRequestV2, MerkleCandidateQuoteResponse, ProtocolError,
62 SettlementCompatibility, XorName, CHUNK_PROTOCOL_ID, CLOSE_GROUP_MAJORITY, CLOSE_GROUP_SIZE,
63 CURRENT_SETTLEMENT_VERSION, DATA_TYPE_CHUNK, MAX_CHUNK_SIZE, MAX_WIRE_MESSAGE_SIZE,
64 MIN_SUPPORTED_SETTLEMENT_VERSION, PROOF_TAG_MERKLE, PROOF_TAG_SINGLE_NODE, PROTOCOL_VERSION,
65 XORNAME_LEN,
66};
67#[cfg(feature = "native")]
68pub use chunk_protocol::{
69 send_and_await_chunk_response, send_and_await_chunk_response_with_metadata,
70 ChunkProtocolResponse,
71};
72pub use data_types::{compute_address, peer_id_to_xor_name, xor_distance, ChunkStats, DataChunk};
73pub use devnet_manifest::{DevnetEvmInfo, DevnetManifest};
74pub use error::{Error, Result};
75pub use payment::{
76 deserialize_merkle_proof, deserialize_proof, detect_proof_type, serialize_merkle_proof,
77 serialize_single_node_proof, verify_merkle_candidate_signature, verify_quote_content,
78 verify_quote_signature, PaymentProof, ProofType, QuotePaymentInfo, SingleNodePayment,
79};
80
81// =============================================================================
82// Transitive-dep re-exports
83//
84// `ant-client` and `ant-node` must compile against the *same* major version
85// of `evmlib`, `saorsa-core`, and `saorsa-pqc`. Re-exporting them here makes
86// `ant-protocol` the single version-pin point: bump the version here and
87// both sides move together. Adding a direct dependency on any of these
88// crates in `ant-client` risks a silent version skew that only manifests
89// at runtime (different `ProofOfPayment` layout, incompatible `P2PNode`
90// behaviours, etc.).
91//
92// These modules hold only `pub use` — no code of our own. They exist as
93// a policy gate, not an abstraction.
94// =============================================================================
95
96/// EVM payment primitives re-exported from [`evmlib`].
97///
98/// Use `ant_protocol::evm::…` in downstream crates instead of a direct
99/// `evmlib` dependency. This guarantees client and node always link the
100/// same `evmlib` major version.
101pub mod evm {
102 pub use evmlib::common::{Address, Amount, QuoteHash, TxHash, U256};
103 pub use evmlib::merkle_batch_payment::PoolCommitment;
104 pub use evmlib::merkle_payments::{
105 MerklePaymentCandidateNode, MerklePaymentCandidatePool, MerklePaymentProof,
106 MerklePaymentVerificationError, MerkleTree, MidpointProof, CANDIDATES_PER_POOL, MAX_LEAVES,
107 MERKLE_PAYMENT_EXPIRATION,
108 };
109 #[cfg(feature = "native")]
110 pub use evmlib::wallet::journal;
111 #[cfg(feature = "rpc")]
112 pub use evmlib::wallet::{PayForQuotesError, Wallet};
113 pub use evmlib::{
114 CustomNetwork, EncodedPeerId, Network, PaymentQuote, ProofOfPayment, RewardsAddress,
115 };
116
117 /// Anvil-backed testnet used by devnets and E2E tests.
118 ///
119 /// Exposed so downstream `LocalDevnet` wrappers and test harnesses
120 /// don't need a direct `evmlib` dep just for the Anvil bindings.
121 #[cfg(feature = "native")]
122 pub mod testnet {
123 pub use evmlib::testnet::Testnet;
124 }
125
126 /// Lower-level `evmlib` surface (RPC provider, contract interface,
127 /// and payment-vault bindings). Re-exported for the node's verifier
128 /// and the Anvil-based tests; most client code will not need these.
129 #[cfg(feature = "rpc")]
130 pub mod contract {
131 pub use evmlib::contract::payment_vault;
132 }
133
134 /// HTTP provider + transaction-config helpers used by on-chain
135 /// verification flows.
136 #[cfg(feature = "rpc")]
137 pub mod utils {
138 pub use evmlib::transaction_config::TransactionConfig;
139 pub use evmlib::utils::{dummy_address, dummy_hash, http_provider};
140 }
141}
142
143/// Saorsa transport primitives re-exported from [`saorsa_core`].
144///
145/// Use `ant_protocol::transport::…` in downstream crates instead of a
146/// direct `saorsa-core` dependency.
147pub mod transport {
148 /// Browser RPC capability requiring owner-signed V2 address records.
149 /// This does not select native DHT protocols; native peers send both versions.
150 pub const ADDRESS_V2_CAPABILITY: &str = "addr-v2";
151
152 pub use saorsa_core::client_routing;
153 pub use saorsa_core::dht_lookup::{
154 DEFAULT_ALPHA_VALUE, DEFAULT_K_VALUE, ITERATION_GRACE_TIMEOUT_SECS, LOOKUP_TIMEOUT_SECS,
155 };
156 pub use saorsa_core::identity::{NodeIdentity, PeerId};
157 pub use saorsa_core::signed_address;
158 pub use saorsa_core::{
159 collect_after_first_with_grace, run_iterative_lookup, xor_distance, AddressType, DHTNode,
160 IterativeLookup, KnownReachability, LookupConfig, LookupKey, LookupNode, LookupQuery,
161 LookupQueryOutcome, LookupRunError, LookupTermination, MlDsa65, MultiAddr, ResponderView,
162 TransportAddressRecord, WitnessedCloseGroup,
163 };
164 #[cfg(feature = "native")]
165 pub use saorsa_core::{
166 IPDiversityConfig, NodeConfig as CoreNodeConfig, NodeMode, P2PEvent, P2PNode, PeerRouteKind,
167 };
168}
169
170/// Post-quantum crypto primitives re-exported from [`saorsa_pqc`].
171///
172/// Both API paths are re-exported:
173/// - `ant_protocol::pqc::ops::*` (lower-level `pqc::*` module) — used
174/// by the node and by this crate's own verification code.
175/// - `ant_protocol::pqc::api::*` (higher-level `api::sig::*` module) —
176/// used by the client's binary-update signature verification.
177pub mod pqc {
178 /// Lower-level `pqc::*` API (types + `MlDsaOperations` trait).
179 pub mod ops {
180 pub use saorsa_pqc::pqc::types::{MlDsaPublicKey, MlDsaSecretKey, MlDsaSignature};
181 pub use saorsa_pqc::pqc::MlDsaOperations;
182 }
183
184 /// Higher-level `api::sig::*` API (used for release signatures).
185 pub mod api {
186 pub use saorsa_pqc::api::sig::{
187 ml_dsa_65, MlDsaPublicKey, MlDsaSecretKey, MlDsaSignature, MlDsaVariant,
188 };
189 }
190}