hft-core 0.1.3

LLM-driven high-frequency trading platform on Solana - PEV loop, Smart Order Routing, SignerContext keypair isolation, and AVM benchmarking via Rig (ARC)
Documentation

hft-core

Optimal High-Frequency Trading Platform - Rig (Rust Inference Gateway / ARC)

[![Crates.io](https://img.shields.io/crates/v/hft-core.svg)](https://crates.io/crates/hft-core)

Docs.rs Rust Edition rig-core Solana CI License: MAI

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
git clone https://github.com/murtazaneuron/hft-core
cd hft-core

# 2. Configure environment
cp .env.example .env
# Optional: set ANTHROPIC_API_KEY=sk-ant-... for live LLM mode
# All subsystems work without a key - see Offline/Stub Mode below

# 3. Build
cargo build --release

# 4. Run - full pipeline, offline stub (no API key needed)
cargo run --release -- --mode full --skip-llm --pair SOL/USDC --amount 1.0

# 5. Run - full pipeline, live LLM (requires ANTHROPIC_API_KEY in .env)
cargo run --release -- --mode full --pair SOL/USDC --amount 1.0

As a library dependency

[dependencies]
hft-core = "0.1"
use hft_core::{config::Config, pev, sor};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let cfg = Config::from_env()?;

    // Smart Order Routing - always works, no API key needed
    let route = sor::best_route("SOL/USDC", 1.0).await?;
    println!("Best venue: {} @ {:.4} USDC", route.venue, route.effective_price);

    // PEV loop - uses offline stubs when ANTHROPIC_API_KEY is absent
    let result = pev::run(&cfg, "SOL/USDC", 1.0).await?;
    println!("PEV passed: {} (score={:.2})", result.passed, result.verify_score);

    Ok(())
}

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-llm is a flag for the compiled binary's clap parser. Never pass it after -- in a cargo test invocation.

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 cargo run --release -- --mode full
RUST_LOG=hft_core=trace cargo run --release -- --mode pev

PEV Loop - Plan โ†’ Execute โ†’ Verify

The PEV loop governs every trade decision. A single pev::run() call:

  1. PLAN - claude-haiku-4-5 decomposes the trade into exactly 4 atomic TradeTask objects:

    Task ID TradeAction Acceptance criteria
    T001 analyse_market Market data retrieved
    T002 select_route Best DEX venue selected
    T003 validate_slippage Slippage within 0.5% tolerance
    T004 simulate_execution Dry-run swap simulation logged
  2. EXECUTE - claude-sonnet-4-6 processes each task, invoking the mapped tool:

    Action Tool call
    analyse_market fetch_price_feed(SOL/USDC)
    select_route query_raydium_pool(), query_orca_pool()
    validate_slippage calculate_slippage(amount)
    simulate_execution jupiter_swap_dry_run()
  3. VERIFY - claude-haiku-4-5 scores 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 hft_core::onchain::signer::{LocalSolanaSigner, with_signer};

# async fn example() -> anyhow::Result<()> {
let signer = LocalSolanaSigner::from_env();
let result = with_signer(signer, || async {
    // CURRENT_SIGNER is only visible inside this async block
    Ok::<&str, anyhow::Error>("swap executed")
   }).await?;
# Ok(()) }

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.toml uses nightly-only options (imports_granularity, group_imports, wrap_comments, etc.) gated by unstable_features = true. Run cargo +nightly fmt locally; the CI fmt job handles this automatically.

Setup

git clone https://github.com/murtazaneuron/hft-core
cd hft-core
cp .env.example .env
# Edit .env: optionally set ANTHROPIC_API_KEY=sk-ant-...

Build commands

cargo build                  # debug build
cargo build --release        # optimised - required for meaningful benchmark timing
cargo check --all-targets    # type-check only, no linking (fastest feedback)
cargo clean                  # remove target/

Release profile (Cargo.toml):

[profile.release]
opt-level     = 3
lto           = true
codegen-units = 1
panic         = "abort"
strip         = "debuginfo"

Test commands

All tests in tests/*.rs are fully deterministic and pass without an API key.

cargo test                                    # all deterministic tests
SKIP_LLM=1 cargo test                         # explicit offline mode
cargo test -- --nocapture                     # with log output to stdout
cargo test --test test_avm_benchmark          # single file
cargo test --test test_pev_loop               # single file
cargo test --test test_signer_context         # single file
cargo test --test test_sor                    # single file

Live provider tests (API key required, #[ignore] in CI):

ANTHROPIC_API_KEY=sk-ant-... \
    cargo test --test providers -- --ignored --test-threads=1

Lint, format, docs

cargo +nightly fmt --all                             # apply formatting (nightly; rustfmt.toml)
cargo +nightly fmt --all -- --check                  # CI format check (nightly rustfmt)
cargo clippy --all-targets -- -D warnings            # lint in CI mode (zero warnings)
cargo doc --open --document-private-items            # browse rustdoc locally
RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo doc   # CI docs check

Coverage (cargo-llvm-cov)

rustfmt uses nightly but all coverage tooling runs on stable.

# Install once
cargo install cargo-llvm-cov --locked
rustup component add llvm-tools-preview

# Full workspace coverage โ†’ lcov.info + coverage-html/
SKIP_LLM=1 cargo llvm-cov --workspace \
  --lcov --output-path lcov.info \
  --ignore-filename-regex 'tests/'
SKIP_LLM=1 cargo llvm-cov report --html --output-dir coverage-html
open coverage-html/index.html

# Quick terminal summary
SKIP_LLM=1 cargo llvm-cov --workspace --summary-only

# Clean stale instrumentation artefacts
cargo llvm-cov clean --workspace

All coverage Zed tasks are self-bootstrapping โ€” they install cargo-llvm-cov and llvm-tools-preview automatically on first run.

Running the binary

# Full pipeline - offline stub
cargo run --release -- --mode full --skip-llm --pair SOL/USDC --amount 1.0

# Full pipeline - live LLM (requires ANTHROPIC_API_KEY)
cargo run --release -- --mode full --pair SOL/USDC --amount 1.0

# Individual subsystems (never need an API key)
cargo run --release -- --mode pev --skip-llm
cargo run --release -- --mode sor
cargo run --release -- --mode signer
cargo run --release -- --mode reactor

# Help
cargo run --release -- --help

Standalone examples

Each example is self-contained and runnable with a single cargo run command.

cargo run --release --example sor_demo        # concurrent SOR, prints winning route
cargo run --release --example signer_demo     # SignerContext isolation across 3 tasks
cargo run --release --example avm_demo        # AVM vs EVM benchmark (use --release)
cargo run --release --example jupiter_dry_run # Jupiter swap simulation + Reactor log

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-preview is installed as part of the toolchain component list
  • cargo-llvm-cov binary is installed via taiki-e/install-action@v2
  • target/ 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


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)