@ballkidz/defifa 0.0.30 → 0.0.32

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/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,10 @@ 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
+
+`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` disables the timeout path entirely, and funds become permanently locked with no exit. Game deployers must ensure `scorecardTimeout > 0` for single-tier configurations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "license": "MIT",
   "engines": {
     "node": "25.9.0"
@@ -31,7 +31,7 @@
     "remappings.txt"
   ],
   "dependencies": {
-    "@bananapus/721-hook-v6": "0.0.43",
+    "@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",

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

package/src/DefifaHook.sol

@@ -97,10 +97,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 +111,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;
 
@@ -285,7 +285,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         )
     {
         // Make sure (fungible) project tokens aren't also being cashed out.
-        if (context.cashOutCount > 0) revert JB721Hook_UnexpectedTokenCashedOut();
+        if (context.cashOutCount > 0) revert JB721Hook_UnexpectedTokenCashedOut({cashOutCount: context.cashOutCount});
 
         // Fetch the cash out hook metadata using the corresponding metadata ID.
         (bool metadataExists, bytes memory metadata) = JBMetadataResolver.getDataFor({
@@ -411,7 +411,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))
         });
@@ -466,7 +466,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
         // interaction with the correct project.
         if (msg.value != 0 || !_isProjectTerminal(projectId) || context.projectId != projectId) {
-            revert JB721Hook_InvalidPay();
+            revert JB721Hook_InvalidPay({caller: msg.sender, contextProjectId: context.projectId, projectId: projectId});
         }
 
         // Process the payment.
@@ -597,11 +597,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.
@@ -645,7 +645,9 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
         // interaction with the correct project.
         if (msg.value != 0 || !_isProjectTerminal(PROJECT_ID) || context.projectId != PROJECT_ID) {
-            revert JB721Hook_InvalidCashOut();
+            revert JB721Hook_InvalidCashOut({
+                caller: msg.sender, contextProjectId: context.projectId, projectId: PROJECT_ID, msgValue: msg.value
+            });
         }
 
         // Fetch the cash out hook metadata using the corresponding metadata ID.
@@ -722,7 +724,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             beneficiaryReceivedTokens = _claimTokensFor({
                 beneficiary: context.beneficiary,
                 shareToBeneficiary: cumulativeMintPrice,
-                outOfTotal: _totalMintCost + _pendingReserveMintCost()
+                outOfTotal: totalMintCost + _pendingReserveMintCost()
             });
         }
 
@@ -737,7 +739,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.
@@ -915,7 +917,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 {