Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
176 lines (123 loc) · 8.79 KB

CONTRIBUTING.md

File metadata and controls

176 lines (123 loc) · 8.79 KB
Raw

Contributing to vero-audit-guard

Thanks for helping harden the Vero watchtower. This document covers local setup, the Docker Compose workflow, and the expected contribution flow.

Prerequisites

For a native (non-Docker) workflow:

  • Rust toolchain (rustup install stable) with cargo
  • Node.js ≥ 20 (CI uses 22) and npm
  • cargo-audit (cargo install cargo-audit --locked)

For the containerised pipeline you only need Docker Engine + Compose v2.

Docker Compose workflow

The root docker-compose.yml starts the local multi-service pipeline described in #279.

First run

cp .env.example .env
docker compose up --build

Compose will:

  1. Build scanner-engine (Rust) and run it against ./docker/sample-target.
  2. Write reports/latest-scan.json on the host via a bind mount.
  3. Run verifiable-audit-trail against that reports directory (dry-run unless AUDIT_KEYPAIR_SECRET is set).
  4. Start atomic-rpc-relayer-bridge on http://localhost:8545 (/health, /metrics, /audit-log).
  5. Start anomaly-detector, which polls http://atomic-rpc-relayer-bridge:8545/metrics on the compose network.

scanner-engine and verifiable-audit-trail are one-shot jobs (restart: "no"). The bridge and detector stay up until you run docker compose down.

Service map

Compose service Dockerfile Default port Notes
scanner-engine scanner-engine/Dockerfile (root build context) — Needs src/audit-guard at build time
anomaly-detector anomaly-detector/Dockerfile (root build context) — Copies the audit-guard TS helpers it imports
atomic-rpc-relayer-bridge atomic-rpc-relayer-bridge/Dockerfile 8545 Local metrics server (npm run start:local)
verifiable-audit-trail verifiable-audit-trail/Dockerfile — Waits for reports/latest-scan.json

Common overrides

# Point the scanner at a real contract tree on the host
SCAN_HOST_TARGET=../vero-core-contracts docker compose up --build scanner-engine verifiable-audit-trail

# Rebuild a single image after a code change
docker compose build anomaly-detector
docker compose up -d anomaly-detector

# Inspect reports produced by the scanner
cat reports/latest-scan.json

Environment variables are documented in .env.example and in the README "Environment Variables" table. Docker Compose reads a host .env for interpolation; do not commit secrets.

Package .env.example files

Each package that reads environment variables keeps a local .env.example with safe placeholder values. Copy the relevant file to .env when running a package locally, then replace placeholder values with your own development configuration.

  • anomaly-detector/.env.example documents relayer metrics, RPC failover, threat feed, dashboard, and telemetry settings.
  • atomic-rpc-relayer-bridge/.env.example documents local server bind, bridge endpoint, relayer address, nonce, and failed-transaction sample settings.
  • verifiable-audit-trail/.env.example documents Stellar Horizon, network, and optional audit keypair settings.
  • src/audit-guard/.env.example documents webhook, dashboard, on-call, policy, CLI, archive, backup, Stellar, and telemetry settings.

Never commit real secrets, API tokens, private keys, production endpoints that should remain private, or local .env files. When adding a new process.env or import.meta.env read, update the nearest package-level .env.example in the same change.

Acceptance check

docker compose up --build should:

  • Produce reports/latest-scan.json
  • Print [audit-trail] hash lines (dry-run without a keypair)
  • Keep atomic-rpc-relayer-bridge healthy on :8545/health
  • Keep anomaly-detector polling without crashing

Native workflow

chmod +x BUILD_GUARD.sh
./BUILD_GUARD.sh [path/to/vero-core-contracts]

See the README for what each step does.

Changelog

We use Keep a Changelog for our CHANGELOG.md. When submitting a pull request, please ensure that you update the CHANGELOG.md to reflect your changes.

