@ballkidz/defifa 0.0.1

package/src/DefifaProjectOwner.sol

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {IERC721Receiver} from "@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol";
+import {DefifaDeployer} from "./DefifaDeployer.sol";
+import {IJBPermissions, JBPermissionsData} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
+import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.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.
+contract DefifaProjectOwner is IERC721Receiver {
+    /// @notice The contract where operator permissions are stored.
+    IJBPermissions public immutable PERMISSIONS;
+
+    /// @notice The contract from which projects are minted.
+    IJBProjects public immutable PROJECTS;
+
+    /// @notice The Defifa deployer.
+    DefifaDeployer public immutable DEPLOYER;
+
+    /// @param permissions The contract where operator permissions are stored.
+    /// @param projects The contract from which projects are minted.
+    /// @param deployer The Defifa deployer which will receive permissions to set splits.
+    constructor(IJBPermissions permissions, IJBProjects projects, DefifaDeployer deployer) {
+        PERMISSIONS = permissions;
+        PROJECTS = projects;
+        DEPLOYER = deployer;
+    }
+
+    /// @notice Give the defifa deployer permission to set splits on this contract's behalf.
+    function onERC721Received(
+        address operator,
+        address from,
+        uint256 tokenId,
+        bytes calldata data
+    )
+        external
+        returns (bytes4)
+    {
+        data;
+        from;
+        operator;
+
+        // Make sure the 721 received is the JBProjects contract.
+        if (msg.sender != address(PROJECTS)) revert();
+
+        // Set the correct permission.
+        uint8[] memory permissionIds = new uint8[](1);
+        permissionIds[0] = JBPermissionIds.SET_SPLIT_GROUPS;
+
+        // Give the defifa deployer contract permission to set splits on this contract's behalf.
+        PERMISSIONS.setPermissionsFor({
+            account: address(this),
+            permissionsData: JBPermissionsData({
+                operator: address(DEPLOYER), projectId: uint64(tokenId), permissionIds: permissionIds
+            })
+        });
+
+        return IERC721Receiver.onERC721Received.selector;
+    }
+}

package/src/DefifaTokenUriResolver.sol

