Skip to main content

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;