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

ant_protocol/
lib.rs
