@ballkidz/defifa 0.0.25 → 0.0.27

package/src/interfaces/IDefifaGamePotReporter.sol

@@ -1,8 +1,18 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice Reports the treasury pot size and commitment status of a Defifa game.
 interface IDefifaGamePotReporter {
+    /// @notice The total amount already distributed from a game's pot to commitment splits.
+    /// @param gameId The ID of the game.
+    /// @return The fulfilled commitment amount.
     function fulfilledCommitmentsOf(uint256 gameId) external view returns (uint256);
 
+    /// @notice The current pot size for a game, optionally including unfulfilled commitments.
+    /// @param gameId The ID of the game.
+    /// @param includeCommitments Whether to include unfulfilled commitment amounts.
+    /// @return pot The current pot amount.
+    /// @return token The token address.
+    /// @return decimals The token's decimal precision.
     function currentGamePotOf(uint256 gameId, bool includeCommitments) external view returns (uint256, address, uint256);
 }

package/src/interfaces/IDefifaGovernor.sol

@@ -123,6 +123,10 @@ interface IDefifaGovernor {
     /// @return The maximum attestation power tier.
     function MAX_ATTESTATION_POWER_TIER() external view returns (uint256);
 
+    /// @notice The minimum attestation grace period enforced during game initialization.
+    /// @return The minimum grace period in seconds.
+    function MIN_ATTESTATION_GRACE_PERIOD() external view returns (uint256);
+
     /// @notice The quorum required to ratify a scorecard.
     /// @param gameId The ID of the game.
     /// @return The quorum threshold.

package/src/interfaces/IDefifaHook.sol

@@ -70,6 +70,11 @@ interface IDefifaHook is IJB721Hook {
     /// @param caller The address that set the tier weights.
     event TierCashOutWeightsSet(DefifaTierCashOutWeight[] tierWeights, address caller);
 
+    /// @notice Returns the adjusted pending reserve count for a tier, subtracting refund-phase burns.
+    /// @param tierId The tier ID.
+    /// @return The adjusted pending reserve count.
+    function adjustedPendingReservesFor(uint256 tierId) external view returns (uint256);
+
     /// @notice The total amount redeemed from this game (refunds not counted).
     /// @return The total redeemed amount.
     function amountRedeemed() external view returns (uint256);

package/src/interfaces/IDefifaTokenUriResolver.sol

@@ -3,6 +3,9 @@ pragma solidity ^0.8.0;
 
 import {ITypeface} from "lib/typeface/contracts/interfaces/ITypeface.sol";
 
+/// @notice Resolves on-chain SVG token URIs for Defifa game NFTs using an on-chain typeface.
 interface IDefifaTokenUriResolver {
+    /// @notice The on-chain typeface contract used for rendering text in token SVGs.
+    /// @return The typeface contract.
     function TYPEFACE() external view returns (ITypeface);
 }

package/src/libraries/DefifaFontImporter.sol

@@ -3,7 +3,7 @@ pragma solidity 0.8.28;
 
 import {ITypeface, Font} from "lib/typeface/contracts/interfaces/ITypeface.sol";
 
-/// @notice Summon fonts.
+/// @notice Helpers for loading on-chain Capsules typeface font sources used in Defifa SVG rendering.
 library DefifaFontImporter {
     /// @notice Gets the Base64 encoded Capsules-500.otf typeface.
     /// @param typeface The typeface contract to query.

package/src/libraries/DefifaHookLib.sol

@@ -8,6 +8,7 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 import {mulDiv} from "@prb/math/src/Common.sol";
 
 import {DefifaGamePhase} from "../enums/DefifaGamePhase.sol";
+import {IDefifaHook} from "../interfaces/IDefifaHook.sol";
 import {DefifaTierCashOutWeight} from "../structs/DefifaTierCashOutWeight.sol";
 
 /// @notice Pure/view helper functions extracted from DefifaHook to reduce contract bytecode size.
@@ -65,6 +66,10 @@ library DefifaHookLib {
             // slither-disable-next-line calls-loop
             tier = hookStore.tierOf({hook: hook, id: tierWeights[i].id, includeResolvedUri: false});
 
+            // Guard against uint32 truncation: if the caller passes a tier ID > type(uint32).max,
+            // the store may silently truncate and return a different tier.
+            if (tierWeights[i].id != tier.id) revert DefifaHook_InvalidTierId();
+
             // Can't set a cashOut weight for tiers not in category 0.
             if (tier.category != 0) revert DefifaHook_InvalidTierId();
 
@@ -129,13 +134,9 @@ library DefifaHookLib {
         uint256 totalTokensForCashoutInTier =
             tier.initialSupply - tier.remainingSupply - (burnedTokens - tokensRedeemedFrom[tierId]);
 
-        // Include pending (unminted) reserve NFTs in the denominator. Without this, paid holders
-        // could cash out before reserves are minted and extract value that should be diluted across
-        // both paid and reserved holders. By counting pending reserves, each token's share of the
-        // tier weight is computed against the full eventual supply.
+        // Include pending (unminted) reserve NFTs in the denominator, adjusted for refund-phase burns.
         // slither-disable-next-line calls-loop
-        uint256 pendingReserves = hookStore.numberOfPendingReservesFor({hook: hook, tierId: tierId});
-        totalTokensForCashoutInTier += pendingReserves;
+        totalTokensForCashoutInTier += IDefifaHook(hook).adjustedPendingReservesFor(tierId);
 
         // Calculate the percentage of the tier cashOut amount a single token counts for.
         // Integer division rounding in cashOutWeight is unavoidable in Solidity. Rounding direction
@@ -210,8 +211,7 @@ library DefifaHookLib {
             // slither-disable-next-line calls-loop
             cumulativeMintPrice += hookStore.tierOfTokenId({
                 hook: hook, tokenId: tokenIds[i], includeResolvedUri: false
-            })
-            .price;
+            }).price;
         }
 
         // Calculate the user's claimable amount proportional to what they paid.
@@ -238,8 +238,7 @@ library DefifaHookLib {
             // slither-disable-next-line calls-loop
             cumulativeMintPrice += hookStore.tierOfTokenId({
                 hook: hook, tokenId: tokenIds[i], includeResolvedUri: false
-            })
-            .price;
+            }).price;
         }
     }
 

