@ballkidz/defifa 0.0.21 → 0.0.23

package/README.md

@@ -1,44 +1,79 @@
 # Defifa
 
-Defifa is an on-chain prediction game system built on Juicebox. Players mint NFT game pieces, scorecards determine how the pot is distributed, and winners cash out by burning the NFTs that backed their position.
+Defifa is an onchain prediction game system built on Juicebox. Each game is a Juicebox project with staged rulesets, tiered NFT game pieces, scorecard governance, and a final settlement path that turns the project's surplus into winner payouts.
 
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Use this repo when the question is about game lifecycle, scorecard ratification, attestation power, or Defifa-specific settlement behavior. Do not start here for generic project accounting, terminal behavior, or standard 721-tier mechanics.
 
-## Overview
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
-Each Defifa game is a Juicebox project with a staged lifecycle:
+## What This Repo Owns
+
+Defifa adds game-specific behavior on top of Juicebox and the 721 hook stack:
+
+- phased game launch and completion packaging in `DefifaDeployer`
+- game-piece behavior, delegation, and settlement weighting in `DefifaHook`
+- scorecard submission, attestation, quorum, grace periods, and ratification in `DefifaGovernor`
+- onchain card rendering and token metadata in `DefifaTokenUriResolver`
+
+This repo does not own:
+
+- canonical terminal accounting or surplus math
+- generic 721 tier storage and most shared NFT-hook machinery
+- generic Juicebox permission, project, or ruleset semantics
+
+## Mental Model
+
+Defifa is easiest to read as one state machine split across three contracts:
+
+1. `DefifaDeployer` launches the game and wires the components together
+2. `DefifaGovernor` decides which scorecard, if any, becomes final
+3. `DefifaHook` converts that ratified result into cash-out weights for game-piece holders
 
-- countdown before minting opens
-- mint phase where players buy outcome NFTs
-- optional refund window
-- scoring phase where holders attest to scorecards
-- completion or no-contest settlement
+Most real issues live at the seams between those contracts.
 
-The project's surplus is the prize pot. Once a scorecard reaches quorum and survives its grace period, the hook updates cash-out weights so players can redeem winning pieces for their share.
+## Read These Files First
 
-Use this repo when you want a full game system with lifecycle, governance, and settlement. Do not treat it as a generic tournament payout primitive; its assumptions are Defifa-specific.
+1. [`src/DefifaDeployer.sol`](./src/DefifaDeployer.sol)
+2. [`src/DefifaHook.sol`](./src/DefifaHook.sol)
+3. [`src/DefifaGovernor.sol`](./src/DefifaGovernor.sol)
+4. [`src/libraries/DefifaHookLib.sol`](./src/libraries/DefifaHookLib.sol)
+5. [`test/DefifaGovernor.t.sol`](./test/DefifaGovernor.t.sol)
+6. [`test/DefifaFeeAccounting.t.sol`](./test/DefifaFeeAccounting.t.sol)
+7. [`test/DefifaNoContest.t.sol`](./test/DefifaNoContest.t.sol)
 
-If the issue is basic NFT issuance, project accounting, or generic governance plumbing, start in the underlying protocol repos first. Defifa is where the game-specific lifecycle and settlement assumptions get introduced.
+Then read the upstream repos this package depends on:
+
+- [`../nana-721-hook-v6/README.md`](../nana-721-hook-v6/README.md)
+- [`../nana-core-v6/README.md`](../nana-core-v6/README.md)
 
 ## Key Contracts
 
 | Contract | Role |
 | --- | --- |
 | `DefifaDeployer` | Launches games, clones hooks, initializes governance, and fulfills post-game fee commitments. |
-| `DefifaHook` | ERC-721 game piece hook that tracks tiers, delegation, and cash-out weights for settlement. |
-| `DefifaGovernor` | Scorecard governance surface that accepts submissions, attestations, and ratification. |
-| `DefifaTokenUriResolver` | On-chain metadata renderer for game cards. |
-| `DefifaProjectOwner` | Ownership helper for the Defifa fee project. |
+| `DefifaHook` | ERC-721 game-piece hook that tracks tiers, delegation, pending reserves, and cash-out weights for settlement. |
+| `DefifaGovernor` | Scorecard governance surface that accepts submissions, attestations, quorum checks, grace periods, and ratification. |
+| `DefifaHookLib` | Shared validation and weight logic extracted from the hook. |
+| `DefifaTokenUriResolver` | Onchain metadata renderer for game cards. |
+| `DefifaProjectOwner` | Ownership sink used for the fee-project surface. |
 
-## Mental Model
+## Lifecycle
 
-Defifa is easiest to read as three layers:
+Each Defifa game is a Juicebox project with a staged lifecycle:
 
-1. launch and lifecycle packaging in `DefifaDeployer`
-2. player position and settlement state in `DefifaHook`
-3. scorecard selection in `DefifaGovernor`
+1. countdown before minting opens
+2. mint phase where players buy outcome NFTs
+3. optional refund or no-contest handling if the game cannot settle normally
+4. scoring phase where participants submit and attest to scorecards
+5. completion after a scorecard reaches quorum and survives its grace period
+6. final cash out where winning pieces redeem against the prize pot
 
