Group fundraising escrow contract

[Douglasacost]

Contract work for the app's Groups feature: a group creates an objective (a target amount and a deadline), members deposit toward it, and the escrow resolves to exactly one of two outcomes — the beneficiary is paid, or every member takes their own money back.

Scope: the contract only. Group management, membership, objective metadata and the backend authorization-signing service are all out of scope here; they live in the app and its backend. This ticket is GroupFundraising.sol, its interface, and its test suite.

Design

Spec merged/under review in #131 → src/fundraising/doc/spec/group-fundraising-design.md.

• Model — all-or-nothing with a goal latch. A member may withdraw their own deposit while the objective is below target; that exit closes permanently once the target is reached.
• Resolution is permissionless — once the goal is met or the deadline passes, anyone can finalize and every member pulls their own funds. No role, signature, or organizer cooperation can freeze member money.
• Lineage — the CrowdFund / RefundEscrow state machine, built on OpenZeppelin primitives, with Party Protocol's published findings carried into the threat model as regression tests.
• Membership — single-use EIP-712 authorizations, signed by the backend, gate objective creation and deposits.

Hard constraint

Deploys new contracts only. No deployed contract is modified, no token migration is required, and no live paymaster needs changing. Anything requiring a change to something already in production is out of scope by definition — that is what makes this shippable independently.

Work

• Design spec (docs(fundraising): group fundraising escrow design spec #131)
• IGroupFundraising — types, events, errors
• GroupFundraising.sol
• Tests: lifecycle, the goal latch boundary (goal - 1 / goal / goal + 1), authorization (expiry, replay, nonce reuse, key rotation), refunds, invariants
• Adversarial token mocks: fee-on-transfer, reentrant, blocklisting
• Deploy script
• Security review

Decisions still open

Immutable vs. upgradeable; whether keep-what-you-raise is a real product case; protocol fee on/off and in which token; overshoot past the goal; one objective per group at a time or many.

Related

• docs(fundraising): group fundraising escrow design spec #131 — the design spec
• NodleCode/meta#193 (bespoke NODL paymaster to replace ZyFi) — adjacent, not blocking. The escrow never assumes a paymaster exists, so without one members simply pay their own gas. If that paymaster ships, serving this escrow is off-chain signer policy and needs no contract change on either side.