@ballkidz/defifa 0.0.21 → 0.0.23

package/ADMINISTRATION.md

@@ -1,166 +1,79 @@
 # Administration
 
-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
+| --- | --- |
+| Scope | Game launch configuration, scorecard governance, no-contest recovery, and optional fee-project ownership locking |
+| Control posture | Permissionless launch, then collective governance plus bounded contract-controlled lifecycle paths |
+| Highest-risk actions | Launching with wrong immutable game settings, misconfiguring governance thresholds, and misunderstanding no-contest handling |
+| Recovery posture | Mostly replacement or documented no-contest handling; there is no broad post-launch owner override |
 
-- 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.
+## Purpose
 
-## 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.
+`defifa` is unusual because game creation is permissionless but ongoing game control is intentionally narrow. The main administration job is understanding what is fixed at launch, what collective governance can still do, and what the deployer must do to finish settlement.
 
-## Recovery Notes
+## Control Model
 
-- 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.
+- `launchGameWith(...)` is the real governance commitment. Core game shape is fixed there.
+- `DefifaGovernor` controls scorecard submission, attestation, and ratification.
+- `DefifaHook` controls phase-aware mint and cash-out behavior but does not expose broad admin mutability.
+- `DefifaDeployer` still owns structural lifecycle duties such as fulfillment and no-contest queuing.
+- `DefifaProjectOwner` is an optional irreversible sink for the fee-project NFT.
 
 ## Roles
 
