evm_amm_state/
lib.rs

1//! A real-time AMM state engine built on a forked-EVM state cache
2//! ([`evm_fork_cache`]).
3//!
4//! `evm-amm-state` composes a forked-EVM state cache ([`evm_fork_cache`]) with a
5//! set of protocol [`adapters`] into a pipeline that tracks a working set of
6//! AMMs, cold-starts their on-chain state into the cache, keeps exact-write
7//! protocols current straight from chain log events, and emits bounded repair
8//! requests for protocols whose events don't carry final storage values. Once a
9//! pool's quote read-set is warmed and current, swap simulations run fast and
10//! offline against it.
11//!
12//! The pieces, roughly in pipeline order:
13//!
14//! - [`adapters`] — per-protocol adapters (Uniswap V2, the Uniswap V3 family,
15//!   Balancer V2, Solidly V2, and Curve — StableSwap/NG + CryptoSwap/Tricrypto-NG)
16//!   over a single [`adapters::AmmAdapter`] trait. Each adapter knows how to cold-start
17//!   a pool's storage into an [`evm_fork_cache::cache::EvmCache`], which log
18//!   events to subscribe to, how to apply those events reactively, and how to
19//!   `simulate_swap` against the cached state. The
20//!   [`adapters::AdapterRegistry`] dispatches by pool key, and
21//!   [`adapters::AmmSyncEngine`] drives the resync-capable live path on top of
22//!   [`adapters::AmmReactiveHandler`] and the `evm_fork_cache` reactive runtime.
23//!
24//! See the crate's `examples/adapter_pipeline.rs` for an end-to-end demo that
25//! cold-starts a pool, subscribes to its events over a WebSocket endpoint,
26//! applies them reactively, and simulates a swap against the live-synced state.
27
28// The public API is broad and stability-sensitive; require docs on every public
29// item so the surface stays fully documented as it grows (CI's `-D warnings`
30// promotes this to an error).
31#![warn(missing_docs)]
32// docs.rs builds with `--cfg docsrs` (see `[package.metadata.docs.rs]`), which
33// enables nightly `doc_cfg`: every feature-gated item renders with its
34// "Available on crate feature … only" badge, derived automatically from the
35// existing `#[cfg]`s with no per-item annotations (auto-cfg is part of
36// `doc_cfg` since 1.92, rust-lang/rust#138907). Inert on stable builds.
37#![cfg_attr(docsrs, feature(doc_cfg))]
38
39/// Re-export of [`alloy_primitives`]: the `Address` / `U256` / `B256` / `Log`
40/// vocabulary this crate's API speaks.
41///
42/// Import from here (`evm_amm_state::alloy_primitives`) to use exactly the
43/// version this crate's signatures expect without pinning `alloy-primitives`
44/// yourself.
45pub use alloy_primitives;
46/// Re-export of the [`evm_fork_cache`] companion crate: `EvmCache`, the
47/// reactive runtime, storage programs, and the typed errors that appear on
48/// this crate's driver seam.
49///
50/// `evm-fork-cache` is a 0.x **public dependency**: a semver-breaking bump
51/// there (e.g. 0.2 → 0.3) is necessarily a breaking release of this crate too,
52/// and the two are released in lockstep. Importing it through this re-export
53/// (`evm_amm_state::evm_fork_cache`) guarantees the versions match.
54pub use evm_fork_cache;
55
56// Always compiled — the adapter layer has no heavy deps.
57pub mod adapters;
58
59/// Compiles the README's code samples as doctests so the quickstart cannot
60/// drift from the real API. Exists only under `cfg(doctest)` — it is never
61/// part of the built crate or the rendered docs. Gated on `uniswap-v3`
62/// because the quickstart registers the V3-family adapter; the default and
63/// all-features test runs (local + CI) still compile it.
64#[cfg(all(doctest, feature = "uniswap-v3"))]
65#[doc = include_str!("../README.md")]
66pub struct ReadmeDoctests;
evm_amm_state/lib.rs

evm_amm_state/
lib.rs
