@ballkidz/defifa 0.0.40 → 0.0.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "license": "MIT",
   "engines": {
     "node": "25.9.0"
@@ -13,22 +13,13 @@
     "url": "git+https://github.com/BallKidz/defifa.git"
   },
   "files": [
-    "src",
-    "script",
-    "lib/base64/base64.sol",
-    "lib/typeface/contracts/interfaces/ITypeface.sol",
-    "README.md",
-    "ARCHITECTURE.md",
-    "ADMINISTRATION.md",
-    "AUDIT_INSTRUCTIONS.md",
-    "CHANGELOG.md",
-    "CRYPTO_ECON.md",
-    "RISKS.md",
-    "SKILLS.md",
-    "STYLE_GUIDE.md",
-    "USER_JOURNEYS.md",
     "foundry.toml",
-    "remappings.txt"
+    "references/",
+    "remappings.txt",
+    "script/",
+    "src/",
+    "lib/base64/base64.sol",
+    "lib/typeface/contracts/interfaces/ITypeface.sol"
   ],
   "dependencies": {
     "@bananapus/721-hook-v6": "^0.0.54",

package/references/operations.md

@@ -0,0 +1,32 @@
+# Defifa Operations
+
+Use this file when the task is about launch config, phase timing, governance windows, or deciding whether a symptom is operational drift or runtime logic.
+
+## Deployment Surface
+
+- [`src/DefifaDeployer.sol`](../src/DefifaDeployer.sol) is the first stop for launch-time config, phase queueing, and post-ratification fulfillment.
+- [`script/Deploy.s.sol`](../script/Deploy.s.sol) and [`script/helpers/DefifaDeploymentLib.sol`](../script/helpers/DefifaDeploymentLib.sol) are the deployment entrypoints when the task is about current wiring rather than game mechanics.
+- [`src/structs/`](../src/structs/) and [`src/enums/`](../src/enums/) define launch data, phase types, and other inputs that often drift from remembered assumptions.
+
+## Change Checklist
+
+- If you edit lifecycle timing, verify phase transitions, no-contest triggers, and the governor's attestation windows together.
+- If you edit hook settlement logic, re-check fee accounting and mint-cost invariants.
+- If you touch governance thresholds or attestation behavior, inspect the governor tests before assuming the change is local.
+- If you touch token metadata or rendering, verify whether the bug belongs in the resolver instead of settlement code.
+- If you touch anything supply-sensitive, inspect the review tests around pending reserves and quorum before relying on current intuition.
+
+## Common Failure Modes
+
+- Game-state issue is blamed on the hook even though the deployer queued the wrong phase or timing.
+- Governance behavior looks wrong, but the real issue is stale launch configuration.
+- Settlement changes accidentally affect fee distribution or redemption accounting.
+- Resolver issues get misdiagnosed as hook or governor problems because they surface through NFTs.
+- Review-style failures around reserve dilution or attestation counting are treated as isolated math issues even though they cross deployer, hook, and governor boundaries.
+
+## Useful Proof Points
+
+- [`test/Fork.t.sol`](../test/Fork.t.sol) for live-integration assumptions.
+- [`test/TestRegressionGaps.sol`](../test/TestRegressionGaps.sol) and [`test/TestQALastMile.t.sol`](../test/TestQALastMile.t.sol) for pinned edge cases.
+- [`test/BWAFunctionComparison.t.sol`](../test/BWAFunctionComparison.t.sol) and [`test/DefifaUSDC.t.sol`](../test/DefifaUSDC.t.sol) when currency or accounting context matters.
+- [`test/regression/`](../test/regression/) when a change touches pending reserves, registry alignment, quorum griefing, or double-counting.

package/references/runtime.md

@@ -0,0 +1,43 @@
+# Defifa Runtime
+
+Use this file when `defifa/SKILLS.md` has already routed you here and you need to reason about the game as a state machine rather than as isolated contracts.
+
+## Contract Roles
+
+- [`src/DefifaDeployer.sol`](../src/DefifaDeployer.sol) launches games, manages phase progression, fulfills commitments, and triggers safety exits such as no-contest.
+- [`src/DefifaHook.sol`](../src/DefifaHook.sol) manages the NFT game pieces, delegation, and settlement-side cash-out behavior.
+- [`src/DefifaGovernor.sol`](../src/DefifaGovernor.sol) handles scorecard submission, attestation, quorum, and ratification.
+- [`src/DefifaTokenUriResolver.sol`](../src/DefifaTokenUriResolver.sol) renders game-card metadata.
+- [`src/DefifaProjectOwner.sol`](../src/DefifaProjectOwner.sol) is the ownership helper for the fee project.
+
+## Lifecycle
+
+1. Countdown before minting opens.
+2. Mint phase where players buy outcome NFTs and can delegate attestation power.
+3. Optional refund phase if the launch configuration allows it.
+4. Scoring phase where scorecards are submitted, attested, and ratified.
+5. Complete or no-contest settlement depending on governance outcome and safety checks.
+
+## High-Risk Areas
+
+- Scorecard ratification and quorum assumptions: changes here directly affect who can settle the pot.
+- No-contest and refund behavior: these paths are economic safety valves, not edge-case garnish.
+- Fee accounting and commitment fulfillment: payout ordering and accounting drift can change final redemption value.
+- Hook/governor/deployer coupling: many bugs come from changing one layer while assuming the others are passive.
+- Pending reserved supply and snapshot assumptions: settlement and quorum logic can drift if supply-sensitive views are taken at the wrong time.
+- Scorecards that miss quorum do not naturally “finish.” New scorecards can still be submitted until no-contest logic takes over, so do not assume a clean defeated terminal state.
+
+## Common Misdiagnoses
+
+- A settlement bug is blamed on [`src/DefifaHook.sol`](../src/DefifaHook.sol) even though the wrong phase or grace-period state was created in [`src/DefifaDeployer.sol`](../src/DefifaDeployer.sol) or [`src/DefifaGovernor.sol`](../src/DefifaGovernor.sol).
+- A governance bug is blamed on the governor even though attestation power or delegation semantics were wrong in the hook layer.
+- An NFT-facing bug is blamed on settlement code even though the problem is resolver output in [`src/DefifaTokenUriResolver.sol`](../src/DefifaTokenUriResolver.sol).
+- A Defifa-specific payout result is patched in this repo when the real bug is shared 721 or core protocol behavior upstream.
+
+## Tests To Trust First
+
+- [`test/DefifaGovernor.t.sol`](../test/DefifaGovernor.t.sol) for governance flow.
+- [`test/DefifaNoContest.t.sol`](../test/DefifaNoContest.t.sol) for safety exits.
+- [`test/DefifaFeeAccounting.t.sol`](../test/DefifaFeeAccounting.t.sol) and [`test/DefifaMintCostInvariant.t.sol`](../test/DefifaMintCostInvariant.t.sol) for economic correctness.
+- [`test/DefifaHookRegressions.t.sol`](../test/DefifaHookRegressions.t.sol), [`test/regression/GracePeriodBypass.t.sol`](../test/regression/GracePeriodBypass.t.sol), [`test/regression/FulfillmentBlocksRatification.t.sol`](../test/regression/FulfillmentBlocksRatification.t.sol), and [`test/regression/AttestationDelegateBeneficiary.t.sol`](../test/regression/AttestationDelegateBeneficiary.t.sol) for pinned regressions.
+- [`test/DefifaSecurity.t.sol`](../test/DefifaSecurity.t.sol), [`test/DefifaGovernanceHardening.t.sol`](../test/DefifaGovernanceHardening.t.sol), [`test/DefifaAdversarialQuorum.t.sol`](../test/DefifaAdversarialQuorum.t.sol), and [`test/regression/`](../test/regression/) for adversarial and regression-derived cases.

package/script/Deploy.s.sol

@@ -119,7 +119,8 @@ contract DeployMainnet is Script, Sphinx {
             registry: registry.registry,
             defifaProjectId: _defifaProjectId,
             baseProtocolProjectId: _baseProtocolProjectId,
-            hookStore: hookStore
+            hookStore: hookStore,
+            initialOwner: safeAddress()
         });
 
         governor.transferOwnership(address(deployer));