@@ -0,0 +1,312 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {Base64} from "lib/base64/base64.sol";
+import {mulDiv} from "@prb/math/src/Common.sol";
+import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
+import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+import {ITypeface} from "lib/typeface/contracts/interfaces/ITypeface.sol";
+import {IDefifaHook} from "./interfaces/IDefifaHook.sol";
+import {IDefifaTokenUriResolver} from "./interfaces/IDefifaTokenUriResolver.sol";
+import {DefifaFontImporter} from "./libraries/DefifaFontImporter.sol";
+import {DefifaGamePhase} from "./enums/DefifaGamePhase.sol";
+
+import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {IJB721TokenUriResolver} from "@bananapus/721-hook-v6/src/interfaces/IJB721TokenUriResolver.sol";
+import {ERC721} from "@bananapus/721-hook-v6/src/abstract/ERC721.sol";
+import {JB721Tier} from "@bananapus/721-hook-v6/src/structs/JB721Tier.sol";
+import {JBIpfsDecoder} from "@bananapus/721-hook-v6/src/libraries/JBIpfsDecoder.sol";
+
+/// @title DefifaTokenUriResolver
+/// @notice Standard Token URIs for Defifa games.
+contract DefifaTokenUriResolver is IDefifaTokenUriResolver, IJB721TokenUriResolver {
+    using Strings for uint256;
+
+    //*********************************************************************//
+    // -------------------- private constant properties ------------------ //
+    //*********************************************************************//
+
+    /// @notice The fidelity of the decimal returned in the NFT image.
+    uint256 private constant _IMG_DECIMAL_FIDELITY = 5;
+
+    //*********************************************************************//
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    /// @notice The typeface of the SVGs.
+    ITypeface public immutable override typeface;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    constructor(ITypeface _typeface) {
+        typeface = _typeface;
+    }
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice The metadata URI of the provided token ID.
+    /// @dev Defer to the token's tier IPFS URI if set.
+    /// @param _nft The address of the nft the token URI should be oriented to.
+    /// @param _tokenId The ID of the token to get the tier URI for.
+    /// @return The token URI corresponding with the tier.
+    function tokenUriOf(address _nft, uint256 _tokenId) external view override returns (string memory) {
+        // Keep a reference to the hook.
+        IDefifaHook _hook = IDefifaHook(_nft);
+
+        // Get the game ID.
+        uint256 _gameId = _hook.PROJECT_ID();
+
+        // Keep a reference to the game phase text.
+        string memory _gamePhaseText;
+
+        // Keep a reference to the rarity text;
+        string memory _rarityText;
+
+        // Keep a reference to the rarity text;
+        string memory _valueText;
+
+        // Keep a reference to the game's name.
+        // TODO: Somehow make the `IDefifaHook` have the `name` function.
+        string memory _title = ERC721(address(_hook)).name();
+
+        // Keep a reference to the tier's name.
+        string memory _team;
+
+        // Keep a reference to the SVG parts.
+        string[] memory parts = new string[](4);
+
+        // Keep a reference to the pot.
+        string memory _potText;
+
+        {
+            // Get a reference to the tier.
+            JB721Tier memory _tier =
+                _hook.store().tierOfTokenId({hook: address(_hook), tokenId: _tokenId, includeResolvedUri: false});
+
+            // Set the tier's name.
+            _team = _hook.tierNameOf(_tier.id);
+
+            // Check to see if the tier has a URI. Return it if it does.
+            if (_tier.encodedIPFSUri != bytes32(0)) {
+                return JBIpfsDecoder.decode({baseUri: _hook.baseURI(), hexString: _tier.encodedIPFSUri});
+            }
+
+            parts[0] = string("data:application/json;base64,");
+
+            parts[1] = string(
+                abi.encodePacked(
+                    '{"name":"',
+                    _team,
+                    '", "id": "',
+                    uint256(_tier.id).toString(),
+                    '","description":"Team: ',
+                    _team,
+                    ", ID: ",
+                    uint256(_tier.id).toString(),
+                    '.","image":"data:image/svg+xml;base64,'
+                )
+            );
+
+            {
+                // Get a reference to the game phase.
+                DefifaGamePhase _gamePhase = _hook.gamePhaseReporter().currentGamePhaseOf(_gameId);
+
+                // Keep a reference to the game pot.
+                (uint256 _gamePot, address _gamePotToken, uint256 _gamePotDecimals) =
+                    _hook.gamePotReporter().currentGamePotOf({gameId: _gameId, includeCommitments: false});
+
+                // Include the amount redeemed.
+                _gamePot = _gamePot + _hook.amountRedeemed();
+
+                // Set the pot text.
+                _potText = _formatBalance({
+                    _amount: _gamePot,
+                    _token: _gamePotToken,
+                    _decimals: _gamePotDecimals,
+                    _fidelity: _IMG_DECIMAL_FIDELITY
+                });
+
+                if (_gamePhase == DefifaGamePhase.COUNTDOWN) {
+                    _gamePhaseText = "Minting starts soon.";
+                } else if (_gamePhase == DefifaGamePhase.MINT) {
+                    _gamePhaseText = "Minting and refunds are open.";
+                } else if (_gamePhase == DefifaGamePhase.REFUND) {
+                    _gamePhaseText = "Minting is over. Refunds are ending.";
+                } else if (_gamePhase == DefifaGamePhase.SCORING) {
+                    _gamePhaseText = "Awaiting scorecard approval.";
+                } else if (_gamePhase == DefifaGamePhase.COMPLETE) {
+                    _gamePhaseText = "Scorecard locked in. Burn to claim reward.";
+                } else if (_gamePhase == DefifaGamePhase.NO_CONTEST) {
+                    _gamePhaseText = "No contest. Refunds open.";
+                }
+
+                // Keep a reference to the number of tokens outstanding from this tier.
+                uint256 _totalMinted = _hook.currentSupplyOfTier(_tier.id);
+
+                if (_gamePhase == DefifaGamePhase.MINT) {
+                    _rarityText = string(
+                        abi.encodePacked(_totalMinted.toString(), _totalMinted == 1 ? " card so far" : " cards so far")
+                    );
+                } else {
+                    _rarityText = string(
+                        abi.encodePacked(
+                            _totalMinted.toString(), _totalMinted == 1 ? " card in existence" : " cards in existence"
+                        )
+                    );
+                }
+
+                if (_gamePhase == DefifaGamePhase.SCORING || _gamePhase == DefifaGamePhase.COMPLETE) {
+                    uint256 _potPortion =
+                        mulDiv(_gamePot, _hook.cashOutWeightOf(_tokenId), _hook.TOTAL_CASHOUT_WEIGHT());
+                    _valueText = !_hook.cashOutWeightIsSet()
+                        ? "Awaiting scorecard..."
+                        : _formatBalance({
+                            _amount: _potPortion,
+                            _token: _gamePotToken,
+                            _decimals: _gamePotDecimals,
+                            _fidelity: _IMG_DECIMAL_FIDELITY
+                        });
+                } else {
+                    _valueText = _formatBalance({
+                        _amount: _tier.price,
+                        _token: _gamePotToken,
+                        _decimals: _gamePotDecimals,
+                        _fidelity: _IMG_DECIMAL_FIDELITY
+                    });
+                }
+            }
+        }
+        parts[2] = Base64.encode(
+            abi.encodePacked(
+                '<svg viewBox="0 0 500 500" xmlns="http://www.w3.org/2000/svg">',
+                '<style>@font-face{font-family:"Capsules-500";src:url(data:font/truetype;charset=utf-8;base64,',
+                DefifaFontImporter.getSkinnyFontSource(typeface),
+                ');format("opentype");}',
+                '@font-face{font-family:"Capsules-700";src:url(data:font/truetype;charset=utf-8;base64,',
+                DefifaFontImporter.getBeefyFontSource(typeface),
+                ');format("opentype");}',
+                "text{white-space:pre-wrap; width:100%; }</style>",
+                '<rect width="100%" height="100%" fill="#181424"/>',
+                '<text x="10" y="30" style="font-size:16px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">GAME: ',
+                _gameId.toString(),
+                " | POT: ",
+                _potText,
+                " | CARDS: ",
+                _hook.store().totalSupplyOf(address(_hook)).toString(),
+                "</text>",
+                '<text x="10" y="50" style="font-size:16px; font-family: Capsules-500; font-weight:500; fill: #ed017c;">',
+                _gamePhaseText,
+                "</text>",
+                '<text x="10" y="85" style="font-size:26px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">',
+                _getSubstring(_title, 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),
+                "</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)
+                    : "",
+                "</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) : "",
+                "</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),
+                "</text>",
+                '<text x="10" y="430" style="font-size:16px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">TOKEN ID: ',
+                _tokenId.toString(),
+                "</text>",
+                '<text x="10" y="455" style="font-size:16px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">RARITY: ',
+                _rarityText,
+                "</text>",
+                '<text x="10" y="480" style="font-size:16px; font-family: Capsules-500; font-weight:500; fill: #c0b3f1;">BACKED BY: ',
+                _valueText,
+                "</text>",
+                "</svg>"
+            )
+        );
+        parts[3] = string('"}');
+        // slither-disable-next-line encode-packed-collision
+        return string.concat(parts[0], Base64.encode(abi.encodePacked(parts[1], parts[2], parts[3])));
+    }
+
+    /// @notice Gets a substring.
+    /// @dev If the first character is a space, it is not included.
+    /// @param _str The string to get a substring of.
+    /// @param _startIndex The first index of the substring from within the string.
+    /// @param _endIndex The last index of the string from within the string.
+    /// @return substring The substring.
+    function _getSubstring(
+        string memory _str,
+        uint256 _startIndex,
+        uint256 _endIndex
+    )
+        internal
+        pure
+        returns (string memory substring)
+    {
+        bytes memory _strBytes = bytes(_str);
+        if (_startIndex >= _strBytes.length) return "";
+        if (_endIndex > _strBytes.length) _endIndex = _strBytes.length;
+        _startIndex = _strBytes[_startIndex] == bytes1(0x20) ? _startIndex + 1 : _startIndex;
+        if (_startIndex >= _endIndex) return "";
+        bytes memory _result = new bytes(_endIndex - _startIndex);
+        for (uint256 _i = _startIndex; _i < _endIndex;) {
+            _result[_i - _startIndex] = _strBytes[_i];
+            unchecked {
+                ++_i;
+            }
+        }
+        return string(_result);
+    }
+
+    /// @notice Formats a balance from a fixed point number to a string.
+    /// @param _amount The fixed point amount.
+    /// @param _token The token the amount is in.
+    /// @param _decimals The number of decimals in the fixed point amount.
+    /// @param _fidelity The number of decimals that should be returned in the formatted string.
+    /// @return The formatted balance.
+    function _formatBalance(
+        uint256 _amount,
+        address _token,
+        uint256 _decimals,
+        uint256 _fidelity
+    )
+        internal
+        view
+        returns (string memory)
+    {
+        bool _isEth = _token == JBConstants.NATIVE_TOKEN;
+
+        uint256 _fixedPoint = 10 ** _decimals;
+
+        // Convert amount to a decimal format
+        string memory _integerPart = (_amount / _fixedPoint).toString();
+
+        uint256 _remainder = _amount % _fixedPoint;
+        uint256 _scaledRemainder = _remainder * (10 ** _fidelity);
+        uint256 _decimalPart = _scaledRemainder / _fixedPoint;
+
+        // Pad with zeros if necessary
+        string memory _decimalPartStr = _decimalPart.toString();
+        while (bytes(_decimalPartStr).length < _fidelity) {
+            _decimalPartStr = string(abi.encodePacked("0", _decimalPartStr));
+        }
+
+        // Concatenate the strings
+        return _isEth
+            ? string(abi.encodePacked("\u039E", _integerPart, ".", _decimalPartStr))
+            : string(abi.encodePacked(_integerPart, ".", _decimalPartStr, " ", IERC20Metadata(_token).symbol()));
+    }
+}

