@ballkidz/defifa 0.0.17 → 0.0.19

package/foundry.lock

@@ -0,0 +1,17 @@
+{
+  "lib/base64": {
+    "branch": {
+      "name": "v1.1.0",
+      "rev": "dcbf852ba545b3d15de0ac0ef88dce934c090c8e"
+    }
+  },
+  "lib/capsules": {
+    "rev": "7432ba95ac69ba4902076660b0dc9a90aeb26706"
+  },
+  "lib/forge-std": {
+    "rev": "8bbcf6e3f8f62f419e5429a0bd89331c85c37824"
+  },
+  "lib/typeface": {
+    "rev": "edd52e2f7c8adc44e75b207bd279710f9b72f5e9"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "license": "MIT",
   "engines": {
     "node": ">=20.0.0"
@@ -13,14 +13,13 @@
     "url": "https://github.com/BallKidz/defifa-collection-deployer"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.28",
-    "@bananapus/address-registry-v6": "^0.0.16",
-    "@bananapus/core-v6": "^0.0.30",
+    "@bananapus/721-hook-v6": "^0.0.30",
+    "@bananapus/core-v6": "^0.0.31",
     "@bananapus/permission-ids-v6": "^0.0.15",
-    "@croptop/core-v6": "^0.0.26",
+    "@croptop/core-v6": "^0.0.29",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.1",
-    "@rev-net/core-v6": "^0.0.24",
+    "@rev-net/core-v6": "^0.0.26",
     "scripty.sol": "^2.1.1"
   },
   "devDependencies": {

package/references/operations.md

@@ -0,0 +1,27 @@
+# Defifa Operations
+
+## 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) is the deployment entry point 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.
+
+## 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.
+
+## Useful Proof Points
+
+- [`test/Fork.t.sol`](../test/Fork.t.sol) for live-integration assumptions.
+- [`test/TestAuditGaps.sol`](../test/TestAuditGaps.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.

package/references/runtime.md

@@ -0,0 +1,32 @@
+# Defifa Runtime
+
+## 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.
+4. Scoring phase where scorecards are submitted, attested, and ratified.
+5. Complete or no-contest settlement depending on governance and safety conditions.
+
+## 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.
+
+## 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) and [`test/regression/`](../test/regression/) for pinned regressions.
+- [`test/DefifaSecurity.t.sol`](../test/DefifaSecurity.t.sol) and [`test/DefifaGovernanceHardening.t.sol`](../test/DefifaGovernanceHardening.t.sol) for adversarial cases.

package/script/Deploy.s.sol

@@ -22,9 +22,8 @@ contract DeployMainnet is Script, Sphinx {
     /// @notice tracks the deployment of the address registry for the chain we are deploying to.
     AddressRegistryDeployment registry;
 
-    // NOTE: This id is revnet, this is temporary until we have a defifa revnet.
-    uint256 _defifaProjectId = 3;
-    uint256 _baseProtocolProjectId = 1;
+    uint256 _defifaProjectId;
+    uint256 _baseProtocolProjectId;
 
     bytes32 _salt = bytes32(keccak256("0.0.2"));
 
@@ -53,6 +52,9 @@ contract DeployMainnet is Script, Sphinx {
             )
         );
 
+        _defifaProjectId = vm.envUint("DEFIFA_PROJECT_ID");
+        _baseProtocolProjectId = vm.envUint("BASE_PROTOCOL_PROJECT_ID");
+
         defifaToken = IERC20(address(core.tokens.tokenOf(_defifaProjectId)));
         baseProtocolToken = IERC20(address(core.tokens.tokenOf(_baseProtocolProjectId)));
 

package/src/DefifaDeployer.sol

@@ -7,6 +7,7 @@ import {
     JB721TiersRulesetMetadataResolver
 } from "@bananapus/721-hook-v6/src/libraries/JB721TiersRulesetMetadataResolver.sol";
 import {JB721TierConfig} from "@bananapus/721-hook-v6/src/structs/JB721TierConfig.sol";
+import {JB721TierConfigFlags} from "@bananapus/721-hook-v6/src/structs/JB721TierConfigFlags.sol";
 import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
 import {IJBController, JBRulesetConfig, JBTerminalConfig} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBMultiTerminal} from "@bananapus/core-v6/src/interfaces/IJBMultiTerminal.sol";
@@ -274,6 +275,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         uint256 _defifaProjectId,
         uint256 _baseProtocolProjectId
     ) {
+        // slither-disable-next-line missing-zero-check
         HOOK_CODE_ORIGIN = _hookCodeOrigin;
         TOKEN_URI_RESOLVER = _tokenUriResolver;
         GOVERNOR = _governor;
@@ -471,13 +473,15 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
                 encodedIPFSUri: defifaTier.encodedIPFSUri,
                 category: 0,
                 discountPercent: 0,
-                allowOwnerMint: false,
-                useReserveBeneficiaryAsDefault: defifaTier.shouldUseReservedTokenBeneficiaryAsDefault,
-                transfersPausable: false,
-                useVotingUnits: false,
-                cantBeRemoved: true,
-                cantIncreaseDiscountPercent: true,
-                cantBuyWithCredits: false,
+                flags: JB721TierConfigFlags({
+                    allowOwnerMint: false,
+                    useReserveBeneficiaryAsDefault: defifaTier.shouldUseReservedTokenBeneficiaryAsDefault,
+                    transfersPausable: false,
+                    useVotingUnits: false,
+                    cantBeRemoved: true,
+                    cantIncreaseDiscountPercent: true,
+                    cantBuyWithCredits: false
+                }),
                 splitPercent: 0,
                 splits: new JBSplit[](0)
             });
@@ -546,8 +550,13 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         // Transfer ownership to the specified owner.
         hook.transferOwnership(address(GOVERNOR));
 
-        // Add the hook to the registry, contract nonce starts at 1
-        REGISTRY.registerAddress({deployer: address(this), nonce: currentNonce});
+        // Register the actual CREATE2 clone address using the same salt and minimal-proxy init code
+        // that produced the deployed hook.
+        REGISTRY.registerAddress({
+            deployer: address(this),
+            salt: keccak256(abi.encodePacked(msg.sender, currentNonce)),
+            bytecode: _cloneCreationCodeFor(address(HOOK_CODE_ORIGIN))
+        });
 
         // slither-disable-next-line reentrancy-events
         emit LaunchGame(gameId, hook, GOVERNOR, uriResolver, msg.sender);
@@ -936,4 +945,19 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
             projectId: gameId, rulesetConfigurations: rulesetConfigs, memo: "Defifa game has finished."
         });
     }
