c54c569f30
Completed clean root directory structure: - Root now contains only: .git, .env, docs/, orig/ - Moved all remaining files and directories to orig/: - Config files (.claude, .dockerignore, .drone.yml, etc.) - All .env variants (except active .env) - Git config (.gitconfig, .github, .gitignore, etc.) - Tool configs (.golangci.yml, .revive.toml, etc.) - Documentation (*.md files, @prompts) - Build files (Dockerfiles, Makefile, go.mod, go.sum) - Docker compose files - All source directories (scripts, tests, tools, etc.) - Runtime directories (logs, monitoring, reports) - Dependency files (node_modules, lib, cache) - Special files (--delete) - Removed empty runtime directories (bin/, data/) V2 structure is now clean: - docs/planning/ - V2 planning documents - orig/ - Complete V1 codebase preserved - .env - Active environment config (not in git) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
42 lines
3.5 KiB
Markdown
42 lines
3.5 KiB
Markdown
# 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.
|