hft-core
Optimal High-Frequency Trading Platform - Rig (Rust Inference Gateway / ARC)
[](https://crates.io/crates/hft-core)
Built by Murtaza Ali Imtiaz ยท Technology Lead ยท mAI (๐ง ) ยท July 2019 โ Present
A production-grade Rust implementation of an LLM-driven HFT agent framework powered by Rig (ARC) - the high-performance enterprise alternative to Python LLM frameworks. The platform demonstrates end-to-end agentic trade governance through a Plan โ Execute โ Verify (PEV) loop, concurrent Smart Order Routing (SOR) across three Solana DEXs, task-local SignerContext keypair isolation, Jupiter swap simulation, AVM vs EVM execution benchmarking, and a Reactor GUI audit log - all within a single Rust crate that compiles as both a library and a binary.
Architecture
CLI Entry โโโโโโโโโโโโโโโ main.rs (clap: --mode, --pair, --amount, --skip-llm, --live)
โ
โโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ PEV Loop (src/pev/) โ
โ โ
โ PLAN claude-haiku-4-5 โ Vec<TradeTask> (4 tasks) โ
โ โ โ
โ EXECUTE claude-sonnet-4-6 โ ExecuteOutput per task โ
โ โ โ
โ VERIFY claude-haiku-4-5 โ score โ [0,1]; pass โฅ 0.80 โ
โ โ score < 0.80: retry up to 2ร with feedback injected โ
โโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Smart Order Routing (src/sor/) โ
โ โ
โ tokio::join! โโโบ Raydium (25 bps, ~143.52 USDC/SOL) โ
โ โโโบ Orca (30 bps, ~143.48 USDC/SOL) โ
โ โโโบ Serum (20 bps, ~143.61 USDC/SOL) โ
โ โ
โ Cost formula: price ร (1 + fee_bps / 10_000) โ
โ Winner: lowest effective cost โ
โโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ On-chain Execution (src/onchain/) โ
โ โ
โ SignerContext (tokio::task_local!) โโ keypair isolation โ
โ Jupiter swap simulation โโ SIM_<hex> signature โ
โ DRY_RUN=true by default โโ no live txns sent โ
โโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AVM Layer (src/avm/) โ
โ โ
โ Benchmark: AVM JIT (~1โ3 ns/op) vs EVM (~10โ30 ns/op) โ
โ Reactor GUI audit log: STATE BEFORE โ EXECUTION โ AFTER โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Tech Stack
| Layer | Technology | Notes |
|---|---|---|
| AI Agent Framework | rig-core ^0.36 |
Rig / ARC - Rust Inference Gateway |
| LLM - Plan & Verify | claude-haiku-4-5 |
Low-cost model for structured decomposition and scoring |
| LLM - Execute | claude-sonnet-4-6 |
High-capability model for agentic tool-use reasoning |
| Async Runtime | Tokio ^1 (full features) |
Drives all async tasks and task_local! storage |
| Blockchain | Solana (solana-sdk ^3, solana-client ^3) |
Devnet by default; mainnet-ready |
| Token | spl-token ^9 |
Aligned with Solana SDK 3.x |
| Cryptography | ed25519-dalek ^2, k256 ^0.13 |
ECDSA and Ed25519 signing primitives |
| HTTP / TLS | reqwest ^0.13 (rustls) |
JSON requests; rustls avoids OpenSSL dependency |
| CLI | clap ^4 (derive) |
--mode, --pair, --amount, --skip-llm, --live |
| Logging | tracing ^0.1 + tracing-subscriber ^0.3 |
Structured fields; env-filter for RUST_LOG |
| Error handling | anyhow ^1, thiserror ^2 |
?-based propagation throughout |
| Env config | dotenvy ^0.15 |
Loads .env before Config::from_env() |
| IDE | Zed | .zed/settings.json, tasks.json, debug.json |
Quick Start
# 1. Clone and enter
# 2. Configure environment
# Optional: set ANTHROPIC_API_KEY=sk-ant-... for live LLM mode
# All subsystems work without a key - see Offline/Stub Mode below
# 3. Build
# 4. Run - full pipeline, offline stub (no API key needed)
# 5. Run - full pipeline, live LLM (requires ANTHROPIC_API_KEY in .env)
As a library dependency
[]
= "0.1"
use ;
async
CLI Reference
USAGE:
hft-core [OPTIONS]
OPTIONS:
-m, --mode <MODE> Operating mode [default: full]
[possible values: full, pev, sor, signer, reactor]
-p, --pair <PAIR> Trading pair, e.g. SOL/USDC [default: SOL/USDC]
-a, --amount <AMOUNT> Base-token amount [default: 1.0]
--skip-llm Force offline stub mode for PEV phases
Implied automatically when ANTHROPIC_API_KEY is absent
--live Enable live on-chain transactions (dry-run by default)
-h, --help Print help
Modes
| Mode | Subsystems exercised | API key required? |
|---|---|---|
full |
PEV loop โ SOR โ Jupiter swap โ AVM audit log | No (stub) / Yes (live LLM) |
pev |
PEV loop only | No (stub) / Yes (live LLM) |
sor |
Smart Order Routing only | No |
signer |
SignerContext isolation demo | No |
reactor |
AVM benchmark + Reactor audit log | No |
Offline / Stub Mode
Every subsystem runs without an ANTHROPIC_API_KEY. When a key is absent (or
--skip-llm is passed), the PEV phases substitute deterministic offline stubs:
| Phase | Live path | Stub path |
|---|---|---|
| Plan | Haiku decomposes to JSON via API | Returns default_tasks() - 4 canonical tasks |
| Execute | Sonnet reasons and calls tools | Returns fixed ExecuteOutput; confidence = 0.90 |
| Verify | Haiku scores against criteria | Returns score = 0.90, feedback = "all criteria assumed met" |
SOR, SignerContext, Jupiter dry-run, and AVM benchmark are unaffected - they never
require an API key.
Stub mode is activated by any of the following:
| Method | When to use |
|---|---|
Leave ANTHROPIC_API_KEY blank in .env |
Default; no key provisioned |
--skip-llm CLI flag |
Force stub for a single cargo run invocation |
SKIP_LLM=1 cargo run |
Force stub via environment variable |
SKIP_LLM=1 set permanently in .env |
Always-on for a whole checkout |
Important -
cargo test:--skip-llmis a flag for the compiled binary's clap parser. Never pass it after--in acargo testinvocation.cargo test -- --skip-llm # โ WRONG - test harness rejects it SKIP_LLM=1 cargo test # โ correct
Environment Variables
All variables are optional. Config::from_env() is infallible - every variable has a
safe default.
| Variable | Default | Description |
|---|---|---|
ANTHROPIC_API_KEY |
"" |
Anthropic API key for rig-core. Absent โ skip_llm = true; all PEV phases use stubs. |
SKIP_LLM |
false |
Set to 1 or true to force stub mode even when a key is present. |
SOLANA_RPC_URL |
https://api.devnet.solana.com |
Solana JSON-RPC endpoint. |
SOLANA_PRIVATE_KEY |
DEMO_KEY_PLACEHOLDER |
Base-58 encoded keypair for signing. In production load from a secrets manager. |
DRY_RUN |
true |
When true, all on-chain operations are simulated and no real transactions are broadcast. |
Log level defaults to hft_core=debug. Override at runtime:
RUST_LOG=debug
RUST_LOG=hft_core=trace
PEV Loop - Plan โ Execute โ Verify
The PEV loop governs every trade decision. A single pev::run() call:
-
PLAN -
claude-haiku-4-5decomposes the trade into exactly 4 atomicTradeTaskobjects:Task ID TradeActionAcceptance criteria T001analyse_marketMarket data retrieved T002select_routeBest DEX venue selected T003validate_slippageSlippage within 0.5% tolerance T004simulate_executionDry-run swap simulation logged -
EXECUTE -
claude-sonnet-4-6processes each task, invoking the mapped tool:Action Tool call analyse_marketfetch_price_feed(SOL/USDC)select_routequery_raydium_pool(),query_orca_pool()validate_slippagecalculate_slippage(amount)simulate_executionjupiter_swap_dry_run() -
VERIFY -
claude-haiku-4-5scores the output against criteria.- Pass threshold: โฅ 0.80
- On failure: feedback is injected into the next attempt
- Max retries per task: 2
Cost model: Haiku handles cheap plan and verify work; Sonnet is reserved for reasoning-heavy execution. This cuts LLM cost by roughly 60โ70% compared with an all-Sonnet pipeline.
Smart Order Routing (SOR)
sor::best_route() fans out to all three venues simultaneously using
tokio::join!, then selects the winner by effective cost:
effective_cost = price ร (1 + fee_bps / 10_000)
| Venue | Price (SOL/USDC) | Fee | Price impact | Simulated latency |
|---|---|---|---|---|
| Raydium | 143.52 | 25 bps | 0.03% | 12 ms |
| Orca | 143.48 | 30 bps | 0.02% | 9 ms |
| Serum (OpenBook) | 143.61 | 20 bps | 0.05% | 15 ms |
If all venue queries fail, a Raydium-fallback route is returned so the pipeline is
never blocked.
On-chain Execution & SignerContext
SignerContext (src/onchain/signer.rs)
Uses tokio::task_local! to scope a solana_sdk::signature::Keypair to exactly one
Tokio task. Multiple concurrent trades cannot share or leak each other's signing keys,
with no mutex overhead.
use ;
# async
Jupiter Swap Simulation (src/onchain/jupiter.rs)
simulate_swap() computes output without sending any RPC call:
output_amount = input_amount ร effective_price
fee_paid = input_amount ร fee_bps / 10_000
simulated_sig = "SIM_" + 16-char random hex
is_dry_run = true is always set in demo mode. Pass --live to attempt live mode
(returns Err in this demo build - production wiring is in progress).
AVM Benchmark & Reactor Audit Log
AVM vs EVM Benchmark (src/avm/benchmark.rs)
Runs 10 000 iterations of each engine and logs ns/op and the speedup ratio:
| Engine | Method | Typical result |
|---|---|---|
| AVM (Agave JIT) | #[inline(always)], stack-only arithmetic, zero heap allocation |
~1โ3 ns/op |
| EVM (bytecode) | #[inline(never)], one Vec allocation per call |
~10โ30 ns/op |
Run with --release for meaningful timing; debug builds omit optimisations.
Reactor GUI Audit Log (src/avm/reactor.rs)
Emits a structured three-phase execution trace at INFO level:
[REACTOR GUI] โโ STATE BEFORE โโ Balance, pool, price, fee
[REACTOR GUI] โโ EXECUTION โโ Method, compute units, AVM mode, signature
[REACTOR GUI] โโ STATE AFTER โโ Output amount, fee paid, status: SUCCESS
Build & Test
Prerequisites
| Requirement | Version | Install |
|---|---|---|
| Rust stable | โฅ 1.97.1 (MSRV) | rustup update stable |
| Rust nightly | any recent | rustup toolchain install nightly --component rustfmt |
clippy |
bundled with stable | rustup component add clippy |
llvm-tools-preview |
bundled with stable | rustup component add llvm-tools-preview |
cargo-llvm-cov |
latest | cargo install cargo-llvm-cov --locked |
ANTHROPIC_API_KEY |
- | Optional. Absent โ offline stub mode. Required only for #[ignore] live tests. |
Note on nightly rustfmt:
rustfmt.tomluses nightly-only options (imports_granularity,group_imports,wrap_comments, etc.) gated byunstable_features = true. Runcargo +nightly fmtlocally; the CIfmtjob handles this automatically.
Setup
# Edit .env: optionally set ANTHROPIC_API_KEY=sk-ant-...
Build commands
Release profile (Cargo.toml):
[]
= 3
= true
= 1
= "abort"
= "debuginfo"
Test commands
All tests in tests/*.rs are fully deterministic and pass without an API key.
SKIP_LLM=1
Live provider tests (API key required, #[ignore] in CI):
ANTHROPIC_API_KEY=sk-ant-... \
Lint, format, docs
RUSTDOCFLAGS="--cfg docsrs -D warnings"
Coverage (cargo-llvm-cov)
rustfmt uses nightly but all coverage tooling runs on stable.
# Install once
# Full workspace coverage โ lcov.info + coverage-html/
SKIP_LLM=1
SKIP_LLM=1
# Quick terminal summary
SKIP_LLM=1
# Clean stale instrumentation artefacts
All coverage Zed tasks are self-bootstrapping โ they install
cargo-llvm-covandllvm-tools-previewautomatically on first run.
Running the binary
# Full pipeline - offline stub
# Full pipeline - live LLM (requires ANTHROPIC_API_KEY)
# Individual subsystems (never need an API key)
# Help
Standalone examples
Each example is self-contained and runnable with a single cargo run command.
Zed IDE Configuration (.zed/)
Three project-local config files are provided for Zed:
| File | Contents |
|---|---|
.zed/settings.json |
rust-analyzer tuned to rustfmt.toml and .clippy.toml; format-on-save; inlay hints; import grouping matching imports_granularity = "Crate" |
.zed/tasks.json |
tasks covering build, test (per-file + live providers), lint, fmt, doc, run (all 5 modes), all 4 examples, and a one-shot local CI simulation |
.zed/debug.json |
CodeLLDB debug configurations: all binary modes (dev + release), all 4 integration test files (via --no-run + glob program path), and tooling checks |
CI Pipeline
.github/workflows/ci.yml runs on every push and pull request to main.
The pipeline has two parallel jobs:
fmt job โ nightly rustfmt
Runs independently so the nightly toolchain never interferes with the matrix job.
rustfmt.toml requires unstable_features = true and a nightly rustfmt binary.
| Step | Command |
|---|---|
| 1 | cargo fmt --all -- --check (via dtolnay/rust-toolchain@nightly) |
ci job โ stable + MSRV matrix (stable, 1.97.1)
| Step | Command | What it enforces |
|---|---|---|
| 1 | cargo clippy --all-targets -- -D warnings |
Zero lint warnings (stable only) |
| 2 | cargo build --release |
Release binary compiles |
| 3 | SKIP_LLM=1 cargo test --workspace |
All deterministic tests pass |
| 4 | cargo llvm-cov --workspace --lcov โฆ |
Coverage report + lcov.info (stable only) |
| 5 | Upload coverage-html/ |
HTML artifact retained 30 days |
| 7 | RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo doc |
Docs compile without warnings (stable only) |
| MSRV | full build + test on 1.97.1 |
Minimum supported Rust version enforced |
Coverage notes:
llvm-tools-previewis installed as part of the toolchain component listcargo-llvm-covbinary is installed viataiki-e/install-action@v2target/is intentionally not cached โ at ~3 GB it causes step-timeout cancellations; the registry cache (~100 MB) is sufficient
Repository Structure
hft-core/
hft-core/
โโโ Cargo.toml Rust 2024; MSRV 1.97.1; all deps; [lints] table; [lib]
โโโ rustfmt.toml 100-col, Rust 2024 edition, crate-level import grouping
โโโ .clippy.toml MSRV 1.97.1, cognitive-complexity 30
โโโ .env.example All optional env vars (ANTHROPIC_API_KEY, SOLANA_RPC_URL, โฆ)
โโโ LICENSE-MIT MIT licence
โโโ LICENSE-APACHE Apache 2.0 licence
โโโ README.md This file
โโโ CHANGELOG.md Version history and fix log
โโโ CONTRIBUTING.md Development workflow and code-style guide
โ
โโโ .github/workflows/
โ โโโ ci.yml fmt (nightly) โฅ clippy โ build โ test โ coverage โ docs โ MSRV
โ
โโโ examples/
โ โโโ sor_demo.rs SOR across 3 venues - no API key needed
โ โโโ signer_demo.rs SignerContext isolation - no API key needed
โ โโโ avm_demo.rs AVM benchmark - run with --release
โ โโโ jupiter_dry_run.rs Jupiter swap + Reactor log - no API key needed
โ
โโโ src/
โ โโโ lib.rs Crate root; re-exports all 5 modules
โ โโโ main.rs Binary entry; CLI (clap)
โ โโโ config.rs Config::from_env(); skip_llm; has_api_key()
โ โโโ pev/ Plan โ Execute โ Verify loop
โ โ โโโ mod.rs Orchestrator; MAX_RETRIES = 2
โ โ โโโ types.rs TradeTask, TradeAction, ExecuteOutput, PEVResult
โ โ โโโ plan.rs Haiku decomposition; default_tasks_pub()
โ โ โโโ execute.rs Sonnet execution; action_tool_calls()
โ โ โโโ verify.rs Haiku scoring; PASS_THRESHOLD = 0.80
โ โโโ sor/ Smart Order Routing
โ โ โโโ mod.rs pub use router::best_route
โ โ โโโ router.rs tokio::join! fan-out; cost ranking; Route struct
โ โ โโโ raydium.rs Stub - Raydium CLMM SDK adapter
โ โ โโโ orca.rs Stub - Orca Whirlpool adapter
โ โ โโโ serum.rs Stub - OpenBook CLOB adapter
โ โโโ onchain/ On-chain execution
โ โ โโโ mod.rs execute_swap(); demo_signer()
โ โ โโโ signer.rs LocalSolanaSigner; with_signer(); task_local!
โ โ โโโ jupiter.rs simulate_swap(); SwapResult; SIM_ signature
โ โ โโโ balance.rs Stub - sol_balance / token_balance
โ โ โโโ types.rs Stub - Lamports, TokenAmount, TxStatus
โ โโโ avm/ AVM execution layer
โ โโโ mod.rs run_benchmark(); audit_log()
โ โโโ benchmark.rs AVM JIT vs EVM, 10 000 iterations
โ โโโ reactor.rs Reactor GUI audit log (3-phase structured trace)
โ
โโโ tests/
โโโ test_pev_loop.rs 10 tests - Config, PEV stub paths, types
โโโ test_sor.rs 3 tests - best_route, cost ordering, latency
โโโ test_signer_context.rs 2 tests - SignerContext isolation, Jupiter dry-run
โโโ test_avm_benchmark.rs 1 test - benchmark smoke test
โโโ providers/
โโโ anthropic.rs 2 tests - live, #[ignore], requires ANTHROPIC_API_KEY
Key Design Decisions
| Decision | Rationale |
|---|---|
| Lib + bin targets from the same source tree | Integration tests are separate crates; hft_core:: is the correct import prefix |
| Rust 2024 edition | Matches the rig upstream repository |
| Haiku for Plan + Verify, Sonnet for Execute | 60โ70% cost reduction vs all-Sonnet; Haiku handles structured, low-complexity steps |
CompletionClient + ProviderClient in all PEV files |
Both required by rig-core โฅ 0.36 for .agent() method resolution |
Client::new(&key)? not Arc::new(Client::new(...)) |
Client::new is fallible in rig-core 0.36+ |
tokio::task_local! with // not /// |
rustdoc cannot attach to macro invocation sites |
#[ignore] on live provider tests |
Prevents CI failures when ANTHROPIC_API_KEY is absent |
strip = "debuginfo" in release profile |
Smaller binary; mirrors rig's own release profile |
CARGO_INCREMENTAL=0 for release builds |
Required when lto = true |
| Fallback route on all-venue failure | Pipeline never blocked by transient DEX outages |
MIT OR Apache-2.0 licence |
SPDX-compliant dual licence for crates.io publication |
Related
- Star Story - project narrative
- Architecture Diagram - deep-dive system design
- Screen Capture Guide - key output walkthroughs
- Rig Framework ยท 0xPlaygrounds/rig
- Solana Program Library
- Jupiter Aggregator ยท Raydium ยท Orca
- arc.fun ยท Ryzome
License
Proprietary - ยฉ 2026 Murtaza Ali Imtiaz / mAI (๐ง )
See LICENSE-MAI for permitted use.
Licensed under:
Author
Murtaza Ali Imtiaz ยท Technology Lead ยท mAI (๐ง ) ยท (July 2019 โ Present)
- GitHub: @murtazaneuron
- LinkedIn: linkedin.com/in/murtazai
- Portfolio: murtazai.com