-Most system-level issues come from how those layers interact, not from one layer in isolation.
+The important boundary is that the pot is still ordinary Juicebox project value until governance ratifies a scorecard. Defifa-specific settlement starts only when the governor installs final cash-out weights on the hook.
 
 ## Install
 
@@ -59,10 +94,6 @@ Useful scripts:
 - `npm run deploy:mainnets`
 - `npm run deploy:testnets`
 
-## Deployment Notes
-
-Deployments are handled through Sphinx. The system composes Juicebox core, the 721 hook stack, and Defifa-specific governance and resolver contracts into a single game-launch surface.
-
 ## Repository Layout
 
 ```text
@@ -77,15 +108,49 @@ src/
   libraries/
   structs/
 test/
-  lifecycle, fee, governance, invariant, fork, audit, and regression coverage
+  governance, fee-accounting, no-contest, adversarial, regression, fork, and audit coverage
 script/
   Deploy.s.sol
   helpers/
+references/
+  operations.md
+  runtime.md
 ```
 
-## Risks And Notes
+## Integration Traps
+
+- Defifa is not a generic tournament payout primitive
+- `DefifaGovernor` and `DefifaHook` must be read together
+- fee accounting and prize accounting are coupled
+- a timeout into `NO_CONTEST` is a real terminal state
+- the shared `JB721TiersHookStore` surface is an upstream ecosystem dependency, not a Defifa-only detail
+
+## High-Signal Tests
+
+- [`test/DefifaGovernor.t.sol`](./test/DefifaGovernor.t.sol)
+- [`test/DefifaGovernanceHardening.t.sol`](./test/DefifaGovernanceHardening.t.sol)
+- [`test/DefifaFeeAccounting.t.sol`](./test/DefifaFeeAccounting.t.sol)
+- [`test/DefifaNoContest.t.sol`](./test/DefifaNoContest.t.sol)
+- [`test/DefifaAdversarialQuorum.t.sol`](./test/DefifaAdversarialQuorum.t.sol)
+- [`test/audit/PendingReserveDilution.t.sol`](./test/audit/PendingReserveDilution.t.sol)
+- [`test/audit/AttestationDoubleCount.t.sol`](./test/audit/AttestationDoubleCount.t.sol)
+- [`test/regression/GracePeriodBypass.t.sol`](./test/regression/GracePeriodBypass.t.sol)
+
+## Deployment Notes
+
+Deployments are handled through Sphinx. The deployer composes Juicebox core, the 721 hook stack, Defifa-specific governance, and metadata rendering into one game-launch surface.
+
+## Where State Lives
+
+- game lifecycle config and post-game fulfillment bookkeeping: `DefifaDeployer`
+- submitted scorecards, attestations, quorum state, and ratification timing: `DefifaGovernor`
+- tier state, delegation, pending reserve awareness, and final cash-out weights: `DefifaHook`
+- base project balance and terminal settlement: `nana-core-v6`
+- shared 721 tier store semantics: `nana-721-hook-v6`
+
+## For AI Agents
 
-- scorecard governance quality depends on quorum, grace period, and participation assumptions set at launch
-- optional refund windows and no-contest thresholds materially change game economics
-- settlement is only as good as the ratified scorecard; bad governance configuration can still produce bad outcomes
-- fee-accounting and pending-reserve edge cases are heavily tested because they are easy places for pot dilution or griefing
+- Treat Defifa as a game-specific layer on top of `nana-core-v6` and `nana-721-hook-v6`, not as a standalone accounting system.
+- Use `DefifaDeployer`, `DefifaHook`, and `DefifaGovernor` as the primary execution surfaces.
+- Treat `NO_CONTEST`, refund handling, and grace-period logic as normal product behavior.
+- If the question is about generic tier storage, terminal settlement, or project accounting, hand off to upstream repos first.

package/RISKS.md

@@ -4,7 +4,7 @@ This file focuses on the game-theoretic, governance, and settlement risks in Def
 
 ## How to use this file
 
-- Read `Priority risks` first; they identify the main ways a game can settle unfairly or get stuck.
+- Read `Priority risks` first.
 - Use the detailed sections below to reason about governor power, live supply assumptions, and downstream hook dependencies.
 - Treat `Accepted Behaviors` and `Invariants to Verify` as explicit boundaries for audit scope.
 
