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;
45pub mod chunk_protocol;
46pub mod data_types;
47pub mod devnet_manifest;
48pub mod error;
49pub mod logging;
50pub mod payment;
51
52// =============================================================================
53// Public surface re-exports
54// =============================================================================
55
56pub use chunk::{
57    ChunkGetRequest, ChunkGetResponse, ChunkMessage, ChunkMessageBody, ChunkPutRequest,
58    ChunkPutResponse, ChunkQuoteRequest, ChunkQuoteResponse, MerkleCandidateQuoteRequest,
59    MerkleCandidateQuoteResponse, ProtocolError, XorName, CHUNK_PROTOCOL_ID, CLOSE_GROUP_MAJORITY,
60    CLOSE_GROUP_SIZE, DATA_TYPE_CHUNK, MAX_CHUNK_SIZE, MAX_WIRE_MESSAGE_SIZE, PROOF_TAG_MERKLE,
61    PROOF_TAG_SINGLE_NODE, PROTOCOL_VERSION, XORNAME_LEN,
62};
63pub use chunk_protocol::send_and_await_chunk_response;
64pub use data_types::{compute_address, peer_id_to_xor_name, xor_distance, ChunkStats, DataChunk};
65pub use devnet_manifest::{DevnetEvmInfo, DevnetManifest};
66pub use error::{Error, Result};
67pub use payment::{
68    deserialize_merkle_proof, deserialize_proof, detect_proof_type, serialize_merkle_proof,
69    serialize_single_node_proof, verify_merkle_candidate_signature, verify_quote_content,
70    verify_quote_signature, PaymentProof, ProofType, QuotePaymentInfo, SingleNodePayment,
71};
72
73// =============================================================================
74// Transitive-dep re-exports
75//
76// `ant-client` and `ant-node` must compile against the *same* major version
77// of `evmlib`, `saorsa-core`, and `saorsa-pqc`. Re-exporting them here makes
78// `ant-protocol` the single version-pin point: bump the version here and
79// both sides move together. Adding a direct dependency on any of these
80// crates in `ant-client` risks a silent version skew that only manifests
81// at runtime (different `ProofOfPayment` layout, incompatible `P2PNode`
82// behaviours, etc.).
83//
84// These modules hold only `pub use` — no code of our own. They exist as
85// a policy gate, not an abstraction.
86// =============================================================================
87
88/// EVM payment primitives re-exported from [`evmlib`].
89///
90/// Use `ant_protocol::evm::…` in downstream crates instead of a direct
91/// `evmlib` dependency. This guarantees client and node always link the
92/// same `evmlib` major version.
93pub mod evm {
94    pub use evmlib::common::{Address, Amount, QuoteHash, TxHash, U256};
95    pub use evmlib::merkle_batch_payment::PoolCommitment;
96    pub use evmlib::merkle_payments::{
97        MerklePaymentCandidateNode, MerklePaymentCandidatePool, MerklePaymentProof,
98        MerklePaymentVerificationError, MerkleTree, MidpointProof, CANDIDATES_PER_POOL, MAX_LEAVES,
99        MERKLE_PAYMENT_EXPIRATION,
100    };
101    pub use evmlib::wallet::{PayForQuotesError, Wallet};
102    pub use evmlib::{
103        CustomNetwork, EncodedPeerId, Network, PaymentQuote, ProofOfPayment, RewardsAddress,
104    };
105
106    /// Anvil-backed testnet used by devnets and E2E tests.
107    ///
108    /// Exposed so downstream `LocalDevnet` wrappers and test harnesses
109    /// don't need a direct `evmlib` dep just for the Anvil bindings.
110    pub mod testnet {
111        pub use evmlib::testnet::Testnet;
112    }
113
114    /// Lower-level `evmlib` surface (RPC provider, contract interface,
115    /// and payment-vault bindings). Re-exported for the node's verifier
116    /// and the Anvil-based tests; most client code will not need these.
117    pub mod contract {
118        pub use evmlib::contract::payment_vault;
119    }
120
121    /// HTTP provider + transaction-config helpers used by on-chain
122    /// verification flows.
123    pub mod utils {
124        pub use evmlib::transaction_config::TransactionConfig;
125        pub use evmlib::utils::{dummy_address, dummy_hash, http_provider};
126    }
127}
128
129/// Saorsa transport primitives re-exported from [`saorsa_core`].
130///
131/// Use `ant_protocol::transport::…` in downstream crates instead of a
132/// direct `saorsa-core` dependency.
133pub mod transport {
134    pub use saorsa_core::identity::{NodeIdentity, PeerId};
135    pub use saorsa_core::{
136        IPDiversityConfig, MlDsa65, MultiAddr, NodeConfig as CoreNodeConfig, NodeMode, P2PEvent,
137        P2PNode,
138    };
139}
140
141/// Post-quantum crypto primitives re-exported from [`saorsa_pqc`].
142///
143/// Both API paths are re-exported:
144/// - `ant_protocol::pqc::ops::*` (lower-level `pqc::*` module) — used
145///   by the node and by this crate's own verification code.
146/// - `ant_protocol::pqc::api::*` (higher-level `api::sig::*` module) —
147///   used by the client's binary-update signature verification.
148pub mod pqc {
149    /// Lower-level `pqc::*` API (types + `MlDsaOperations` trait).
150    pub mod ops {
151        pub use saorsa_pqc::pqc::types::{MlDsaPublicKey, MlDsaSecretKey, MlDsaSignature};
152        pub use saorsa_pqc::pqc::MlDsaOperations;
153    }
154
155    /// Higher-level `api::sig::*` API (used for release signatures).
156    pub mod api {
157        pub use saorsa_pqc::api::sig::{ml_dsa_65, MlDsaPublicKey, MlDsaSignature, MlDsaVariant};
158    }
159}
ant_protocol/lib.rs

ant_protocol/
lib.rs