package/src/enums/DefifaGamePhase.sol

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+enum DefifaGamePhase {
+    COUNTDOWN,
+    MINT,
+    REFUND,
+    SCORING,
+    COMPLETE,
+    NO_CONTEST
+}

package/src/enums/DefifaScorecardState.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+enum DefifaScorecardState {
+    PENDING,
+    ACTIVE,
+    DEFEATED,
+    SUCCEEDED,
+    RATIFIED
+}

package/src/interfaces/IDefifaDeployer.sol

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {DefifaLaunchProjectData} from "../structs/DefifaLaunchProjectData.sol";
+import {DefifaOpsData} from "../structs/DefifaOpsData.sol";
+import {IDefifaHook} from "./IDefifaHook.sol";
+import {IDefifaGovernor} from "./IDefifaGovernor.sol";
+
+import {IJB721TokenUriResolver} from "@bananapus/721-hook-v6/src/interfaces/IJB721TokenUriResolver.sol";
+import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
+import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
+import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
+
+/// @notice Deploys and manages Defifa prediction games, including lifecycle phase transitions
+/// and commitment fulfillment.
+interface IDefifaDeployer {
+    event LaunchGame(
+        uint256 indexed gameId,
+        IDefifaHook indexed hook,
+        IDefifaGovernor indexed governor,
+        IJB721TokenUriResolver tokenUriResolver,
+        address caller
+    );
+
+    event QueuedRefundPhase(uint256 indexed gameId, address caller);
+
+    event QueuedScoringPhase(uint256 indexed gameId, address caller);
+
+    event QueuedNoContest(uint256 indexed gameId, address caller);
+
+    event FulfilledCommitments(uint256 indexed gameId, uint256 pot, address caller);
+
+    event DistributeToSplit(JBSplit split, uint256 amount, address caller);
+
+    /// @notice The split group ID used for distributing game pot funds.
+    /// @return The split group.
+    function splitGroup() external view returns (uint256);
+
+    /// @notice The Juicebox project ID of the Defifa project.
+    /// @return The project ID.
+    function defifaProjectId() external view returns (uint256);
+
+    /// @notice The Juicebox project ID of the base protocol project.
+    /// @return The project ID.
+    function baseProtocolProjectId() external view returns (uint256);
+
+    /// @notice The code origin address used as an implementation for hook clones.
+    /// @return The code origin address.
+    function hookCodeOrigin() external view returns (address);
+
+    /// @notice The token URI resolver used for game NFT metadata.
+    /// @return The token URI resolver contract.
+    function tokenUriResolver() external view returns (IJB721TokenUriResolver);
+
+    /// @notice The governor contract used for scorecard governance.
+    /// @return The governor contract.
+    function governor() external view returns (IDefifaGovernor);
+
+    /// @notice The Juicebox controller used to manage projects.
+    /// @return The controller contract.
+    function controller() external view returns (IJBController);
+
+    /// @notice The address registry used for content-addressable deployment lookups.
+    /// @return The address registry contract.
+    function registry() external view returns (IJBAddressRegistry);
+
+    /// @notice The fee divisor for Defifa fees (100 / fee percent).
+    /// @return The fee divisor.
+    function DEFIFA_FEE_DIVISOR() external view returns (uint256);
+
+    /// @notice The fee divisor for base protocol fees (100 / fee percent).
+    /// @return The fee divisor.
+    function BASE_PROTOCOL_FEE_DIVISOR() external view returns (uint256);
+
+    /// @notice The timing parameters for a game.
+    /// @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.
+    /// @param gameId The ID of the game.
+    /// @return The token address.
+    function tokenOf(uint256 gameId) external view returns (address);
+
+    /// @notice The safety parameters for a game.
+    /// @param gameId The ID of the game.
+    /// @return minParticipation The minimum participation threshold.
+    /// @return scorecardTimeout The scorecard timeout duration.
+    function safetyParamsOf(uint256 gameId) external view returns (uint256 minParticipation, uint32 scorecardTimeout);
+
+    /// @notice Whether the next game phase needs to be queued.
+    /// @param gameId The ID of the game.
+    /// @return True if the next phase needs queueing.
+    function nextPhaseNeedsQueueing(uint256 gameId) external view returns (bool);
+
+    /// @notice Launch a new Defifa game.
+    /// @param launchProjectData The configuration for launching the game.
+    /// @return gameId The ID of the newly launched game.
+    function launchGameWith(DefifaLaunchProjectData calldata launchProjectData) external returns (uint256 gameId);
+
+    /// @notice Fulfill the commitments of a game by distributing the pot.
+    /// @param gameId The ID of the game.
+    function fulfillCommitmentsOf(uint256 gameId) external;
+
+    /// @notice Trigger a no-contest outcome for a game.
+    /// @param gameId The ID of the game.
+    function triggerNoContestFor(uint256 gameId) external;
+}