+
+    /// @notice Returns the minimal-proxy init code used to deploy a clone for the provided implementation.
+    /// @dev Defifa deploys hooks with `Clones.cloneDeterministic`, which uses `CREATE2`.
+    /// The address registry's CREATE2 path must be given the exact init code hash that was used at deployment time,
+    /// not the runtime bytecode and not a CREATE nonce. This helper reconstructs the standard EIP-1167 creation code
+    /// by inserting the implementation address into OpenZeppelin's minimal-proxy init-code template.
+    /// @param implementation The contract address the clone will delegate all calls to.
+    /// @return bytecode The full EIP-1167 creation bytecode hashed by CREATE2 to derive the clone address.
+    function _cloneCreationCodeFor(address implementation) internal pure returns (bytes memory bytecode) {
+        // EIP-1167 minimal proxy init code, mirroring OpenZeppelin's Clones.sol layout:
+        // [prefix (20 bytes)] [implementation address (20 bytes)] [suffix (15 bytes)]
+        bytecode = abi.encodePacked(
+            hex"3d602d80600a3d3981f3363d3d373d3d3d363d73", bytes20(implementation), hex"5af43d82803e903d91602b57fd5bf3"
+        );
+    }
 }

package/src/DefifaGovernor.sol

@@ -18,6 +18,7 @@ import {IDefifaHook} from "./interfaces/IDefifaHook.sol";
 import {DefifaAttestations} from "./structs/DefifaAttestations.sol";
 import {DefifaScorecard} from "./structs/DefifaScorecard.sol";
 import {DefifaTierCashOutWeight} from "./structs/DefifaTierCashOutWeight.sol";
