@ballkidz/defifa 0.0.26 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "license": "MIT",
   "engines": {
     "node": "25.9.0"

package/src/DefifaDeployer.sol

@@ -41,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;
@@ -95,13 +99,13 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @notice The default Defifa token URI resolver.
     IJB721TokenUriResolver public immutable override TOKEN_URI_RESOLVER;
 
-    /// @notice The Defifa governor.
+    /// @notice The governance contract that ratifies scorecards for each game.
     IDefifaGovernor public immutable override GOVERNOR;
 
     /// @notice The controller with which new projects should be deployed.
     IJBController public immutable override CONTROLLER;
 
-    /// @notice The hooks registry.
+    /// @notice The Juicebox 721 tiers hook registry used to register deployed games.
     IJBAddressRegistry public immutable REGISTRY;
 
     /// @notice The 721 tiers hook store used by all games.
@@ -137,7 +141,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice The current pot the game is being played with.
+    /// @notice The current pot the game is played with.
     /// @param gameId The ID of the game for which the pot applies.
     /// @param includeCommitments A flag indicating if the portion of the pot committed to fulfill preprogrammed
     /// obligations should be included.
@@ -199,7 +203,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         return (ops.minParticipation, ops.scorecardTimeout);
     }
 
-    /// @notice The game times.
+    /// @notice Get the countdown, minting, and refund deadline timestamps for a game.
     /// @param gameId The ID of the game for which the game times apply.
     /// @return The game's start time, as a unix timestamp.
     /// @return The game's minting period duration, in seconds.
@@ -209,7 +213,7 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         return (ops.start, ops.mintPeriodDuration, ops.refundPeriodDuration);
     }
 
-    /// @notice The token of a game.
+    /// @notice Get the ERC-20 token address associated with a given game.
     /// @param gameId The ID of the game to get the token of.
     /// @return The game's token.
     function tokenOf(uint256 gameId) external view override returns (address) {

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 ------------------------- //
@@ -126,7 +129,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Attests to a scorecard.
+    /// @notice Cast an attestation supporting a proposed scorecard, weighted by the caller's tier voting power.
     /// @param gameId The ID of the game to which the scorecard belongs.
     /// @param scorecardId The scorecard ID.
     /// @return weight The attestation weight that was applied.
@@ -443,7 +446,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     }
 
     /// @notice The ID of a scorecard representing the provided tier weights.
-    /// @param gameHook The address where the game is being played.
+    /// @param gameHook The address where the game is played.
     /// @param tierWeights The weights of each tier in the scorecard.
     function scorecardIdOf(
         address gameHook,
@@ -462,10 +465,10 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     // ----------------------- public transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Initializes a game.
+    /// @notice Initialize governance for a newly deployed game, setting the initial block number for vote accounting.
     /// @param gameId The ID of the game.
-    /// @param attestationStartTime The amount of time between a scorecard being submitted and attestations to it being
-    /// enabled, measured in seconds.
+    /// @param attestationStartTime The amount of time between a scorecard submission and attestations becoming enabled,
+    /// measured in seconds.
     /// @param attestationGracePeriod The amount of time that must go by before a scorecard can be ratified.
     /// @param timelockDuration The cooling period after quorum is met before a scorecard can be ratified.
     function initializeGame(
@@ -520,9 +523,8 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         return uint256(uint48(_packedScorecardInfoOf[gameId] >> 48));
     }
 
-    /// @notice The amount of time between a scorecard being submitted and attestations to it being enabled, measured in
-    /// seconds.
-    /// @dev This can be increased to leave time for users to acquire attestation power, or delegate it, before
+    /// @notice The amount of time between a scorecard submission and attestations becoming enabled, measured in
+    /// seconds. @dev This can be increased to leave time for users to acquire attestation power, or delegate it, before
     /// a scorecard becomes live.
     /// @param gameId The ID of the game to get the attestation delay of.
     /// @return The delay, in seconds.
@@ -538,7 +540,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     /// MAX_ATTESTATION_POWER_TIER; a holder of 1-of-100 gets MAX_ATTESTATION_POWER_TIER / 100.
     /// This ensures each game outcome (tier) has equal governance weight — the scorecard reflects
     /// consensus across outcomes, not dominance by whichever outcome sold the most tokens.
-    /// @param gameId The ID of the game for which attestations are being counted.
+    /// @param gameId The ID of the game to count attestations for.
     /// @param account The account to get attestations for.
     /// @param timestamp The timestamp to measure attestations from.
     /// @return attestationPower The amount of attestation power of an account.
@@ -745,7 +747,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         return eligibleTierWeights / 2;
     }
 
