degenbot_pathfinding/lib.rs
1//! Pure-Rust arbitrage pathfinding graph + depth-first search.
2//!
3//! This crate is a **zero-dependency leaf** — it has no `pyo3`, no `tokio`,
4//! no `alloy`, no `degenbot-core`. The graph operates on plain `u64` token IDs
5//! and pool IDs, making it independently testable without a Python
6//! interpreter and reusable in non-Python Rust code. A standalone Rust
7//! consumer can build a path graph and discover arbitrage cycles without
8//! pulling the engine, the pump, or the RPC stack.
9//!
10//! # Design
11//!
12//! The graph is a multigraph: nodes are token IDs and edges are liquidity
13//! pools, identified by `(pool_id, pool_kind)`. Parallel edges (multiple
14//! pools connecting the same token pair) are naturally supported. The
15//! [`PathGraph`] stores an adjacency list (`HashMap<u64, Vec<Edge>>`)
16//! preserving edge insertion order for deterministic DFS traversal.
17//!
18//! The [`PathGraph::find_paths`] method performs an iterative depth-first
19//! search for all valid cycles from a start token back to an end token,
20//! honoring minimum/maximum depth bounds, per-depth pool-type filters, and
21//! lookahead pruning via precomputed node valid-depth sets.
22//!
23//! # Relationship to the Python module
24//!
25//! The Python `degenbot.pathfinding` module handles database orchestration
26//! (`SQLAlchemy` pool/token queries, address resolution) and calls into this
27//! crate via the `PyO3` binding layer. Address resolution stays in Python
28//! (where `SQLAlchemy` lives); the graph algorithm lives here.
29
30pub mod graph;
31
32pub use graph::{Edge, EdgeKey, OwnedPathFinder, PathFinder, PathGraph, PoolKind};