How to update the Changelog

  • All unreleased changes should be added under the ## [Unreleased] section.
  • Categorize your changes using one of the following labels:
    • Added for new features.
    • Changed for changes in existing functionality.
    • Deprecated for soon-to-be removed features.
    • Removed for now removed features.
    • Fixed for any bug fixes.
    • Security in case of vulnerabilities.
  • Provide a clear, concise description of the change.

When a new version is released, the [Unreleased] changes will be moved to a specific version block by the maintainers.

Code Review & CODEOWNERS

This repository uses a .github/CODEOWNERS file to define per-sub-package review ownership. When you open a pull request, GitHub automatically requests a review from the owner(s) of every path your PR touches — you do not need to assign reviewers manually.

How automatic review requests work

GitHub's CODEOWNERS integration is activated by branch protection rules on main. The rule that matters is "Require review from Code Owners" (found under Settings → Branches → Branch protection rules → main). Once that setting is enabled:

  1. Open a PR against main (or any protected branch).
  2. GitHub inspects the diff and matches every changed path against .github/CODEOWNERS.
  3. The matching owner(s) are automatically added as required reviewers — the PR cannot be merged until at least one of them approves.
  4. If no specific rule matches, the global fallback owner (@mimi-esc) is requested.

Sub-package ownership at a glance

Path Owners
scanner-engine/ @mimi-esc @N-thnI @nazteeemba
anomaly-detector/ @mimi-esc @N-thnI
atomic-rpc-relayer-bridge/ @mimi-esc @telemarkdigital-publisher
verifiable-audit-trail/ @mimi-esc @Errordog2 @gloskull
src/audit-guard/ @mimi-esc @N-thnI @gloskull @Agbasimere
.github/ @mimi-esc @N-thnI @gloskull
Everything else @mimi-esc

Updating CODEOWNERS

If you add a new top-level sub-package or significantly shift ownership of an existing one, open a PR that updates .github/CODEOWNERS alongside the code change. The .github/ path itself is owned by the core infra maintainers, so the update will be reviewed by them automatically.

Pull requests

  1. Fork the upstream repository at https://github.com/Vero-protocol/vero-audit-guard if you haven't already.
  2. Branch from main using the issue naming convention when one is specified (for example chore/issue-279-add-docker-compose-setup).
  3. Keep changes scoped to the issue. Prefer additive tooling over drive-by refactors.
  4. Make sure new TypeScript compiles under strict and that package tests still pass (npm test / cargo test in the touched crate).
  5. Update CHANGELOG.md under ## [Unreleased] with a clear, concise description of your change (see Changelog section above).
  6. Push your branch to your fork.
  7. Open the PR from your fork against Vero-protocol/vero-audit-guard and reference the issue (Closes #227).
  8. Fill in the repository PR description completely — state what was completed from the issue.

Do not commit .env, keypairs, or report JSON that may contain sensitive paths.

Pull Request Guidelines

When opening a Pull Request, please ensure you complete all sections of the automatically populated PR Template, including explicitly linking the originating issue using Closes #<number>.

Writing the pull request description

Every pull request needs a detailed description. A one-line summary, a restatement of the issue title, or "fixes the issue" is not enough, and a PR that arrives with one will be sent back before review.

Write it for a reviewer who has not read the issue. Cover:

  • What was wrong — the problem or gap, and the behaviour before your change.
  • What you did — the approach you took, and any alternative you considered and rejected, with the reason.
  • What to look at — anything subtle, risky, or that you are unsure about. Flagging your own uncertainty speeds review up; it does not count against you.
  • How you verified it — tests you added, commands you ran, manual checks.

Two things this is not: it is not a diff summary — the diff already says which lines changed, and the description should say why. And it is not a place to hide problems. If something is incomplete or a known limitation remains, say so explicitly.

Keep the Closes #<issue-number> reference in the description itself. GitHub ignores closing keywords written in PR comments, so a link posted as a comment will not close the issue on merge.