hft_core/lib.rs
1//! # hft-core
2//!
3//! **LLM-driven high-frequency trading platform on Solana**, built on
4//! [Rig (ARC)](https://rig.rs) - the Rust Inference Gateway.
5//!
6//! Combines agentic LLM pipelines with on-chain `DeFi` execution on Solana,
7//! enabling statefully supervised, multi-step agent workflows with full PEV
8//! loop governance.
9//!
10//! > **mAI (π§ )** Β· Technology Lead: Murtaza Ali Imtiaz (July 2019 β present)
11//!
12//! ## Architecture
13//!
14//! ```text
15//! ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
16//! β hft-core β
17//! ββββββββββββ¬βββββββββββ¬ββββββββββββ¬ββββββββββ¬βββββββββββ€
18//! β pev β sor β onchain β avm β config β
19//! β Plan β β Smart β Jupiter β AVM β Env β
20//! β Executeββ Order β swap + β bench- β loader β
21//! β Verify β Routing β Signer β mark β β
22//! ββββββββββββ΄βββββββββββ΄ββββββββββββ΄ββββββββββ΄βββββββββββ
23//! ```
24//!
25//! ## Full pipeline
26//!
27//! 1. **PEV loop** ([`pev`]) - Haiku decomposes the trade into four [`pev::types::TradeTask`]
28//! objects; Sonnet executes each one using tool calls; Haiku verifies the output (pass β₯ 0.80).
29//! Up to two retries on failure.
30//! 2. **SOR** ([`sor`]) - Raydium, Orca, and Serum are queried concurrently; the lowest
31//! cost-adjusted venue wins.
32//! 3. **On-chain** ([`onchain`]) - Jupiter swap is simulated (dry-run by default) inside an
33//! isolated [`onchain::signer::LocalSolanaSigner`] context.
34//! 4. **AVM audit** ([`avm`]) - Reactor GUI audit log records state-before, execution details, and
35//! state-after for every swap.
36//!
37//! ## Quick start
38//!
39//! ```text
40//! cp .env.example .env # set ANTHROPIC_API_KEY (optional - stub mode works without it)
41//! cargo run --release -- --mode full --pair SOL/USDC --amount 1.0
42//! ```
43//!
44//! ## Offline / stub mode
45//!
46//! All subsystems work without an `ANTHROPIC_API_KEY`. When a key is absent
47//! (or `--skip-llm` is passed), every PEV phase substitutes a deterministic
48//! offline stub:
49//!
50//! ```text
51//! SKIP_LLM=1 cargo run --release -- --mode full
52//! ```
53//!
54//! ## Feature flags
55//!
56//! This crate has no optional feature flags. All subsystems are always compiled.
57//!
58//! ## Crate status
59//!
60//! The venue adapters (`raydium.rs`, `orca.rs`, `serum.rs`) and the balance
61//! query helpers (`balance.rs`, `types.rs` in `onchain`) are documented stubs
62//! awaiting real SDK integration. The PEV loop, SOR router, `SignerContext`,
63//! Jupiter dry-run simulation, and AVM benchmark are fully implemented.
64
65pub mod avm;
66pub mod config;
67pub mod onchain;
68pub mod pev;
69pub mod sor;