@ballkidz/defifa 0.0.17 → 0.0.19

package/ADMINISTRATION.md

@@ -2,6 +2,33 @@
 
 Admin privileges and their scope in defifa-collection-deployer-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Defifa game launch, scorecard ratification, lifecycle progression, and fee-project ownership locking. |
+| Operators | Permissionless game creators and scorecard participants, plus the protocol contracts `DefifaDeployer`, `DefifaGovernor`, `DefifaHook`, and optional `DefifaProjectOwner`. |
+| Highest-risk actions | Launching a game with bad immutable parameters, ratifying the winning scorecard, or transferring a fee-project NFT into `DefifaProjectOwner`. |
+| Recovery posture | Game parameters are intentionally immutable after launch. A bad game setup usually means launching a new game or falling back to the no-contest path if available. |
+
+## Routine Operations
+
+- Validate game timings, tier setup, fee routing, and attestation settings before calling `launchGameWith()`.
+- During scoring, rely on the documented submission, attestation, and ratification flow rather than looking for discretionary admin overrides that do not exist.
+- Use `triggerNoContestFor()` when the game has entered the documented no-contest condition and refunds need to be unlocked.
+- Treat the fee-project ownership proxy as a burn-lock mechanism, not a recoverable custody tool.
+
+## One-Way Or High-Risk Actions
+
+- `launchGameWith()` fixes the game's core configuration.
+- `setTierCashOutWeightsTo()` is irreversible once weights are set for a game.
+- `DefifaProjectOwner` permanently locks the project NFT it receives.
+
+## Recovery Notes
+
+- If a scorecard never reaches a valid ratification path and timeout conditions are met, use the documented no-contest recovery flow.
+- If the game launched with the wrong immutable economics or timing, recovery is a replacement game deployment rather than an admin patch.
+
 ## Roles
 
 | Role | Who | How Assigned |
@@ -30,10 +57,10 @@ Admin privileges and their scope in defifa-collection-deployer-v6.
 
 | Function | Required Role | Permission Check | What It Does |
 |----------|--------------|-----------------|-------------|
-| `initializeGame()` | DefifaDeployer (owner) | `onlyOwner` | Sets attestation start time and grace period for a game. Enforces minimum 1-day grace period. Called automatically during `launchGameWith()`. |
+| `initializeGame()` | DefifaDeployer (owner) | `onlyOwner` | Sets the attestation start time, attestation grace period, and optional post-quorum `timelockDuration` for a game. Enforces a minimum 1-day grace period. Called automatically during `launchGameWith()`. |
 | `submitScorecardFor()` | Anyone | Must be in SCORING phase; no ratified scorecard yet; no duplicate scorecard hash; weighted tiers must have nonzero supply | Submits a scorecard for attestation. Sets `attestationsBegin` and `gracePeriodEnds` timestamps. Snapshots pending reserves per tier for BWA computation. |
-| `attestToScorecardFrom()` | Any NFT holder | Must be in SCORING phase; scorecard must be ACTIVE or SUCCEEDED; caller cannot have already attested | Records attestation weight based on tier holdings at the `attestationsBegin - 1` checkpoint timestamp. Uses pending reserve snapshot from submission time. |
-| `ratifyScorecardFrom()` | Anyone | Scorecard must be in SUCCEEDED state (quorum met + grace period elapsed); no scorecard already ratified | Executes the scorecard via low-level call to `setTierCashOutWeightsTo` on the hook, then calls `fulfillCommitmentsOf`. |
+| `attestToScorecardFrom()` | Any NFT holder | Must be in SCORING phase; scorecard must be `ACTIVE`, `QUEUED`, or `SUCCEEDED`; caller cannot have already attested | Records attestation weight based on tier holdings at the `attestationsBegin - 1` checkpoint timestamp. Uses pending reserve snapshot from submission time. |
+| `ratifyScorecardFrom()` | Anyone | Scorecard must be in SUCCEEDED state (quorum met, grace period elapsed, and any configured `timelockDuration` elapsed); no scorecard already ratified | Executes the scorecard via low-level call to `setTierCashOutWeightsTo` on the hook, then calls `fulfillCommitmentsOf`. |
 
 ### DefifaHook
 
@@ -73,7 +100,7 @@ COUNTDOWN --> MINT --> REFUND (optional) --> SCORING --> COMPLETE or NO_CONTEST
 **Who controls scoring:**
 1. Anyone submits a scorecard during SCORING (`submitScorecardFor`)
 2. NFT holders attest based on their per-tier voting weight (`attestToScorecardFrom`)
