rara-strategies

Autonomous trading strategy repository for rara-trading.

Strategies are WASM-compiled Rust crates, iterated by LLM agents and validated through CI + backtesting.

Prerequisites

# Rust toolchain with WASM target
rustup target add wasm32-wasip1

# Install the strategy CLI
cargo install --path crates/rara-strategy-cli

# Verify
rara-strategy --version

Quick Start

# 1. Create a strategy
rara-strategy create my-strategy --description "My trading strategy"

# 2. Edit the logic
$EDITOR strategies/my-strategy/src/logic.rs

# 3. Validate (clippy + WASM build + fmt)
rara-strategy check my-strategy

# 4. Backtest with candle data
rara-strategy backtest my-strategy --candles data/btcusdt-1h.json

# 5. Promote to paper trading (requires sharpe > 1.0, drawdown < 0.15)
./scripts/promote.sh --strategy my-strategy --stage paper

Project Structure

rara-strategies/
├── crates/
│   ├── strategy-api/       # Shared types: Candle, Signal, RiskLevels, Side
│   ├── factor-lib/         # Reusable technical indicators (SMA, EMA, RSI, …)
│   ├── wasm-glue/          # WASM ABI glue (auto-generated, never edit)
│   └── rara-strategy-cli/  # CLI tool for all strategy operations
├── strategies/             # One cdylib crate per strategy → compiles to WASM
│   ├── btc-momentum/
│   ├── hmm-regime/
│   └── rsi-reversion/
├── templates/strategy/     # cargo-generate template for new strategies
├── benchmarks/             # Backtest results (results.json)
├── features/               # BDD acceptance specs (cucumber-rs)
├── scripts/
│   ├── promote.sh          # Lifecycle promotion via git tags
│   └── update-benchmark.sh # Write backtest results to benchmarks/
└── docs/
    ├── guides/             # Development workflow, style guides
    └── prompts/            # LLM prompts for strategy generation

CLI Reference

All commands output JSON to stdout. Logs go to stderr.

rara-strategy create

Scaffold a new strategy from template (idempotent).

rara-strategy create my-strategy --description "RSI mean-reversion on BTC"

rara-strategy build

Compile strategies to WASM (wasm32-wasip1).

rara-strategy build my-strategy    # single strategy
rara-strategy build                # all strategies

rara-strategy list

List all strategies with metadata and lifecycle stage.

rara-strategy list

rara-strategy check

Run clippy + WASM build + fmt check.

rara-strategy check my-strategy    # single strategy
rara-strategy check                # all strategies

rara-strategy backtest

Run backtest via built-in WASM engine or external runner.

# Built-in engine with candle data file
rara-strategy backtest my-strategy --candles data/btcusdt-1h.json

# With date range and symbol context
rara-strategy backtest my-strategy \
  --candles data/btcusdt-1h.json \
  --symbol BTCUSDT \
  --timeframe 1h \
  --start 2024-01-01 \
  --end 2024-06-01

# Record results to benchmarks/
rara-strategy backtest my-strategy --candles data/btcusdt-1h.json --record

# External runner (or set RARA_BACKTEST_RUNNER env var)
rara-strategy backtest my-strategy --runner "my-runner --wasm {wasm} --symbol {symbol}"

Runner template placeholders: {strategy}, {wasm}, {symbol}, {timeframe}, {start}, {end}, {status}

Strategy Development

Every strategy has two files:

File	Purpose	Edit?
src/logic.rs	Trading logic — your code	Yes
src/lib.rs	WASM glue (auto-generated)	Never

The Three Functions

Implement these in src/logic.rs:

use strategy_api::{API_VERSION, Candle, RiskLevels, Side, Signal, StrategyMeta};

/// Strategy metadata.
pub fn meta() -> StrategyMeta { /* name, version, description */ }

/// Core trading logic — receives candles (oldest first), returns a signal.
pub fn on_candles(candles: &[Candle]) -> Signal { /* Entry / Exit / Hold */ }

/// Risk management — compute stop-loss and take-profit from entry price.
pub fn risk_levels(entry_price: f64, side: Side) -> RiskLevels { /* stop, target */ }

Factor Library

crates/factor-lib provides reusable technical indicators:

Factor	Module	Description
SmaFactor	sma	Simple moving average
EmaFactor	ema	Exponential moving average
RsiFactor	rsi	Wilder's RSI (0–100)
MomentumFactor	momentum	Price rate of change
VolatilityFactor	volatility	Bollinger breakout ratio
VolumeSurgeFactor	volume	Volume vs SMA ratio
MeanReversionFactor	mean_reversion	Distance from SMA

use factor_lib::{Factor, rsi::RsiFactor, sma::SmaFactor};

let rsi = RsiFactor::new(14).compute(candles);
let sma = SmaFactor::new(20).compute(candles);

See docs/guides/factor-development.md for creating new factors.

Strategy Lifecycle

research → backtest passes → paper trading → live trading
                                    ↓
                                archived

Promotion via Git Tags

# Research → Paper (requires sharpe > 1.0, max_drawdown < 0.15)
./scripts/promote.sh --strategy my-strategy --stage paper

# Paper → Live
./scripts/promote.sh --strategy my-strategy --stage live

# Demote
./scripts/promote.sh --strategy my-strategy --stage archived

Tag format: {stage}/{strategy}/v{N} — version auto-increments.

Backtest Metrics

The backtest command produces these metrics:

Metric	Description	Promotion Threshold
sharpe_ratio	Risk-adjusted return	> 1.0
max_drawdown	Largest peak-to-trough decline	< 0.15
win_rate	Fraction of winning trades	—
pnl	Net profit/loss	—
trade_count	Number of executed trades	—

Testing

Unit Tests

Each strategy should have tests in src/logic.rs covering metadata, insufficient data, entry/exit signals, and risk levels.

cargo test -p my-strategy

BDD Acceptance Tests

This project uses cucumber-rs scaffolded by rara-bdd.

cargo test --test bdd              # Run BDD tests
rara-bdd coverage                  # Check for missing step definitions
rara-bdd generate                  # Generate step skeletons

Features live in features/*.feature, step definitions in tests/steps/.

CI Pipeline

Every PR runs:

1. Check & Clippy — cargo clippy --all-targets -- -D warnings
2. WASM Build — compile all strategies to wasm32-wasip1
3. BDD Suite — acceptance tests

All checks must pass before merge.

Guides

• Development Workflow — issue → worktree → PR → merge
• Commit Style — conventional commits
• Rust Style — error handling, struct construction, functional style
• Code Comments — doc comment conventions
• Factor Development — creating new indicators
• Strategy Generation Prompt — LLM prompt for new strategies