-| Role | Who | How Assigned |
-|------|-----|-------------|
-| **Game Creator** | Any EOA or contract that calls `DefifaDeployer.launchGameWith()` | Self-selected; permissionless |
-| **DefifaDeployer** (contract) | Singleton deployed at protocol setup | Immutable; owns all game JB projects and the governor |
-| **DefifaGovernor** (contract) | Singleton; `Ownable` by the DefifaDeployer | Ownership transferred from deployer at construction |
-| **DefifaHook** (per-game clone) | One clone per game; `Ownable` by the DefifaGovernor | Ownership transferred from deployer during `launchGameWith()` |
-| **DefifaProjectOwner** | Optional proxy contract that holds the Defifa fee project NFT | Receives project NFT; grants `SET_SPLIT_GROUPS` to deployer |
-| **Scorecard Submitter** | Any address during SCORING phase | Permissionless (`submitScorecardFor`) |
-| **Attestor** | Any NFT holder with attestation weight | Must hold game NFTs; weight proportional to holdings per tier |
-| **Default Attestation Delegate** | Address set at game launch | Set via `DefifaLaunchProjectData.defaultAttestationDelegate` |
-| **Tier Delegate** | Any address delegated attestation units by an NFT holder | Set via `setTierDelegateTo` / `setTierDelegatesTo` during MINT phase only |
-
-## Privileged Functions
-
-### DefifaDeployer
-
-| Function | Required Role | Permission Check | What It Does |
-|----------|--------------|-----------------|-------------|
-| `launchGameWith()` | Anyone | None (permissionless) | Creates a new JB project, clones DefifaHook, initializes governor, configures rulesets with MINT/REFUND/SCORING phases. Game parameters are immutable after this call. |
-| `fulfillCommitmentsOf()` | Anyone | Guarded by `fulfilledCommitmentsOf[gameId] != 0` reentrancy check; requires `cashOutWeightIsSet` on the hook | Sends fee payouts (Defifa 5% + NANA 2.5% + user splits) via try-catch `sendPayoutsOf`, then queues the final COMPLETE ruleset. If payout fails, emits `CommitmentPayoutFailed` and sets sentinel. Can only execute once per game. |
-| `triggerNoContestFor()` | Anyone | Requires `currentGamePhaseOf(gameId) == NO_CONTEST` and `!noContestTriggeredFor[gameId]` | Queues a new ruleset without payout limits so surplus equals balance, enabling full refunds. Can only execute once per game. |
-
-### DefifaGovernor
-
-| Function | Required Role | Permission Check | What It Does |
-|----------|--------------|-----------------|-------------|
-| `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`, `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
-
-| Function | Required Role | Permission Check | What It Does |
-|----------|--------------|-----------------|-------------|
-| `initialize()` | DefifaDeployer | Reverts if `address(this) == codeOrigin` or already initialized (`store != address(0)`) | One-time initialization of the cloned hook with game configuration, tiers, and tier names. Transfers ownership to caller. |
-| `setTierCashOutWeightsTo()` | DefifaGovernor (owner) | `onlyOwner`; must be in SCORING phase; weights not already set | Sets the cash-out weight distribution across tiers. Validates weights sum to `TOTAL_CASHOUT_WEIGHT` (1e18). Irreversible -- once set, `cashOutWeightIsSet` is permanently true. |
-| `setTierDelegateTo()` | Any NFT holder | Must be in MINT phase | Delegates attestation units for a specific tier to another address. |
-| `setTierDelegatesTo()` | Any NFT holder | Must be in MINT phase; delegatee cannot be address(0) | Batch delegation of attestation units across multiple tiers. |
-| `mintReservesFor()` | Anyone | Reverts if `pauseMintPendingReserves` is set in ruleset metadata | Mints reserved tokens to the tier's reserve beneficiary. Increments `_totalMintCost` so reserved recipients can claim fee tokens. |
-| `afterPayRecordedWith()` | JB Terminal | Caller must be a terminal of the project; `msg.value` must be 0 | Processes payment: validates currency, mints NFTs, sets up attestation delegation. |
-| `afterCashOutRecordedWith()` | JB Terminal | Caller must be a terminal of the project; `msg.value` must be 0 | Burns NFTs on cash-out, tracks redeemed amounts, distributes fee tokens during COMPLETE phase. |
-| `transferOwnership()` | Current owner | `onlyOwner` (inherited from Ownable) | Transfers hook ownership. Used once during deployment to transfer from deployer to governor. |
-
-### DefifaProjectOwner
-
-| Function | Required Role | Permission Check | What It Does |
-|----------|--------------|-----------------|-------------|
-| `onERC721Received()` | JBProjects contract | `msg.sender` must be the JBProjects contract | When the Defifa fee project NFT is transferred here, auto-grants `SET_SPLIT_GROUPS` permission to the DefifaDeployer. The project NFT is permanently locked -- cannot be recovered. |
-
-## Game Lifecycle Administration
-
-The game lifecycle is fully automated through Juicebox rulesets configured at launch. No admin can change phases manually.
-
-```
-COUNTDOWN --> MINT --> REFUND (optional) --> SCORING --> COMPLETE or NO_CONTEST
-```
-
-**Phase transitions are time-based, encoded in JBRuleset durations:**
-- **COUNTDOWN**: Before `start - mintPeriodDuration - refundPeriodDuration`. Cycle number 0.
-- **MINT**: Duration = `mintPeriodDuration`. Payments open, refunds at mint price. Cycle number 1.
-- **REFUND**: Duration = `refundPeriodDuration` (optional, only if nonzero). Payments paused, refunds still at mint price. Cycle number 2.
-- **SCORING**: Duration = 0 (no expiry). Payments paused. Cash-out weights must be set via governance. Cycle number 3+.
-- **COMPLETE**: Entered when `cashOutWeightIsSet == true`. Cash-outs use scorecard weights.
-- **NO_CONTEST**: Entered when `minParticipation` threshold is not met, or `scorecardTimeout` elapses without ratification. Requires `triggerNoContestFor()` to unlock refunds.
-
-**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, 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
-
-### Attestation Quorum Details
-
-The quorum threshold is 50% of the total attestation power across all tiers with nonzero mint supply. Attestation power per tier is proportional to the tier's minted supply at the `attestationsBegin - 1` checkpoint timestamp, with pending reserves snapshotted at scorecard submission time to prevent reserve minting from inflating attestation power.
-
-**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 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.
-
-## Immutable Configuration
-
-The following are set at game creation and cannot be changed:
-
-| Parameter | Set In | Notes |
-|-----------|--------|-------|
-| Tier prices | `launchGameWith()` | Uniform price across all tiers (`tierPrice`) |
-| Tier count and names | `launchGameWith()` | Stored in hook during `initialize()` |
-| Game timing (start, mint duration, refund duration) | `launchGameWith()` | Encoded as JBRuleset durations |
-| Payment token | `launchGameWith()` | Single token per game |
-| 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 |
-| User splits | `launchGameWith()` | Stored as JB split groups at game creation |
-| Hook code origin | Constructor | Template contract for cloning |
-| `TOTAL_CASHOUT_WEIGHT` | Constant | 1e18, cannot be changed |
-| JB project ownership | `launchGameWith()` | Project owned by DefifaDeployer contract |
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Game creator | Calls `launchGameWith(...)` | Launch only | Does not receive broad runtime admin power afterward |
+| Scorecard participant | Holds or receives attestation power | Per game | Can submit, attest, revoke, and help ratify |
+| Ratification path caller | Any caller who meets the documented conditions | Per game | Finalizes a valid scorecard |
+| Fulfillment path caller | Any valid caller once ratified | Per game | Must run the completion commitment path |
+| `DefifaProjectOwner` holder | Project NFT sent into sink | Per fee project | Irreversible ownership lock |
 
-## Admin Boundaries
-
-What admins CANNOT do:
+## Privileged Surfaces
 
-1. **No one can change game rules after launch.** Tier prices, timing, token, fees, and split configuration are all immutable.
+- `launchGameWith(...)` fixes phase timing, tiers, fee routing, and governance shape
+- `submitScorecardFor(...)`, `attestToScorecardFrom(...)`, `revokeAttestationFrom(...)`, and `ratifyScorecardFrom(...)` govern outcome selection
+- `fulfillCommitmentsOf(...)` turns a ratified scorecard into real settlement
+- `triggerNoContestFor(...)` moves failed games into the documented recovery path
 
-2. **No one can unilaterally set scorecard weights.** The `setTierCashOutWeightsTo` function requires `onlyOwner` (the governor), and the governor only calls it after a scorecard reaches quorum through collective attestation.
+## Immutable And One-Way
 
-3. **No one can pause or cancel a game.** Once launched, the game proceeds through its phases automatically based on time.
+- Game phase timing is fixed at launch.
+- Scorecard timeout, minimum participation, and default delegation choices are fixed at launch.
+- `setTierCashOutWeightsTo()` is effectively one-way once final weights are installed.
+- `cashOutWeightIsSet` permanently closes the score-setting path after success.
+- `DefifaProjectOwner` permanently locks the project NFT it receives.
+- `fulfillCommitmentsOf()` and `triggerNoContestFor()` are single-use style lifecycle paths.
 
-4. **No one can extract funds from the treasury.** The `ownerMustSendPayouts` flag is set on the SCORING ruleset, and payouts are limited to the pre-configured splits. The deployer can only send payouts matching the split configuration.
+## Operational Notes
 
-5. **No one can mint new tiers or change tier supply.** Tiers are set once during `initialize()` with `cannotBeRemoved: true`.
+- Validate game timings, tier setup, fee routing, and attestation settings before launch.
+- Treat `launchGameWith()` as the real admin commitment.
+- During scoring, follow the submission, attestation, and ratification flow rather than looking for discretionary overrides.
+- Use `triggerNoContestFor()` only when the game has actually entered the documented no-contest condition.
+- Treat the fee-project ownership proxy as a burn-lock mechanism, not a recoverable custody tool.
 
-6. **No one can change delegates after MINT phase.** `setTierDelegateTo` and `setTierDelegatesTo` both revert with `DefifaHook_DelegateChangesUnavailableInThisPhase` outside MINT.
+## Machine Notes
 
-7. **No one can re-set cash-out weights.** The `cashOutWeightIsSet` flag is checked before setting and the function reverts with `DefifaHook_CashoutWeightsAlreadySet`.
+- Do not infer ongoing admin power for the game creator; launch is permissionless but not an ongoing authority grant.
+- Treat `DefifaDeployer`, `DefifaGovernor`, `DefifaHook`, and `DefifaProjectOwner` as the minimum source-of-truth set for authority review.
+- If scorecard state, quorum assumptions, or timeout state differ from the expected lifecycle, inspect the current phase before documenting the next action.
+- If a game launched with wrong immutable economics, timing, or split assumptions, do not guess at an in-place fix.
 
-8. **No one can re-ratify a scorecard.** The `ratifiedScorecardIdOf[gameId] != 0` check prevents double ratification.
+## Recovery
 
-9. **No one can fulfill commitments twice.** The `fulfilledCommitmentsOf[gameId] != 0` check prevents re-entry.
+- If a scorecard never reaches a valid ratification path and timeout conditions are met, use the documented no-contest flow.
+- If a game launched with wrong immutable economics, timing, fee routing, or tier design, recovery is usually a replacement deployment.
+- If fee-project ownership was transferred into `DefifaProjectOwner`, there is no recovery path for that NFT.
+- There is no broad owner override that can pause, cancel, or rewrite a live game after launch.
 
-10. **No one can recover the project NFT from DefifaProjectOwner.** Once transferred, the NFT is permanently locked.
+## Admin Boundaries
 
-11. **The game creator has no ongoing privileges.** After `launchGameWith()` returns, the caller has no special role. All game administration is handled by the protocol contracts and collective governance.
+- No one can change tier prices, timing, payment token, fees, or split configuration after launch.
+- No one can unilaterally set scorecard weights without the documented governance path.
+- No one can manually pause, cancel, or rewind a game phase.
+- No one can set cash-out weights twice.
+- No one can fulfill commitments twice.
+- No one can recover the project NFT from `DefifaProjectOwner`.

package/ARCHITECTURE.md

@@ -2,66 +2,130 @@
 
 ## Purpose
 
-`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.
+`defifa` builds phased prediction games on top of Juicebox and the 721 hook stack. A game is a Juicebox project with a custom NFT hook, a scorecard governor, and a deployer that launches the project and later fulfills the economic commitments that make completion real.
 
