Skip to content

PLAN.md

Latest commit

 

History

History
70 lines (47 loc) · 4.51 KB

PLAN.md

File metadata and controls

70 lines (47 loc) · 4.51 KB
Raw

WhoZNext — Wave Program Contribution Plan

Project Overview

WhoZNext is an automated milestone and issue escrow release system built on Stellar Soroban. It lets repository maintainers lock a token budget against a GitHub milestone and automatically release micro-payouts to contributors when their issues are closed and merged — no manual reconciliation, no end-of-month delays.

The contract integrates with WaveGuard for maintainer access control. The frontend is a React + TypeScript application connecting to the deployed contract via the Stellar SDK and Freighter wallet.

Scope of Work for Wave Contributors

Each sprint cycle will have a pool of scoped, bounty-tagged issues ready to pick up. Issues are sized for completion within one sprint. All work is merged to main via pull request with a linked issue.

1. Bug Fixes

Active targets:

  • Frontend wallet edge cases — Freighter connection occasionally fails silently when the extension is locked. Needs detection and a user-facing error with a retry prompt.
  • View call fallback — fetchMilestoneInfo returns a raw error when no pool exists instead of gracefully returning null. Affects the Overview tab on fresh deployments.
  • Balance display precision — Stroop-to-token conversion produces trailing zeros for whole-number amounts (e.g. 100.0000000 instead of 100).
  • Clawback confirmation state — After a successful clawback, the confirm button remains visible until page refresh.

2. New Features

Planned additions:

  • Claim history table — Surface get_claim_history data in the frontend as a paginated table showing issue ID, developer address, amount, and timestamp.
  • Repo hash utility panel — A dedicated UI input that computes and copies the SHA-256 repo hash, so maintainers don't need to calculate it externally before calling release_issue_bounty.
  • Pool expiry countdown — A live countdown timer on the Overview tab showing time remaining before the milestone expires and clawback becomes available.
  • Multi-pool read mode — Allow the frontend to query any contract address by entering it manually, not just the one set in .env.
  • Event log feed — Poll the Soroban RPC for bounty_released and milestone_pool_created events and display them as a live activity feed.

3. Documentation

Needed:

  • Deployment guide update — docs/DEPLOYMENT.md needs a step-by-step walkthrough for deploying to testnet using the Soroban CLI, including how to fund the deployer account via Friendbot and verify the contract ID.
  • Frontend setup guide — A frontend/README.md covering environment variable configuration, local dev setup, and how to point the app at a testnet contract.
  • WaveGuard integration tutorial — A practical walkthrough in docs/WAVEGUARD_MAINTAINER.md showing how to deploy a WaveGuard instance, register a maintainer, and link it to a WhoZNext pool.
  • Contract method examples — Extend docs/examples/ with working CLI invocation examples for all three mutating contract methods.

4. Testing

Coverage gaps:

  • Frontend component tests — No tests exist for the React components. Add Vitest + Testing Library unit tests covering form validation, wallet-disconnected state, and error display for each panel.
  • RPC helper tests — Unit tests for stroopsToDisplay, repoHashHex, isExpired, and shortAddress in src/lib/contract.ts.
  • Contract integration: clawback edge cases — Missing integration test for the scenario where a pool is partially claimed and then clawed back, verifying the exact transferred amount.
  • CI frontend step — The GitHub Actions workflow does not run tsc --noEmit or vite build for the frontend. Add a frontend-ci job to .github/workflows/ci.yml.

Issue Sizing

Label Typical Effort
good first issue < 2 hours — isolated, self-contained
bounty:small 2–4 hours — single file or component
bounty:medium 4–8 hours — cross-cutting or new feature
bounty:large 8+ hours — architectural, requires design discussion

How to Contribute

  1. Browse open issues tagged bounty:* or good first issue.
  2. Comment on the issue to claim it before starting work.
  3. Fork the repo, create a branch named feat/<issue-number>-short-description or fix/<issue-number>-short-description.
  4. Open a draft PR early and link it to the issue.
  5. Ensure cargo test and npm run build pass before requesting review.
  6. Once merged, the bounty is released on-chain to your Stellar address.