diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4816474 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing to ProofWorks GenLayer + +## Setup + +1. **Clone the repository:** + ```bash + git clone https://github.com/tommycet/proofworks-genlayer.git + cd proofworks-genlayer + ``` + +2. **Install Python dependencies:** + ```bash + pip install -r requirements.txt + ``` + +3. **Run the GenVM environment setup:** + ```bash + make setup-genvmroot + ``` + +4. **Install frontend dependencies (optional, for UI development):** + ```bash + make frontend-install + ``` + +## Running the tests + +Run the full test suite with: + +```bash +make test +``` + +This executes `pytest -q` after initializing the GenVM environment. For linting smart contracts: + +```bash +make lint-contract +``` + +To validate everything (tests, lint, frontend build): + +```bash +make validate-all +``` + +## Submitting a pull request + +1. **Fork the repository** and create a feature branch from `main`. +2. **Make your changes** — follow existing code style and conventions. +3. **Run the tests** with `make test` to ensure nothing is broken. +4. **Commit** with a clear, descriptive message (e.g., `feat: add escrow expiration check`). +5. **Push** your branch and open a pull request against `tommycet/proofworks-genlayer:main`. +6. **Describe your changes** in the PR body — include what you changed, why, and any relevant issue references. + +PRs are reviewed on a rolling basis. Ensure all CI checks pass before requesting review. diff --git a/docs/bounty-rules.md b/docs/bounty-rules.md new file mode 100644 index 0000000..88a2cf1 --- /dev/null +++ b/docs/bounty-rules.md @@ -0,0 +1,35 @@ +# ProofWorks — Bounty Rules: Appeal Fees & Staking + +This document describes the appeal bond and worker staking rules introduced in [ProofWorks Phase 9](https://github.com/tommycet/proofworks-genlayer). + +--- + +## Appeal Bond + +Workers who wish to appeal a **REJECT** verdict must post an appeal bond before the appeal can be reviewed. + +- **Bond amount:** 20% of the original task reward. +- **Purpose:** The bond prevents frivolous appeals by requiring the worker to put additional funds at risk. +- **Outcome:** + - If the appeal is **upheld** (verdict changed to APPROVE): the bond is returned to the worker along with the task reward. + - If the appeal is **denied** (verdict remains REJECT): the bond is forfeited and distributed according to the contract's fee rules. +- **Process:** After a REJECT verdict is finalized, the worker may call `appeal_task(task_id)` and fund it with the required bond amount. The task re-enters the evaluation phase for re-adjudication. + +--- + +## Worker Staking + +When a worker claims a task, the contract may require a stake to be locked as collateral. + +- **Stake purpose:** The stake demonstrates commitment and prevents workers from claiming tasks and abandoning them. +- **Forfeiture condition:** If the worker's claim **expires** (the claim window closes) without the worker submitting a proof (PR URL), the stake is **forfeited**. +- **Return condition:** If the worker submits proof before the claim expires, the stake is returned upon task finalization, regardless of the verdict. +- **Stake amount:** Configured per task by the creator at task creation time. A stake of `0` means no staking is required for that task. + +--- + +## Related + +- Issue: [tommycet/proofworks-genlayer#4](https://github.com/tommycet/proofworks-genlayer/issues/4) +- Contract reference: See `README.md#contract-reference` for the escrow and finalization functions. +- Phase 9 changelog: See `CHANGELOG.md` for the full list of Phase 9 changes.