hydra_amm/lib.rs
1//! # Hydra AMM
2//!
3//! Universal AMM engine: build, configure, and operate any Automated Market
4//! Maker through a unified interface.
5//!
6//! This crate provides domain types, core traits, configuration structures,
7//! and feature-gated pool implementations for six AMM families:
8//!
9//! - **Constant Product** (Uniswap v2 style) — `constant-product` feature
10//! - **Concentrated Liquidity** (Uniswap v3 style) — `clmm` feature
11//! - **Hybrid / StableSwap** (Curve style) — `hybrid` feature
12//! - **Weighted Pools** (Balancer style) — `weighted` feature
13//! - **Dynamic / Proactive MM** (DODO style) — `dynamic` feature
14//! - **Order Book Hybrid** (Phoenix style) — `order-book` feature
15//!
16//! # Feature Flags
17//!
18//! | Feature | Default | Description |
19//! |---------|---------|-------------|
20//! | `std` | yes | Standard library support |
21//! | `fixed-point` | no | I80F48 fixed-point arithmetic |
22//! | `float` | no | f64 floating-point (implies `std`) |
23//! | `all-pools` | yes | Enables all six pool types |
24//!
25//! # Quick Start
26//!
27//! Add to your `Cargo.toml`:
28//!
29//! ```toml
30//! [dependencies]
31//! hydra-amm = "0.1"
32//! ```
33//!
34//! To use only specific pool types:
35//!
36//! ```toml
37//! [dependencies]
38//! hydra-amm = { version = "0.1", default-features = false, features = ["std", "constant-product"] }
39//! ```
40//!
41//! ## Create a pool and execute a swap
42//!
43//! ```rust
44//! use hydra_amm::config::{AmmConfig, ConstantProductConfig};
45//! use hydra_amm::domain::{
46//! Amount, BasisPoints, Decimals, FeeTier, SwapSpec,
47//! Token, TokenAddress, TokenPair,
48//! };
49//! use hydra_amm::factory::DefaultPoolFactory;
50//! use hydra_amm::traits::SwapPool;
51//!
52//! // 1. Define two tokens
53//! let usdc = Token::new(
54//! TokenAddress::from_bytes([1u8; 32]),
55//! Decimals::new(6).expect("valid decimals"),
56//! );
57//! let weth = Token::new(
58//! TokenAddress::from_bytes([2u8; 32]),
59//! Decimals::new(18).expect("valid decimals"),
60//! );
61//!
62//! // 2. Build a Constant Product pool configuration
63//! let pair = TokenPair::new(usdc, weth).expect("distinct tokens");
64//! let fee = FeeTier::new(BasisPoints::new(30)); // 0.30%
65//! let config = AmmConfig::ConstantProduct(
66//! ConstantProductConfig::new(pair, fee, Amount::new(1_000_000), Amount::new(1_000_000))
67//! .expect("valid config"),
68//! );
69//!
70//! // 3. Create the pool via the factory
71//! let mut pool = DefaultPoolFactory::create(&config).expect("pool created");
72//!
73//! // 4. Execute a swap (sell 10 000 units of token A for token B)
74//! let spec = SwapSpec::exact_in(Amount::new(10_000)).expect("non-zero");
75//! let result = pool.swap(spec, usdc).expect("swap succeeded");
76//!
77//! assert!(result.amount_out().get() > 0);
78//! assert!(result.fee().get() > 0);
79//! ```
80//!
81//! # Architecture
82//!
83//! ```text
84//! ┌─────────────┐
85//! │ Consumer │ uses AmmConfig + DefaultPoolFactory
86//! └──────┬──────┘
87//! │ create(&config)
88//! ▼
89//! ┌─────────────┐
90//! │ Factory │ validates config, dispatches to FromConfig
91//! └──────┬──────┘
92//! │ PoolBox (enum dispatch)
93//! ▼
94//! ┌─────────────┐
95//! │ Pools │ ConstantProduct, CLMM, Hybrid, Weighted, Dynamic, OrderBook
96//! └──────┬──────┘
97//! │ SwapPool + LiquidityPool traits
98//! ▼
99//! ┌─────────────┐
100//! │ Domain │ Amount, Price, Tick, Token, SwapResult, …
101//! └─────────────┘
102//! ```
103//!
104//! # Module Guide
105//!
106//! | Module | Purpose |
107//! |--------|---------|
108//! | [`domain`] | Newtype value types: [`Amount`](domain::Amount), [`Price`](domain::Price), [`Token`](domain::Token), etc. |
109//! | [`traits`] | Core abstractions: [`SwapPool`](traits::SwapPool), [`LiquidityPool`](traits::LiquidityPool), [`FromConfig`](traits::FromConfig) |
110//! | [`config`] | Declarative pool blueprints: [`AmmConfig`](config::AmmConfig) and per-pool config structs |
111//! | [`pools`] | Feature-gated pool implementations and [`PoolBox`](pools::PoolBox) dispatch enum |
112//! | [`factory`] | [`DefaultPoolFactory`](factory::DefaultPoolFactory) for config-driven pool construction |
113//! | [`math`] | Checked arithmetic, precision backends, tick math |
114//! | [`error`] | [`AmmError`](error::AmmError) unified error enum |
115//! | [`prelude`] | Convenience re-exports for common types and traits |
116
117// Module declarations (always compiled)
118pub mod config;
119pub mod domain;
120pub mod error;
121pub mod factory;
122pub mod math;
123pub mod pools;
124pub mod prelude;
125pub mod traits;