-## Boundaries
+## System Overview
 
-- `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`.
+`DefifaHook`, `DefifaGovernor`, and `DefifaDeployer` form one game-state machine even though they are deployed separately. The hook owns game-piece NFT behavior, attestation delegation, and phase-sensitive cash-out weighting. The governor owns scorecard submission, attestation, quorum, and ratification. The deployer owns game launch, phased ruleset setup, and commitment fulfillment after governance decides the outcome.
 
-## Main Components
+## Core Invariants
 
-| 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 |
+- The game is economically coherent only if deployer, governor, and hook agree on phase progression.
+- Ratification is the only path that should install final cash-out weights for the complete phase.
+- Attestation power should reflect tier semantics, not raw circulating supply.
+- Refund, scoring, complete, and no-contest behavior must be mutually coherent.
+- The deployer's post-ratification fulfillment path is mandatory economics, not optional housekeeping.
+- Completion-phase cash outs must account for already redeemed tokens and pending reserve dilution correctly.
 
-## Runtime Model
+## Modules
+
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `DefifaDeployer` | Launches games, sets phased rulesets, clones hooks, initializes governance, and fulfills commitments | Launch-time and completion-time runtime surface |
+| `DefifaHook` | NFT minting, delegation, game-phase-aware cash-out behavior, and completion claims | Main game-facing runtime hook |
+| `DefifaGovernor` | Scorecard submission, attestation weighting, quorum, grace periods, and ratification | Governance surface |
+| `DefifaHookLib` | Shared validation and weight math extracted from the hook | Bytecode-management helper |
+| `DefifaTokenUriResolver` | Dynamic token metadata and SVG rendering | Metadata layer |
+| `DefifaProjectOwner` | Irreversible project-owner sink that preserves selected operator permissions | Governance-sensitive helper |
+
+## Trust Boundaries
+
+- Canonical treasury accounting, project ownership, rulesets, terminals, and payout mechanics remain in `nana-core-v6`.
+- Tier storage, reserve minting mechanics, and generic ERC-721 behavior come from `nana-721-hook-v6`.
+- `DefifaGovernor` is trusted to ratify scorecards only through its quorum, grace-period, and timelock rules.
+- `DefifaDeployer` is trusted to convert governance output into the final completion envelope.
+
+## Critical Flows
+
+### Launch Game
 
 ```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
+  -> deployer validates mint/refund/start timings
+  -> deployer predicts the game project ID and clones a game hook deterministically
+  -> deployer builds phased rulesets and optional fee splits
+  -> controller launches the project
+  -> governor is initialized for the game
+  -> hook ownership and project ownership are transferred into the intended long-term shape
+```
+
+### Mint During Open Play
+
+```text
+player
+  -> pays the game project during the mint window
+  -> hook mints the selected game-piece NFT tier
+  -> delegation state and total mint-cost accounting are updated
+  -> reserved mints and pending reserves continue to affect later completion claims
 ```
 