package/src/interfaces/IDefifaGamePhaseReporter.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {DefifaGamePhase} from "./../enums/DefifaGamePhase.sol";
+
+interface IDefifaGamePhaseReporter {
+    function currentGamePhaseOf(uint256 gameId) external view returns (DefifaGamePhase);
+}

package/src/interfaces/IDefifaGamePotReporter.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+interface IDefifaGamePotReporter {
+    function fulfilledCommitmentsOf(uint256 gameId) external view returns (uint256);
+
+    function currentGamePotOf(uint256 gameId, bool includeCommitments) external view returns (uint256, address, uint256);
+}

package/src/interfaces/IDefifaGovernor.sol

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {DefifaScorecardState} from "../enums/DefifaScorecardState.sol";
+import {DefifaTierCashOutWeight} from "../structs/DefifaTierCashOutWeight.sol";
+import {IDefifaHook} from "./IDefifaHook.sol";
+import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
+
+/// @notice Manages the ratification of Defifa scorecards through attestation-based governance.
+interface IDefifaGovernor {
+    event GameInitialized(
+        uint256 indexed gameId, uint256 attestationStartTime, uint256 attestationGracePeriod, address caller
+    );
+
+    event ScorecardSubmitted(
+        uint256 indexed gameId,
+        uint256 indexed scorecardId,
+        DefifaTierCashOutWeight[] tierWeights,
+        bool isDefaultAttestationDelegate,
+        address caller
+    );
+
+    event ScorecardAttested(uint256 indexed gameId, uint256 indexed scorecardId, uint256 weight, address caller);
+
+    event ScorecardRatified(uint256 indexed gameId, uint256 indexed scorecardId, address caller);
+
+    /// @notice The maximum tier ID that contributes attestation power.
+    /// @return The maximum attestation power tier.
+    function MAX_ATTESTATION_POWER_TIER() external view returns (uint256);
+
+    /// @notice The Juicebox controller used to manage projects.
+    /// @return The controller contract.
+    function controller() external view returns (IJBController);
+
+    /// @notice The scorecard proposal submitted by the default attestation delegate for a game.
+    /// @param gameId The ID of the game.
+    /// @return The scorecard ID.
+    function defaultAttestationDelegateProposalOf(uint256 gameId) external view returns (uint256);
+
+    /// @notice The ID of the ratified scorecard for a game.
+    /// @param gameId The ID of the game.
+    /// @return The ratified scorecard ID, or 0 if none.
+    function ratifiedScorecardIdOf(uint256 gameId) external view returns (uint256);
+
+    /// @notice Compute the scorecard ID for a given hook and tier weights.
+    /// @param gameHook The game hook address.
+    /// @param tierWeights The tier cash out weights.
+    /// @return The scorecard ID.
+    function scorecardIdOf(address gameHook, DefifaTierCashOutWeight[] calldata tierWeights) external returns (uint256);
+
+    /// @notice The state of a scorecard.
+    /// @param gameId The ID of the game.
+    /// @param scorecardId The ID of the scorecard.
+    /// @return The scorecard state.
+    function stateOf(uint256 gameId, uint256 scorecardId) external view returns (DefifaScorecardState);
+
+    /// @notice Get the attestation weight for an account at a specific timestamp.
+    /// @param gameId The ID of the game.
+    /// @param account The account to check.
+    /// @param timestamp The timestamp to check.
+    /// @return attestationPower The attestation power.
+    function getAttestationWeight(
+        uint256 gameId,
+        address account,
+        uint48 timestamp
+    )
+        external
+        view
+        returns (uint256 attestationPower);
+
+    /// @notice The number of attestations for a scorecard.
+    /// @param gameId The ID of the game.
+    /// @param scorecardId The ID of the scorecard.
+    /// @return The attestation count.
+    function attestationCountOf(uint256 gameId, uint256 scorecardId) external view returns (uint256);
+
+    /// @notice Whether an account has attested to a specific scorecard.
+    /// @param gameId The ID of the game.
+    /// @param scorecardId The ID of the scorecard.
+    /// @param account The account to check.
+    /// @return True if the account has attested.
+    function hasAttestedTo(uint256 gameId, uint256 scorecardId, address account) external view returns (bool);
+
+    /// @notice The timestamp when attestation begins for a game.
+    /// @param gameId The ID of the game.
+    /// @return The attestation start time.
+    function attestationStartTimeOf(uint256 gameId) external view returns (uint256);
+
+    /// @notice The grace period after attestation starts during which attestation is still allowed.
+    /// @param gameId The ID of the game.
+    /// @return The grace period in seconds.
+    function attestationGracePeriodOf(uint256 gameId) external view returns (uint256);
+
+    /// @notice The quorum required to ratify a scorecard.
+    /// @param gameId The ID of the game.
+    /// @return The quorum threshold.
+    function quorum(uint256 gameId) external view returns (uint256);
+
+    /// @notice Initialize a game's governance parameters.
+    /// @param gameId The ID of the game.
+    /// @param attestationStartTime The timestamp when attestation begins.
+    /// @param attestationGracePeriod The grace period duration in seconds.
+    function initializeGame(uint256 gameId, uint256 attestationStartTime, uint256 attestationGracePeriod) external;
+
+    /// @notice Submit a scorecard for attestation.
+    /// @param gameId The ID of the game.
+    /// @param tierWeights The tier cash out weights.
+    /// @return The scorecard ID.
+    function submitScorecardFor(
+        uint256 gameId,
+        DefifaTierCashOutWeight[] calldata tierWeights
+    )
+        external
+        returns (uint256);
+
+    /// @notice Attest to a submitted scorecard.
+    /// @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 Ratify a scorecard that has reached quorum.
+    /// @param gameId The ID of the game.
+    /// @param tierWeights The tier cash out weights (must match the scorecard).
+    /// @return The scorecard ID that was ratified.
+    function ratifyScorecardFrom(
+        uint256 gameId,
+        DefifaTierCashOutWeight[] calldata tierWeights
+    )
+        external
+        returns (uint256);
+}