@ballkidz/defifa 0.0.25 → 0.0.27

package/src/DefifaGovernor.sol

@@ -20,7 +20,10 @@ 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.
+/// @notice Manages the ratification of Defifa scorecards through token-weighted attestation. After a game ends,
+/// anyone can submit a scorecard proposing cash-out weights for each tier. NFT holders attest to scorecards using
+/// their voting power (proportional to NFTs held). A scorecard is ratified once it reaches quorum and survives the
+/// grace period, after which the deployer applies the weights to the game's treasury.
 contract DefifaGovernor is Ownable, IDefifaGovernor {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -31,6 +34,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     error DefifaGovernor_AlreadyRatified();
     error DefifaGovernor_DuplicateScorecard();
     error DefifaGovernor_GameNotFound();
+    error DefifaGovernor_GracePeriodTooShort();
     error DefifaGovernor_IncorrectTierOrder();
     error DefifaGovernor_NotAllowed();
     error DefifaGovernor_NotAttested();
@@ -45,6 +49,9 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     /// @notice The max attestation power each tier has if every token within the tier attestations.
     uint256 public constant override MAX_ATTESTATION_POWER_TIER = 1_000_000_000;
 
+    /// @notice The minimum attestation grace period enforced during game initialization.
+    uint256 public constant override MIN_ATTESTATION_GRACE_PERIOD = 1 days;
+
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
     //*********************************************************************//
@@ -104,6 +111,12 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     /// @custom:param tierId The tier ID (0-indexed).
     mapping(uint256 => mapping(uint256 => mapping(uint256 => uint256))) internal _scorecardTierWeightsOf;
 
+    /// @notice The timestamp when quorum was first reached for a scorecard.
+    /// @dev Reset to 0 if attestations drop below quorum via revocation.
+    /// @custom:param gameId The ID of the game.
+    /// @custom:param scorecardId The ID of the scorecard.
+    mapping(uint256 => mapping(uint256 => uint48)) internal _quorumReachedAtOf;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -164,6 +177,11 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         // Increase the attestation count.
         attestations.count += weight;
 
+        // Record when quorum is first reached so the timelock anchors to this moment.
+        if (_quorumReachedAtOf[gameId][scorecardId] == 0 && attestations.count >= scorecard.quorumSnapshot) {
+            _quorumReachedAtOf[gameId][scorecardId] = uint48(block.timestamp);
+        }
+
         // Store the BWA weight that was added (used for accurate subtraction on revoke).
         attestations.attestedWeightOf[msg.sender] = weight;
 
@@ -237,6 +255,12 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         attestations.count -= weight;
         attestations.attestedWeightOf[msg.sender] = 0;
 
+        // Reset quorum timestamp if attestations drop below quorum.
+        DefifaScorecard storage scorecard = _scorecardOf[gameId][scorecardId];
+        if (attestations.count < scorecard.quorumSnapshot) {
+            _quorumReachedAtOf[gameId][scorecardId] = 0;
+        }
+
         emit AttestationRevoked(gameId, scorecardId, msg.sender, weight);
     }
 
@@ -302,17 +326,24 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         if (scorecard.attestationsBegin != 0) revert DefifaGovernor_DuplicateScorecard();
 
         uint256 attestationStartTime = attestationStartTimeOf(gameId);
+
+        // Game phase timing is timestamp-based by design.
+        uint256 currentTimestamp = block.timestamp;
         uint256 timeUntilAttestationsBegin =
-            block.timestamp > attestationStartTime ? 0 : attestationStartTime - block.timestamp;
+            currentTimestamp > attestationStartTime ? 0 : attestationStartTime - currentTimestamp;
 
         // Casting to uint48 is safe because block.timestamp fits in uint48 until year 8921556.
         // forge-lint: disable-next-line(unsafe-typecast)