-## Critical Invariants
+### Scorecard Governance
+
+```text
+attester or proposer
+  -> governor accepts a scorecard candidate
+  -> attestation power is computed from tier-relative holdings
+  -> quorum, grace period, and timelock gates are enforced
+  -> governor ratifies exactly one winning scorecard
+```
+
+### Fulfill Commitments And Complete
+
+```text
+authorized completion path
+  -> deployer reads the ratified outcome
+  -> deployer fulfills the game's promised commitments and queues the final ruleset
+  -> hook installs final cash-out weights
+  -> holders burn pieces during complete phase to reclaim their weighted share of the pot
+```
+
+## Accounting Model
+
+This repo does not replace `nana-core-v6` treasury accounting. Its critical economic state is:
 
-- 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.
+- phase timestamps and game ops data in the deployer
+- scorecard and attestation state in the governor
+- tier cash-out weights, redeemed-token tracking, mint-cost totals, and delegation state in the hook
 
-## Where Complexity Lives
+The hook's completion math is intentionally phase-sensitive:
 
-- 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.
+- before completion, cash-out behavior is refund or fallback oriented
+- after ratification and fulfillment, cash-out weights become the game outcome
+- completion claims use minted cost, redeemed tracking, and pending-reserve-aware dilution together
 
-## Dependencies
+## Security Model
 