@@ -12,87 +12,78 @@ This file focuses on the game-theoretic, governance, and settlement risks in Def
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
-| P0 | Scorecard capture at quorum | An actor that assembles 50%+ of attestation power can ratify an arbitrary scorecard and redirect the pot. | Tier-level attestation caps, grace period, and governance review of delegate concentration. |
-| P1 | Shared 721 hook store blast radius | Defifa inherits the same shared `JB721TiersHookStore` surface as the general 721 hook ecosystem. A store bug hits every game. | Reuse of audited 721-hook invariants, store-focused testing, and ecosystem-level monitoring. |
-| P1 | Supply and reserve accounting drift | Game fairness depends on attestation power, fee-token dilution, and cash-out weights tracking real mint/reserve state. | Explicit invariants on supply, reserve inclusion, and tier-weight arithmetic. |
-
+| P0 | Scorecard capture at quorum | An actor that assembles enough attestation power can ratify an arbitrary scorecard and redirect the pot. | Tier-level attestation caps, grace period, and governance review of delegate concentration. |
+| P1 | Shared 721-hook store blast radius | Defifa inherits the same shared `JB721TiersHookStore` surface as the general 721-hook ecosystem. | Reuse of 721-hook invariants, store-focused testing, and ecosystem-level monitoring. |
+| P1 | Supply and reserve accounting drift | Game fairness depends on attestation power, fee-token dilution, and cash-out weights tracking real mint and reserve state. | Explicit invariants on supply, reserve inclusion, and tier-weight arithmetic. |
 
 ## 1. Trust Assumptions
 
-- **Governor as Hook Owner.** The DefifaGovernor owns each DefifaHook clone. The governor can set tier cash-out weights via `ratifyScorecardFrom`, which executes an arbitrary call to the hook. If the governor is compromised, the hook's cash-out weights can be set to any values.
-- **Deployer as Project Owner.** The DefifaDeployer contract owns all game projects. It controls ruleset queuing, payout sending, and split configuration. Its logic is immutable (no upgradability), so the trust boundary is the contract code itself.
-- **DefifaProjectOwner Irrecoverability.** Once the Defifa project NFT is transferred to DefifaProjectOwner, it cannot be recovered. This is intentional but irreversible.
-- **External Dependencies.** Relies on JB721TiersHookStore, JBController, JBMultiTerminal, JBRulesets, and JBPrices. Bugs in any upstream contract affect all Defifa games.
-- **Default Attestation Delegate.** If set, the default attestation delegate receives delegated attestation power for all new minters who do not specify a delegate. This entity accumulates significant governance power.
-- **721 hook store shared with nana-721-hook-v6.** `DefifaHook` uses the same `JB721TiersHookStore` dependency as the broader 721-hook ecosystem even though it has its own hook implementation. All store-level risks from [nana-721-hook-v6 RISKS.md](../nana-721-hook-v6/RISKS.md) still apply wherever Defifa relies on shared tier-store semantics. Store bugs affect all Defifa games simultaneously.
+- **Governor as hook owner.** The governor can set tier cash-out weights through ratification.
+- **Deployer as project owner.** The deployer owns game projects and controls ruleset queuing and commitment fulfillment.
+- **DefifaProjectOwner irrecoverability.** Once the project NFT is transferred there, it cannot be recovered.
+- **External dependencies.** Core protocol and shared 721-store behavior remain upstream trust boundaries.
+- **Default attestation delegate.** If set, it can accumulate meaningful governance power across new minters.
 
 ## 2. Economic Risks
 
-- **Scorecard manipulation via 50% quorum.** A single entity that acquires 50%+ of attestation power across tiers can unilaterally ratify any scorecard, directing the entire pot to chosen tiers. Per-tier cap at `MAX_ATTESTATION_POWER_TIER` limits single-tier dominance. 1-day minimum grace period gives counter-attestors time to respond.
-- **Dynamic quorum from live supply (mitigated).** `quorum()` counts tiers with circulating supply (`currentSupplyOfTier > 0`) OR pending reserves (`numberOfPendingReservesFor > 0`). No snapshot is needed because during SCORING, supply is frozen (no new paid mints, no burns) and reserve minting doesn't change which tiers are counted — tiers with pending reserves are already included. Pending reserves also dilute attestation power — `getAttestationWeight` includes them in the denominator so every token holder's voting power already accounts for reserves that will eventually be minted. When the reserve beneficiary mints later, power redistributes smoothly (no shift). Consistent with the cash-out path which also dilutes by pending reserves.
-- **Cash-out weight integer division truncation.** `_weight / _totalTokensForCashoutInTier` rounds down, permanently locking dust in the contract. Maximum loss: 1 wei per tier per game (128 wei max with 128 tiers).
-- **Fee token dilution from reserved mints.** Reserved mints increment `_totalMintCost` by `tier.price * count` even though no ETH was paid. This dilutes paid minters' share of fee tokens (`$DEFIFA` / `$NANA`). Example: if 1000 NFTs are minted by payers (paying 1 ETH each = 1000 ETH total), and 100 reserved NFTs are minted (adding 100 ETH to `_totalMintCost` with no ETH deposited), fee token claims are diluted by ~9.1% (100/1100). The dilution is bounded by the reserve frequency — at `reserveFrequency=10`, every 10th mint is a reserve, capping dilution at ~10%.
-- **128-tier limit hard-coded.** `_tierCashOutWeights` is a fixed `uint256[128]` array. Games with more than 128 tiers have tiers beyond index 128 unable to receive cash-out weights.
+- **Scorecard manipulation via quorum.** Enough attestation power can redirect the whole pot.
+- **Supply and pending-reserve drift.** Governance and settlement both depend on correct reserve-aware denominators.
+- **Cash-out-weight truncation.** Integer division can lock small dust amounts.
+- **Fee-token dilution from reserved mints.** Reserved mints can dilute fee-token shares even though no ETH was paid for them.
+- **128-tier settlement ceiling.** Games that rely on more than 128 scored tiers can fail settlement.
 
 ## 3. Governance Risks
 