-        uint48 attestationsBegin = uint48(block.timestamp + timeUntilAttestationsBegin);
+        uint48 attestationsBegin = uint48(currentTimestamp + timeUntilAttestationsBegin);
         scorecard.attestationsBegin = attestationsBegin;
         // Grace period extends from when attestations begin, not from submission time.
         // This prevents the grace period from expiring before attestations even start
         // when a scorecard is submitted early.
-        scorecard.gracePeriodEnds = uint48(attestationsBegin + attestationGracePeriodOf(gameId));
+        uint256 gracePeriodEnds = uint256(attestationsBegin) + attestationGracePeriodOf(gameId);
+        if (gracePeriodEnds > type(uint48).max) revert DefifaGovernor_Uint48Overflow();
+        // Safe after the explicit max check above.
+        // forge-lint: disable-next-line(unsafe-typecast)
+        scorecard.gracePeriodEnds = uint48(gracePeriodEnds);
 
         // Store tier weights for BWA computation.
         for (uint256 i; i < numberOfTierWeights;) {
@@ -335,9 +366,9 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
                 // slither-disable-next-line calls-loop
                 JB721Tier memory tier =
                     hookStore.tierOf({hook: metadata.dataHook, id: tierId, includeResolvedUri: false});
+                // Use adjusted pending reserves that account for refund-phase burns.
                 // slither-disable-next-line calls-loop
-                uint256 pendingReserves =
-                    hookStore.numberOfPendingReservesFor({hook: metadata.dataHook, tierId: tierId});
+                uint256 pendingReserves = IDefifaHook(metadata.dataHook).adjustedPendingReservesFor(tierId);
                 // slither-disable-next-line calls-loop
                 uint256 submittedTierAttestationUnits =
                     IDefifaHook(metadata.dataHook).currentSupplyOfTier(tierId) * tier.votingUnits;
@@ -457,8 +488,8 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         // Set a default attestation start time if needed.
         if (attestationStartTime == 0) attestationStartTime = block.timestamp;
 
-        // Enforce a minimum grace period of 1 day to prevent instant ratification.
-        if (attestationGracePeriod < 1 days) attestationGracePeriod = 1 days;
+        // Enforce a minimum grace period to prevent instant ratification.
+        if (attestationGracePeriod < MIN_ATTESTATION_GRACE_PERIOD) revert DefifaGovernor_GracePeriodTooShort();
 
         // Ensure values fit within their allocated 48-bit widths before packing.
         if (attestationStartTime > type(uint48).max) revert DefifaGovernor_Uint48Overflow();
@@ -554,8 +585,9 @@ 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.
             {
+                // Use adjusted pending reserves that account for refund-phase burns.
                 // slither-disable-next-line calls-loop
-                uint256 pendingReserves = store.numberOfPendingReservesFor({hook: metadata.dataHook, tierId: tierId});
+                uint256 pendingReserves = IDefifaHook(metadata.dataHook).adjustedPendingReservesFor(tierId);
                 if (pendingReserves != 0) {
                     // slither-disable-next-line calls-loop
                     JB721Tier memory tier =
@@ -700,8 +732,9 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
             // burner erase another participant's quorum contribution without erasing their claim.
             // slither-disable-next-line calls-loop
             uint256 currentTierSupply = hook.currentSupplyOfTier(tierId);
+            // Use adjusted pending reserves that account for refund-phase burns.
             // slither-disable-next-line calls-loop
-            uint256 pendingReserves = store.numberOfPendingReservesFor({hook: metadata.dataHook, tierId: tierId});
+            uint256 pendingReserves = hook.adjustedPendingReservesFor(tierId);
             if (currentTierSupply != 0 || pendingReserves != 0) {
                 eligibleTierWeights += MAX_ATTESTATION_POWER_TIER;
             }
@@ -744,12 +777,16 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
 
         // If the scorecard has attestations beginning in the future, the state is PENDING.
         // At exactly `attestationsBegin`, attestations are open so the state is ACTIVE.
+        // Game phase timing is timestamp-based by design.
+        // forge-lint: disable-next-line(block-timestamp)
         if (scorecard.attestationsBegin > block.timestamp) {
             return DefifaScorecardState.PENDING;
         }
 
         // If the scorecard's grace period has not yet ended, the state is ACTIVE.
         // At exactly `gracePeriodEnds`, the grace period has elapsed so we fall through to the quorum check.
+        // Game phase timing is timestamp-based by design.
+        // forge-lint: disable-next-line(block-timestamp)
         if (scorecard.gracePeriodEnds > block.timestamp) {
             return DefifaScorecardState.ACTIVE;
         }
@@ -757,8 +794,16 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         // If quorum has been reached (using the concentration-adjusted snapshot), check timelock.
         if (scorecard.quorumSnapshot <= _scorecardAttestationsOf[gameId][scorecardId].count) {
             uint256 timelockDur = timelockDurationOf(gameId);
-            if (timelockDur > 0 && block.timestamp < uint256(scorecard.gracePeriodEnds) + timelockDur) {
-                return DefifaScorecardState.QUEUED;
+            if (timelockDur > 0) {
+                // Anchor the timelock to the later of grace period end or when quorum was reached.
+                uint256 quorumReachedAt = _quorumReachedAtOf[gameId][scorecardId];
+                uint256 timelockAnchor =
+                    quorumReachedAt > scorecard.gracePeriodEnds ? quorumReachedAt : uint256(scorecard.gracePeriodEnds);
+                // Game phase timing is timestamp-based by design.
+                // forge-lint: disable-next-line(block-timestamp)
+                if (block.timestamp < timelockAnchor + timelockDur) {
+                    return DefifaScorecardState.QUEUED;
+                }
             }
             return DefifaScorecardState.SUCCEEDED;
         }

package/src/DefifaHook.sol

@@ -36,7 +36,10 @@ import {DefifaTierCashOutWeight} from "./structs/DefifaTierCashOutWeight.sol";
 import {DefifaGamePhase} from "./enums/DefifaGamePhase.sol";
 import {DefifaHookLib} from "./libraries/DefifaHookLib.sol";
 
-/// @notice A hook that transforms Juicebox treasury interactions into a Defifa game.
+/// @notice The 721 hook that powers Defifa games. Extends JB721Hook to enforce game phase rules on minting and
+/// cashing out, track per-tier voting power via checkpoints, and apply scorecard-determined cash-out weights after
+/// ratification. Mints are only allowed during the MINT phase, refunds during the REFUND phase, and cash outs
+/// with scoring weights only after a scorecard is ratified in the COMPLETE phase.
 contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     using Checkpoints for Checkpoints.Trace208;
 
@@ -45,6 +48,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     //*********************************************************************//
 
     error DefifaHook_BadTierOrder();
+    error DefifaHook_IdenticalTokens();
     error DefifaHook_DelegateAddressZero();
     error DefifaHook_DelegateChangesUnavailableInThisPhase();
     error DefifaHook_GameIsntScoringYet();
@@ -116,14 +120,23 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
+    /// @notice The amount that has been redeemed from this game, refunds are not counted.
+    uint256 public override amountRedeemed;
+
+    /// @notice The common base for the tokenUri's
+    string public override baseURI;
+
+    /// @notice A flag indicating if the cashout weights has been set.
+    bool public override cashOutWeightIsSet;
+
     /// @notice The address of the origin 'DefifaHook', used to check in the init if the contract is the original or not
     address public immutable override CODE_ORIGIN;
 
-    /// @notice The contract that stores and manages the NFT's data.
-    IJB721TiersHookStore public override store;
+    /// @notice Contract metadata uri.
+    string public override contractURI;
 
-    /// @notice The contract storing all funding cycle configurations.
-    IJBRulesets public override rulesets;
+    /// @notice The address that'll be set as the attestation delegate by default.
+    address public override defaultAttestationDelegate;
 
     /// @notice The contract reporting game phases.
     IDefifaGamePhaseReporter public override gamePhaseReporter;
@@ -138,20 +151,16 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// @notice The currency that is accepted when minting tier NFTs.
     uint256 public override pricingCurrency;
 
-    /// @notice A flag indicating if the cashout weights has been set.
-    bool public override cashOutWeightIsSet;
-
-    /// @notice The common base for the tokenUri's
-    string public override baseURI;
-
-    /// @notice Contract metadata uri.
-    string public override contractURI;
+    /// @notice The number of tokens burned from a tier during non-COMPLETE phases (refund, no-contest).
+    /// @dev Used to adjust pending reserve counts so reserves that correspond to refunded mints
+    /// are excluded from the cash-out denominator.
+    mapping(uint256 => uint256) public refundedBurnsFrom;
 
-    /// @notice The address that'll be set as the attestation delegate by default.
-    address public override defaultAttestationDelegate;
+    /// @notice The contract storing all funding cycle configurations.
+    IJBRulesets public override rulesets;
 
-    /// @notice The amount that has been redeemed from this game, refunds are not counted.
-    uint256 public override amountRedeemed;
+    /// @notice The contract that stores and manages the NFT's data.
+    IJB721TiersHookStore public override store;
 
     /// @notice The amount of tokens that have been redeemed from a tier, refunds are not counted.
     /// @custom:param The tier from which tokens have been redeemed.
@@ -161,6 +170,41 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
+    /// @notice Returns the adjusted pending reserve count for a tier, accounting for refund-phase burns.
+    /// @dev Recalculates reserves from (paidMints - burns) / reserveFrequency since the relationship
+    /// between burns and reserves is not linear — it depends on the tier's reserve frequency.
+    /// @param tierId The tier ID.
+    /// @return The adjusted pending reserve count (floored at 0).
+    // slither-disable-next-line calls-loop
+    function adjustedPendingReservesFor(uint256 tierId) public view returns (uint256) {
+        uint256 refundBurns = refundedBurnsFrom[tierId];
+
+        // If no refund burns, return the store's value directly.
+        if (refundBurns == 0) return store.numberOfPendingReservesFor({hook: address(this), tierId: tierId});
+
+        // Get the tier to access reserveFrequency and supply data.
+        JB721Tier memory tier = store.tierOf({hook: address(this), id: tierId, includeResolvedUri: false});
+
+        // No reserves if no reserve frequency.
+        if (tier.reserveFrequency == 0) return 0;
+
+        // Calculate the number of reserves already minted.
+        uint256 reservesMinted = store.numberOfReservesMintedFor({hook: address(this), tierId: tierId});
+
+        // Calculate non-reserve mints: initialSupply - remainingSupply - reservesMinted.
+        uint256 nonReserveMints = tier.initialSupply - tier.remainingSupply - reservesMinted;
+
+        // Subtract refund burns from non-reserve mints (burns can't exceed non-reserve mints).
+        uint256 adjustedMints = nonReserveMints > refundBurns ? nonReserveMints - refundBurns : 0;
+
+        // Recalculate available reserves: ceil(adjustedMints / reserveFrequency).
+        uint256 availableReserves = adjustedMints / tier.reserveFrequency;
+        if (adjustedMints % tier.reserveFrequency > 0) ++availableReserves;
+
+        // Return pending = available - already minted (floored at 0).
+        return availableReserves > reservesMinted ? availableReserves - reservesMinted : 0;
+    }
+
     /// @notice The first owner of each token ID, which corresponds to the address that originally contributed to the
     /// project to receive the NFT.
     /// @param tokenId The ID of the token to get the first owner of.
@@ -304,8 +348,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
                     // slither-disable-next-line calls-loop
                     cumulativeMintPrice -= hookStore.tierOfTokenId({
                         hook: address(this), tokenId: decodedTokenIds[i], includeResolvedUri: false
-                    })
-                    .price;
+                    }).price;
                 }
 
                 unchecked {
@@ -418,12 +461,15 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         // If the game isn't complete, we do not have any tokens to claim.
         if (gamePhaseReporter.currentGamePhaseOf(PROJECT_ID) != DefifaGamePhase.COMPLETE) return (0, 0);
 
+        // Include unminted reserves in the denominator. Once reserves are pending, their future recipients are
+        // entitled to fee-token claims as if the reserve NFTs had already been minted; otherwise paid holders could
+        // claim too large a share before the reserve mint transaction lands.
         // slither-disable-next-line unused-return
         return DefifaHookLib.computeTokensClaim({
             tokenIds: tokenIds,
             hookStore: store,
             hook: address(this),
-            totalMintCost: _totalMintCost,
+            totalMintCost: _totalMintCost + _pendingReserveMintCost(),
             defifaBalance: DEFIFA_TOKEN.balanceOf(address(this)),
             baseProtocolBalance: BASE_PROTOCOL_TOKEN.balanceOf(address(this))
         });
@@ -449,6 +495,8 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         JB721Hook(_directory)
         Ownable(msg.sender)
     {
+        if (address(_defifaToken) == address(_baseProtocolToken)) revert DefifaHook_IdenticalTokens();
+
         CODE_ORIGIN = address(this);
         DEFIFA_TOKEN = _defifaToken;
         BASE_PROTOCOL_TOKEN = _baseProtocolToken;
@@ -574,6 +622,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// @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-benign,reentrancy-no-eth
     function mintReservesFor(uint256 tierId, uint256 count) public override {
         // Minting reserves must not be paused.
         // slither-disable-next-line calls-loop
@@ -703,13 +752,20 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             }
 
             // Burn the token.
+            // slither-disable-next-line reentrancy-no-eth
             _burn(tokenId);
 
-            // Track per-tier redemptions during the complete phase.
+            // slither-disable-next-line calls-loop
+            uint256 tierId = hookStore.tierIdOfToken(tokenId);
             if (isComplete) {
+                // Track per-tier redemptions during the complete phase.
+                unchecked {
+                    ++tokensRedeemedFrom[tierId];
+                }
+            } else {
+                // Track non-COMPLETE burns (refund/no-contest) so pending reserve counts can be adjusted.
                 unchecked {
-                    // slither-disable-next-line reentrancy-no-eth,calls-loop
-                    ++tokensRedeemedFrom[hookStore.tierIdOfToken(tokenId)];
+                    ++refundedBurnsFrom[tierId];
                 }
             }
 
@@ -735,7 +791,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
             // are accounted for, preventing paid holders from claiming a disproportionate share.
             // slither-disable-next-line reentrancy-events
             beneficiaryReceivedTokens = _claimTokensFor({
-                beneficiary: context.holder,
+                beneficiary: context.beneficiary,
                 shareToBeneficiary: cumulativeMintPrice,
                 outOfTotal: _totalMintCost + _pendingReserveMintCost()
             });
@@ -854,11 +910,12 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
 
         for (uint256 i; i < numberOfTiers;) {
             uint256 tierId = i + 1;
-            // slither-disable-next-line calls-loop
-            uint256 pendingReserves = hookStore.numberOfPendingReservesFor({hook: address(this), tierId: tierId});
+            uint256 pendingReserves = adjustedPendingReservesFor(tierId);
             if (pendingReserves != 0) {
                 // slither-disable-next-line calls-loop
                 JB721Tier memory tier = hookStore.tierOf({hook: address(this), id: tierId, includeResolvedUri: false});
+
+                // Pending reserves dilute claims by the same economic weight as paid mints at this tier's price.
                 cost += pendingReserves * tier.price;
             }
             unchecked {

package/src/DefifaProjectOwner.sol

@@ -8,9 +8,10 @@ import {IERC721Receiver} from "@openzeppelin/contracts/token/ERC721/IERC721Recei
 
 import {DefifaDeployer} from "./DefifaDeployer.sol";
 
-/// @notice A contract that can be sent a project to be burned, while still allowing defifa permissions.
-/// @dev Once the project NFT is transferred here, it cannot be recovered. This contract permanently
-/// holds the project NFT and grants SET_SPLIT_GROUPS permission to the Defifa deployer.
+/// @notice A dead-end owner for Defifa project NFTs. When the project NFT is transferred here, this contract
+/// permanently holds it and grants SET_SPLIT_GROUPS permission to the Defifa deployer — allowing the deployer to
+/// manage splits without any human having project ownership.
+/// @dev Once the project NFT is transferred here, it cannot be recovered.
 contract DefifaProjectOwner is IERC721Receiver {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //

package/src/DefifaTokenUriResolver.sol

@@ -19,7 +19,8 @@ import {DefifaGamePhase} from "./enums/DefifaGamePhase.sol";
 import {IDefifaHook} from "./interfaces/IDefifaHook.sol";
 import {IDefifaTokenUriResolver} from "./interfaces/IDefifaTokenUriResolver.sol";
 
-/// @notice Standard Token URIs for Defifa games.
+/// @notice Generates on-chain SVG token URIs for Defifa game NFTs. Each NFT image shows the tier name, game phase,
+/// and current cash-out value. Uses an on-chain typeface for rendering text within the SVG.
 contract DefifaTokenUriResolver is IDefifaTokenUriResolver, IJB721TokenUriResolver {
     using Strings for uint256;
 
@@ -70,12 +71,13 @@ contract DefifaTokenUriResolver is IDefifaTokenUriResolver, IJB721TokenUriResolv
         // Keep a reference to the rarity text;
         string memory valueText;
 
-        // Keep a reference to the game's name.
+        // Keep a reference to the game's name (escaped for JSON/SVG safety).
         // TODO: Somehow make the `IDefifaHook` have the `name` function.
-        string memory title = ERC721(address(hook)).name();
+        string memory titleSvg = _escapeSvg(ERC721(address(hook)).name());
 
         // Keep a reference to the tier's name.
-        string memory team;
+        string memory teamJson;
+        string memory teamSvg;
 
         // Keep a reference to the SVG parts.
         string[] memory parts = new string[](4);
@@ -88,8 +90,10 @@ contract DefifaTokenUriResolver is IDefifaTokenUriResolver, IJB721TokenUriResolv
             JB721Tier memory tier =
                 hook.store().tierOfTokenId({hook: address(hook), tokenId: tokenId, includeResolvedUri: false});
 
-            // Set the tier's name.
-            team = hook.tierNameOf(tier.id);
+            // Set the tier's name (escaped for JSON/SVG safety).
+            string memory rawTeam = hook.tierNameOf(tier.id);
+            teamJson = _escapeJson(rawTeam);
+            teamSvg = _escapeSvg(rawTeam);
 
             // Check to see if the tier has a URI. Return it if it does.
             if (tier.encodedIPFSUri != bytes32(0)) {
@@ -101,11 +105,11 @@ contract DefifaTokenUriResolver is IDefifaTokenUriResolver, IJB721TokenUriResolv
             parts[1] = string(
                 abi.encodePacked(
                     '{"name":"',
-                    team,
+                    teamJson,
                     '", "id": "',
                     uint256(tier.id).toString(),
                     '","description":"Team: ',
-                    team,
+                    teamJson,
                     ", ID: ",
                     uint256(tier.id).toString(),
                     '.","image":"data:image/svg+xml;base64,'
@@ -201,27 +205,27 @@ contract DefifaTokenUriResolver is IDefifaTokenUriResolver, IJB721TokenUriResolv
                 gamePhaseText,
                 "</text>",
                 '<text x="10" y="85" style="font-size:26px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">',
-                _getSubstring(title, 0, 30),
+                _getSubstring(titleSvg, 0, 30),
                 "</text>",
                 '<text x="10" y="120" style="font-size:26px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">',
-                _getSubstring(title, 30, 60),
+                _getSubstring(titleSvg, 30, 60),
                 "</text>",
                 '<text x="10" y="205" style="font-size:80px; font-family: Capsules-700; font-weight:700; fill: #fea282;">',
-                bytes(_getSubstring(team, 20, 30)).length != 0 && bytes(_getSubstring(team, 10, 20)).length != 0
-                    ? _getSubstring(team, 0, 10)
+                bytes(_getSubstring(teamSvg, 20, 30)).length != 0 && bytes(_getSubstring(teamSvg, 10, 20)).length != 0
+                    ? _getSubstring(teamSvg, 0, 10)
                     : "",
                 "</text>",
                 '<text x="10" y="295" style="font-size:80px; font-family: Capsules-700; font-weight:700; fill: #fea282;">',
-                bytes(_getSubstring(team, 20, 30)).length != 0
-                    ? _getSubstring(team, 10, 20)
-                    : bytes(_getSubstring(team, 10, 20)).length != 0 ? _getSubstring(team, 0, 10) : "",
+                bytes(_getSubstring(teamSvg, 20, 30)).length != 0
+                    ? _getSubstring(teamSvg, 10, 20)
+                    : bytes(_getSubstring(teamSvg, 10, 20)).length != 0 ? _getSubstring(teamSvg, 0, 10) : "",
                 "</text>",
                 '<text x="10" y="385" style="font-size:80px; font-family: Capsules-700; font-weight:700; fill: #fea282;">',
-                bytes(_getSubstring(team, 20, 30)).length != 0
-                    ? _getSubstring(team, 20, 30)
-                    : bytes(_getSubstring(team, 10, 20)).length != 0
-                        ? _getSubstring(team, 10, 20)
-                        : _getSubstring(team, 0, 10),
+                bytes(_getSubstring(teamSvg, 20, 30)).length != 0
+                    ? _getSubstring(teamSvg, 20, 30)
+                    : bytes(_getSubstring(teamSvg, 10, 20)).length != 0
+                        ? _getSubstring(teamSvg, 10, 20)
+                        : _getSubstring(teamSvg, 0, 10),
                 "</text>",
                 '<text x="10" y="430" style="font-size:16px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">TOKEN ID: ',
                 tokenId.toString(),
@@ -312,4 +316,93 @@ contract DefifaTokenUriResolver is IDefifaTokenUriResolver, IJB721TokenUriResolv
         }
         return string(result);
     }
+
+    /// @notice Escapes special characters for safe JSON string interpolation.
+    /// @param input The raw string.
+    /// @return The escaped string.
+    function _escapeJson(string memory input) internal pure returns (string memory) {
+        bytes memory b = bytes(input);
+        // Worst case: every char needs escaping (2x length).
+        bytes memory out = new bytes(b.length * 2);
+        uint256 j;
+        for (uint256 i; i < b.length;) {
+            bytes1 c = b[i];
+            if (c == '"' || c == "\\") {
+                out[j++] = "\\";
+                out[j++] = c;
+            } else if (c == 0x0a) {
+                // newline
+                out[j++] = "\\";
+                out[j++] = "n";
+            } else if (c == 0x0d) {
+                // carriage return
+                out[j++] = "\\";
+                out[j++] = "r";
+            } else {
+                out[j++] = c;
+            }
+            unchecked {
+                ++i;
+            }
+        }
+        // Trim to actual length.
+        bytes memory trimmed = new bytes(j);
+        for (uint256 k; k < j;) {
+            trimmed[k] = out[k];
+            unchecked {
+                ++k;
+            }
+        }
+        return string(trimmed);
+    }
+
+    /// @notice Escapes special characters for safe SVG text interpolation.
+    /// @param input The raw string.
+    /// @return The escaped string.
+    function _escapeSvg(string memory input) internal pure returns (string memory) {
+        bytes memory b = bytes(input);
+        // Worst case: each char becomes 5 chars (&amp;).
+        bytes memory out = new bytes(b.length * 5);
+        uint256 j;
+        for (uint256 i; i < b.length;) {
+            bytes1 c = b[i];
+            if (c == "&") {
+                out[j++] = "&";
+                out[j++] = "a";
+                out[j++] = "m";
+                out[j++] = "p";
+                out[j++] = ";";
+            } else if (c == "<") {
+                out[j++] = "&";
+                out[j++] = "l";
+                out[j++] = "t";
+                out[j++] = ";";
+            } else if (c == ">") {
+                out[j++] = "&";
+                out[j++] = "g";
+                out[j++] = "t";
+                out[j++] = ";";
+            } else if (c == '"') {
+                out[j++] = "&";
+                out[j++] = "q";
+                out[j++] = "u";
+                out[j++] = "o";
+                out[j++] = "t";
+                out[j++] = ";";
+            } else {
+                out[j++] = c;
+            }
+            unchecked {
+                ++i;
+            }
+        }
+        bytes memory trimmed = new bytes(j);
+        for (uint256 k; k < j;) {
+            trimmed[k] = out[k];
+            unchecked {
+                ++k;
+            }
+        }
+        return string(trimmed);
+    }
 }

package/src/enums/DefifaGamePhase.sol

@@ -1,6 +1,12 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice The lifecycle phases of a Defifa game.
+/// COUNTDOWN — before minting opens. MINT — players can mint tier NFTs. REFUND — minting closed but refunds
+/// allowed.
+/// SCORING — event has ended, scorecards can be submitted and attested. COMPLETE — scorecard ratified, cash outs
+/// open.
+/// NO_CONTEST — game voided (minimum participation not met or scorecard timed out), full refunds available.
 enum DefifaGamePhase {
     COUNTDOWN,
     MINT,

package/src/enums/DefifaScorecardState.sol

@@ -1,6 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice The governance lifecycle of a submitted scorecard.
+/// PENDING — submitted but attestation period hasn't started. ACTIVE — accepting attestations.
+/// DEFEATED — failed to reach quorum. SUCCEEDED — reached quorum, in grace period.
+/// QUEUED — grace period passed, awaiting application. RATIFIED — applied to the game's cash-out weights.
 enum DefifaScorecardState {
     PENDING,
     ACTIVE,

package/src/interfaces/IDefifaDeployer.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.0;
 
 import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
+import {IJB721TiersHookStore} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHookStore.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";
@@ -88,6 +89,10 @@ interface IDefifaDeployer {
     /// @return The code origin address.
     function HOOK_CODE_ORIGIN() external view returns (address);
 
+    /// @notice The 721 tiers hook store used by all games.
+    /// @return The hook store contract.
+    function HOOK_STORE() external view returns (IJB721TiersHookStore);
+
     /// @notice The address registry used for content-addressable deployment lookups.
     /// @return The address registry contract.
     function REGISTRY() external view returns (IJBAddressRegistry);

package/src/interfaces/IDefifaGamePhaseReporter.sol

@@ -3,6 +3,10 @@ pragma solidity ^0.8.0;
 
 import {DefifaGamePhase} from "../enums/DefifaGamePhase.sol";
 
+/// @notice Reports the current lifecycle phase of a Defifa game.
 interface IDefifaGamePhaseReporter {
+    /// @notice The current phase of a game (COUNTDOWN, MINT, REFUND, SCORING, COMPLETE, or NO_CONTEST).
+    /// @param gameId The ID of the game.
+    /// @return The current game phase.
     function currentGamePhaseOf(uint256 gameId) external view returns (DefifaGamePhase);
 }