-    /// @notice The state of a proposal.
+    /// @notice Get the current governance state (pending, active, defeated, succeeded) of a scorecard proposal.
     /// @param gameId The ID of the game to get a proposal state of.
     /// @param scorecardId The ID of the proposal to get the state of.
     /// @return The state.
@@ -836,7 +838,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     }
 
     /// @notice A value representing the contents of a scorecard.
-    /// @param gameHook The address where the game is being played.
+    /// @param gameHook The address where the game is played.
     /// @param calldataBytes The calldata that will be sent if the scorecard is ratified.
     function _hashScorecardOf(address gameHook, bytes memory calldataBytes) internal pure virtual returns (uint256) {
         return uint256(keccak256(abi.encode(gameHook, calldataBytes)));

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;
 
@@ -79,16 +82,16 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
 
     /// @notice The delegation status for each address and for each tier.
     /// _delegator The delegator.
-    /// _tierId The ID of the tier being delegated.
+    /// _tierId The ID of the tier to delegate.
     mapping(address => mapping(uint256 => address)) internal _tierDelegation;
 
     /// @notice The delegation checkpoints for each address and for each tier.
     /// _delegator The delegator.
-    /// _tierId The ID of the tier being checked.
+    /// _tierId The ID of the tier to check.
     mapping(address => mapping(uint256 => Checkpoints.Trace208)) internal _delegateTierCheckpoints;
 
     /// @notice The total delegation status for each tier.
-    /// _tierId The ID of the tier being checked.
+    /// _tierId The ID of the tier to check.
     mapping(uint256 => Checkpoints.Trace208) internal _totalTierCheckpoints;
 
     /// @notice The first owner of each token ID, stored on first transfer out.
@@ -129,7 +132,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// @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 Contract metadata uri.
+    /// @notice The contract-level metadata URI used by marketplaces to display collection information.
     string public override contractURI;
 
     /// @notice The address that'll be set as the attestation delegate by default.
@@ -849,7 +852,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         emit TierCashOutWeightsSet(tierWeights, msg.sender);
     }
 
-    /// @notice Delegate attestations.
+    /// @notice Delegate this account's voting power for a single tier to a specified delegate.
     /// @param delegatee The account to delegate tier attestation units to.
     /// @param tierId The ID of the tier to delegate attestation units for.
     function setTierDelegateTo(address delegatee, uint256 tierId) public virtual override {
@@ -864,7 +867,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
         _delegateTier({account: msg.sender, delegatee: delegatee, tierId: tierId});
     }
 
