@ballkidz/defifa 0.0.27 → 0.0.28

package/package.json

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

package/src/DefifaDeployer.sol

@@ -99,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.
@@ -141,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.
@@ -203,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.
@@ -213,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

@@ -129,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.
@@ -446,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,
@@ -465,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(
@@ -523,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.
@@ -541,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.
@@ -748,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.
@@ -839,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

@@ -82,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.
@@ -132,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.
@@ -852,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 {
@@ -867,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.
@@ -949,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];
@@ -1036,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.
@@ -1145,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)) {
@@ -1193,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/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/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/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/DefifaLaunchProjectData.sol

@@ -10,7 +10,7 @@ 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 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

@@ -2,7 +2,7 @@
 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 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