-- **Single governor instance across all games.** All games share one DefifaGovernor. A bug in `ratifyScorecardFrom`, `attestToScorecardFrom`, or `submitScorecardFor` affects every game simultaneously.
-- **Scorecard timeout can block legitimate ratification.** If `scorecardTimeout` elapses before ratification, the game permanently enters NO_CONTEST. Even a scorecard that has reached quorum cannot be ratified. `triggerNoContestFor()` is permissionless and allows fund recovery.
-- **Delegation locked after MINT phase.** `setTierDelegateTo` only works during MINT phase. After MINT, NFT transfers auto-delegate to the recipient, but holders cannot explicitly re-delegate to a third party.
-- **No-contest requires explicit trigger.** In NO_CONTEST, users cannot immediately cash out -- someone must call `triggerNoContestFor()` to queue a refund ruleset. Without this trigger, the SCORING ruleset allocates the entire balance as payouts, leaving surplus at 0.
+- **Single governor instance across games.** A bug in the governor affects every game that uses it.
+- **Scorecard timeout can block legitimate ratification.** Once timeout is reached, the game may have to fall into no-contest even if a scorecard was close to success.
+- **Delegation is phase-sensitive.** Some delegation behavior freezes after mint phase.
+- **No-contest requires an explicit trigger.** The fallback path does not activate itself just because the timeout happened.
+- **No-contest trigger is not the same as active refund state.** Integrators must distinguish queued recovery from currently active refund rules.
 
 ## 4. Reentrancy Surface
 
-- **afterCashOutRecordedWith.** Burns tokens before external calls. `_claimTokensFor` calls `safeTransfer` on ERC-20 tokens (DEFIFA_TOKEN, BASE_PROTOCOL_TOKEN). Preceding burn and state updates prevent meaningful reentrancy profit.
+- **`afterCashOutRecordedWith`.** Burns happen before external fee-token transfers, which narrows the surface, but transfer compatibility still matters.
+- **Ratification uses a low-level call into the hook.** Double-set protections must hold.
 
 ## 5. DoS Vectors
 
-- **Unbounded tier iteration in governance.** `getAttestationWeight` and `quorum` iterate over all tiers (`maxTierIdOf`). Gas cost: ~3-5k per tier (storage read + bitmap check). At 128 tiers (the hard cap), ~400-650k gas for a single `quorum()` call. At the block gas limit (30M), this is safe, but composing `quorum()` inside a larger transaction (e.g., `ratifyScorecardFrom`) adds the iteration cost on top of the ratification logic. Games should target <64 tiers for comfortable gas headroom.
-- **_buildSplits iteration.** Iterates over user-provided splits array. No explicit cap, but total percent constraint limits practical count.
+- **Tier iteration in governance.** Quorum and attestation-weight calculations scale with tier count.
+- **Large split arrays.** User-provided split arrays can increase gas and complexity even if practical counts stay bounded.
 
 ## 6. Integration Risks
 
-- **Immutable phase timing.** Game rulesets are queued at launch and progress automatically based on duration. Once deployed, phase timing cannot be changed.
-- **Permanent cash-out weights.** Cash-out weights are set once via the governor. There is no mechanism to correct a ratified scorecard.
-- **No deployer upgrade.** The deployer contract has no upgrade mechanism. Bugs require deploying a new deployer.
-- **Clone initialization.** Clones use `cloneDeterministic` with `msg.sender` + nonce in the salt. Salt includes `msg.sender`, preventing cross-caller collision. `initialize()` has a re-initialization guard.
+- **Immutable phase timing.** Once deployed, the game timeline cannot be edited.
+- **Permanent cash-out weights.** A ratified scorecard is final.
+- **No deployer upgrade path.** Bugs require a new deployer, not an in-place fix.
+- **Clone initialization assumptions matter.** Per-game clone setup must stay correct.
 
 ## 7. Invariants to Verify
 
-- `_totalMintCost == tierPrice * liveTokenCount` after every mint and burn.
-- Total cash-outs + remaining surplus == pre-fulfillment pot minus fees.
-- Scorecard weights sum to exactly `TOTAL_CASHOUT_WEIGHT` (1e18).
-- Attestation units are conserved across all transfers (no units lost to `address(0)`).
-- `fulfilledCommitmentsOf[gameId]` is set at most once per game.
+- `_totalMintCost` stays consistent with live tier state and burns.
+- Total cash-outs plus remaining surplus match the pre-fulfillment pot minus intended fees.
+- Scorecard weights sum to `TOTAL_CASHOUT_WEIGHT`.
+- Attestation units are conserved across transfers and delegation.
+- `fulfilledCommitmentsOf[gameId]` is set at most once.
 - Per-tier supply never exceeds `initialSupply`.
-- Sum of all delegate attestation units equals total attestation supply.
 
 ## 8. Accepted Behaviors
 
 ### 8.1 Scorecard timeout is intentionally irreversible
 
