@ballkidz/defifa 0.0.26 → 0.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "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;

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 ------------------------- //

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;
 

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/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/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/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,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.

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.