@ballkidz/defifa 0.0.25 → 0.0.27

package/AUDIT_INSTRUCTIONS.md

@@ -90,5 +90,9 @@ The contracts split responsibility as follows:
 ## Verification
 
 - `npm install`
-- `forge build`
-- `forge test`
+- `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`

package/README.md

@@ -85,8 +85,17 @@ npm install @ballkidz/defifa
 
 ```bash
 npm install
-forge build
-forge test
+forge build --deny notes
+forge test --deny notes
+```
+
+Useful checks before opening or updating a PR:
+
+```bash
+forge fmt --check
+forge build --deny notes --sizes --skip "*/test/**" --skip "*/script/**"
+forge build --deny notes --build-info --skip "*/test/**" --skip "*/script/**"
+npm pack --dry-run --json
 ```
 
 Useful scripts:

package/RISKS.md

@@ -26,9 +26,11 @@ This file focuses on the game-theoretic, governance, and settlement risks in Def
 
 ## 2. Economic Risks
 
-- **Scorecard manipulation via quorum.** Enough attestation power can redirect the whole pot.
+- **Scorecard manipulation via quorum.** Enough attestation power can redirect the whole pot. Once a coalition reaches the BWA (best winning attestation) quorum threshold, they can lock in a scorecard that favors their tiers. The grace period is the primary defense window for other participants to revoke attestations.
+- **BWA quorum lockout.** If a scorecard reaches quorum and the grace period elapses before opponents can revoke, the scorecard becomes ratifiable. In games with concentrated attestation power (few large holders), quorum may be reached quickly, leaving little time for the grace period defense to be effective.
 - **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.
+- **Commitment fee rounding to zero.** When commitment amounts are small relative to the fee percent, `mulDiv(amount, feePercent, MAX_FEE)` can round down to zero, allowing tiny commitments to bypass fees entirely. This is economically insignificant for practical game sizes but means fee accounting is not perfectly tight at 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.
 

package/STYLE_GUIDE.md

@@ -419,17 +419,17 @@ jobs:
           submodules: recursive
       - uses: actions/setup-node@v4
         with:
-          node-version: 22.4.x
+          node-version: 25.9.0
       - name: Install npm dependencies
-        run: npm install --omit=dev
+        run: npm install
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
       - name: Run tests
-        run: forge test --fail-fast --summary --detailed --skip "*/script/**"
+        run: forge test --deny notes --fail-fast --summary --detailed --skip "*/script/**"
         env:
           RPC_ETHEREUM_MAINNET: ${{ secrets.RPC_ETHEREUM_MAINNET }}
-      - name: Check contract sizes
-        run: forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils
+      - name: Build contracts
+        run: forge build --deny notes --skip "*/test/**" --skip "*/script/**"
 ```
 
 **lint.yml:**
@@ -470,16 +470,19 @@ jobs:
           submodules: recursive
       - uses: actions/setup-node@v4
         with:
-          node-version: latest
+          node-version: 25.9.0
       - name: Install npm dependencies
         run: npm install --omit=dev
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
+      - name: Prebuild contracts
+        run: forge build --deny notes --build-info --skip "*/test/**" --skip "*/script/**"
       - name: Run slither
-        uses: crytic/slither-action@v0.3.1
+        uses: crytic/slither-action@v0.4.1
         with:
             slither-config: slither-ci.config.json
             fail-on: medium
+            ignore-compile: true
 ```
 
 **slither-ci.config.json:**
@@ -508,14 +511,14 @@ jobs:
   "version": "x.x.x",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/Org/repo.git" },
