From e6fd6ceb90fd66dc59f0041eff470df9f744e08c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 3 Dec 2025 08:52:52 +0000 Subject: [PATCH 1/3] Initial plan From f4731c8de7303203b183dac27f86ba2129704da9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 3 Dec 2025 08:57:05 +0000 Subject: [PATCH 2/3] feat: add Copilot instructions file Co-authored-by: sfroment <7238385+sfroment@users.noreply.github.com> --- .github/copilot-instructions.md | 238 ++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..0d2e61d --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,238 @@ +# Copilot Instructions for Mojave + +## Project Overview + +**Mojave** is a new layer built on top of Bitcoin. It brings scalability, programmability, and fast transaction speed without compromising Bitcoin's core strengths: security and decentralization. + +This is a Rust-based blockchain infrastructure project organized as a Cargo workspace with multiple binaries (node, sequencer, prover) and supporting libraries. + +## Tech Stack + +- **Language**: Rust (nightly toolchain) +- **Build System**: Cargo workspace +- **Task Runner**: `just` (justfile) +- **Core Dependencies**: + - ethrex (custom fork for blockchain/EVM functionality) + - Bitcoin libraries (bitcoin, bitcoincore-rpc) + - Async runtime: tokio + - RPC: axum + - Serialization: serde, bincode + - Cryptography: secp256k1, ed25519-dalek + - Messaging: zeromq + - Error handling: thiserror, anyhow + +## Project Structure + +The repository follows a strict structure: + +``` +.github/workflows/ # CI/CD workflows +cmd/ # All runnable binaries (node, sequencer, prover) +crates/ # Reusable libraries (no top-level binaries) +data/ # Chain configs and genesis files +tests/ # E2E test fixtures and scripts +scripts/ # Utility scripts +justfile # Common development tasks +``` + +### Key Principles + +- **Keep binaries thin, libraries fat**: Business logic belongs in `crates/`, not in `cmd/` +- **Each binary in `cmd/`**: Has `main.rs` (minimal), `cli.rs` (clap-based), and delegates to library crates +- **Library structure**: Each crate has `lib.rs`, `error.rs`, `types.rs`, and domain modules +- **No unsafe code** without justification and `// SAFETY:` comments +- **Explicit error handling**: Use `thiserror` for domain errors, `anyhow::Result` only at binary boundaries + +## Coding Standards + +### Code Style + +- **Format**: Always run `cargo fmt` before committing (uses `rustfmt.toml` config) +- **Imports**: Use `imports_granularity = "Crate"` (configured in rustfmt.toml) +- **Linting**: Run `cargo clippy --all-targets --all-features --workspace -- -D warnings` +- **Comments**: Add comments only when they match existing style or explain complex logic +- **Naming**: Follow Rust API Guidelines +- **Functions**: Prefer small, composable functions + +### Error Handling + +```rust +// In libraries: use thiserror +pub type Result = core::result::Result; + +#[derive(thiserror::Error, Debug)] +pub enum Error { + #[error("rpc failed: {0}")] + Rpc(#[from] rpc::Error), + #[error("config invalid: {0}")] + Config(String), +} + +// In binaries: use anyhow::Result at boundaries only +``` + +### Types and Serialization + +- Define types in `types.rs` with serde support +- Use `#[serde(deny_unknown_fields)]` for untrusted input +- Prefer type wrappers for IDs/Keys over naked `String`/`Vec` + +### Module Organization + +- One file per concern: `error.rs`, `types.rs`, `context.rs`, `service.rs` +- Use `mod.rs` only for directory roots +- Re-export public APIs in `lib.rs` or `prelude` module + +## Building and Testing + +### Commands + +```bash +# Build the project +cargo build +cargo build --release + +# Run tests +cargo test --workspace + +# Run E2E tests +bash tests/tests-e2e.sh + +# Format code +cargo fmt --all + +# Lint code +cargo clippy --all-targets --all-features --workspace -- -D warnings + +# Using justfile +just build # Build in debug mode +just lint # Format check + clippy +just test # Run E2E tests +just fix # Auto-fix issues (fmt, clippy, etc.) +``` + +### Test Organization + +- Unit tests: Colocated with code using `#[cfg(test)]` +- Integration tests: In `crates/tests/tests/*.rs` +- E2E tests: In `/tests/` directory with bash scripts + +### CI Requirements + +All PRs must pass: +- `cargo build --workspace --locked` +- `cargo test --workspace` +- `cargo fmt --all --check` +- `cargo clippy --workspace --all-features --all-targets --no-deps -- -D warnings` +- PR title must follow Conventional Commits format + +## Git Workflow + +### Branch Naming + +- Feature branches: `feature/` +- Bug fixes: `fix/` +- Copilot branches: `copilot/` + +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/) format: +- `feat:` - New features +- `fix:` - Bug fixes +- `chore:` - Maintenance tasks +- `refactor:` - Code improvements without changing functionality +- `test:` - Test additions or updates +- `docs:` - Documentation changes +- `perf:` - Performance improvements + +### Pull Request Guidelines + +- Keep PRs focused - one change per PR +- PR titles must follow Conventional Commits format +- Add tests for new functionality or bug fixes +- Ensure all CI checks pass before submitting +- Update documentation if relevant + +## Boundaries and Security + +### What Copilot SHOULD Do + +- Implement features according to the project structure guidelines +- Add unit and integration tests for new code +- Follow existing code patterns and conventions +- Update documentation when making changes +- Use workspace dependencies defined in root `Cargo.toml` +- Apply appropriate error handling patterns + +### What Copilot SHOULD NOT Do + +- **Never commit secrets, private keys, or credentials** +- **Never modify `.env` files** (only `.env.example` is acceptable) +- **Never introduce unsafe code** without explicit justification +- **Never use `unwrap()` or `expect()` outside of tests** +- **Never add new external dependencies** without checking if a workspace dependency exists +- **Never modify the core project structure** (cmd/, crates/ layout) +- **Never bypass existing error handling patterns** +- **Never modify configuration files** in `/data/` without clear requirements +- **Never add non-additive feature flags** that break existing functionality + +## Common Tasks + +### Adding a New Binary + +1. Create directory in `cmd//` +2. Add `main.rs` (minimal, just wiring) +3. Add `cli.rs` with clap-based CLI +4. Add to workspace members in root `Cargo.toml` +5. Implement logic in appropriate `crates/` library + +### Adding a New Library Crate + +1. Create directory in `crates//` +2. Create `Cargo.toml` with workspace inheritance +3. Add standard structure: `lib.rs`, `error.rs`, `types.rs` +4. Add to workspace members and dependencies in root `Cargo.toml` +5. Document public APIs + +### Adding Dependencies + +1. Check if the dependency exists in workspace `[workspace.dependencies]` +2. If yes, reference it from your crate's `Cargo.toml` +3. If no, add to workspace dependencies first, then reference +4. Pin major versions and avoid heavy default features +5. Document reason for new dependencies + +## Configuration + +- **Source order**: CLI args > Config file > Environment (.env) > Code defaults +- **Validation**: Validate configuration early with actionable error messages +- **Environment**: Use `.env.example` as template, never commit `.env` + +## Logging + +- Use `mojave-utils::logging::init()` for tracing initialization +- Respect `RUST_LOG` environment variable +- Use structured logging with `tracing` crate +- Add context to errors at boundaries using `anyhow::Context` + +## Documentation + +- Document all public functions with rustdoc comments +- Include examples in documentation where helpful +- Keep `PROJECT_STRUCTURE.md` updated for structural changes +- Update `README.md` for user-facing changes +- Keep `CONTRIBUTING.md` updated for process changes + +## Resources + +- [LICENSE](../LICENSE) - MIT License +- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines +- [PROJECT_STRUCTURE.md](../PROJECT_STRUCTURE.md) - Detailed project structure +- [README.md](../README.md) - Project overview and quickstart + +## Questions? + +For questions about Mojave: +- [Telegram](https://t.me/mojavezk) +- [Discord](https://discord.gg/wR4srtyhuU) +- [GitHub Issues](https://github.com/1sixtech/mojave/issues) From 9226a48a416f5b669bc8cf5c64c221542b9d21ce Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 3 Dec 2025 08:59:05 +0000 Subject: [PATCH 3/3] docs: clarify test directory naming in copilot-instructions.md Co-authored-by: sfroment <7238385+sfroment@users.noreply.github.com> --- .github/copilot-instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0d2e61d..bf1ec73 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -30,7 +30,7 @@ The repository follows a strict structure: cmd/ # All runnable binaries (node, sequencer, prover) crates/ # Reusable libraries (no top-level binaries) data/ # Chain configs and genesis files -tests/ # E2E test fixtures and scripts +tests/ # E2E test fixtures and scripts (actual directory name) scripts/ # Utility scripts justfile # Common development tasks ``` @@ -115,7 +115,7 @@ just fix # Auto-fix issues (fmt, clippy, etc.) - Unit tests: Colocated with code using `#[cfg(test)]` - Integration tests: In `crates/tests/tests/*.rs` -- E2E tests: In `/tests/` directory with bash scripts +- E2E tests: In `/tests/` directory with bash scripts (note: some docs reference `test_data/` but actual directory is `tests/`) ### CI Requirements