stealth/CONTRIBUTING.md

Contributing to Stealth

Contributions are welcome. This document explains how to set up the project, submit changes, and what we expect during code review.

Before you start

• Open an issue first for non-trivial changes so we can discuss the approach before you invest time writing code.
• Keep PRs focused — one concern per pull request.
• Stay aligned with the project's philosophy — Stealth is a local-first, privacy-preserving analysis engine. Changes that introduce external service dependencies or move away from this model are generally not a good fit.

See GOVERNANCE.md for how decisions are made.

Setup

Requirements

• Rust (stable, >= 1.93.1)
• Bitcoin Core (>= 29.0) — needed for integration tests

Building

cargo build --workspace

Running tests

cargo test --workspace

Integration tests start a local bitcoind in regtest mode automatically via corepc-node.

Code formatting and linting

CI enforces both. Run these before pushing:

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Formatting rules are defined in rustfmt.toml (100-char line width, 4-space indentation).

Submitting a pull request

1. Fork the repository and create a branch from main.
2. Write your code, add tests if applicable.
3. Make sure cargo fmt, cargo clippy, and cargo test pass.
4. Open a pull request against main.

Commit messages

Use conventional commits format:

feat(engine): add peeling chain detector
fix(bitcoincore): handle missing address in listunspent
refactor(model): extract WalletHistory builder
test(engine): add CIOH edge case
docs: update README with CLI usage

During review

Once your PR is open and under review:

• Do not rebase or force-push. If you need to make changes, add new commits. Force-pushing destroys the review context — reviewers lose track of what changed between rounds and have to start over.
• Do not squash commits during review. Keep fixup commits separate so reviewers can see exactly what changed in response to each comment.

This follows the same approach used by Envoy, LLVM, and Miri.

Project structure

stealth/
  model/          # Shared types, traits, configuration (stealth-model)
  engine/         # Detection engine, heuristics, TxGraph (stealth-engine)
  bitcoincore/    # Bitcoin Core RPC gateway (stealth-bitcoincore)

What we look for in code

• Use bitcoin crate types (Txid, Address, Amount) instead of raw strings and floats.
• Prefer borrowing (&) over .clone() when you only need to read.
• Prefer generics over dyn trait objects when the concrete type is known at compile time.
• Keep thresholds and constants configurable via DetectorThresholds, not hardcoded.
• All detectors should be covered by integration tests.

License

By contributing, you agree that your contributions will be licensed under the MIT License.