package/src/structs/DefifaAttestations.sol

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:param count A count of attestation weight.
-/// @custom:param attestedWeightOf The BWA weight each account attested with (0 = not attested).
+/// @notice Tracks cumulative attestation weight for a scorecard and which accounts have attested.
+/// @custom:member count The total attestation weight accumulated so far.
+/// @custom:member attestedWeightOf The voting weight each account attested with (0 = has not attested).
 struct DefifaAttestations {
     uint256 count;
     mapping(address => uint256) attestedWeightOf;

package/src/structs/DefifaDelegation.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice A delegation of a player's voting power for a specific tier to another address.
 /// @custom:member delegatee The account to delegate tier voting units to.
 /// @custom:member tierId The ID of the tier to delegate voting units for.
 struct DefifaDelegation {

package/src/structs/DefifaLaunchProjectData.sol

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-import {IJB721TiersHookStore} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "@bananapus/721-hook-v6/src/interfaces/IJB721TokenUriResolver.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
 import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
@@ -9,6 +8,8 @@ import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 
 import {DefifaTierParams} from "./DefifaTierParams.sol";
 
+/// @notice All parameters needed to launch a new Defifa game — the name, tiers, timing, splits, and governance
+/// configuration.
 /// @custom:member name The name of the game being created.
 /// @custom:member projectUri Metadata to associate with the project.
 /// @custom:member contractUri The URI to associate with the 721.
@@ -29,7 +30,6 @@ import {DefifaTierParams} from "./DefifaTierParams.sol";
 /// @custom:member defaultAttestationDelegate The address that'll be set as the attestation delegate by default.
 /// @custom:member defaultTokenUriResolver The contract used to resolve token URIs if not provided by a tier
 /// specifically. @custom:member terminal The payment terminal where the project will accept funds through.
-/// @custom:member store A contract to store standard JB721 data in.
 /// @custom:member minParticipation The minimum treasury balance required for the game to proceed to scoring. If the
 /// balance is below this when scoring would begin, the game enters NO_CONTEST. Set to 0 to disable. @custom:member
 /// scorecardTimeout The maximum time (in seconds) after the scoring phase begins for a scorecard to be ratified. If
@@ -51,7 +51,6 @@ struct DefifaLaunchProjectData {
     address defaultAttestationDelegate;
     IJB721TokenUriResolver defaultTokenUriResolver;
     IJBTerminal terminal;
-    IJB721TiersHookStore store;
     uint256 minParticipation;
     uint32 scorecardTimeout;
     uint256 timelockDuration;

package/src/structs/DefifaOpsData.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice Operational parameters stored for a deployed game — the token, timing, and contest rules.
 /// @custom:member token The token being used by the game.
 /// @custom:member start The time at which the game should start, measured in seconds.
 /// @custom:member mintPeriodDuration The duration of the game's mint phase, measured in seconds.

package/src/structs/DefifaScorecard.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice A submitted scorecard's governance state — when attestations begin, when the grace period ends, and the
+/// quorum threshold needed for ratification.
 /// @custom:member attestationsBegin The block at which attestations to the scorecard become allowed.
 /// @custom:member gracePeriodEnds The block at which the scorecard can become ratified.
 /// @custom:member quorumSnapshot The HHI-adjusted quorum threshold snapshotted at submission time.

package/src/structs/DefifaTierCashOutWeight.sol

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice A tier's share of the treasury pot after scoring. Tiers with higher weight let their NFT holders cash out
+/// for more of the treasury.
 /// @custom:member id The tier's ID.
-/// @custom:member cashOutWeight The weight that all tokens of this tier can be cashed out for.
+/// @custom:member cashOutWeight The cash-out weight assigned to this tier (relative to all other tiers' weights).
 struct DefifaTierCashOutWeight {
     uint256 id;
     uint256 cashOutWeight;

package/src/structs/DefifaTierParams.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice Parameters for creating a tier (outcome) in a Defifa game.
 /// @custom:member name The name of the tier.
 /// @custom:member reservedRate The number of minted tokens needed in the tier to allow for minting another reserved
 /// token. @custom:member reservedRateBeneficiary The beneficiary of the reserved tokens for this tier.