+import {DefifaHookLib} from "./libraries/DefifaHookLib.sol";
 
 /// @notice Manages the ratification of Defifa scorecards.
 contract DefifaGovernor is Ownable, IDefifaGovernor {
@@ -83,12 +84,20 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     mapping(uint256 => mapping(uint256 => DefifaAttestations)) internal _scorecardAttestationsOf;
 
     /// @notice Snapshot of pending reserves per tier at scorecard submission time.
-    /// @dev Prevents reserve dilution between submission and attestation.
+    /// @dev Used to keep unminted reserve units in the BWA denominator.
     /// @custom:param gameId The ID of the game.
     /// @custom:param scorecardId The ID of the scorecard.
     /// @custom:param tierId The tier ID (1-indexed).
     mapping(uint256 => mapping(uint256 => mapping(uint256 => uint256))) internal _pendingReservesSnapshotOf;
 
+    /// @notice Snapshot of each tier's minted attestation units at scorecard submission time.
+    /// @dev Caps later checkpoint reads so reserve mints after submission can't increase the denominator
+    /// before the pending-reserve snapshot is added back in.
+    /// @custom:param gameId The ID of the game.
+    /// @custom:param scorecardId The ID of the scorecard.
+    /// @custom:param tierId The tier ID (1-indexed).
+    mapping(uint256 => mapping(uint256 => mapping(uint256 => uint256))) internal _submittedTierAttestationUnitsOf;
+
     /// @notice Tier weights per scorecard for BWA computation.
     /// @custom:param gameId The ID of the game.
     /// @custom:param scorecardId The ID of the scorecard.
@@ -260,15 +269,23 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         }
 
         // If there's a weight assigned to the tier, make sure there is a token backed by it.
+        // slither-disable-next-line calls-loop
         for (uint256 i; i < numberOfTierWeights; i++) {
-            if (
-                tierWeights[i].cashOutWeight > 0
-                    && IDefifaHook(metadata.dataHook).currentSupplyOfTier(tierWeights[i].id) == 0
-            ) {
+            // A nonzero cashout weight is only valid once that tier has live ownership.
+            // slither-disable-next-line calls-loop
+            uint256 currentTierSupply = IDefifaHook(metadata.dataHook).currentSupplyOfTier(tierWeights[i].id);
+            if (tierWeights[i].cashOutWeight > 0 && currentTierSupply == 0) {
                 revert DefifaGovernor_UnownedProposedCashoutValue();
             }
         }
 
+        // Run the same structural validation the hook will apply at ratification time so malformed
+        // scorecards fail on submission instead of reaching a misleading SUCCEEDED state first.
+        // slither-disable-next-line unused-return
+        DefifaHookLib.validateAndBuildWeights({
+            tierWeights: tierWeights, hookStore: IDefifaHook(metadata.dataHook).store(), hook: metadata.dataHook
+        });
+
         // Hash the scorecard.
         scorecardId =
             _hashScorecardOf({gameHook: metadata.dataHook, calldataBytes: _buildScorecardCalldataFor(tierWeights)});
@@ -295,15 +312,25 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
             _scorecardTierWeightsOf[gameId][scorecardId][tierWeights[i].id - 1] = tierWeights[i].cashOutWeight;
         }
 
-        // Snapshot pending reserves for each tier at submission time.
-        // This prevents reserve minting between submission and attestation from diluting votes.
+        // Snapshot each tier's pending reserves and minted attestation units at submission time.
+        // BWA later reads an account checkpoint at `attestationsBegin - 1`. If reserve mints happen
+        // after submission but before that checkpoint, clamp the live total back down to the minted
+        // units that existed at submission and only then add the snapshotted pending reserves.
         {
             IJB721TiersHookStore _store = IDefifaHook(metadata.dataHook).store();
             uint256 _numberOfTiers = _store.maxTierIdOf(metadata.dataHook);
+            // slither-disable-next-line calls-loop
             for (uint256 i; i < _numberOfTiers; i++) {
                 uint256 tierId = i + 1;
-                _pendingReservesSnapshotOf[gameId][scorecardId][tierId] =
-                    _store.numberOfPendingReservesFor(metadata.dataHook, tierId);
+                // slither-disable-next-line calls-loop
+                JB721Tier memory tier = _store.tierOf({hook: metadata.dataHook, id: tierId, includeResolvedUri: false});
+                // slither-disable-next-line calls-loop
+                uint256 pendingReserves = _store.numberOfPendingReservesFor(metadata.dataHook, tierId);
+                // slither-disable-next-line calls-loop
+                uint256 submittedTierAttestationUnits =
+                    IDefifaHook(metadata.dataHook).currentSupplyOfTier(tierId) * tier.votingUnits;
+                _pendingReservesSnapshotOf[gameId][scorecardId][tierId] = pendingReserves;
+                _submittedTierAttestationUnitsOf[gameId][scorecardId][tierId] = submittedTierAttestationUnits;
             }
         }
 
