feat: collateralized permissionless saving circles

[RonTuretzky]

Summary

This PR adds a collateralized, permissionless variant of the saving circle that removes the trust bound present in the current SavingCircles design, together with a formal specification and a full unit-test suite.

It is a direct response to the design question: what mechanism lets membership be opened permissionlessly — anyone joins, anyone leaves — without an honest member ever subsidizing a defaulter?

The idea (Variant A — "collateral-first")

A circle runs exactly two cycles of n rounds:

• Cycle 0 — the collateral cycle (rounds 0..n-1): everyone deposits the per-round amount m, but nobody withdraws. Each member's n deposits accrue into a locked collateral balance of n·m — one whole pot. This is the "complete the first full circle without withdrawing" phase.
• Cycle 1 — the payout cycle (rounds n..2n-1): a normal ROSCA. Each round the slot's occupant withdraws the full pot n·m. If any member fails to deposit, the shortfall is drawn from that member's own locked collateral, so the recipient is always paid in full.

Because every member's collateral (n·m) is at least its maximum possible unmet obligation, an honest member never loses funds regardless of how many others default. Eliminating this credit risk is precisely what makes membership safe to open permissionlessly: there is no owner, no EIP-712 invite, and no frozen cohort. If the collateral cycle finishes under-funded, anyone can abort and everyone is refunded — no payout can have occurred yet, so no one is harmed.

What changed vs. the baseline

The baseline SavingCircles can only guarantee an honest saver recovers (n − t)·m under an adversary controlling t savers (its Bounded-recovery theorem). The residual t·m is the unsecured credit an early recipient can walk away with, and it is why the baseline must gate entry with owner-signed invites and freeze the cohort at start. This variant drives t → 0: the guarantee becomes an unconditional n·m, so the door can be opened.

Contents

• docs/collateralized-permissionless-circles.md — a formal spec extending the Deckstacking / Bartoletti–Zunino model used in the project's specification. It gives the extended contract state and SOS transition rules (Deposit, Lock, Withdraw, Cover, Join, Leave), proves fund conservation, payout uniqueness, and the Collateral-Safety theorem (no trust threshold), and sketches two neighbouring designs:
  • Variant B — rolling bond: a tight (n−1)·m lump bond posted at join, enabling any-round permissionless join/leave (no cycle-0 latency).
  • Variant C — insured under-collateral: α·m collateral (α ≪ n) plus a mutual insurance buffer and late-slot placement, trading unconditional safety for capital efficiency.
  • Variant D — foremanless chit (§5, added in follow-up commit): the spec is stress-tested against the Indian chit fund (Chit Funds Act 1982) and the bidding-ROSCA literature. Findings: only prized members carry credit-theft risk, so A/B over-collateralize ~4× vs the outstanding-credit parabola K(j)=(j+1)(n−1−j)m; fix is prize-time (JIT) collateral. Variant D composes a sealed-bid reverse auction (Deckstacking-robust 2k/k commit-reveal; the winning discount is withheld as first-loss security, so withheld + lock = residual — Theorem D3) with substitution-based any-round join/leave; dividends give patient members endogenous interest; capital is within n·m of the theoretical floor (D4). Also: a proof-sketched trilemma (safety / anonymity / same-asset credit — pick two) and a warning that the auction must not be combined with under-collateralized Variant C (adverse selection, §5.5).
• src/interfaces/ICollateralSavingCircles.sol + src/contracts/CollateralSavingCircles.sol — upgradeable implementation of Variant A (lump-of-collateral-by-accrual form), following repo conventions (interface holds errors/events/structs, @inheritdoc, ReentrancyGuard, SafeERC20, admin-managed token allow-list).
• test/unit/CollateralSavingCirclesUnit.t.sol — 11 unit tests: full happy path (net-zero for all), a total defaulter with recipients still made whole and honest members losing nothing, partial default slashing only the defaulter, safe abort of an incomplete collateral cycle, and permissionless create/join/start plus parameter/guard checks.

Testing

forge test --match-contract CollateralSavingCirclesUnit   # 11 passed
forge test                                                # 179 passed (full suite)
forge fmt --check … && solhint …                          # clean

Notes / scope

• v1 implements the clean two-cycle form (faithful to "first circle collateral, second circle payouts"). For continuous membership churn the spec now recommends Variant D (which subsumes the rolling-bond Variant B at ~¼ the lockup) as the follow-up implementation; multi-payout-cycle circles need proportionally more collateral, noted there.
• Contract is standalone and does not touch the existing SavingCircles/AutomaticSavingCircles contracts.

Formal model and rationale in full: docs/collateralized-permissionless-circles.md.

[RonTuretzky]

Follow-up commit (49529df): stress-tested the model against chit funds & the reverse-auction (bidding-ROSCA) literature — it changed the spec.

TL;DR of what the chit-fund lens (Chit Funds Act 1982; Besley–Coate–Loury 1993; Kovsted–Lyk-Jensen 1999) surfaced:

1. Variants A/B secure the wrong thing. Chit practice demands security only from prized subscribers, at prize time — and it's right: only a member who has already taken a pot can steal; a non-prized defaulter merely stops lending and forfeits her own claim (handled by the Act's §§28–30 removal + substitution). Formalized as Lemmas 5.1–5.3: outstanding credit follows the parabola K(j) = (j+1)(n−1−j)·m ≤ n²m/4, so B's uniform n(n−1)·m bond pool is ~4× over-collateralized at peak. Fix: prize-time (JIT) collateral (n−1−j)·m, plus a 1-round membership bond.
2. New Variant D — the "foremanless chit" (§5.4): sealed-bid reverse auction (commit-reveal with 2k/k margins so the Deckstacking scheduler-adversary can't censor or snipe bids — open outcry would be auction MEV), with the winning discount withheld as first-loss security, so withheld + lock = residual always: bidding more means locking less cash, safety unchanged (Theorem D3), and a would-be defaulter's max bid is self-defeating. Capital held ≈ the theoretical floor (D4). Dividends give patient members endogenous interest — A/B/C all paid lenders 0%, a real incentive gap for anonymous membership. Rotation remains the no-bid degenerate case (per BCL: random dominates under homogeneous preferences, bidding under heterogeneous — so it's a parameter, not a commitment).
3. Substitution = true permissionless leave. The Act's substituted-subscriber mechanism generalizes Leave to any round for every variant: exit by selling your position to a successor who assumes your schedule; nobody else's position changes.
4. A warning, not just wins: the auction must not be bolted onto under-collateralized Variant C — intending defaulters are discount-insensitive, so open bidding routes pots to the worst risks first and drains the buffer (adverse selection). Safe compositions enumerated in §5.5.
5. An honest limit (Prop. 5.4 trilemma): unconditional safety + fresh-anonymous-key membership + net credit in the circle's own asset — pick two. Cash-collateralized circles are commitment-savings + mutual insurance (+ an interest market in D), not lenders; unsecured credit is exactly what the foreman's vetting buys. Safe permissionless credit requires heterogeneous collateral assets or on-chain sureties — parameterized in D as extension points.

Spec-only change (docs/collateralized-permissionless-circles.md); the Variant A implementation in this PR is unaffected and remains the recommended v1. Variant D supersedes B on every axis and is the natural follow-up implementation.