package/src/DefifaDeployer.sol

@@ -21,6 +21,7 @@ import {JBFundAccessLimitGroup} from "@bananapus/core-v6/src/structs/JBFundAcces
 import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadata.sol";
 import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 import {JBSplitGroup} from "@bananapus/core-v6/src/structs/JBSplitGroup.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
@@ -46,7 +47,7 @@ import {DefifaTierParams} from "./structs/DefifaTierParams.sol";
 /// the event concludes, a scorecard assigns cash-out weights to each tier. The treasury is distributed proportionally
 /// to winning NFT holders. Games progress through phases: COUNTDOWN → MINT → REFUND → SCORING → COMPLETE (or
 /// NO_CONTEST if minimum participation isn't met or scorecard ratification times out).
-contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGamePotReporter, IERC721Receiver {
+contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGamePotReporter, IERC721Receiver, Ownable {
     using Strings for uint256;
     using SafeERC20 for IERC20;
 
@@ -61,6 +62,8 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     error DefifaDeployer_InvalidCurrency(address token, uint256 currency);
     error DefifaDeployer_NotNoContest(uint256 gameId, DefifaGamePhase phase);
     error DefifaDeployer_NoContestAlreadyTriggered(uint256 gameId);
+    error DefifaDeployer_ReferralChainIdTooLarge(uint256 referralChainId);
+    error DefifaDeployer_ReferralProjectIdTooLarge(uint256 referralProjectId);
     error DefifaDeployer_SplitsDontAddUp(uint256 totalPercent, uint256 maxPercent);
 
     //*********************************************************************//
@@ -133,6 +136,12 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @dev Once triggered, the game stays in NO_CONTEST and refunds are enabled.
     mapping(uint256 => bool) public noContestTriggeredFor;
 
+    /// @notice The packed `(referralChainId << 48) | referralProjectId` reference credited as the referrer on
+    /// every fee-payout `sendPayoutsOf` call this deployer makes during `fulfillCommitmentsOf`. Defaults to
+    /// `(1, DEFIFA_PROJECT_ID)` so fee-volume credit accrues to the Defifa project on Ethereum mainnet
+    /// regardless of which chain the game runs on. Settable by the owner via `setReferralProjectId`.
+    uint256 public override referralProjectId;
+
     //*********************************************************************//
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
@@ -281,6 +290,9 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @param defifaProjectId The ID of the project that should take the fee from the games.
     /// @param baseProtocolProjectId The ID of the protocol project that'll receive fees from fulfilling commitments.
     /// @param hookStore The store used by Defifa hooks.
+    /// @param initialOwner The address granted authority to call `setReferralProjectId`. The contract is otherwise
+    /// stateless from an admin perspective — the owner only controls the referrer reference used when crediting
+    /// fee-volume on `fulfillCommitmentsOf` payouts.
     constructor(
         address hookCodeOrigin,
         IJB721TokenUriResolver tokenUriResolver,
@@ -289,8 +301,11 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         IJBAddressRegistry registry,
         uint256 defifaProjectId,
         uint256 baseProtocolProjectId,
-        IJB721TiersHookStore hookStore
-    ) {
+        IJB721TiersHookStore hookStore,
+        address initialOwner
+    )
+        Ownable(initialOwner)
+    {
         HOOK_CODE_ORIGIN = hookCodeOrigin;
         TOKEN_URI_RESOLVER = tokenUriResolver;
         GOVERNOR = governor;
@@ -301,6 +316,10 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         HOOK_STORE = hookStore;
         /// @dev Uses the deployer address as group ID. Game scoring rulesets use uint160(token) as group ID.
         SPLIT_GROUP = uint256(uint160(address(this)));
+
+        // Default referrer reference: Defifa project on Ethereum mainnet. Encoded `(chainId << 48) | projectId`
+        // per `JBMultiTerminal.currentReferralProjectId`. Owner can retarget via `setReferralProjectId`.
+        referralProjectId = (uint256(1) << 48) | defifaProjectId;
     }
 
     //*********************************************************************//
@@ -346,24 +365,18 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
 
         // Send only the fee portion as payouts. The remaining balance stays as surplus for cash-outs.
         // Use the ruleset's baseCurrency — this matches the currency under which payout limits were stored
-        // at launch time, regardless of whether the token is native ETH or an ERC-20.
-        // Wrapped in try-catch so the final ruleset is always queued even if payout fails.
-        // Credit `DEFIFA_PROJECT_ID` as the referrer so the protocol fee volume from every game's commitment
-        // payout attributes back to the Defifa project itself — Defifa is the project that facilitated the
-        // fee-paying activity, regardless of which `gameId` triggered it.
-        //
-        // The referrer reference is encoded as `(referralChainId << 48) | referralProjectId` per `JBMultiTerminal`'s
-        // `currentReferralProjectId` packing. Defifa lives on Ethereum mainnet, so we hard-code `referralChainId = 1`
-        // here: this ensures the protocol fee volume credit accrues to Defifa on mainnet regardless of which chain
-        // the game runs on. (Auto-resolving to `block.chainid` would scatter credit across L2s where Defifa has no
-        // canonical project ID, so we pin mainnet explicitly.)
+        // at launch time, regardless of whether the token is native ETH or an ERC-20. Wrapped in try-catch so
+        // the final ruleset is always queued even if payout fails. The configured `referralProjectId` (default
+        // `(1, DEFIFA_PROJECT_ID)`, owner-settable via `setReferralProjectId`) credits Defifa with the protocol
+        // fee volume from every game's commitment payout. Pinning mainnet by default avoids scattering credit
+        // across L2s where Defifa has no canonical project ID.
         try terminal.sendPayoutsOf({
             projectId: gameId,
             token: token,
             amount: feeAmount,
             currency: metadata.baseCurrency,
             minTokensPaidOut: 0,
-            referralProjectId: (uint256(1) << 48) | DEFIFA_PROJECT_ID
+            referralProjectId: referralProjectId
         }) {}
         catch (bytes memory reason) {
             // Payout failed — fee stays in pot. Reset to 0 so currentGamePotOf
@@ -653,6 +666,36 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         return IERC721Receiver.onERC721Received.selector;
     }
 
+    /// @notice Update the referrer reference credited on every fee-payout `sendPayoutsOf` call this deployer
+    /// makes during `fulfillCommitmentsOf`.
+    /// @dev Stores the packed `(newReferralChainId << 48) | newReferralProjectId` value used by
+    /// `JBMultiTerminal.currentReferralProjectId`. Either field may be zero — passing `(0, 0)` disables the
+    /// referral credit entirely. Bounded so the pack is lossless: `newReferralProjectId` must fit in `uint48`,
+    /// `newReferralChainId` must fit in `uint208` (so the left-shift by 48 doesn't drop high bits).
+    /// @param newReferralProjectId The referring project's bare ID on `newReferralChainId`.
+    /// @param newReferralChainId The EIP-155 chain ID of the referrer's home chain.
+    function setReferralProjectId(
+        uint256 newReferralProjectId,
+        uint256 newReferralChainId
+    )
+        external
+        override
+        onlyOwner
+    {
+        // Bound the inputs to the on-chain encoding so the pack is lossless. The same shape JBMultiTerminal uses:
+        // projectId in bits [47:0], chainId in bits [255:48].
+        if (newReferralProjectId > type(uint48).max) {
+            revert DefifaDeployer_ReferralProjectIdTooLarge(newReferralProjectId);
+        }
+        if (newReferralChainId >> 208 != 0) revert DefifaDeployer_ReferralChainIdTooLarge(newReferralChainId);
+
+        referralProjectId = (newReferralChainId << 48) | newReferralProjectId;
+
+        emit SetReferralProjectId({
+            referralChainId: newReferralChainId, referralProjectId: newReferralProjectId, caller: msg.sender
+        });
+    }
+
     /// @notice Triggers the no-contest refund mechanism for a game.
     /// @dev Anyone can call this once the game is in the NO_CONTEST phase. This queues a new ruleset without
     /// payout limits, making the surplus equal to the balance so users can cash out at their mint price.

package/src/interfaces/IDefifaDeployer.sol

@@ -45,6 +45,12 @@ interface IDefifaDeployer {
     /// @param caller The address that queued the phase transition.
     event QueuedNoContest(uint256 indexed gameId, address caller);
 
+    /// @notice Emitted when the referrer reference for fee-volume credit is updated.
+    /// @param referralChainId The EIP-155 chain ID of the new referrer's home chain.
+    /// @param referralProjectId The new referring project's bare project ID on `referralChainId`.
+    /// @param caller The address that set the new referrer.
+    event SetReferralProjectId(uint256 indexed referralChainId, uint256 indexed referralProjectId, address caller);
+
     /// @notice The fee divisor for base protocol fees (100 / fee percent).
     /// @return The fee divisor.
     function BASE_PROTOCOL_FEE_DIVISOR() external view returns (uint256);
@@ -81,6 +87,12 @@ interface IDefifaDeployer {
     /// @return The address registry contract.
     function REGISTRY() external view returns (IJBAddressRegistry);
 
+    /// @notice The packed `(referralChainId << 48) | referralProjectId` reference credited as the referrer on
+    /// every fee-payout `sendPayoutsOf` call this deployer makes. Defaults to `(1, DEFIFA_PROJECT_ID)` so
+    /// credit accrues to Defifa on Ethereum mainnet; owner-settable via `setReferralProjectId`.
+    /// @return The packed referrer reference.
+    function referralProjectId() external view returns (uint256);
+
     /// @notice The split group ID used for distributing game pot funds.
     /// @return The split group.
     function SPLIT_GROUP() external view returns (uint256);
@@ -119,6 +131,16 @@ interface IDefifaDeployer {
     /// @return gameId The ID of the newly launched game.
     function launchGameWith(DefifaLaunchProjectData calldata launchProjectData) external returns (uint256 gameId);
 
+    /// @notice Update the referrer reference credited on every fee-payout `sendPayoutsOf` call this deployer
+    /// makes during `fulfillCommitmentsOf`.
+    /// @dev Stores the packed `(newReferralChainId << 48) | newReferralProjectId` value used by
+    /// `JBMultiTerminal.currentReferralProjectId`. Either field may be zero (passing `(0, 0)` disables the
+    /// referral credit). Bounded so the pack is lossless: `newReferralProjectId <= type(uint48).max`,
+    /// `newReferralChainId <= type(uint208).max`.
+    /// @param newReferralProjectId The referring project's bare ID on `newReferralChainId`.
+    /// @param newReferralChainId The EIP-155 chain ID of the referrer's home chain.
+    function setReferralProjectId(uint256 newReferralProjectId, uint256 newReferralChainId) external;
+
     /// @notice Trigger a no-contest outcome for a game.
     /// @param gameId The ID of the game.
     function triggerNoContestFor(uint256 gameId) external;

package/ADMINISTRATION.md

@@ -1,79 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| 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 |
-
-## Purpose
-
-`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.
-
-## Control Model
-
-- `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 | 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 |
-
-## Privileged Surfaces
-
-- `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
-
-## Immutable And One-Way
-
-- 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.
-
-## Operational Notes
-
-- 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.
-
-## Machine Notes
-
-- 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.
-
-## Recovery
-
-- 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.
-
-## Admin Boundaries
-
-- 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

@@ -1,131 +0,0 @@
-# Architecture
-
-## Purpose
-
-`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.
-
-## System Overview
-
-`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.
-
-## Core Invariants
-
-- 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.
-
-## 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
-  -> 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
-```
-
-### 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:
-
-- 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
-
-The hook's completion math is intentionally phase-sensitive:
-
-- 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
-
-## Security Model
-
-- 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
-
-- 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/regression/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/regression/PendingReserveSnapshotBypass.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,100 +0,0 @@
-# Audit Instructions
-
-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.
-
-## Audit Objective
-
-There is a billion dollars of well-meaning projects' money in the Juicebox Money Engine, growing exponentially. Your job is to hack it before anyone else. Whoever hacks it first saves/steals the money, and you are obsessed with being this winner, while also being a steward of the protocol and wanting it to keep growing safely.
-
-Suggestions of where to look:
-
-- let players extract more than their fair share of the game pot
-- 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
-- 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`
-- enums, interfaces, structs, and deployment helpers
-
-## Start Here
-
-1. `src/DefifaGovernor.sol`
-2. `src/DefifaHook.sol`
-3. `src/DefifaDeployer.sol`
-4. `src/DefifaProjectOwner.sol`
-
-## Security Model
-
-High-level lifecycle:
-
-- deploy a game as a Juicebox project
-- sell outcome NFTs during the mint phase
-- optionally allow refunds or no-contest handling
-- run scorecard governance through submissions and attestations
-- ratify one scorecard
-- update cash-out weights so winning pieces can redeem the treasury
-
-The contracts split responsibility as follows:
-
-- `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
-
-## Roles And Privileges
-
-| 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 |
-
-## Integration Assumptions
-
-| 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 |
-
-## Critical Invariants
-
-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.
-
-## Attack Surfaces
-
-- `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
-
-## 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
-
-- `npm install`
-- `forge fmt --check`
-- `forge build --deny notes`
-- `forge build --deny notes --sizes --skip "*/test/**" --skip "*/script/**"`
-- `forge build --deny notes --build-info --skip "*/test/**" --skip "*/script/**"`
-- `forge test --deny notes`
-- `npm pack --dry-run --json`