@ballkidz/defifa 0.0.31 → 0.0.34

package/AUDIT_INSTRUCTIONS.md

@@ -4,7 +4,9 @@ Defifa is a staged prediction-game system built on Juicebox and the tiered 721 s
 
 ## Audit Objective
 
-Find issues that:
+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

package/CHANGELOG.md

@@ -23,6 +23,8 @@ This file instead describes the current v6 repo at a high level and the broad mi
 ## Local review remediations
 
 - Reserve-minted NFTs are now excluded from refund calculations during MINT, REFUND, and NO_CONTEST phases. A public `isReserveMint` mapping tracks which tokens were created via tier reserve frequency rather than paid for. `beforeCashOutRecordedWith` subtracts their tier price from `cumulativeMintPrice`, preventing reserve beneficiaries from withdrawing funds they never contributed.
+- One-tier games now revert at launch with `DefifaDeployer_InvalidGameConfiguration` if `scorecardTimeout == 0`. A one-tier game cannot reach quorum (the BWA multiplier reduces the sole tier's power to zero), so a zero timeout would leave funds permanently locked with no exit path. Enforcement moves this from a launcher-side responsibility (previously documented in `RISKS.md §8.6`) to a contract-level guarantee.
+- `DefifaHook.mintReservesFor` now reverts with `DefifaHook_ReservedTokenMintingBlockedInNoContest` while the game is in `NO_CONTEST`. Reserve mints inflate `totalMintCost` so reserved recipients can claim fee tokens; without the block, a game that failed `minParticipation` could be revived back to SCORING via free notional face value before `triggerNoContestFor` latches the failure.
 
 ## Migration notes
 

package/CRYPTO_ECON.md

@@ -777,11 +777,11 @@ Defifa includes a comprehensive safety system — the **NO_CONTEST** mechanism
 
 #### 9.1.1 Trigger 1: Minimum Participation Threshold
 
-**Mechanism.** At game creation, the organizer sets `minParticipation` — a minimum token supply required for the game to proceed to scoring. The `currentGamePhaseOf()` function checks the total token supply (via `CONTROLLER.TOKENS().totalSupplyOf(gameId)`) against this threshold before returning SCORING. If the supply is below the threshold, it returns NO_CONTEST.
+**Mechanism.** At game creation, the organizer sets `minParticipation` — a minimum cumulative NFT mint cost required for the game to proceed to scoring. The `currentGamePhaseOf()` function checks the hook's `totalMintCost()` against this threshold before returning SCORING. If the mint cost is below the threshold, it returns NO_CONTEST. `totalMintCost` tracks only actual paid mint value and is decremented on refunds/burns — it cannot be inflated by `addToBalanceOf` top-ups.
 
 **What it solves.** Ghost games with negligible participation skip directly to refundability without requiring any governance action. A 32-team World Cup game with `minParticipation = 1 ETH` won't enter scoring if only 50 people mint (0.5 ETH pot).
 
-**Attack surface.** An adversary who wants to force no-contest can cash out enough tokens during the refund phase to push the supply below the threshold. Note that direct balance top-ups (via `addToBalanceOf`) cannot inflate participation since the check uses token supply, not treasury balance. Mitigation: set the threshold conservatively low relative to expected participation.
+**Attack surface.** An adversary who wants to force no-contest can refund enough NFTs during the refund phase to push `totalMintCost` below the threshold. Direct balance top-ups (via `addToBalanceOf`) cannot inflate participation since the check uses `totalMintCost`, not treasury balance. Mitigation: set the threshold conservatively low relative to expected participation.
 
 **Configuration.** Set to 0 to disable. The threshold is set at launch before any minting occurs, so calibration depends on organizer judgment.
 
@@ -820,7 +820,7 @@ The phase resolution follows strict priority:
 
 2. **Explicit trigger is sticky.** Once `noContestTriggeredFor[gameId]` is set, the game stays in NO_CONTEST permanently (cannot transition to SCORING even if conditions change).
 
-3. **Both thresholds are checked independently.** A game can enter NO_CONTEST from either `minParticipation` (token supply too low) or `scorecardTimeout` (time elapsed) — whichever condition is met first.
+3. **Both thresholds are checked independently.** A game can enter NO_CONTEST from either `minParticipation` (cumulative mint cost too low) or `scorecardTimeout` (time elapsed) — whichever condition is met first.
 
 #### 9.1.5 The Default Attestation Delegate
 

package/RISKS.md

@@ -22,6 +22,7 @@ This file focuses on the game-theoretic, governance, and settlement risks in Def
 - **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.
+- **Terminal provenance is the launcher's responsibility.** The hook authenticates terminals via directory registration, not implementation identity. A game is only as trustworthy as the terminal its launcher chose. Users must verify a game's terminal before participating.
 - **Default attestation delegate.** If set, it can accumulate meaningful governance power across new minters.
 
 ## 2. Economic Risks
@@ -86,6 +87,22 @@ Completion and ratification paths use one-way state to prevent replay or double-
 
 This is conservative, but it prevents users from front-running reserve dilution out of governance power or fee-token distribution.
 
-### 8.5 One-tier games always resolve via no-contest
+### 8.5 Launcher-selected terminals are trusted per game
 
-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.
+`DefifaDeployer.launchGameWith(...)` is permissionless and allows the launcher to choose the terminal registered for the game. `DefifaHook` trusts any registered terminal as the source of pay and cash-out callbacks. This means a malicious launcher can register a callback-forging terminal that fabricates hook contexts without recording real payments. Users and integrators must verify a game's registered terminal before trusting or participating in it. The same applies to scorecard timing parameters and tier configuration — a game's safety depends on the launcher choosing sane inputs. Frontends and aggregators should cross-reference a game's terminal against the canonical `JBMultiTerminal` for the chain before displaying it as trustworthy.
+
+### 8.6 One-tier games always resolve via no-contest
+
+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` would disable the timeout path entirely and leave funds permanently locked. `DefifaDeployer.launchGameWith` now enforces this at the contract level: a one-tier game with `scorecardTimeout == 0` reverts with `DefifaDeployer_InvalidGameConfiguration`. Two-tier games are still rounding-fragile in the same direction and should also be launched with a nonzero `scorecardTimeout`, but this is not enforced because some two-tier configurations can still reach quorum.
+
+### 8.7 Commitment splits are responsible for never reverting
+
+`DefifaDeployer.fulfillCommitmentsOf` calls `terminal.sendPayoutsOf` to distribute the commitment portion of the pot. Core processes splits inside a try/catch — when an individual split reverts (rejecting split hook, recipient terminal that does not accept the game token, fee project with a missing currency feed) the failed amount is silently re-credited to the game's terminal balance and the outer call succeeds. The unpaid commitment funds then remain available to game players via the cash-out path.
+
+This means **a single bad split cannot block the others from being paid**, and the unpaid funds are never lost — but it also means the recipient configured behind the failing split does not get paid through `fulfillCommitmentsOf` and must be settled separately if the game launcher cares. Game launchers are responsible for configuring commitment splits that will not revert under the game's terminal/currency setup. Recipients of commitment splits should treat split delivery as best-effort; the canonical post-game pot accounting still holds.
+
+`fulfilledCommitmentsOf[gameId]` always equals the requested commitment amount whenever any portion was attempted, regardless of whether every split succeeded. `currentGamePotOf(gameId, true)` adds this back to the remaining balance so the displayed pot represents the original pre-commitment value, but the actual on-terminal balance may be higher than the displayed pot when splits silently failed — by exactly the failed split amounts, which remain redeemable by game players. The bound therefore stays one-sided: real balance ≥ reported pot.
+
+### 8.8 Reserve minting is blocked during NO_CONTEST
+
+`DefifaHook.mintReservesFor` reverts with `DefifaHook_ReservedTokenMintingBlockedInNoContest` once `currentGamePhaseOf` reports `NO_CONTEST`. Reserve mints inflate `totalMintCost` so reserved recipients can claim a proportional share of fee tokens. Without this block, a game that failed `minParticipation` could be revived back into a SCORING-eligible state via free notional face value (reserves bump `totalMintCost` over the threshold) before `triggerNoContestFor()` latches the failure into a refund ruleset. The block tightens the §8.4 trust assumption that pending reserves are folded into governance and fee accounting: that remains true while the game is live, but once a game has already failed participation the reserve channel is closed so the no-contest outcome is final.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.31",
+  "version": "0.0.34",
   "license": "MIT",
   "engines": {
     "node": "25.9.0"
@@ -31,10 +31,10 @@
     "remappings.txt"
   ],
   "dependencies": {
-    "@bananapus/721-hook-v6": "0.0.46",
-    "@bananapus/address-registry-v6": "0.0.25",
-    "@bananapus/core-v6": "0.0.44",
-    "@bananapus/permission-ids-v6": "0.0.22",
+    "@bananapus/721-hook-v6": "^0.0.46",
+    "@bananapus/address-registry-v6": "^0.0.25",
+    "@bananapus/core-v6": "^0.0.48",
+    "@bananapus/permission-ids-v6": "^0.0.22",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1",
     "scripty.sol": "2.1.1"

package/src/DefifaDeployer.sol

@@ -186,7 +186,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
 
     /// @notice The safety mechanism parameters of a game.
     /// @param gameId The ID of the game to get the safety params of.
-    /// @return minParticipation The minimum treasury balance for the game to proceed to scoring.
+    /// @return minParticipation The minimum cumulative NFT mint cost for the game to proceed to scoring.
     /// @return scorecardTimeout The maximum time after scoring begins for a scorecard to be ratified.
     function safetyParamsOf(uint256 gameId)
         external
@@ -249,12 +249,13 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         // Get the game's ops data for the safety mechanism checks. Cache to avoid repeated SLOAD.
         DefifaOpsData memory ops = _opsOf[gameId];
 
-        // Check minimum participation threshold using token supply (not terminal balance).
-        // Token supply reflects actual minted participation — direct `addToBalanceOf` top-ups
-        // don't mint tokens and therefore can't bypass this check.
+        // Check minimum participation threshold using cumulative NFT mint cost from the hook.
+        // Terminal balance is NOT used because `addToBalanceOf` can inflate it without minting NFTs.
+        // `totalMintCost` tracks only actual paid mint value and is decremented on refunds/burns.
         if (ops.minParticipation > 0) {
-            uint256 totalTokenSupply = CONTROLLER.TOKENS().totalSupplyOf(gameId);
-            if (totalTokenSupply < ops.minParticipation) return DefifaGamePhase.NO_CONTEST;
+            if (IDefifaHook(metadata.dataHook).totalMintCost() < ops.minParticipation) {
+                return DefifaGamePhase.NO_CONTEST;
+            }
         }
 
         // Check scorecard ratification timeout: if enough time has passed without a ratified scorecard, the game is
@@ -424,6 +425,20 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             });
         }
 
+        // One-tier games cannot reach quorum (the BWA multiplier reduces the sole beneficiary tier's power to zero),
+        // so they must have a nonzero scorecardTimeout to resolve via NO_CONTEST. Without a timeout they would lock
+        // forever with no exit. Two-tier games are also rounding-fragile (see RISKS.md §8.6) and should set a
+        // scorecardTimeout, but this is not enforced at the contract level because some configurations can still
+        // reach quorum with luck-of-the-draw holder distributions.
+        if (launchProjectData.tiers.length == 1 && launchProjectData.scorecardTimeout == 0) {
+            revert DefifaDeployer_InvalidGameConfiguration({
+                start: launchProjectData.start,
+                mintPeriodDuration: launchProjectData.mintPeriodDuration,
+                refundPeriodDuration: launchProjectData.refundPeriodDuration,
+                tierCount: launchProjectData.tiers.length
+            });
+        }
+
         // Reject ERC-20 games with a zero currency. A zero baseCurrency would cause payout limit lookups
         // in fulfillCommitmentsOf to silently fail, skipping all commitment payouts.
         if (launchProjectData.token.token != JBConstants.NATIVE_TOKEN && launchProjectData.token.currency == 0) {

package/src/DefifaHook.sol

@@ -57,6 +57,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     error DefifaHook_Overspending(uint256 leftoverAmount);
     error DefifaHook_CashoutWeightsAlreadySet(uint256 projectId);
     error DefifaHook_ReservedTokenMintingPaused(uint256 projectId, uint256 tierId);
+    error DefifaHook_ReservedTokenMintingBlockedInNoContest(uint256 projectId, uint256 tierId);
     error DefifaHook_TransfersPaused(uint256 projectId, uint256 tokenId, address from, address to);
     error DefifaHook_Unauthorized(uint256 tokenId, address owner, address caller);
 
@@ -97,10 +98,6 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// @dev _tierId The ID of the tier to get a name for.
     mapping(uint256 => string) internal _tierNameOf;
 
-    /// @notice The cumulative mint price of all tokens (paid and reserved). Used as the denominator for fee token
-    /// ($DEFIFA/$NANA) distribution.
-    uint256 internal _totalMintCost;
-
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //
     //*********************************************************************//
@@ -115,6 +112,10 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
+    /// @notice The cumulative mint price of all paid and reserved NFTs. Decremented on burns/refunds. Used as the
+    /// participation metric — immune to `addToBalanceOf` inflation because only actual mints increment it.
+    uint256 public override totalMintCost;
+
     /// @notice The amount that has been redeemed from this game, refunds are not counted.
     uint256 public override amountRedeemed;
 
@@ -411,7 +412,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             tokenIds: tokenIds,
             hookStore: store,
             hook: address(this),
-            totalMintCost: _totalMintCost + _pendingReserveMintCost(),
+            totalMintCost: totalMintCost + _pendingReserveMintCost(),
             defifaBalance: DEFIFA_TOKEN.balanceOf(address(this)),
             baseProtocolBalance: BASE_PROTOCOL_TOKEN.balanceOf(address(this))
         });
@@ -568,6 +569,13 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             revert DefifaHook_ReservedTokenMintingPaused({projectId: PROJECT_ID, tierId: tierId});
         }
 
+        // Block reserve minting while the game is in NO_CONTEST. Reserve mints inflate `totalMintCost` (so reserved
+        // recipients can claim fee tokens), which would otherwise let a game that failed `minParticipation` revive
+        // back to SCORING via free notional face value before `triggerNoContestFor` latches the failure.
+        if (_currentGamePhaseOf(PROJECT_ID) == DefifaGamePhase.NO_CONTEST) {
+            revert DefifaHook_ReservedTokenMintingBlockedInNoContest({projectId: PROJECT_ID, tierId: tierId});
+        }
+
         // Cache the store reference in a local variable to avoid repeated SLOAD.
         IJB721TiersHookStore hookStore = store;
 
@@ -597,11 +605,11 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         // Fetch the tier details (needed for votingUnits below).
         JB721Tier memory tier = hookStore.tierOf({hook: address(this), id: tierId, includeResolvedUri: false});
 
-        // Increment _totalMintCost so reserved recipients can claim their share of fee tokens ($DEFIFA/$NANA).
+        // Increment totalMintCost so reserved recipients can claim their share of fee tokens ($DEFIFA/$NANA).
         // Note: reserved mints dilute existing fee token claimants because they increase the total mint cost
         // denominator without contributing new funds to the fee token balances. This is the intended design —
         // reserved recipients receive a proportional claim on fee tokens as if they had paid to mint.
-        _totalMintCost += tier.price * count;
+        totalMintCost += tier.price * count;
 
         for (uint256 i; i < count;) {
             // Set the token ID.
@@ -724,7 +732,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             beneficiaryReceivedTokens = _claimTokensFor({
                 beneficiary: context.beneficiary,
                 shareToBeneficiary: cumulativeMintPrice,
-                outOfTotal: _totalMintCost + _pendingReserveMintCost()
+                outOfTotal: totalMintCost + _pendingReserveMintCost()
             });
         }
 
@@ -739,7 +747,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         }
 
         // Decrement the paid mint cost by the cumulative mint price of the tokens being burned.
-        _totalMintCost -= cumulativeMintPrice;
+        totalMintCost -= cumulativeMintPrice;
     }
 
     /// @notice Mint reserved tokens within the tier for the provided value.
@@ -917,7 +925,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         uint256 tokenId;
 
         // Increment the paid mint cost.
-        _totalMintCost += amount;
+        totalMintCost += amount;
 
         // Loop through each token ID and mint.
         for (uint256 i; i < mintsLength;) {

package/src/interfaces/IDefifaHook.sol

@@ -117,6 +117,11 @@ interface IDefifaHook is IJB721Hook {
     /// @return The Defifa ERC-20 token.
     function DEFIFA_TOKEN() external view returns (IERC20);
 
+    /// @notice The cumulative mint price of all paid and reserved NFTs. Decremented on burns/refunds. Used as the
+    /// participation metric — immune to `addToBalanceOf` inflation because only actual mints increment it.
+    /// @return The total mint cost in the game's payment token.
+    function totalMintCost() external view returns (uint256);
+
     /// @notice The first owner of a given token ID.
     /// @param tokenId The token ID.
     /// @return The address of the first owner.

package/src/structs/DefifaLaunchProjectData.sol

@@ -30,8 +30,9 @@ import {DefifaTierParams} from "./DefifaTierParams.sol";
 /// @custom:member defaultAttestationDelegate The address that'll be set as the attestation delegate by default.
 /// @custom:member defaultTokenUriResolver The contract used to resolve token URIs if not provided by a tier
 /// specifically. @custom:member terminal The payment terminal where the project will accept funds through.
-/// @custom:member minParticipation The minimum treasury balance required for the game to proceed to scoring. If the
-/// balance is below this when scoring would begin, the game enters NO_CONTEST. Set to 0 to disable. @custom:member
+/// @custom:member minParticipation The minimum cumulative NFT mint cost required for the game to proceed to scoring.
+/// Compared against the hook's `totalMintCost` (immune to `addToBalanceOf` inflation). If below this when scoring
+/// would begin, the game enters NO_CONTEST. Set to 0 to disable. @custom:member
 /// scorecardTimeout The maximum time (in seconds) after the scoring phase begins for a scorecard to be ratified. If
 /// exceeded, the game enters NO_CONTEST. Set to 0 to disable.
 struct DefifaLaunchProjectData {

package/src/structs/DefifaOpsData.sol

@@ -6,9 +6,10 @@ pragma solidity ^0.8.0;
 /// @custom:member start The time at which the game should start, measured in seconds.
 /// @custom:member mintPeriodDuration The duration of the game's mint phase, measured in seconds.
 /// @custom:member refundPeriodDuration The time between the mint phase and the start time when mint's are no longer
-/// open but refunds are still allowed, measured in seconds. @custom:member minParticipation The minimum treasury
-/// balance required for the game to proceed to scoring. If the balance is below this when scoring would begin, the game
-/// enters NO_CONTEST. Set to 0 to disable.
+/// open but refunds are still allowed, measured in seconds. @custom:member minParticipation The minimum cumulative NFT
+/// mint cost required for the game to proceed to scoring. Compared against the hook's `totalMintCost` (immune to
+/// `addToBalanceOf` inflation). If below this when scoring would begin, the game enters NO_CONTEST. Set to 0 to
+/// disable.
 /// @custom:member scorecardTimeout The maximum time (in seconds) after the scoring phase begins for a scorecard to be
 /// ratified. If exceeded, the game enters NO_CONTEST. Set to 0 to disable.
 struct DefifaOpsData {