# Qwen Code Agent Guide

Qwen focuses on the numerical core of the MEV Bot—pricing math, precision, and performance. Follow the shared repository practices first (see `AGENTS.md`) and layer the instructions below when working on math-heavy changes.

## Environment & Setup
- Run `./setup-env.sh` after cloning to provision `.env` and required directories.
- Export temporary secrets before executing simulations: `export MEV_BOT_ENCRYPTION_KEY="$(openssl rand -base64 32)"`, `export ARBITRUM_RPC_ENDPOINT="wss://…"`, `export ARBITRUM_WS_ENDPOINT="wss://…"`.
- Keep `.env` synced with `docs/5_development/CONFIGURATION.md`; avoid committing credentials from `keystore/` or `storage/`.

## Core Commands
- `make build` – compile the service to `bin/mev-bot` for integration checks.
- `.qwen/scripts/math-test.sh` – run the focused math suite (unit/property/fuzz/bench) and archive logs under `.qwen/results/`.
- `.qwen/scripts/math-optimize.sh` & `.qwen/scripts/perf-test.sh` – profile hot paths when tuning algorithms.
- `./scripts/run_audit_suite.sh` – execute the deterministic math audit and refresh `reports/math/latest/report.{json,md}`.
- `make simulate-profit` (or `./scripts/run_profit_simulation.sh`) – replay profitability vectors and review `reports/simulation/latest/summary.{json,md}`.
- `make fmt`, `make lint`, `make vet`, `gosec ./pkg/uniswap/... ./pkg/math/...` – quality gates prior to commits.
- `go tool pprof` against the profiles generated above to validate improvements and regressions.

## Implementation Guidelines
- Keep mathematical helpers inside `pkg/math/` or `pkg/uniswap/` and prefer small, well-documented functions; reference `docs/MATH_OPTIMIZATIONS.md` for canonical formulas.
- Use `math/big` and `github.com/holiman/uint256` where precision demands it; justify alternative types in code comments when trade-offs are made.
- Preserve determinism—no randomness in production math paths. Table-driven tests should cover boundary ticks, precision edge cases, and error handling.
- Target >85% coverage on math packages (CI minimum is 80%); refresh `coverage.out` via `make test-coverage` when significant changes land.

## Testing & Benchmarking
- Default smoke check: `go test ./pkg/math/... ./pkg/uniswap/...`.
- Property/fuzz cases reside in `test/property/` and are exercised by `.qwen/scripts/math-test.sh`; extend those instead of ad-hoc harnesses.
- Use benchmarks (`go test -bench=.` or the Qwen scripts) to record before/after metrics; capture summaries in PRs when performance shifts.

## Workflow & Collaboration
- Branch from `develop` using Conventional Commit scopes: `feat(math): …`, `perf(uniswap): …`, `fix(precision): …`.
- Every commit must pass `make test lint gosec`; mention any precision, coverage, or performance deltas in the commit body or PR description.
- Pull requests should attach command output (especially from the math scripts) and describe assumptions around numerical accuracy.
- Coordinate with security reviewers when touching cryptographic code, rate limiting, or anything under `keystore/`.

## Security & Safety
- Never store keys or RPC secrets in scripts; rely on environment variables sourced locally.
- Validate inputs for overflow/underflow, enforce gas and slippage guards, and keep fallbacks aligned with `PROJECT_SPECIFICATION.md`.
- When generating new fixtures, document the data source and regeneration steps in `test/fixtures/README.md` (or add one if missing).

Stay aligned with the global repository practices, and use this guide as the math-specialist overlay for Qwen-focused contributions.