-  "engines": { "node": ">=20.0.0" },
+  "engines": { "node": "25.9.0" },
   "scripts": {
     "test": "forge test",
     "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary"
   },
   "dependencies": { ... },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }
 ```
@@ -603,8 +606,8 @@ CI checks formatting via `forge fmt --check`.
 - `forge-std` as a git submodule in `lib/`
 - Sphinx plugins as a devDependency
 - Cross-repo references use `file:../sibling-repo` in local development
-- Published versions use semver ranges (`^0.0.x`) for npm
+- Published npm versions are pinned exactly; do not use semver ranges or `latest`
 
 ### Contract Size Checks
 
-CI runs `forge build --sizes` to catch contracts approaching the 24KB limit. When the repo's default `optimizer_runs` differs from what you want for size checking, use `FOUNDRY_PROFILE=ci_sizes forge build --sizes` with a `[profile.ci_sizes]` section in `foundry.toml`.
+CI runs `forge build --deny notes --sizes` to catch contracts approaching the 24KB limit. When the repo's default `optimizer_runs` differs from what you want for size checking, use `FOUNDRY_PROFILE=ci_sizes forge build --deny notes --sizes` with a `[profile.ci_sizes]` section in `foundry.toml`.

package/package.json

@@ -1,30 +1,47 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "license": "MIT",
   "engines": {
-    "node": ">=20.0.0"
+    "node": "25.9.0"
   },
   "bugs": {
-    "url": "https://github.com/BallKidz/defifa-collection-deployer/issues"
+    "url": "https://github.com/BallKidz/defifa/issues"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/BallKidz/defifa-collection-deployer"
+    "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"
+  ],
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.38",
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@croptop/core-v6": "^0.0.36",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@prb/math": "^4.1.1",
-    "@rev-net/core-v6": "^0.0.35",
-    "scripty.sol": "^2.1.1"
+    "@bananapus/721-hook-v6": "0.0.43",
+    "@bananapus/address-registry-v6": "0.0.25",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@openzeppelin/contracts": "5.6.1",
+    "@prb/math": "4.1.1",
+    "scripty.sol": "2.1.1"
   },
   "devDependencies": {
-    "@bananapus/address-registry-v6": "^0.0.17",
-    "@sphinx-labs/plugins": "^0.33.3"
+    "@sphinx-labs/contracts": "0.23.1",
+    "@sphinx-labs/plugins": "0.33.3"
   },
   "scripts": {
     "test": "forge test",

package/script/Deploy.s.sol

@@ -4,6 +4,7 @@ pragma solidity 0.8.28;
 import {Script} from "forge-std/Script.sol";
 import {ITypeface} from "lib/typeface/contracts/interfaces/ITypeface.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {JB721TiersHookStore} from "@bananapus/721-hook-v6/src/JB721TiersHookStore.sol";
 import {DefifaHook} from "../src/DefifaHook.sol";
 import {DefifaDeployer} from "../src/DefifaDeployer.sol";
 import {DefifaGovernor} from "../src/DefifaGovernor.sol";
@@ -109,6 +110,7 @@ contract DeployMainnet is Script, Sphinx {
         });
         DefifaTokenUriResolver tokenUriResolver = new DefifaTokenUriResolver{salt: _salt}(_typeface);
         DefifaGovernor governor = new DefifaGovernor{salt: _salt}({controller: core.controller, owner: safeAddress()});
+        JB721TiersHookStore hookStore = new JB721TiersHookStore{salt: _salt}();
         DefifaDeployer deployer = new DefifaDeployer{salt: _salt}({
             _hookCodeOrigin: address(hook),
             _tokenUriResolver: tokenUriResolver,
@@ -116,7 +118,8 @@ contract DeployMainnet is Script, Sphinx {
             _controller: core.controller,
             _registry: registry.registry,
             _defifaProjectId: _defifaProjectId,
-            _baseProtocolProjectId: _baseProtocolProjectId
+            _baseProtocolProjectId: _baseProtocolProjectId,
+            _hookStore: hookStore
         });
 
         governor.transferOwnership(address(deployer));

package/src/DefifaDeployer.sol

@@ -28,6 +28,8 @@ import {IERC721Receiver} from "@openzeppelin/contracts/token/ERC721/IERC721Recei
 import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
 
+import {IJB721TiersHookStore} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHookStore.sol";
+
 import {DefifaHook} from "./DefifaHook.sol";
 import {DefifaGamePhase} from "./enums/DefifaGamePhase.sol";
 import {IDefifaDeployer} from "./interfaces/IDefifaDeployer.sol";
@@ -39,7 +41,11 @@ import {DefifaLaunchProjectData} from "./structs/DefifaLaunchProjectData.sol";
 import {DefifaOpsData} from "./structs/DefifaOpsData.sol";
 import {DefifaTierParams} from "./structs/DefifaTierParams.sol";
 
-/// @notice Deploys and manages Defifa games.
+/// @notice Deploys and manages Defifa games — prediction-market-style contests built on Juicebox. Each game has
+/// tiers representing outcomes (teams, players, events). Players mint tier NFTs during the mint phase, then after
+/// 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 {
     using Strings for uint256;
     using SafeERC20 for IERC20;
@@ -102,6 +108,9 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @notice The hooks registry.
     IJBAddressRegistry public immutable REGISTRY;
 
+    /// @notice The 721 tiers hook store used by all games.
+    IJB721TiersHookStore public immutable HOOK_STORE;
+
     /// @notice The divisor that describes the protocol fee that should be taken.
     /// @dev This is equal to 100 divided by the fee percent (e.g. 40 = 2.5% fee).
     uint256 public constant override BASE_PROTOCOL_FEE_DIVISOR = 40;
@@ -121,6 +130,9 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @notice The total absolute split percent for each game (out of SPLITS_TOTAL_PERCENT).
     mapping(uint256 => uint256) internal _commitmentPercentOf;
 
+    /// @notice Whether commitments have been fulfilled for a game.
+    mapping(uint256 => bool) public commitmentsFulfilledFor;
+
     /// @notice Whether the no-contest refund ruleset has been triggered for a game.
     /// @dev Once triggered, the game stays in NO_CONTEST and refunds are enabled.
     mapping(uint256 => bool) public noContestTriggeredFor;
@@ -253,6 +265,8 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
 
         // Check scorecard ratification timeout: if enough time has passed without a ratified scorecard, the game is
         // NO_CONTEST.
+        // Game phase timing is timestamp-based by design.
+        // forge-lint: disable-next-line(block-timestamp)
         if (ops.scorecardTimeout > 0 && block.timestamp > currentRuleset.start + ops.scorecardTimeout) {
             return DefifaGamePhase.NO_CONTEST;
         }
@@ -278,7 +292,8 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         IJBController _controller,
         IJBAddressRegistry _registry,
         uint256 _defifaProjectId,
-        uint256 _baseProtocolProjectId
+        uint256 _baseProtocolProjectId,
+        IJB721TiersHookStore _hookStore
     ) {
         // slither-disable-next-line missing-zero-check
         HOOK_CODE_ORIGIN = _hookCodeOrigin;
@@ -288,6 +303,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         REGISTRY = _registry;
         DEFIFA_PROJECT_ID = _defifaProjectId;
         BASE_PROTOCOL_PROJECT_ID = _baseProtocolProjectId;
+        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)));
     }
@@ -298,9 +314,11 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
 
     /// @notice Fulfill split amounts between all splits for a game.
     /// @param gameId The ID of the game to fulfill splits for.
+    // slither-disable-next-line reentrancy-benign,reentrancy-no-eth
     function fulfillCommitmentsOf(uint256 gameId) external virtual override {
         // Make sure commitments haven't already been fulfilled.
-        if (fulfilledCommitmentsOf[gameId] != 0) return;
+        if (commitmentsFulfilledFor[gameId]) return;
+        commitmentsFulfilledFor[gameId] = true;
 
         // Get the game's current funding cycle along with its metadata.
         // slither-disable-next-line unused-return
@@ -319,10 +337,9 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         // Get the current pot and store it. This also prevents re-entrance since the check above will return early.
         uint256 pot = terminal.STORE().balanceOf({terminal: address(terminal), projectId: gameId, token: token});
 
-        // If the pot is empty, set the sentinel and queue the final ruleset without attempting payouts.
+        // If the pot is empty, queue the final ruleset without attempting payouts.
         // slither-disable-next-line incorrect-equality
         if (pot == 0) {
-            fulfilledCommitmentsOf[gameId] = 1;
             _queueFinalRuleset({gameId: gameId, metadata: metadata});
             // slither-disable-next-line reentrancy-events
             emit FulfilledCommitments({gameId: gameId, pot: 0, caller: msg.sender});
@@ -334,8 +351,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             mulDiv({x: pot, y: _commitmentPercentOf[gameId], denominator: JBConstants.SPLITS_TOTAL_PERCENT});
 
         // Store the actual fee amount for accurate currentGamePotOf reporting.
-        // Use max(feeAmount, 1) to preserve the reentrancy guard when pot is 0.
-        fulfilledCommitmentsOf[gameId] = feeAmount > 0 ? feeAmount : 1;
+        fulfilledCommitmentsOf[gameId] = feeAmount;
 
         // 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
@@ -346,9 +362,9 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             projectId: gameId, token: token, amount: feeAmount, currency: metadata.baseCurrency, minTokensPaidOut: 0
         }) {}
         catch (bytes memory reason) {
-            // Payout failed — fee stays in pot. Reset to sentinel (1) so currentGamePotOf
-            // doesn't double-count the fee, while preserving the reentrancy guard.
-            fulfilledCommitmentsOf[gameId] = 1;
+            // Payout failed — fee stays in pot. Reset to 0 so currentGamePotOf
+            // doesn't double-count the fee.
+            fulfilledCommitmentsOf[gameId] = 0;
             // slither-disable-next-line reentrancy-events
             emit CommitmentPayoutFailed({gameId: gameId, amount: feeAmount, reason: reason});
         }
@@ -363,24 +379,34 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @notice Launches a new game owned by this contract with a DefifaHook attached.
     /// @param launchProjectData Data necessary to fulfill the transaction to launch a game.
     /// @return gameId The ID of the newly configured game.
+    // slither-disable-next-line reentrancy-benign,reentrancy-no-eth
     function launchGameWith(DefifaLaunchProjectData memory launchProjectData)
         external
         override
         returns (uint256 gameId)
     {
-        // Start the game right after the mint and refund durations if it isnt provided.
+        // Game launch timing is timestamp-based by design.
+        uint256 currentTimestamp = block.timestamp;
+
+        // If no explicit game start is provided, start after the configured mint and refund windows.
         if (launchProjectData.start == 0) {
-            launchProjectData.start =
-                uint48(block.timestamp + launchProjectData.mintPeriodDuration + launchProjectData.refundPeriodDuration);
+            uint256 start =
+                currentTimestamp + launchProjectData.mintPeriodDuration + launchProjectData.refundPeriodDuration;
+            if (start > type(uint48).max) revert DefifaDeployer_InvalidGameConfiguration();
+
+            // Casting to uint48 is safe because `start` was bounded above.
+            // forge-lint: disable-next-line(unsafe-typecast)
+            launchProjectData.start = uint48(start);
         }
-        // Start minting right away if a start time isn't provided.
+        // If callers provide a future start with no mint duration, derive a mint window that begins now and ends
+        // before the refund window. This preserves the requested start while keeping minting immediately available.
         // slither-disable-next-line incorrect-equality
         else if (
             launchProjectData.mintPeriodDuration == 0
-                && launchProjectData.start > block.timestamp + launchProjectData.refundPeriodDuration
+                && launchProjectData.start > currentTimestamp + launchProjectData.refundPeriodDuration
         ) {
             launchProjectData.mintPeriodDuration =
-                uint24(launchProjectData.start - (block.timestamp + launchProjectData.refundPeriodDuration));
+                uint24(launchProjectData.start - (currentTimestamp + launchProjectData.refundPeriodDuration));
         }
 
         // Make sure the provided gameplay timestamps are sequential and that there is a mint duration.
@@ -388,24 +414,29 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             // slither-disable-next-line incorrect-equality
             launchProjectData.mintPeriodDuration == 0
                 || launchProjectData.start
-                    < block.timestamp + launchProjectData.refundPeriodDuration + launchProjectData.mintPeriodDuration
+                    < currentTimestamp + launchProjectData.refundPeriodDuration + launchProjectData.mintPeriodDuration
         ) revert DefifaDeployer_InvalidGameConfiguration();
 
         // The hook and governor hardcode uint256[128] tier-weight tables, so reject games with more than 128 tiers.
         if (launchProjectData.tiers.length > 128) revert DefifaDeployer_InvalidGameConfiguration();
 
-        // Reject ERC-20 games with a zero currency — a zero baseCurrency would cause payout limit lookups
+        // 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.
         // slither-disable-next-line incorrect-equality
         if (launchProjectData.token.token != JBConstants.NATIVE_TOKEN && launchProjectData.token.currency == 0) {
             revert DefifaDeployer_InvalidCurrency();
         }
 
-        // Get the game ID, optimistically knowing it will be one greater than the current count.
-        // Note: this prediction can race with other concurrent project deployments. If another project is
-        // created between reading count() and launchProjectFor(), the actual ID will differ. This is
-        // caught by the equality check after launch (gameId != actualGameId reverts).
-        gameId = CONTROLLER.PROJECTS().count() + 1;
+        // If a scorecard timeout is set, it must exceed the grace period + timelock duration.
+        // Otherwise the game would enter NO_CONTEST before a scorecard could ever reach SUCCEEDED.
+        if (
+            launchProjectData.scorecardTimeout > 0
+                && launchProjectData.scorecardTimeout
+                    <= launchProjectData.attestationGracePeriod + launchProjectData.timelockDuration
+        ) revert DefifaDeployer_InvalidGameConfiguration();
+
+        // Reserve the game ID up front so permissionless project creations cannot invalidate hook deployment.
+        gameId = CONTROLLER.PROJECTS().createFor(address(this));
 
         {
             // Store the timestamps that'll define the game phases.
@@ -536,19 +567,15 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             _contractUri: launchProjectData.contractUri,
             _tiers: hookTiers,
             _currency: launchProjectData.token.currency,
-            _store: launchProjectData.store,
+            _store: HOOK_STORE,
             _gamePhaseReporter: this,
             _gamePotReporter: this,
             _defaultAttestationDelegate: launchProjectData.defaultAttestationDelegate,
             _tierNames: tierNames
         });
 
-        // Launch the Juicebox project.
-        uint256 actualGameId =
-            _launchGame({launchProjectData: launchProjectData, gameId: gameId, dataHook: address(hook)});
-
-        // Revert if the game ID does not match (e.g. front-run by another project creation).
-        if (gameId != actualGameId) revert DefifaDeployer_InvalidGameConfiguration();
+        // Launch the Juicebox rulesets for the reserved project.
+        _launchGame({launchProjectData: launchProjectData, gameId: gameId, dataHook: address(hook)});
 
         // Clone and initialize the new governor.
         GOVERNOR.initializeGame({
@@ -742,15 +769,15 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         return groupedSplits;
     }
 
-    function _launchGame(
-        DefifaLaunchProjectData memory launchProjectData,
-        uint256 gameId,
-        address dataHook
-    )
-        internal
-        returns (uint256 projectId)
-    {
-        //
+    /// @notice Launch the Juicebox project rulesets that define a Defifa game's lifecycle.
+    /// @dev The project ID is reserved before the hook clone is initialized, so this function launches rulesets for
+    /// that existing project instead of creating a new one. It also forwards `projectUri` to the controller so the
+    /// project metadata is set atomically with the first rulesets.
+    /// @param launchProjectData The normalized launch data for the game.
+    /// @param gameId The reserved Juicebox project ID for the game.
+    /// @param dataHook The initialized Defifa hook clone used by every ruleset.
+    function _launchGame(DefifaLaunchProjectData memory launchProjectData, uint256 gameId, address dataHook) internal {
+        // Accept exactly the token/accounting context the game was configured to use.
         JBAccountingContext[] memory accountingContexts = new JBAccountingContext[](1);
         accountingContexts[0] = launchProjectData.token;
 
@@ -759,11 +786,13 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         terminalConfigurations[0] =
             JBTerminalConfig({terminal: launchProjectData.terminal, accountingContextsToAccept: accountingContexts});
 
-        // Build the rulesets that this Defifa game will go through.
+        // Build the rulesets that this Defifa game will go through. Games always have MINT and SCORING phases; the
+        // REFUND phase is omitted entirely when its duration is zero so the scoring ruleset can follow minting.
         bool hasRefundPhase = launchProjectData.refundPeriodDuration != 0;
         JBRulesetConfig[] memory rulesetConfigs = new JBRulesetConfig[](hasRefundPhase ? 3 : 2);
 
-        // `MINT` cycle.
+        // MINT cycle: payments are accepted, cash-outs are enabled, and pending reserved tokens are paused so the
+        // scoring/final phases decide how reserved tokens are distributed.
         rulesetConfigs[0] = JBRulesetConfig({
             mustStartAtOrAfter: launchProjectData.start - launchProjectData.mintPeriodDuration
                 - launchProjectData.refundPeriodDuration,
@@ -806,7 +835,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
 
         uint256 cycleNumber = 1;
         if (hasRefundPhase) {
-            // `REFUND` cycle.
+            // REFUND cycle: payments are paused while cash-outs remain available at pre-scoring terms.
             rulesetConfigs[cycleNumber++] = JBRulesetConfig({
                 mustStartAtOrAfter: launchProjectData.start - launchProjectData.refundPeriodDuration,
                 duration: launchProjectData.refundPeriodDuration,
@@ -848,7 +877,8 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             });
         }
 
-        // Set fund access constraints.
+        // The scoring ruleset can send the whole pot as payouts. `fulfillCommitmentsOf` only sends the commitment
+        // portion and leaves the rest as surplus for the final cash-out ruleset.
         JBCurrencyAmount[] memory payoutAmounts = new JBCurrencyAmount[](1);
         payoutAmounts[0] = JBCurrencyAmount({
             // We allow a payout of the full amount, this will then mostly be added back to the balance of the project.
@@ -864,7 +894,8 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             surplusAllowances: new JBCurrencyAmount[](0)
         });
 
-        // `SCORING` cycle.
+        // SCORING cycle: payments pause, the game owner must send payouts, and the Defifa hook determines the final
+        // cash-out weights once a scorecard is ratified.
         rulesetConfigs[cycleNumber++] = JBRulesetConfig({
             mustStartAtOrAfter: launchProjectData.start,
             duration: 0,
@@ -906,9 +937,10 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             fundAccessLimitGroups: fundAccessConstraints
         });
 
-        // launch the project.
-        return CONTROLLER.launchProjectFor({
-            owner: address(this),
+        // Launch the rulesets for the reserved project and set the project URI in the same controller call.
+        // slither-disable-next-line unused-return
+        CONTROLLER.launchRulesetsFor({
+            projectId: gameId,
             projectUri: launchProjectData.projectUri,
             rulesetConfigurations: rulesetConfigs,
             terminalConfigurations: terminalConfigurations,