@@ -490,16 +517,17 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         // Get a reference to the number of tiers.
         uint256 numberOfTiers = store.maxTierIdOf(metadata.dataHook);
 
-        // slither-disable-next-line calls-inside-a-loop
         for (uint256 i; i < numberOfTiers; i++) {
             // Tiers are 1-indexed.
             uint256 tierId = i + 1;
 
             // Get this account's attestation units within the tier (snapshot at timestamp).
+            // slither-disable-next-line calls-loop
             uint256 tierAttestationUnitsForAccount =
                 hook.getPastTierAttestationUnitsOf({account: account, tier: tierId, timestamp: timestamp});
 
             // Get the total attestation units for this tier (snapshot at timestamp).
+            // slither-disable-next-line calls-loop
             uint256 tierTotalAttestationUnits =
                 hook.getPastTierTotalAttestationUnitsOf({tier: tierId, timestamp: timestamp});
 
@@ -508,8 +536,10 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
             // When the reserve beneficiary later mints, their new NFTs add to the numerator while
             // pending reserves decrease by the same amount — so no one's voting power shifts.
             {
+                // slither-disable-next-line calls-loop
                 uint256 pendingReserves = store.numberOfPendingReservesFor(metadata.dataHook, tierId);
                 if (pendingReserves != 0) {
+                    // slither-disable-next-line calls-loop
                     JB721Tier memory tier =
                         store.tierOf({hook: metadata.dataHook, id: tierId, includeResolvedUri: false});
                     tierTotalAttestationUnits += pendingReserves * tier.votingUnits;
@@ -567,30 +597,33 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         // Cache the total cashout weight denominator from the hook.
         uint256 totalCashOutWeight = hook.TOTAL_CASHOUT_WEIGHT();
 
-        // slither-disable-next-line calls-inside-a-loop
         for (uint256 i; i < numberOfTiers; i++) {
             // Tiers are 1-indexed.
             uint256 tierId = i + 1;
 
             // Get this account's attestation units within the tier (snapshot at timestamp).
+            // slither-disable-next-line calls-loop
             uint256 tierAttestationUnitsForAccount =
                 hook.getPastTierAttestationUnitsOf({account: account, tier: tierId, timestamp: timestamp});
 
             if (tierAttestationUnitsForAccount != 0) {
-                // Get the total attestation units for this tier (snapshot at timestamp).
+                // Start from the checkpointed tier total at the requested timestamp.
+                // If reserve mints happened after submission, clamp them out before adding the
+                // pending-reserve snapshot back in so each reserve unit is counted exactly once.
+                // slither-disable-next-line calls-loop
                 uint256 tierTotalAttestationUnits =
                     hook.getPastTierTotalAttestationUnitsOf({tier: tierId, timestamp: timestamp});
+                uint256 submittedTierAttestationUnits = _submittedTierAttestationUnitsOf[gameId][scorecardId][tierId];
+                if (tierTotalAttestationUnits > submittedTierAttestationUnits) {
+                    tierTotalAttestationUnits = submittedTierAttestationUnits;
+                }
 
-                // Include unminted pending reserves in the total (denominator only).
-                // Uses the snapshot taken at scorecard submission time to prevent reserve
-                // minting between submission and attestation from diluting votes.
-                {
-                    uint256 pendingReserves = _pendingReservesSnapshotOf[gameId][scorecardId][tierId];
-                    if (pendingReserves != 0) {
-                        JB721Tier memory tier =
-                            store.tierOf({hook: metadata.dataHook, id: tierId, includeResolvedUri: false});
-                        tierTotalAttestationUnits += pendingReserves * tier.votingUnits;
-                    }
+                uint256 pendingReserves = _pendingReservesSnapshotOf[gameId][scorecardId][tierId];
+                if (pendingReserves != 0) {
+                    // slither-disable-next-line calls-loop
+                    JB721Tier memory tier =
+                        store.tierOf({hook: metadata.dataHook, id: tierId, includeResolvedUri: false});
+                    tierTotalAttestationUnits += pendingReserves * tier.votingUnits;
                 }
 
                 // Raw power for this tier.
@@ -630,18 +663,18 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         // Keep a reference to the total eligible tier weight.
         uint256 eligibleTierWeights;
 
-        // slither-disable-next-line calls-inside-a-loop
         for (uint256 i; i < numberOfTiers; i++) {
             uint256 tierId = i + 1;
 
             // A tier contributes to quorum if it has circulating tokens OR unminted pending reserves.
-            // Pending reserves exist when participation occurred (mints triggered reserve accrual),
-            // even if all paid tokens were later burned during REFUND. The reserve beneficiary still
-            // has a stake in that tier's outcome, so the tier should count toward governance quorum.
-            if (
-                hook.currentSupplyOfTier(tierId) != 0
-                    || store.numberOfPendingReservesFor(metadata.dataHook, tierId) != 0
-            ) {
+            // Pending reserves still belong economically to the reserve beneficiary, even after the
+            // last paid token in the tier is burned during REFUND, so excluding them would let a
+            // burner erase another participant's quorum contribution without erasing their claim.
+            // slither-disable-next-line calls-loop
+            uint256 currentTierSupply = hook.currentSupplyOfTier(tierId);
+            // slither-disable-next-line calls-loop
+            uint256 pendingReserves = store.numberOfPendingReservesFor(metadata.dataHook, tierId);
+            if (currentTierSupply != 0 || pendingReserves != 0) {
                 eligibleTierWeights += MAX_ATTESTATION_POWER_TIER;
             }
         }

package/src/DefifaHook.sol

@@ -59,6 +59,8 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     error DefifaHook_TransfersPaused();
     error DefifaHook_Unauthorized(uint256 tokenId, address owner, address caller);
 
+    event PricingCurrencySet(uint256 currency, address caller);
+
     //*********************************************************************//
     // --------------------- public constant properties ------------------ //
     //*********************************************************************//
@@ -497,6 +499,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         pricingCurrency = _currency;
         gamePhaseReporter = _gamePhaseReporter;
         gamePotReporter = _gamePotReporter;
+        // slither-disable-next-line missing-zero-check
         defaultAttestationDelegate = _defaultAttestationDelegate;
 
         // Store the base URI if provided.
@@ -529,19 +532,22 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
 
         // Transfer ownership to the initializer.
         _transferOwnership(msg.sender);
+
+        emit PricingCurrencySet(_currency, msg.sender);
     }
 
     /// @notice Mint reserved tokens within the tier for the provided value.
     /// @param tierId The ID of the tier to mint within.
     /// @param count The number of reserved tokens to mint.
-    // slither-disable-next-line reentrancy-no-eth
     function mintReservesFor(uint256 tierId, uint256 count) public override {
         // Minting reserves must not be paused.
+        // slither-disable-next-line calls-loop
         if (JB721TiersRulesetMetadataResolver.mintPendingReservesPaused(
                 (JBRulesetMetadataResolver.metadata(rulesets.currentOf(PROJECT_ID)))
             )) revert DefifaHook_ReservedTokenMintingPaused();
 
         // Keep a reference to the reserved token beneficiary.
+        // slither-disable-next-line calls-loop
         address reservedTokenBeneficiary = store.reserveBeneficiaryOf({hook: address(this), tierId: tierId});
 
         // Get a reference to the old delegate.
@@ -559,12 +565,14 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         }
 
         // Record the minted reserves for the tier.
+        // slither-disable-next-line calls-loop
         uint256[] memory tokenIds = store.recordMintReservesFor({tierId: tierId, count: count});
 
         // Keep a reference to the token ID being iterated on.
         uint256 tokenId;
 
         // Fetch the tier details (needed for votingUnits below).
+        // slither-disable-next-line calls-loop
         JB721Tier memory tier = store.tierOf({hook: address(this), id: tierId, includeResolvedUri: false});
 
         // Increment _totalMintCost so reserved recipients can claim their share of fee tokens ($DEFIFA/$NANA).
@@ -579,6 +587,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             tokenId = tokenIds[i];
 
             // Mint the token.
+            // slither-disable-next-line reentrancy-no-eth
             _mint({to: reservedTokenBeneficiary, tokenId: tokenId});
 
             emit MintReservedToken(tokenId, tierId, reservedTokenBeneficiary, msg.sender);
@@ -589,6 +598,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         }
 
         // Transfer the attestation units to the delegate.
+        // slither-disable-next-line reentrancy-no-eth
         _transferTierAttestationUnits({
             from: address(0), to: reservedTokenBeneficiary, tierId: tierId, amount: tier.votingUnits * tokenIds.length
         });
@@ -602,7 +612,6 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// `context.beneficiary`. Part of `IJBCashOutHook`.
     /// @dev Reverts if the calling contract is not one of the project's terminals.
     /// @param context The cash out context passed in by the terminal.
-    // slither-disable-next-line locked-ether,reentrancy-no-eth
     function afterCashOutRecordedWith(JBAfterCashOutRecordedContext calldata context)
         external
         payable
@@ -654,6 +663,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
 
             if (isComplete) {
                 unchecked {
+                    // slither-disable-next-line reentrancy-no-eth,calls-loop
                     ++tokensRedeemedFrom[store.tierIdOfToken(tokenId)];
                 }
             }
@@ -674,6 +684,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             // Claim the $DEFIFA and $NANA tokens for the user.
             // Include pending reserve mint cost in the denominator so that unminted reserves
             // are accounted for, preventing paid holders from claiming a disproportionate share.
+            // slither-disable-next-line reentrancy-events
             beneficiaryReceivedTokens = _claimTokensFor({
                 beneficiary: context.holder,
                 shareToBeneficiary: cumulativeMintPrice,
@@ -795,8 +806,10 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
 
         for (uint256 i; i < numberOfTiers;) {
             uint256 tierId = i + 1;
+            // slither-disable-next-line calls-loop
             uint256 pendingReserves = _store.numberOfPendingReservesFor({hook: hook, tierId: tierId});
             if (pendingReserves != 0) {
+                // slither-disable-next-line calls-loop
                 JB721Tier memory tier = _store.tierOf({hook: hook, id: tierId, includeResolvedUri: false});
                 cost += pendingReserves * tier.price;
             }
@@ -862,6 +875,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// @param tierId The ID of the tier to get attestation units for.
     /// @return The attestation units.
     function _getTierAttestationUnits(address account, uint256 tierId) internal view virtual returns (uint256) {
+        // slither-disable-next-line calls-loop
         return store.tierVotingUnitsOf({hook: address(this), account: account, tierId: tierId});
     }
 
@@ -882,7 +896,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         uint256[] memory tokenIds;
 
         // Record the mint. The returned token IDs correspond to the tiers passed in.
-        // slither-disable-next-line reentrancy-benign
+        // slither-disable-next-line unused-return,reentrancy-benign
         (tokenIds, leftoverAmount,) = store.recordMint({
             amount: amount,
             tierIds: mintTierIds,
@@ -994,8 +1008,12 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
 
             // If there's either a new delegate or old delegate, set delegation and transfer units.
             if (attestationDelegate != address(0) || oldDelegate != address(0)) {
-                // Switch delegates if needed.
-                if (attestationDelegate != address(0) && attestationDelegate != oldDelegate) {
+                // Delegation is beneficiary-owned state. A third-party payer can fund this mint, but
+                // cannot overwrite the beneficiary's long-lived delegate preference through metadata.
+                if (
+                    context.payer == context.beneficiary && attestationDelegate != address(0)
+                        && attestationDelegate != oldDelegate
+                ) {
                     _delegateTier({account: context.beneficiary, delegatee: attestationDelegate, tierId: tierId});
                 }
 
@@ -1083,8 +1101,9 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         // Transfers must not be paused (when not minting or burning).
         if (from != address(0)) {
             // If transfers are pausable, check if they're paused.
-            if (tier.transfersPausable) {
+            if (tier.flags.transfersPausable) {
                 // Get a reference to the project's current ruleset.
+                // slither-disable-next-line calls-loop
                 JBRuleset memory ruleset = rulesets.currentOf(PROJECT_ID);
 
                 // If transfers are paused and the NFT isn't being transferred to the zero address, revert.
@@ -1101,14 +1120,15 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             if (_firstOwnerOf[tokenId] == address(0)) _firstOwnerOf[tokenId] = from;
         }
 
-        // Record the transfer.
-        // slither-disable-next-line reentrancy-events,calls-loop
-        store.recordTransferForTier({tierId: tier.id, from: from, to: to});
-
         // Dont transfer on mint since the delegation will be transferred more efficiently in _processPayment.
-        if (from == address(0)) return from;
+        if (from != address(0)) {
+            _transferTierAttestationUnits({from: from, to: to, tierId: tier.id, amount: tier.votingUnits});
+        }
+
+        // Record the transfer after local delegation state has been finalized.
+        // slither-disable-next-line calls-loop
+        store.recordTransferForTier({tierId: tier.id, from: from, to: to});
 
-        // Transfer the attestation units.
-        _transferTierAttestationUnits({from: from, to: to, tierId: tier.id, amount: tier.votingUnits});
+        return from;
     }
 }

package/src/interfaces/IDefifaDeployer.sol

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-import {IJB721TokenUriResolver} from "@bananapus/721-hook-v6/src/interfaces/IJB721TokenUriResolver.sol";
 import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
+import {IJB721TokenUriResolver} from "@bananapus/721-hook-v6/src/interfaces/IJB721TokenUriResolver.sol";
 import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 
@@ -13,12 +13,30 @@ import {IDefifaHook} from "./IDefifaHook.sol";
 /// @notice Deploys and manages Defifa prediction games, including lifecycle phase transitions
 /// and commitment fulfillment.
 interface IDefifaDeployer {
+    /// @notice Emitted when a commitment payout fails during fulfillment.
+    /// @param gameId The ID of the game being fulfilled.
+    /// @param amount The amount that failed to pay out.
+    /// @param reason The revert reason bytes from the failed payout.
     event CommitmentPayoutFailed(uint256 indexed gameId, uint256 amount, bytes reason);
 
+    /// @notice Emitted when a split receives a portion of the game pot.
+    /// @param split The split that received funds.
+    /// @param amount The amount sent to the split.
+    /// @param caller The address that triggered the distribution.
     event DistributeToSplit(JBSplit split, uint256 amount, address caller);
 
+    /// @notice Emitted when a game's commitments have been fulfilled.
+    /// @param gameId The ID of the fulfilled game.
+    /// @param pot The total game pot that was fulfilled.
+    /// @param caller The address that triggered fulfillment.
     event FulfilledCommitments(uint256 indexed gameId, uint256 pot, address caller);
 
+    /// @notice Emitted when a new Defifa game is launched.
+    /// @param gameId The ID of the launched game.
+    /// @param hook The hook deployed for the game.
+    /// @param governor The governor responsible for scorecard ratification.
+    /// @param tokenUriResolver The token URI resolver used for the game's NFTs.
+    /// @param caller The address that launched the game.
     event LaunchGame(
         uint256 indexed gameId,
         IDefifaHook indexed hook,
@@ -27,10 +45,19 @@ interface IDefifaDeployer {
         address caller
     );
 
+    /// @notice Emitted when a game is queued into its no-contest phase.
+    /// @param gameId The ID of the game.
+    /// @param caller The address that queued the phase transition.
     event QueuedNoContest(uint256 indexed gameId, address caller);
 
+    /// @notice Emitted when a game is queued into its refund phase.
+    /// @param gameId The ID of the game.
+    /// @param caller The address that queued the phase transition.
     event QueuedRefundPhase(uint256 indexed gameId, address caller);
 
+    /// @notice Emitted when a game is queued into its scoring phase.
+    /// @param gameId The ID of the game.
+    /// @param caller The address that queued the phase transition.
     event QueuedScoringPhase(uint256 indexed gameId, address caller);
 
     /// @notice The fee divisor for base protocol fees (100 / fee percent).