-If `scorecardTimeout` elapses before ratification, the game permanently enters NO_CONTEST. Even a scorecard that has reached quorum cannot be ratified after timeout. This is accepted because: (1) allowing late ratification would keep player funds locked indefinitely while governance debates, (2) NO_CONTEST triggers a refund path (`triggerNoContestFor`) that returns funds pro-rata, and (3) the timeout creates a credible commitment to resolve the game within a bounded time. The timeout duration is set at deployment and cannot be changed.
-
-### 8.2 Permanent cash-out weights (no correction mechanism)
-
-Cash-out weights set via `ratifyScorecardFrom` cannot be updated or corrected. This is accepted because: (1) allowing weight changes would introduce governance attack surfaces where a quorum re-ratifies to steal from other tiers, (2) the attestation process provides a dispute window (grace period) before ratification finalizes, and (3) the alternative (upgradeable weights) would undermine the trust-minimized game design. If a scorecard is wrong, the game should be allowed to timeout into NO_CONTEST for refunds.
-
-### 8.3 fulfillCommitmentsOf reentrancy is guarded
-
-`fulfillCommitmentsOf` uses `fulfilledCommitmentsOf[gameId]` as a reentrancy guard (set before `sendPayoutsOf`). Returns early if already non-zero. Uses `max(feeAmount, 1)` to ensure the guard works even when pot rounds to 0. `sendPayoutsOf` is wrapped in try-catch: on failure, resets to sentinel (1) and emits `CommitmentPayoutFailed`, ensuring the final ruleset is always queued.
+If timeout elapses before ratification, the game can permanently move toward `NO_CONTEST`. This bounds how long funds can remain locked in unresolved governance.
 
-### 8.4 ratifyScorecardFrom reentrancy is double-guarded
+### 8.2 Permanent cash-out weights
 
-`ratifyScorecardFrom` executes arbitrary calldata on the hook via low-level call. The hook's `setTierCashOutWeightsTo` has an `onlyOwner` guard and a `cashOutWeightIsSet` check preventing double-set. Both guards prevent reentrancy exploitation.
+Once cash-out weights are installed through a valid ratification path, they cannot be corrected in place. The design prefers determinism over mutable post-hoc fixes.
 
-### 8.5 Attestation snapshot uses attestationsBegin - 1 (Codex R2 fix)
+### 8.3 `fulfillCommitmentsOf` and ratification are deliberately guarded
 
-`attestToScorecardFrom` snapshots attestation weight at `attestationsBegin - 1` instead of `attestationsBegin`. This prevents same-block transfer manipulation where a holder attests, transfers the NFT, and the recipient also attests in the same block. The trade-off is that NFTs minted in the same block as `attestationsBegin` have zero weight for that attestation call. This is acceptable because attestation typically happens well after minting, and the delay is negligible.
+Completion and ratification paths use one-way state to prevent replay or double-finalization.
 
-### 8.6 Pending reserves snapshotted at submission and included in denominators (Codex R2 fix)
+### 8.4 Pending reserves are intentionally included in governance and fee-accounting logic
 
-Two related protections:
+This is conservative, but it prevents users from front-running reserve dilution out of governance power or fee-token distribution.
 
-**Governance:** `submitScorecardFor` snapshots `numberOfPendingReservesFor()` per tier into `_pendingReservesSnapshotOf`. `getBWAAttestationWeight` reads from this snapshot instead of live state. This prevents reserve minting between submission and attestation from inflating a holder's voting power by removing pending-reserve dilution. The trade-off is that if reserves are minted after submission, the dilution persists even though the reserves are no longer pending. This is conservative but correct -- it locks governance power at submission time.
+### 8.5 One-tier games always resolve via no-contest
 
-**Cash-out (fee tokens):** `afterCashOutRecordedWith` includes `_pendingReserveMintCost()` (sum of `pendingReserves * tier.price` across all tiers) in the fee token claim denominator. This prevents paid holders from claiming a disproportionate share of $DEFIFA/$NANA tokens before reserves are minted. The trade-off is that if reserve NFTs are never minted (e.g., the reserve beneficiary is set to address(0) and minting reverts), those shares of fee tokens remain locked in the contract. This is acceptable because: (1) it prevents paid holders from front-running reserve minting to extract the reserves' share, and (2) reserve beneficiaries are set at deployment and should always be valid.
+A single-tier game cannot complete normal governance because the governance attestation model gives zero weight to holders of a tier that receives 100% of the scorecard, making quorum unreachable. This is expected: the game falls through to `NO_CONTEST` once `scorecardTimeout` elapses, and players recover their mint price via the permissionless `triggerNoContestFor()` refund path that queues a refund ruleset. This only works when `scorecardTimeout > 0`. A one-tier game launched with `scorecardTimeout = 0` disables the timeout path entirely, and funds become permanently locked with no exit. Game deployers must ensure `scorecardTimeout > 0` for single-tier configurations.

package/SKILLS.md