-- `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
+- The primary risk is semantic drift across hook, governor, and deployer.
+- Ratification and fulfillment are separate steps; a ratified scorecard without correct fulfillment still leaves the game economically unfinished.
+- Attestation weighting is part of game fairness, not just governance plumbing.
+- Pending reserves and reserved-mint behavior affect both quorum fairness and completion-time claim dilution.
+- Phase transitions are safety-critical. A timing bug can enable refunds, scoring, or completion in the wrong order.
 
 ## Safe Change Guide
 
-- 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.
+- Review `DefifaHook`, `DefifaGovernor`, and `DefifaDeployer` together for any nontrivial change.
+- If phase semantics change, re-check mint, refund, scoring, ratification, fulfillment, and completion cash-out behavior together.
+- If attestation math changes, inspect tier semantics, delegation, quorum, and ratification thresholds together.
+- If completion claim math changes, re-check redeemed tracking, pending reserve dilution, and fee-token side claims in the same review.
+
+## Canonical Checks
+
+- governor state transitions and scorecard handling:
+  `test/DefifaGovernor.t.sol`
+- fulfillment and ratification coupling:
+  `test/regression/FulfillmentBlocksRatification.t.sol`
+- pending reserve effects on completion fairness:
+  `test/audit/PendingReserveSnapshotBypass.t.sol`
+
+## Source Map
+
+- `src/DefifaDeployer.sol`
+- `src/DefifaGovernor.sol`
+- `src/DefifaHook.sol`
+- `src/libraries/DefifaHookLib.sol`
+- `src/DefifaTokenUriResolver.sol`
+- `test/DefifaGovernor.t.sol`
+- `test/DefifaHookRegressions.t.sol`
+- `test/DefifaFeeAccounting.t.sol`
+- `test/regression/FulfillmentBlocksRatification.t.sol`
+- `test/audit/PendingReserveSnapshotBypass.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,96 +1,94 @@
 # Audit Instructions
 
-Defifa is a staged prediction-game system built on Juicebox and the 721 hook stack. The main risks are governance correctness, treasury settlement, and cash-out weight integrity.
+Defifa is a staged prediction-game system built on Juicebox and the tiered 721 stack. Audit it as a governance-and-settlement protocol, not just an NFT game.
 
-## Objective
+## Audit Objective
 
 Find issues that:
+
 - let players extract more than their fair share of the game pot
-- break the game-phase lifecycle or let actions occur in the wrong phase
-- corrupt scorecard submission, attestation, quorum, grace-period, or ratification logic
+- break the game-phase lifecycle or allow actions in the wrong phase
+- corrupt scorecard submission, attestation, quorum, delegation, grace-period, or ratification logic
 - miscompute tier cash-out weights or fee-token distribution
-- let deployment or ownership helpers leave a game misconfigured
+- leave a deployed game misconfigured through deployer or owner-helper mistakes
 
 ## Scope
 
 In scope:
+
 - `src/DefifaDeployer.sol`
 - `src/DefifaGovernor.sol`
 - `src/DefifaHook.sol`
 - `src/DefifaProjectOwner.sol`
 - `src/DefifaTokenUriResolver.sol`
 - `src/libraries/DefifaHookLib.sol`
-- `src/interfaces/`, `src/structs/`, and `src/enums/`
-- deployment scripts in `script/`
+- enums, interfaces, structs, and deployment helpers
+
+## Start Here
 
-Key integrations:
-- `nana-core-v6`
-- `nana-721-hook-v6`
-- deployer and ownership helper patterns shared across the ecosystem
+1. `src/DefifaGovernor.sol`
+2. `src/DefifaHook.sol`
+3. `src/DefifaDeployer.sol`
+4. `src/DefifaProjectOwner.sol`
 
