From 1cbe58daff6f549ba837cec79622cd34cc144eb7 Mon Sep 17 00:00:00 2001 From: MyouzzZ Date: Thu, 25 Jun 2026 23:25:11 +0800 Subject: [PATCH 1/4] Add WaveFlow contributing guide --- CONTRIBUTING.md | 78 ++++++++++++++++++++++++++++++++----------------- README.md | 9 +++--- 2 files changed, 56 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ea5d56..b0b5085 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,40 +1,64 @@ # Contributing to WaveFlow -WaveFlow automates bounty escrow on Stellar/Soroban with GitHub merge-triggered payouts. +WaveFlow is a Stellar/Soroban bounty escrow system. Keep contributions small, auditable, and tied to the production readiness path in the PRD and roadmap. ## Before you start -1. Read [docs/PRD.md](docs/PRD.md) for product scope. -2. Read [docs/ROADMAP.md](docs/ROADMAP.md) for phase plan. -3. Walk through [docs/core-loop.md](docs/core-loop.md) for the merge-to-payout path. +- Pick an open issue whose scope matches the code or docs you plan to change. +- Check for an existing assignee, active pull request, or maintainer comment before starting. +- Prefer one issue per pull request. Split unrelated contract, gateway, API, and docs work. +- Do not introduce secrets, private data, paid services, or destructive actions into tests or examples. -## Development setup +## Issue labels and title prefixes -```bash -git checkout main && git pull -git checkout -b feature/your-change -cp .env.example .env -docker-compose up -d -cargo build --workspace -cargo test --workspace -``` +Use issue title prefixes to make the affected area clear: -## Workspace layout +| Prefix | Area | +|--------|------| +| `[contract]` | Soroban escrow code in `contracts/waveflow-escrow` | +| `[gateway]` | GitHub webhook ingestion, HMAC checks, attestation, metrics, and chain submission in `crates/gateway` | +| `[api]` | REST routes, admin auth, health/readiness, and read models in `crates/api` | +| `[shared]` | Shared errors, types, config, and idempotency keys in `crates/shared` | +| `[infra]` | Docker, Render, migrations, deployment scripts, and environment templates | +| `[docs]` | README, PRD, roadmap, runbooks, agent notes, and walkthroughs | +| `[tests]` | Focused test-only changes or test coverage for an existing feature | +| `[security]` | Auth, replay protection, secret handling, rate limits, and fail-closed behavior | -| Crate / path | Role | -|--------------|------| -| `contracts/waveflow-escrow` | Soroban escrow contract | -| `crates/gateway` | GitHub webhooks and chain attestation | -| `crates/api` | REST API for programs and payouts | -| `crates/shared` | Config, types, errors | +Maintainers may also add status labels such as `documentation`, `good first issue`, or `help wanted` when a task is ready for contributors. -## Pull requests +## Wave bounty label workflow -- Branch from `main`, open PRs against `main`. -- Run `cargo fmt`, `cargo clippy`, and `cargo test --workspace` before pushing. -- Use issue prefixes: `[contracts]`, `[backend]`, `[documentation]`, `[infra]`. -- Label Drips Wave issues with `Drips Wave` and `complexity:*`. +WaveFlow follows Drips Wave-style contributor mechanics, but the product remains Stellar-native. PRD NG6 makes replacing or depending on StellarRoute DEX aggregation a non-goal, and the WaveFlow core loop must not depend on a Drips API. Treat Drips Wave as the program model, not as a runtime dependency. -## Security +For Wave-aligned issues: -Never commit real webhook secrets or Stellar secret keys. See [docs/security-checklist.md](docs/security-checklist.md). +1. Maintainers mark the issue with the Wave program label, such as `Drips Wave` or `Stellar Wave`. +2. Maintainers add one complexity label, such as `complexity:low`, `complexity:medium`, or `complexity:high`. +3. Gateway-related issues should reference the label-to-points mapping issue or PR when points affect payout calculation. +4. If no mapping issue is linked yet, include the proposed mapping in the PR description and keep the implementation configurable rather than hardcoded. +5. A merged PR should include enough context for the gateway to map repo, PR number, contributor, complexity tier, and points without relying on off-chain manual memory. + +## Branch and pull request conventions + +- Use a branch name that includes the issue number, for example `feature/38-contributing-guide`. +- Put `Closes #` or `Refs #` in the PR body. +- Keep the PR description focused on what changed, how it was validated, and any follow-up work. +- For code changes, run the relevant checks from `AGENTS.md` before requesting review. +- For documentation-only changes, mention that no Rust build was required. + +## Quality bar + +Contributions should preserve the PRD production target: + +- fail closed on auth, signature, idempotency, and insufficient escrow failures; +- avoid placeholder production paths, simulated transaction hashes, and secret logging; +- update docs when behavior, environment variables, APIs, or operational steps change; +- include tests for changed contract, gateway, API, and shared logic where practical. + +## Useful references + +- [README](README.md) +- [Product Requirements](docs/PRD.md) +- [Implementation Roadmap](docs/ROADMAP.md) +- [Core loop walkthrough](docs/core-loop.md) +- [Agent guidance](AGENTS.md) diff --git a/README.md b/README.md index 351345e..66a5701 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ Automated bounty escrow on Stellar/Soroban with GitHub merge-triggered payouts. ## Architecture ``` -GitHub PR merge → Gateway (webhook + HMAC) → Soroban Escrow → Contributor wallet - ↓ +GitHub PR merge -> Gateway (webhook + HMAC) -> Soroban Escrow -> Contributor wallet + | Postgres audit trail - ↓ + | REST API (read paths) ``` @@ -55,7 +55,8 @@ cargo run -p waveflow-api - [Product Requirements](docs/PRD.md) - [Implementation Roadmap](docs/ROADMAP.md) - [Core loop walkthrough](docs/core-loop.md) +- [Contributing guide](CONTRIBUTING.md) ## License -MIT +MIT \ No newline at end of file From 0e470c5f73c4b659a0a039d661d33b4699b15a4a Mon Sep 17 00:00:00 2001 From: MyouzzZ Date: Thu, 25 Jun 2026 23:25:57 +0800 Subject: [PATCH 2/4] Preserve README diagram formatting --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 66a5701..2b1da87 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ Automated bounty escrow on Stellar/Soroban with GitHub merge-triggered payouts. ## Architecture ``` -GitHub PR merge -> Gateway (webhook + HMAC) -> Soroban Escrow -> Contributor wallet - | +GitHub PR merge ? Gateway (webhook + HMAC) ? Soroban Escrow ? Contributor wallet + ? Postgres audit trail - | + ? REST API (read paths) ``` From 51b150ade6563fc1fd65d7fb30d5d69aa00ff045 Mon Sep 17 00:00:00 2001 From: MyouzzZ Date: Thu, 25 Jun 2026 23:26:50 +0800 Subject: [PATCH 3/4] Restore README diagram encoding --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2b1da87..9b9816a 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ Automated bounty escrow on Stellar/Soroban with GitHub merge-triggered payouts. ## Architecture ``` -GitHub PR merge ? Gateway (webhook + HMAC) ? Soroban Escrow ? Contributor wallet - ? +GitHub PR merge → Gateway (webhook + HMAC) → Soroban Escrow → Contributor wallet + ↓ Postgres audit trail - ? + ↓ REST API (read paths) ``` @@ -59,4 +59,4 @@ cargo run -p waveflow-api ## License -MIT \ No newline at end of file +MIT From a404201f16f6a94a463f0a8dfbad41d2c154f378 Mon Sep 17 00:00:00 2001 From: MyouzzZ Date: Thu, 25 Jun 2026 23:27:55 +0800 Subject: [PATCH 4/4] Preserve contributing setup details --- CONTRIBUTING.md | 42 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0b5085..36b1f98 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,38 @@ # Contributing to WaveFlow -WaveFlow is a Stellar/Soroban bounty escrow system. Keep contributions small, auditable, and tied to the production readiness path in the PRD and roadmap. +WaveFlow automates bounty escrow on Stellar/Soroban with GitHub merge-triggered payouts. Keep contributions small, auditable, and tied to the production readiness path in the PRD and roadmap. ## Before you start +- Read [docs/PRD.md](docs/PRD.md) for product scope. +- Read [docs/ROADMAP.md](docs/ROADMAP.md) for phase plan. +- Walk through [docs/core-loop.md](docs/core-loop.md) for the merge-to-payout path. - Pick an open issue whose scope matches the code or docs you plan to change. - Check for an existing assignee, active pull request, or maintainer comment before starting. - Prefer one issue per pull request. Split unrelated contract, gateway, API, and docs work. -- Do not introduce secrets, private data, paid services, or destructive actions into tests or examples. + +## Development setup + +```bash +git checkout main && git pull +git checkout -b feature/your-change +cp .env.example .env +docker-compose up -d +cargo build --workspace +cargo test --workspace +``` + +Run the focused command for your change when possible, then run the wider workspace check before review if you touched shared behavior. + +## Workspace layout + +| Crate / path | Role | +|--------------|------| +| `contracts/waveflow-escrow` | Soroban escrow contract | +| `crates/gateway` | GitHub webhooks and chain attestation | +| `crates/api` | REST API for programs and payouts | +| `crates/shared` | Config, types, errors | +| `docs/` | PRD, roadmap, runbooks, and walkthroughs | ## Issue labels and title prefixes @@ -28,7 +53,7 @@ Maintainers may also add status labels such as `documentation`, `good first issu ## Wave bounty label workflow -WaveFlow follows Drips Wave-style contributor mechanics, but the product remains Stellar-native. PRD NG6 makes replacing or depending on StellarRoute DEX aggregation a non-goal, and the WaveFlow core loop must not depend on a Drips API. Treat Drips Wave as the program model, not as a runtime dependency. +WaveFlow follows Drips Wave-style contributor mechanics, but the product remains Stellar-native. PRD NG6 keeps WaveFlow focused on its own Stellar/Soroban escrow and payout loop; the gateway should not depend on a Drips API for payout execution. Treat Drips Wave as the program model, not as a runtime dependency. For Wave-aligned issues: @@ -38,12 +63,13 @@ For Wave-aligned issues: 4. If no mapping issue is linked yet, include the proposed mapping in the PR description and keep the implementation configurable rather than hardcoded. 5. A merged PR should include enough context for the gateway to map repo, PR number, contributor, complexity tier, and points without relying on off-chain manual memory. -## Branch and pull request conventions +## Pull requests +- Branch from `main`, open PRs against `main`. - Use a branch name that includes the issue number, for example `feature/38-contributing-guide`. - Put `Closes #` or `Refs #` in the PR body. - Keep the PR description focused on what changed, how it was validated, and any follow-up work. -- For code changes, run the relevant checks from `AGENTS.md` before requesting review. +- For code changes, run `cargo fmt`, `cargo clippy`, and `cargo test --workspace` before pushing. - For documentation-only changes, mention that no Rust build was required. ## Quality bar @@ -55,6 +81,12 @@ Contributions should preserve the PRD production target: - update docs when behavior, environment variables, APIs, or operational steps change; - include tests for changed contract, gateway, API, and shared logic where practical. +## Security + +Never commit real webhook secrets or Stellar secret keys. See [docs/security-checklist.md](docs/security-checklist.md). + +Do not introduce secrets, private data, paid services, or destructive actions into tests or examples. + ## Useful references - [README](README.md)