@@ -3,18 +3,20 @@
 ## Use This File For
 
 - Use this file when the task involves Defifa game deployment, phase transitions, scorecards, attestations, governance thresholds, fee accounting, or Defifa token URI behavior.
-- Start here, then open the deployer, hook, governor, resolver, or tests based on which phase or subsystem is relevant.
+- Start here, then decide whether the issue is launch shape, hook runtime, governor ratification, or resolver output.
 
 ## Read This Next
 
 | If you need... | Open this next |
 |---|---|
-| Repo overview and lifecycle framing | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
-| Deployment and phase scheduling | [`src/DefifaDeployer.sol`](./src/DefifaDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
-| Cash-out and game-phase behavior | [`src/DefifaHook.sol`](./src/DefifaHook.sol), [`src/libraries/`](./src/libraries/) |
-| Governance and scorecards | [`src/DefifaGovernor.sol`](./src/DefifaGovernor.sol) |
-| Project-owner or token URI behavior | [`src/DefifaProjectOwner.sol`](./src/DefifaProjectOwner.sol), [`src/DefifaTokenUriResolver.sol`](./src/DefifaTokenUriResolver.sol) |
-| Security, lifecycle, and regressions | [`test/DefifaGovernor.t.sol`](./test/DefifaGovernor.t.sol), [`test/DefifaNoContest.t.sol`](./test/DefifaNoContest.t.sol), [`test/DefifaFeeAccounting.t.sol`](./test/DefifaFeeAccounting.t.sol), [`test/regression/`](./test/regression/) |
+| Lifecycle framing and repo boundaries | [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Launch shape, phase queueing, and commitment fulfillment | [`src/DefifaDeployer.sol`](./src/DefifaDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
+| Minting, delegation, game-state gating, and cash-out behavior | [`src/DefifaHook.sol`](./src/DefifaHook.sol), [`src/libraries/DefifaHookLib.sol`](./src/libraries/DefifaHookLib.sol) |
+| Scorecard submission, attestation power, quorum, and ratification | [`src/DefifaGovernor.sol`](./src/DefifaGovernor.sol) |
+| Token URI rendering and fee-project ownership helper | [`src/DefifaTokenUriResolver.sol`](./src/DefifaTokenUriResolver.sol), [`src/DefifaProjectOwner.sol`](./src/DefifaProjectOwner.sol) |
+| Runtime and operational invariants | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
+| Governance and lifecycle proofs | [`test/DefifaGovernor.t.sol`](./test/DefifaGovernor.t.sol), [`test/DefifaGovernanceHardening.t.sol`](./test/DefifaGovernanceHardening.t.sol), [`test/DefifaNoContest.t.sol`](./test/DefifaNoContest.t.sol) |
+| Fee and adversarial accounting coverage | [`test/DefifaFeeAccounting.t.sol`](./test/DefifaFeeAccounting.t.sol), [`test/DefifaMintCostInvariant.t.sol`](./test/DefifaMintCostInvariant.t.sol), [`test/DefifaSecurity.t.sol`](./test/DefifaSecurity.t.sol), [`test/DefifaAdversarialQuorum.t.sol`](./test/DefifaAdversarialQuorum.t.sol) |
 
 ## Repo Map
 
@@ -27,16 +29,18 @@
 
 ## Purpose
 
-Defifa is an on-chain prediction game system built on Juicebox. This repo packages game launch, phased lifecycle control, scorecard governance, and NFT-based settlement into a single game-specific deployment surface.
+Defifa is an onchain prediction game system built on Juicebox. This repo packages game launch, phased lifecycle control, scorecard governance, and NFT-based settlement into one game-specific deployment surface.
 
 ## Reference Files
 
-- Open [`references/runtime.md`](./references/runtime.md) when you need the game lifecycle, contract roles, settlement path, or the main economic and governance invariants.
-- Open [`references/operations.md`](./references/operations.md) when you need deployment and phase-queueing behavior, test breadcrumbs, or the common sources of stale operational assumptions.
+- Open [`references/runtime.md`](./references/runtime.md) for the game lifecycle, contract roles, settlement path, and the main economic and governance invariants.
+- Open [`references/operations.md`](./references/operations.md) for deployment and phase-queueing behavior, test breadcrumbs, and common stale operational assumptions.
 
 ## Working Rules
 
-- Start in [`src/DefifaDeployer.sol`](./src/DefifaDeployer.sol) for lifecycle and queueing behavior, but verify hook and governor assumptions before treating a game-state issue as deployer-only.
-- Treat scorecard ratification, no-contest behavior, and fee accounting as treasury-sensitive. Small changes there can alter settlement outcomes materially.
-- When a task mentions NFT rendering or metadata, confirm whether it belongs in [`src/DefifaTokenUriResolver.sol`](./src/DefifaTokenUriResolver.sol) instead of the hook or deployer.
-- If you edit phase transitions, check both lifecycle tests and fee/governance tests. Defifa behavior is cross-coupled.
+- Start in [`src/DefifaDeployer.sol`](./src/DefifaDeployer.sol) for phase shape and commitment fulfillment, [`src/DefifaHook.sol`](./src/DefifaHook.sol) for NFT runtime and settlement behavior, and [`src/DefifaGovernor.sol`](./src/DefifaGovernor.sol) for scorecards, attestation, and ratification.
+- Treat phase transitions, scorecard ratification, no-contest behavior, and fee accounting as one economic system.
+- Defifa-specific cash-out weights and governance thresholds sit on top of `nana-721-hook-v6` and `nana-core-v6`.
+- When a task mentions NFT rendering or metadata, confirm whether it belongs in [`src/DefifaTokenUriResolver.sol`](./src/DefifaTokenUriResolver.sol).
+- If you edit phase transitions, check lifecycle, governance, and fee-accounting tests together.
+- If ratification, attestation, or quorum behavior changes, re-read the audit and regression tests before trusting a clean happy-path result.

package/USER_JOURNEYS.md

@@ -1,69 +1,169 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
 
-- teams launching Defifa prediction games
-- players minting outcome pieces and later redeeming winning positions
-- participants submitting, attesting to, and ratifying scorecards
-- operators handling refund, no-contest, and fee-settlement edges
+This repo turns a Juicebox project into a prediction-game lifecycle with fixed phase timing, tiered outcome pieces, attestation-based scorecard governance, and final cash-out weights that decide how the pot settles. It owns Defifa's game-specific launch, scoring, no-contest, and settlement logic.
+
+## Primary Actors
+
+- game creators launching a new Defifa market with fixed timing, tiers, and fee routing
+- players minting outcome pieces during MINT and later redeeming or refunding them
+- attestors and delegates submitting, supporting, revoking, and ratifying scorecards during SCORING
+- auditors tracing where game fairness depends on shared 721-store behavior, governor state, and core terminal flows
+- operators handling no-contest recovery or optional fee-project ownership locking
+
+## Key Surfaces
+
+- `DefifaDeployer.launchGameWith(...)`: launches a Defifa game as a JB project and wires hook, governor, splits, and lifecycle timing
+- `DefifaHook.afterPayRecordedWith(...)`: mints outcome NFTs when players pay during the mintable phase
+- `DefifaHook.beforeCashOutRecordedWith(...)` and `afterCashOutRecordedWith(...)`: define refund, winning-piece redemption, and fee-token claim behavior
+- `DefifaGovernor.submitScorecardFor(...)`, `attestToScorecardFrom(...)`, `revokeAttestationFrom(...)`, `ratifyScorecardFrom(...)`: scorecard governance lifecycle
+- `DefifaDeployer.fulfillCommitmentsOf(...)` and `triggerNoContestFor(...)`: finalize commitments after ratification or unlock refund-oriented no-contest recovery
 
 ## Journey 1: Launch A Defifa Game
 
-**Starting state:** the team knows the countdown, mint window, scoring mechanics, and payout assumptions for a new game.
+**Actor:** game creator.
+
+**Intent:** launch a prediction game with fixed timing, tiers, fee routing, and governance rules.
+
+**Preconditions**
+
+- the creator knows the game start time, mint duration, optional refund duration, and scoring-timeout assumptions
+- tier count, tier names, tier price, and split commitments are finalized
+- the chosen terminal and payment token are correct because the launch path is intentionally one-way
+
+**Main Flow**
+
+1. Prepare launch data with timing, tiers, splits, fee-project settings, terminal, and governance params.
+2. Call `DefifaDeployer.launchGameWith(...)`.
+3. The deployer launches the JB project, clones and initializes `DefifaHook`, initializes the governor state, and stores the game's immutable ops data.
+4. The game now advances through its documented phase sequence.
+
+**Failure Modes**
+
+- launch parameters are wrong, but the creator assumes they can patch them later
+- fee routing, token decimals, or terminal assumptions drift from the terminal actually configured
+- the creator mistakes permissionless launch for ongoing admin power
+
+**Postconditions**
+
+- the game exists as a staged JB project with Defifa-specific lifecycle wiring
+
+## Journey 2: Mint Outcome Pieces During Open Play
+
+**Actor:** player.
+
+**Intent:** buy one or more outcome pieces during the mint phase.
+
+**Preconditions**
+
+- the game is in the mintable phase
+- the selected tier exists and is still mintable
+
+**Main Flow**
+
+1. Pay the game project during the mint window.
+2. `DefifaHook` mints the selected outcome NFT tier.
+3. Delegation and mint-cost accounting are updated.
+4. Reserved mints and pending reserves continue to matter for later governance and settlement.
+
+**Failure Modes**
+
+- mint is attempted in the wrong phase
+- assumptions about attestation power ignore pending reserves or tier weighting
+
+**Postconditions**
+
+- the player holds game pieces that later affect governance and settlement
+
+## Journey 3: Submit And Ratify A Scorecard
+
+**Actor:** proposer, attestor, or delegate.
+
+**Intent:** turn the game's result into a ratified scorecard.
+
+**Preconditions**
+
+- the game is in SCORING
+- the actor understands quorum, grace-period, and timeout rules
+
+**Main Flow**
+
+1. Submit a scorecard candidate.
+2. Attest or revoke while the scorecard is active.
+3. Wait for quorum and the grace period.
+4. Ratify one winning scorecard.
+
+**Failure Modes**
+
+- attestation power is concentrated enough to capture the result
+- timeout is reached before ratification
+- integrations misread live attestation power or pending-reserve dilution
+
+**Postconditions**
+
+- exactly one scorecard can become the game's final outcome, or the game moves toward no-contest handling
+
+## Journey 4: Fulfill Commitments And Settle The Game
+
+**Actor:** completion path caller.
+
+**Intent:** turn the ratified scorecard into final redeemable economics.
+
+**Preconditions**
+
+- a scorecard has been ratified
+- the fulfillment path has not already run
+
+**Main Flow**
 
-**Success:** the game launches as a staged Juicebox project with hook, governor, and metadata surfaces all aligned.
+1. Read the ratified outcome.
+2. Call `fulfillCommitmentsOf(...)`.
+3. Queue the completion ruleset and finalize the promised commitment flow.
+4. Let winning-piece holders redeem under the installed cash-out weights.
 
-**Flow**
-1. Use `DefifaDeployer` with launch config, tier params, governance settings, and fee commitments.
-2. The deployer launches the project, clones or wires the game hook, and initializes governance through `DefifaGovernor`.
-3. The game now has a defined lifecycle instead of being a plain NFT sale.
+**Failure Modes**
 
-## Journey 2: Participate As A Player During The Mint Phase
+- ratification succeeds but fulfillment is never run
+- commitment logic or fee accounting drifts from the documented outcome
 
-**Starting state:** the game is in its countdown or live mint window and players want to buy outcome pieces.
+**Postconditions**
 
-**Success:** the player mints the intended game pieces and their payment becomes part of the prize pot.
+- the game enters its final redeemable state
 
-**Flow**
-1. Wait until the lifecycle enters the mintable phase.
-2. Pay into the game to mint the chosen outcome NFTs through `DefifaHook`.
-3. The treasury accumulates the prize pot and the player's position is now represented by the minted pieces.
+## Journey 5: Enter No-Contest And Unlock Refund Recovery
 
-## Journey 3: Handle Refund Or No-Contest Outcomes
+**Actor:** any caller when the no-contest conditions are met.
 
-**Starting state:** the game cannot settle normally, either because the refund window is triggered or because governance fails to reach a contestable result.
+**Intent:** move a game out of failed scoring and into the documented refund-oriented fallback path.
 
-**Success:** participants can exit under the repo's explicit failure-mode rules instead of ad hoc admin intervention.
+**Preconditions**
 
-**Flow**
-1. Observe the current game phase and whether it has entered refund or no-contest handling.
-2. Use the game-defined exit path for participants rather than assuming the winning-scorecard path will eventually resolve.
-3. Keep treasury and piece-state assumptions aligned with the phase actually reached.
+- the game has hit its no-contest conditions
+- the caller understands that `NO_CONTEST` and active refund rules are related but not identical states
 
-## Journey 4: Submit, Attest To, And Ratify A Scorecard
+**Main Flow**
 
-**Starting state:** minting is over and the game is in its scoring phase.
+1. Call `triggerNoContestFor(...)` when the timeout or participation conditions make the game ineligible for normal settlement.
+2. Queue the no-contest recovery ruleset.
+3. Let players exit under the fallback path once the queued ruleset becomes active.
 
-**Success:** a valid scorecard reaches quorum, survives any grace period, and becomes the game's settled result.
+**Failure Modes**
 
-**Flow**
-1. A participant submits a scorecard through `DefifaGovernor`.
-2. Holders attest, delegate where permitted, and push the preferred scorecard toward quorum.
-3. After the grace period, the governor ratifies the winning scorecard if it still satisfies the game's rules.
-4. `DefifaHook` updates the relevant cash-out weights for settlement.
+- integrators assume same-transaction full refunds immediately after the trigger
+- the game becomes stuck because nobody triggers the no-contest path
 
-## Journey 5: Redeem Winning Pieces And Settle The Pot
+**Postconditions**
 
-**Starting state:** the game has a ratified result and winning positions are now known.
+- the game moves onto the documented no-contest recovery track
 
-**Success:** holders of winning pieces burn or cash out them for their share of the prize pot.
+## Trust Boundaries
 
-**Flow**
-1. Holders use the game's redemption path after settlement.
-2. The hook applies the now-final weights associated with the winning scorecard.
-3. Winners receive their proportional share while losers no longer have equivalent claim on the pot.
+- this repo is trusted for game-specific phase logic, governance, and settlement weighting
+- terminal accounting still comes from `nana-core-v6`
+- shared tier-storage behavior still comes from `nana-721-hook-v6`
 
 ## Hand-Offs
 
-- Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) for the standard tiered NFT mechanics underneath the game-specific logic.
-- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for base project accounting once the question is no longer Defifa-specific lifecycle or governance behavior.
+- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for underlying treasury and terminal behavior.
+- Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) for shared tier-store and reserve semantics that Defifa builds on.

package/foundry.toml

@@ -17,6 +17,8 @@ runs = 1024
 depth = 100
 fail_on_revert = false
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"