-## System Model
+## Security Model
 
 High-level lifecycle:
+
 - deploy a game as a Juicebox project
-- sell outcome NFTs during mint phase
+- sell outcome NFTs during the mint phase
 - optionally allow refunds or no-contest handling
 - run scorecard governance through submissions and attestations
-- ratify a scorecard
+- ratify one scorecard
 - update cash-out weights so winning pieces can redeem the treasury
 
 The contracts split responsibility as follows:
-- `DefifaDeployer`: project launch and lifecycle orchestration
-- `DefifaHook`: minting, burning, and game-specific cash-out accounting
-- `DefifaGovernor`: scorecard governance and ratification
-- `DefifaTokenUriResolver`: game NFT metadata
-
-## Critical Invariants
 
-1. Pot conservation
-Total redeemable value across all settled tiers must not exceed the game treasury after applying intended fees.
+- `DefifaDeployer` launches the project and wires lifecycle configuration
+- `DefifaHook` handles minting, burning, fee accounting, and game-specific cash-out math
+- `DefifaGovernor` owns scorecard governance and ratification
+- `DefifaProjectOwner` acts as a project-owner helper where governance needs a stable admin surface
+- `DefifaTokenUriResolver` handles game NFT metadata
 
-2. Governance phase safety
-Submission, attestation, ratification, no-contest, and refund paths must be reachable only in the intended lifecycle windows.
+## Roles And Privileges
 
-3. Quorum and grace-period correctness
-Attestation power, delegation, quorum thresholds, and grace-period timing must not be manipulable to ratify an invalid scorecard early or indefinitely block a valid one.
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Game deployer or owner path | Configure a game's initial lifecycle and helper wiring | Must not retain hidden post-launch powers |
+| Governor participants | Submit, attest to, and ratify scorecards | Must remain bounded by phase, quorum, and delegation rules |
+| `DefifaHook` | Determine mint and final redeem economics | Must not over-credit players or under-account fees |
+| Project owner helper | Stand in for project ownership where configured | Must not diverge from the intended governance authority |
 
-4. Settlement determinism
-Once the winning scorecard is finalized, the resulting cash-out weights must match the intended outcome and remain internally consistent.
+## Integration Assumptions
 
-5. No fee-token dilution bugs
-Fee accounting and reserve-related side effects must not dilute players or over-credit non-paying participants.
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `nana-core-v6` | Treasury accounting, rulesets, and cash-out surfaces stay coherent | Pot settlement and redeem math become unsound |
+| `nana-721-hook-v6` | Tier issuance and reserve behavior match Defifa's game logic | Voting power, supply, and cash-out weights drift |
+| Owner-helper and deployer patterns | Launch-time authority fully converges to the intended game authority | Games remain misconfigured or over-privileged |
 
-## Threat Model
+## Critical Invariants
 
-Prioritize:
-- whale participants trying to dominate attestation power
-- players exploiting pending reserves, delegation, or snapshot timing
-- callers trying to ratify with partially completed commitments
-- phase-boundary and timestamp races
-- settlement paths that assume external payout success
+1. Pot conservation.
+2. Governance phase safety.
+3. Quorum and grace-period correctness.
+4. Settlement determinism once a scorecard is final.
+5. Fee-token and reserve correctness.
 
-## Hotspots
+## Attack Surfaces
 
-- `DefifaGovernor` scorecard state transitions
+- `DefifaGovernor` scorecard state transitions and ratification gating
+- delegation, attestation, and quorum calculations
 - `DefifaHook` cash-out weight and fee-token accounting
 - reserve-related denominators during governance and settlement
 - deployer logic that queues or fulfills lifecycle rulesets
-- any low-level call used during ratification or fulfillment
-- token URI or metadata logic only insofar as it can desync governance or settlement assumptions
 
-## Build And Verification
+## Accepted Risks Or Behaviors
+
+- Governance and settlement are intentionally phase-heavy, so timestamp and lifecycle transitions are core audit targets rather than edge cases.
+
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-The current tests focus on:
-- quorum hardening
-- no-contest and refund handling
-- pending reserve dilution
-- fee accounting
-- regressions around attestation delegation and grace-period bypass
-
-The best findings in this repo usually demonstrate either treasury over-redemption or a governance state transition that should be impossible.