-    /// @notice Delegate attestations.
+    /// @notice Delegate this account's voting power across multiple tiers to specified delegates.
     /// @param delegations An array of tiers to set delegates for.
     function setTierDelegatesTo(DefifaDelegation[] memory delegations) external virtual override {
         // Make sure the current game phase is the minting phase.
@@ -946,7 +949,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// @notice Delegate all attestation units for the specified tier.
     /// @param account The account delegating tier attestation units.
     /// @param delegatee The account to delegate tier attestation units to.
-    /// @param tierId The ID of the tier for which attestation units are being transferred.
+    /// @param tierId The ID of the tier to transfer attestation units for.
     function _delegateTier(address account, address delegatee, uint256 tierId) internal virtual {
         // Get the current delegatee
         address oldDelegate = _tierDelegation[account][tierId];
@@ -1033,7 +1036,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// @notice Moves delegated tier attestations from one delegate to another.
     /// @param from The account to transfer tier attestation units from.
     /// @param to The account to transfer tier attestation units to.
-    /// @param tierId The ID of the tier for which attestation units are being transferred.
+    /// @param tierId The ID of the tier to transfer attestation units for.
     /// @param amount The amount of attestation units to delegate.
     function _moveTierDelegateAttestations(address from, address to, uint256 tierId, uint256 amount) internal {
         // Nothing to do if moving to the same account, or no amount is being moved.
@@ -1142,7 +1145,7 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     /// register a burn, `to` should be zero. Total supply of attestation units will be adjusted with mints and burns.
     /// @param from The account to transfer tier attestation units from.
     /// @param to The account to transfer tier attestation units to.
-    /// @param tierId The ID of the tier for which attestation units are being transferred.
+    /// @param tierId The ID of the tier to transfer attestation units for.
     /// @param amount The amount of attestation units to delegate.
     function _transferTierAttestationUnits(address from, address to, uint256 tierId, uint256 amount) internal virtual {
         if (from == address(0) || to == address(0)) {
@@ -1190,8 +1193,8 @@ contract DefifaHook is JB721Hook, Ownable, IDefifaHook {
     }
 
     /// @notice Before transferring an NFT, register its first owner (if necessary).
-    /// @param to The address the NFT is being transferred to.
-    /// @param tokenId The token ID of the NFT being transferred.
+    /// @param to The address to transfer the NFT to.
+    /// @param tokenId The token ID of the NFT to transfer.
     /// @param auth The address authorizing the transfer.
     /// @return from The address the token was transferred from.
     function _update(address to, uint256 tokenId, address auth) internal virtual override returns (address from) {

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;
 

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

@@ -15,7 +15,7 @@ import {IDefifaHook} from "./IDefifaHook.sol";
 /// and commitment fulfillment.
 interface IDefifaDeployer {
     /// @notice Emitted when a commitment payout fails during fulfillment.
-    /// @param gameId The ID of the game being fulfilled.
+    /// @param gameId The ID of the game that was 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);
@@ -81,7 +81,7 @@ interface IDefifaDeployer {
     /// @return The project ID.
     function DEFIFA_PROJECT_ID() external view returns (uint256);
 
-    /// @notice The governor contract used for scorecard governance.
+    /// @notice The governor contract responsible for scorecard submission and attestation-based ratification.
     /// @return The governor contract.
     function GOVERNOR() external view returns (IDefifaGovernor);
 
@@ -116,12 +116,12 @@ interface IDefifaDeployer {
     /// @return scorecardTimeout The scorecard timeout duration.
     function safetyParamsOf(uint256 gameId) external view returns (uint256 minParticipation, uint32 scorecardTimeout);
 
-    /// @notice The timing parameters for a game.
+    /// @notice The timing parameters for a game (start time, mint duration, and refund period).
     /// @param gameId The ID of the game.
     /// @return The mint duration, start time, and refund period.
     function timesFor(uint256 gameId) external view returns (uint48, uint24, uint24);
 
-    /// @notice The token address for a game.
+    /// @notice The token address used for payments and cash outs in a specific game.
     /// @param gameId The ID of the game.
     /// @return The token address.
     function tokenOf(uint256 gameId) external view returns (address);

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);
 }

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

@@ -24,7 +24,7 @@ interface IDefifaGovernor {
 
     /// @notice Emitted when an account attests to a scorecard.
     /// @param gameId The ID of the game.
-    /// @param scorecardId The ID of the scorecard being attested to.
+    /// @param scorecardId The ID of the scorecard attested to.
     /// @param weight The attestation weight applied.
     /// @param caller The address that submitted the attestation.
     event ScorecardAttested(uint256 indexed gameId, uint256 indexed scorecardId, uint256 weight, address caller);
@@ -143,7 +143,8 @@ interface IDefifaGovernor {
     /// @return The scorecard ID.
     function scorecardIdOf(address gameHook, DefifaTierCashOutWeight[] calldata tierWeights) external returns (uint256);
 
-    /// @notice The state of a scorecard.
+    /// @notice The governance state of a submitted scorecard (PENDING, ACTIVE, DEFEATED, SUCCEEDED, QUEUED, or
+    /// RATIFIED).
     /// @param gameId The ID of the game.
     /// @param scorecardId The ID of the scorecard.
     /// @return The scorecard state.
@@ -154,13 +155,14 @@ interface IDefifaGovernor {
     /// @return The timelock duration in seconds.
     function timelockDurationOf(uint256 gameId) external view returns (uint256);
 
-    /// @notice Attest to a submitted scorecard.
+    /// @notice Attest to a submitted scorecard using your NFT voting power, adding your weight toward ratification.
     /// @param gameId The ID of the game.
     /// @param scorecardId The ID of the scorecard to attest to.
     /// @return weight The attestation weight applied.
     function attestToScorecardFrom(uint256 gameId, uint256 scorecardId) external returns (uint256 weight);
 
-    /// @notice Initialize a game's governance parameters.
+    /// @notice Initialize governance parameters for a game — sets when attestation begins, the grace period, and
+    /// timelock duration.
     /// @param gameId The ID of the game.
     /// @param attestationStartTime The timestamp when attestation begins.
     /// @param attestationGracePeriod The grace period duration in seconds.

package/src/interfaces/IDefifaHook.sol

@@ -100,7 +100,7 @@ interface IDefifaHook is IJB721Hook {
     /// @return The code origin address.
     function CODE_ORIGIN() external view returns (address);
 
-    /// @notice The contract-level metadata URI.
+    /// @notice The contract-level metadata URI (used by marketplaces for collection-level info).
     /// @return The contract URI string.
     function contractURI() external view returns (string memory);
 
@@ -257,12 +257,12 @@ interface IDefifaHook is IJB721Hook {
     /// @param tierWeights The tier cash out weights to set.
     function setTierCashOutWeightsTo(DefifaTierCashOutWeight[] memory tierWeights) external;
 
-    /// @notice Set the attestation delegate for a specific tier.
+    /// @notice Delegate your attestation voting power for a specific tier to another address.
     /// @param delegatee The address to delegate to.
     /// @param tierId The tier ID.
     function setTierDelegateTo(address delegatee, uint256 tierId) external;
 
-    /// @notice Set attestation delegates for multiple tiers at once.
+    /// @notice Delegate your attestation voting power for multiple tiers to other addresses in a single call.
     /// @param delegations The delegation assignments.
     function setTierDelegatesTo(DefifaDelegation[] memory delegations) external;
 }

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

@@ -244,7 +244,7 @@ library DefifaHookLib {
 
     /// @notice Compute the cash out count for the beforeCashOutRecorded hook.
     /// @param gamePhase The current game phase.
-    /// @param cumulativeMintPrice The cumulative mint price of the tokens being cashed out.
+    /// @param cumulativeMintPrice The cumulative mint price of the tokens to cash out.
     /// @param surplusValue The surplus value from the context.
     /// @param totalAmountRedeemed The amount already redeemed.
     /// @param cumulativeCashOutWeight The cumulative cash out weight of the tokens.
@@ -294,7 +294,7 @@ library DefifaHookLib {
 
     /// @notice Computes the attestation units for tiers during payment processing.
     /// @dev Returns parallel arrays: tier IDs, cumulative attestation units per tier, and whether to switch delegate.
-    /// @param tierIdsToMint The tier IDs being minted (must be in ascending order).
+    /// @param tierIdsToMint The tier IDs to mint (must be in ascending order).
     /// @param hookStore The 721 tiers hook store.
     /// @param hook The hook address.
     /// @return tierIds The unique tier IDs.

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

@@ -8,7 +8,9 @@ import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 
 import {DefifaTierParams} from "./DefifaTierParams.sol";
 
-/// @custom:member name The name of the game being created.
+/// @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 to create.
 /// @custom:member projectUri Metadata to associate with the project.
 /// @custom:member contractUri The URI to associate with the 721.
 /// @custom:member baseUri The URI base to prepend onto any tier token URIs.

package/src/structs/DefifaOpsData.sol

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member token The token being used by the game.
+/// @notice Operational parameters stored for a deployed game — the token, timing, and contest rules.
+/// @custom:member token The token 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.
 /// @custom:member refundPeriodDuration The time between the mint phase and the start time when mint's are no longer

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.