-3. Once quorum (50% of minted tiers' attestation power) is met and grace period passes, anyone ratifies (`ratifyScorecardFrom`)
+3. Once quorum (50% of minted tiers' attestation power) is met, the grace period has elapsed, and any configured `timelockDuration` has elapsed, the scorecard reaches `SUCCEEDED` and anyone can ratify it with `ratifyScorecardFrom`
 4. The governor calls `setTierCashOutWeightsTo` on the hook via low-level call
 5. `fulfillCommitmentsOf` sends fee payouts (try-catch) and queues the final ruleset
 
@@ -84,8 +111,8 @@ The quorum threshold is 50% of the total attestation power across all tiers with
 **Edge cases:**
 - **Tiers with zero mints:** Tiers with `currentSupplyOfTier(tierId) == 0` are excluded from the quorum calculation. They have no attestation power and cannot influence scoring.
 - **All mints in a single tier:** If all participation concentrates in one tier, that tier's holders control the quorum. The 50% threshold still applies -- holders of 50% of that tier's supply can ratify a scorecard.
-- **Grace period:** After a scorecard reaches quorum (SUCCEEDED state), a grace period (`attestationsGracePeriod`, minimum 1 day) must elapse before ratification. This gives dissenters time to attest to a competing scorecard that could overtake the first.
-- **Competing scorecards:** Multiple scorecards can be submitted. Each tracks attestations independently. Only the first to be ratified (quorum met + grace period elapsed + `ratifyScorecardFrom()` called) takes effect. Once ratified, no other scorecard can be ratified for the same game.
+- **Grace period and timelock:** After submission, a scorecard stays `ACTIVE` until its grace period ends. If it has quorum at that point, it becomes `QUEUED` when `timelockDuration > 0`, or `SUCCEEDED` immediately when `timelockDuration == 0`. Attestations remain allowed while the scorecard is `ACTIVE`, `QUEUED`, or `SUCCEEDED`, but revocations are only allowed while it is `ACTIVE`. Ratification is only allowed from `SUCCEEDED`.
+- **Competing scorecards:** Multiple scorecards can be submitted. Each tracks attestations independently. Only the first to be ratified after meeting quorum, clearing the grace period, and clearing any configured timelock takes effect. Once ratified, no other scorecard can be ratified for the same game.
 - **Scorecard timeout:** If `scorecardTimeout` is nonzero and elapses without ratification, the game enters NO_CONTEST state, enabling full refunds via `triggerNoContestFor()`.
 
 **No single entity controls scoring.** The process requires collective attestation from NFT holders across tiers.
@@ -103,6 +130,7 @@ The following are set at game creation and cannot be changed:
 | Fee structure | Constructor constants | `DEFIFA_FEE_DIVISOR = 20` (5%), `BASE_PROTOCOL_FEE_DIVISOR = 40` (2.5%) |
 | Attestation start time | `launchGameWith()` | Stored in governor via `initializeGame()` |
 | Attestation grace period | `launchGameWith()` | Minimum 1 day enforced in `initializeGame()` |
+| Timelock duration | `launchGameWith()` | Optional cooling period after quorum before a scorecard becomes ratifiable |
 | Default attestation delegate | `launchGameWith()` | Stored in hook |
 | `minParticipation` threshold | `launchGameWith()` | 0 = disabled |
 | `scorecardTimeout` | `launchGameWith()` | 0 = disabled |

package/ARCHITECTURE.md

@@ -1,115 +1,67 @@
-# defifa-collection-deployer-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-Prediction game platform built on Juicebox V6. Creates games where players buy NFT tiers representing outcomes, a governance process scores the outcomes, and winners claim treasury funds proportional to their tier's score.
-
-## Contract Map
-
-```
-src/
-├── DefifaDeployer.sol          — Deploys games: project + hook + governor + URI resolver
-├── DefifaHook.sol              — Pay/cashout hook with game phase logic and attestation
-├── DefifaGovernor.sol          — Scorecard ratification via tier-weighted governance
-├── DefifaProjectOwner.sol      — Proxy owner for Defifa projects
-├── DefifaTokenUriResolver.sol  — On-chain SVG metadata for game NFTs
-├── enums/
-│   ├── DefifaGamePhase.sol     — COUNTDOWN → MINT → REFUND → SCORING → COMPLETE → NO_CONTEST
-│   └── DefifaScorecardState.sol
-├── interfaces/                 — IDefifaDeployer, IDefifaHook, IDefifaGovernor, etc.
-├── libraries/
-│   ├── DefifaFontImporter.sol  — Font loading for on-chain SVG rendering
-│   └── DefifaHookLib.sol       — Game logic helpers
-└── structs/                    — Scorecards, attestations, tier params, delegations
-```
-
-## Key Data Flows
-
-### Game Lifecycle
-```
-MINT Phase:
-  Creator → DefifaDeployer.launchGameWith()
-    → Create JB project with DefifaHook as data/pay/cashout hook
-    → Deploy DefifaGovernor for scorecard governance
-    → Players buy NFT tiers (outcomes they predict)
-    → Delegation happens during this phase only
-
-REFUND Phase:
-  → Players can cash out for full refund (100% redemption rate)
-
-SCORING Phase:
-  → Anyone → DefifaGovernor.submitScorecard(weights[])
-    → Tier holders attest to scorecards
-    → Scorecard reaches quorum → ratified
-    → DefifaHook receives final cash-out weights per tier
-
-COMPLETE Phase:
-  → Deployer → fulfillCommitmentsOf() sends fee payouts and queues the final ruleset
-  → Winners → cash out NFTs at scored weights (see "Scored Weight Redemption" below)
-```
-
-### Governance Flow
-```
-Scorer → DefifaGovernor.submitScorecard(tierWeights[])
-  → Validate: correct phase, valid tier order, weights sum correctly
-  → Create proposal hash
-  → Snapshot pending reserves per tier for BWA computation
-
-Attestor → DefifaGovernor.attestToScorecard(proposalId)
-  → Must hold NFT tier tokens at attestationsBegin - 1 checkpoint
-  → Attestation weight = voting power from held tiers (diluted by snapshotted pending reserves)
-  → When quorum reached → scorecard ratified
-  → DefifaHook.setScorecard() called
+`defifa-collection-deployer-v6` builds prediction games on top of Juicebox and the 721 tiers hook. Each game is a project with phased rulesets, a hook that mints and cashes out game-piece NFTs, and a governor that ratifies scorecards which decide how the prize pool is distributed.
+
+## Boundaries
+
+- `DefifaHook` owns game-piece behavior, delegation, and cash-out math.
+- `DefifaGovernor` owns scorecard submission, attestation, quorum, and ratification.
+- `DefifaDeployer` owns game launch and post-ratification commitment fulfillment.
+- Generic tier storage and terminal accounting stay in `nana-721-hook-v6` and `nana-core-v6`.
+
+## Main Components
+
+| Component | Responsibility |
+| --- | --- |
+| `DefifaDeployer` | Launches phased projects, clones hooks, initializes the governor, and fulfills commitments |
+| `DefifaHook` | ERC-721 game pieces, attestation delegation, custom cash-out weighting, and game-state aware behavior |
+| `DefifaGovernor` | Scorecard proposals, attestations, quorum checks, grace periods, and ratification |
+| `DefifaHookLib` | Shared validation and weight math extracted to keep the hook within size limits |
+| `DefifaTokenUriResolver` | Dynamic token metadata and SVG rendering |
+| `DefifaProjectOwner` | Lock helper for the fee project |
+
+## Runtime Model
+
+```text
+creator
+  -> DefifaDeployer launches a project with staged rulesets
+players
+  -> mint tiered NFTs during the mint window
+holders
+  -> optionally refund during the refund window
+attesters
+  -> submit and attest to scorecards during scoring
+governor
+  -> ratifies the winning scorecard after quorum and grace-period checks
+holders
+  -> cash out NFTs for their share of the prize pool during completion
 ```
 
-### Scored Weight Redemption
+## Critical Invariants
 
-When a scorecard is ratified, `setTierCashOutWeightsTo` stores a weight per tier. Weights must sum to `TOTAL_CASHOUT_WEIGHT` (1e18). A tier with weight 0 means that outcome lost and holders get nothing.
+- Delegation and attestation power must stay aligned with tier semantics; a scorecard system that can be inflated by supply alone breaks the game.
+- Ratification is the only path that should install final cash-out weights.
+- Refund, scoring, complete, and no-contest phases must remain mutually coherent. If phase transitions drift, funds get stuck.
+- The deployer's commitment-fulfillment logic is part of game completion, not optional bookkeeping.
 
-When a holder cashes out an NFT during the COMPLETE phase:
+## Where Complexity Lives
 
-1. **Per-token weight**: The tier's weight is divided equally among all tokens minted in that tier: `tokenWeight = tierWeight / tokensInTier`.
-2. **Cash out amount**: `amount = (surplus + totalAmountRedeemed) * tokenWeight / TOTAL_CASHOUT_WEIGHT`. The formula uses `surplus + totalAmountRedeemed` (the original pot size) so that early and late redeemers receive the same value.
-3. The token is burned and the holder receives their share of the treasury.
-
-Example: 100 ETH pot, 4 tiers, winning tier gets weight 500000000000000000 (50%). If that tier had 10 minted tokens, each token redeems for `100 * (500000000000000000 / 10) / 1e18 = 5 ETH`.
-
-### fulfillCommitmentsOf
-
-Called automatically when a scorecard is ratified (by `ratifyScorecardFrom`). It performs two actions:
-
-1. **Sends fee payouts**: Computes the fee portion of the pot based on the split percentages configured at game creation, then calls `sendPayoutsOf` to distribute fees to the protocol. If the payout fails, the fee stays in the pot and the function continues (try-catch ensures the final ruleset is always queued).
-2. **Queues the final ruleset**: Queues a new Juicebox ruleset with `pausePay: true` (no new payments), `cashOutTaxRate: 0` (no tax on cash-outs), and the data hook still active so scored weights are enforced. This transitions the game to its terminal state where only cash-outs remain.
-
-## Extension Points
-
-| Point | Interface | Purpose |
-|-------|-----------|---------|
-| Data hook | `IJBRulesetDataHook` | Phase-aware pay/cashout behavior |
-| Pay hook | `IJBPayHook` | NFT minting during MINT phase |
-| Cash out hook | `IJBCashOutHook` | Scored weight redemptions |
-| Token URI resolver | `IJB721TokenUriResolver` | On-chain SVG generation |
-| Governor | `IDefifaGovernor` | Scorecard governance |
+- The game is split across hook, governor, and deployer contracts, but users experience it as one state machine.
+- Scorecard weighting, attestation accounting, and phase transitions are tightly coupled.
+- Completion logic is economically sensitive because it combines prize distribution with fee fulfillment.
 
 ## Dependencies
-- `@bananapus/core-v6` — Core protocol
-- `@bananapus/721-hook-v6` — NFT tier system
-- `@bananapus/address-registry-v6` — Deterministic deploys
-- `@bananapus/permission-ids-v6` — Permission constants
-- `@croptop/core-v6` — Croptop integration
-- `@rev-net/core-v6` — Revnet integration
-- `@openzeppelin/contracts` — Checkpoints, Ownable, Clones
-- `@prb/math` — mulDiv
-- `scripty.sol` — On-chain scripting for SVG
-
-## Design Decisions
-
-**Attestation-based governance over token-weighted voting.** Each tier gets equal max attestation power (`MAX_ATTESTATION_POWER_TIER = 1e9`) regardless of how many tokens it sold. A holder's power within a tier is proportional to their share of that tier's supply. This prevents a popular outcome (e.g., the favorite team) from dominating the scorecard simply by having more buyers. Every outcome's community has equal say in ratification.
-
-**Six distinct game phases.** The MINT, REFUND, SCORING, and COMPLETE phases enforce a strict lifecycle where each action is only valid in its phase. MINT allows buying in, REFUND provides a grace period for full refunds, SCORING locks the treasury while governance resolves, and COMPLETE enables scored cash-outs. The COUNTDOWN phase gates minting before the game starts, and NO_CONTEST acts as a fallback if no scorecard is ratified within the timeout. This phased approach prevents timing exploits (e.g., buying in after seeing results) and ensures the treasury is never drained during scoring.
 
-**Proxy owner pattern (DefifaProjectOwner).** Game projects are owned by `DefifaDeployer` itself (`launchProjectFor` sets `owner: address(this)`), which restricts game operations to the deployer's hardcoded logic -- no EOA can rug the game by migrating terminals, minting tokens, or changing controllers. Separately, `DefifaProjectOwner` permanently holds the Defifa fee project NFT (DEFIFA_PROJECT_ID) and grants only `SET_SPLIT_GROUPS` permission to the `DefifaDeployer`, so the deployer can set splits on the fee project as needed for fee distribution.
+- `nana-721-hook-v6` for tiered NFT infrastructure
+- `nana-core-v6` for phased rulesets, terminals, and payout mechanics
+- Juicebox governance and permission surfaces for project ownership and split updates
 
-**Weight-based redemption instead of per-tier pots.** Rather than splitting the treasury into separate pots per tier at scoring time, the system assigns each tier a weight out of `TOTAL_CASHOUT_WEIGHT` (1e18). Cash-outs compute their share of the entire surplus on the fly. This avoids complex accounting for partial redemptions and lets the bonding math work naturally as tokens are burned. Early and late redeemers within the same tier get the same per-token value because the formula uses `surplus + totalAmountRedeemed` as the denominator base.
+## Safe Change Guide
 
-**Scorecard immutability after ratification.** Once a scorecard reaches quorum and is ratified, `cashOutWeightIsSet` is permanently set to `true` and no new weights can be written. Combined with the final ruleset that pauses payments, this guarantees the game's outcome is final and the treasury can only decrease through cash-outs.
+- Treat phase logic, governor logic, and hook cash-out logic as one system.
+- If you change scorecard validation, also inspect attestation weighting and ratification thresholds.
+- Keep `DefifaHookLib` and hook storage assumptions in sync; library extraction is for size, not for a separate trust boundary.
+- Do not move generic 721 behavior into Defifa just because the game uses it heavily.
+- When in doubt, trace an end-to-end game lifecycle rather than auditing one contract in isolation.