@bananapus/core-v6 0.0.1

package/src/JBTokens.sol

@@ -0,0 +1,376 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.23;
+
+import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
+
+import {JBControlled} from "./abstract/JBControlled.sol";
+import {IJBDirectory} from "./interfaces/IJBDirectory.sol";
+import {IJBToken} from "./interfaces/IJBToken.sol";
+import {IJBTokens} from "./interfaces/IJBTokens.sol";
+
+/// @notice Manages minting, burning, and balances of projects' tokens and token credits.
+/// @dev Token balances can either be ERC-20s or token credits. This contract manages these two representations and
+/// allows credit -> ERC-20 claiming.
+/// @dev The total supply of a project's tokens and the balance of each account are calculated in this contract.
+/// @dev An ERC-20 contract must be set by a project's owner for ERC-20 claiming to become available. Projects can bring
+/// their own IJBToken if they prefer.
+contract JBTokens is JBControlled, IJBTokens {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JBTokens_EmptyName();
+    error JBTokens_EmptySymbol();
+    error JBTokens_EmptyToken(uint256 projectId);
+    error JBTokens_InsufficientCredits(uint256 count, uint256 creditBalance);
+    error JBTokens_InsufficientTokensToBurn(uint256 count, uint256 tokenBalance);
+    error JBTokens_OverflowAlert(uint256 value, uint256 limit);
+    error JBTokens_ProjectAlreadyHasToken(IJBToken token);
+    error JBTokens_TokenAlreadyBeingUsed(uint256 projectId);
+    error JBTokens_TokenCantBeAdded(uint256 projectId);
+    error JBTokens_TokenNotFound();
+    error JBTokens_TokensMustHave18Decimals(uint256 decimals);
+
+    //*********************************************************************//
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    /// @notice A reference to the token implementation that'll be cloned as projects deploy their own tokens.
+    IJBToken public immutable TOKEN;
+
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    /// @notice Each holder's credit balance for each project.
+    /// @custom:param holder The credit holder.
+    /// @custom:param projectId The ID of the project to which the credits belong.
+    mapping(address holder => mapping(uint256 projectId => uint256)) public override creditBalanceOf;
+
+    /// @notice Each token's project.
+    /// @custom:param token The address of the token associated with the project.
+    // slither-disable-next-line unused-return
+    mapping(IJBToken token => uint256) public override projectIdOf;
+
+    /// @notice Each project's attached token contract.
+    /// @custom:param projectId The ID of the project the token belongs to.
+    mapping(uint256 projectId => IJBToken) public override tokenOf;
+
+    /// @notice The total supply of credits for each project.
+    /// @custom:param projectId The ID of the project to which the credits belong.
+    mapping(uint256 projectId => uint256) public override totalCreditSupplyOf;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    /// @param directory A contract storing directories of terminals and controllers for each project.
+    /// @param token The implementation of the token contract that project can deploy.
+    constructor(IJBDirectory directory, IJBToken token) JBControlled(directory) {
+        TOKEN = token;
+    }
+
+    //*********************************************************************//
+    // ------------------------- external views -------------------------- //
+    //*********************************************************************//
+
+    /// @notice The total balance a holder has for a specified project, including both tokens and token credits.
+    /// @param holder The holder to get a balance for.
+    /// @param projectId The project to get the `holder`'s balance for.
+    /// @return balance The combined token and token credit balance of the `holder`.
+    function totalBalanceOf(address holder, uint256 projectId) external view override returns (uint256 balance) {
+        // Get a reference to the holder's credits for the project.
+        balance = creditBalanceOf[holder][projectId];
+
+        // Get a reference to the project's current token.
+        IJBToken token = tokenOf[projectId];
+
+        // If the project has a current token, add the holder's balance to the total.
+        if (token != IJBToken(address(0))) {
+            balance += token.balanceOf(holder);
+        }
+    }
+
+    //*********************************************************************//
+    // --------------------------- public views -------------------------- //
+    //*********************************************************************//
+
+    /// @notice The total supply for a specific project, including both tokens and token credits.
+    /// @param projectId The ID of the project to get the total supply of.
+    /// @return totalSupply The total supply of the project's tokens and token credits.
+    function totalSupplyOf(uint256 projectId) public view override returns (uint256 totalSupply) {
+        // Get a reference to the total supply of the project's credits
+        totalSupply = totalCreditSupplyOf[projectId];
+
+        // Get a reference to the project's current token.
+        IJBToken token = tokenOf[projectId];
+
+        // If the project has a current token, add its total supply to the total.
+        if (token != IJBToken(address(0))) {
+            totalSupply += token.totalSupply();
+        }
+    }
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Burns (destroys) credits or tokens.
+    /// @dev Credits are burned first, then tokens are burned.
+    /// @dev Only a project's current controller can burn its tokens.
+    /// @param holder The address that owns the tokens which are being burned.
+    /// @param projectId The ID of the project to the burned tokens belong to.
+    /// @param count The number of tokens to burn.
+    function burnFrom(address holder, uint256 projectId, uint256 count) external override onlyControllerOf(projectId) {
+        // Get a reference to the project's current token.
+        IJBToken token = tokenOf[projectId];
+
+        // Get a reference to the amount of credits the holder has.
+        uint256 creditBalance = creditBalanceOf[holder][projectId];
+
+        // Get a reference to the amount of the project's current token the holder has in their wallet.
+        uint256 tokenBalance = token == IJBToken(address(0)) ? 0 : token.balanceOf(holder);
+
+        // There must be enough tokens to burn across the holder's combined token and credit balance.
+        if (count > tokenBalance + creditBalance) {
+            revert JBTokens_InsufficientTokensToBurn(count, tokenBalance + creditBalance);
+        }
+
+        // The amount of tokens to burn.
+        uint256 tokensToBurn;
+
+        // Get a reference to how many tokens should be burned
+        if (tokenBalance != 0) {
+            // Burn credits before tokens.
+            unchecked {
+                tokensToBurn = creditBalance < count ? count - creditBalance : 0;
+            }
+        }
+
+        // The amount of credits to burn.
+        uint256 creditsToBurn;
+        unchecked {
+            creditsToBurn = count - tokensToBurn;
+        }
+
+        // Subtract the burned credits from the credit balance and credit supply.
+        if (creditsToBurn > 0) {
+            creditBalanceOf[holder][projectId] = creditBalanceOf[holder][projectId] - creditsToBurn;
+            totalCreditSupplyOf[projectId] = totalCreditSupplyOf[projectId] - creditsToBurn;
+        }
+
+        emit Burn({
+            holder: holder,
+            projectId: projectId,
+            count: count,
+            creditBalance: creditBalance,
+            tokenBalance: tokenBalance,
+            caller: msg.sender
+        });
+
+        // Burn the tokens.
+        if (tokensToBurn > 0) token.burn(holder, tokensToBurn);
+    }
+
+    /// @notice Redeem credits to claim tokens into a holder's wallet.
+    /// @dev Only a project's controller can claim that project's tokens.
+    /// @param holder The owner of the credits being redeemed.
+    /// @param projectId The ID of the project whose tokens are being claimed.
+    /// @param count The number of tokens to claim.
+    /// @param beneficiary The account into which the claimed tokens will go.
+    function claimTokensFor(
+        address holder,
+        uint256 projectId,
+        uint256 count,
+        address beneficiary
+    )
+        external
+        override
+        onlyControllerOf(projectId)
+    {
+        // Get a reference to the project's current token.
+        IJBToken token = tokenOf[projectId];
+
+        // The project must have a token contract attached.
+        if (token == IJBToken(address(0))) revert JBTokens_TokenNotFound();
+
+        // Get a reference to the amount of credits the holder has.
+        uint256 creditBalance = creditBalanceOf[holder][projectId];
+
+        // There must be enough credits to claim.
+        if (count > creditBalance) revert JBTokens_InsufficientCredits(count, creditBalance);
+
+        unchecked {
+            // Subtract the claim amount from the holder's credit balance.
+            creditBalanceOf[holder][projectId] = creditBalance - count;
+
+            // Subtract the claim amount from the project's total credit supply.
+            totalCreditSupplyOf[projectId] -= count;
+        }
+
+        emit ClaimTokens({
+            holder: holder,
+            projectId: projectId,
+            creditBalance: creditBalance,
+            count: count,
+            beneficiary: beneficiary,
+            caller: msg.sender
+        });
+
+        // Mint the equivalent amount of the project's token for the holder.
+        token.mint(beneficiary, count);
+    }
+
+    /// @notice Deploys an ERC-20 token for a project. It will be used when claiming tokens.
+    /// @dev Deploys a project's ERC-20 token contract.
+    /// @dev Only a project's controller can deploy its token.
+    /// @param projectId The ID of the project to deploy an ERC-20 token for.
+    /// @param name The ERC-20's name.
+    /// @param symbol The ERC-20's symbol.
+    /// @param salt The salt used for ERC-1167 clone deployment. Pass a non-zero salt for deterministic deployment based
+    /// on `msg.sender` and the `TOKEN` implementation address.
+    /// @return token The address of the token that was deployed.
+    function deployERC20For(
+        uint256 projectId,
+        string calldata name,
+        string calldata symbol,
+        bytes32 salt
+    )
+        external
+        override
+        onlyControllerOf(projectId)
+        returns (IJBToken token)
+    {
+        // There must be a name.
+        if (bytes(name).length == 0) revert JBTokens_EmptyName();
+
+        // There must be a symbol.
+        if (bytes(symbol).length == 0) revert JBTokens_EmptySymbol();
+
+        // The project shouldn't already have a token.
+        if (tokenOf[projectId] != IJBToken(address(0))) revert JBTokens_ProjectAlreadyHasToken(tokenOf[projectId]);
+
+        token = salt == bytes32(0)
+            ? IJBToken(Clones.clone(address(TOKEN)))
+            : IJBToken(Clones.cloneDeterministic(address(TOKEN), keccak256(abi.encode(msg.sender, salt))));
+
+        // Store the token contract.
+        tokenOf[projectId] = token;
+
+        // Store the project for the token.
+        projectIdOf[token] = projectId;
+
+        emit DeployERC20({
+            projectId: projectId, token: token, name: name, symbol: symbol, salt: salt, caller: msg.sender
+        });
+
+        // Initialize the token.
+        token.initialize({name: name, symbol: symbol, owner: address(this)});
+    }
+
+    /// @notice Mint (create) new tokens or credits.
+    /// @dev Only a project's current controller can mint its tokens.
+    /// @param holder The address receiving the new tokens.
+    /// @param projectId The ID of the project to which the tokens belong.
+    /// @param count The number of tokens to mint.
+    /// @return token The address of the token that was minted, if the project has a token.
+    function mintFor(
+        address holder,
+        uint256 projectId,
+        uint256 count
+    )
+        external
+        override
+        onlyControllerOf(projectId)
+        returns (IJBToken token)
+    {
+        // Get a reference to the project's current token.
+        token = tokenOf[projectId];
+
+        // Save a reference to whether there a token exists.
+        bool tokensWereClaimed = token != IJBToken(address(0));
+
+        // The total supply after minting can't exceed the maximum value storable in a uint208.
+        if (totalSupplyOf(projectId) + count > type(uint208).max) {
+            revert JBTokens_OverflowAlert(totalSupplyOf(projectId) + count, type(uint208).max);
+        }
+
+        if (tokensWereClaimed) {
+            // If tokens should be claimed, mint tokens into the holder's wallet.
+            // slither-disable-next-line reentrancy-events
+            token.mint(holder, count);
+        } else {
+            // Otherwise, add the tokens to their credits and the credit supply.
+            creditBalanceOf[holder][projectId] += count;
+            totalCreditSupplyOf[projectId] += count;
+        }
+
+        emit Mint({
+            holder: holder, projectId: projectId, count: count, tokensWereClaimed: tokensWereClaimed, caller: msg.sender
+        });
+    }
+
+    /// @notice Set a project's token if not already set.
+    /// @dev Only a project's controller can set its token.
+    /// @param projectId The ID of the project to set the token of.
+    /// @param token The new token's address.
+    function setTokenFor(uint256 projectId, IJBToken token) external override onlyControllerOf(projectId) {
+        // Can't set to the zero address.
+        if (token == IJBToken(address(0))) revert JBTokens_EmptyToken(projectId);
+
+        // Can't set a token if the project is already associated with another token.
+        if (tokenOf[projectId] != IJBToken(address(0))) revert JBTokens_ProjectAlreadyHasToken(tokenOf[projectId]);
+
+        // Can't set a token if it's already associated with another project.
+        if (projectIdOf[token] != 0) revert JBTokens_TokenAlreadyBeingUsed(projectIdOf[token]);
+
+        // Can't change to a token that doesn't use 18 decimals.
+        if (token.decimals() != 18) revert JBTokens_TokensMustHave18Decimals(token.decimals());
+
+        // Make sure the token can be added to the project its being added to.
+        if (!token.canBeAddedTo(projectId)) revert JBTokens_TokenCantBeAdded(projectId);
+
+        // Store the new token.
+        tokenOf[projectId] = token;
+
+        // Store the project for the token.
+        projectIdOf[token] = projectId;
+
+        emit SetToken({projectId: projectId, token: token, caller: msg.sender});
+    }
+
+    /// @notice Allows a holder to transfer credits to another account.
+    /// @dev Only a project's controller can transfer credits for that project.
+    /// @param holder The address to transfer credits from.
+    /// @param projectId The ID of the project whose credits are being transferred.
+    /// @param recipient The recipient of the credits.
+    /// @param count The number of token credits to transfer.
+    function transferCreditsFrom(
+        address holder,
+        uint256 projectId,
+        address recipient,
+        uint256 count
+    )
+        external
+        override
+        onlyControllerOf(projectId)
+    {
+        // Get a reference to the holder's unclaimed project token balance.
+        uint256 creditBalance = creditBalanceOf[holder][projectId];
+
+        // The holder must have enough unclaimed tokens to transfer.
+        if (count > creditBalance) revert JBTokens_InsufficientCredits(count, creditBalance);
+
+        // Subtract from the holder's unclaimed token balance.
+        unchecked {
+            creditBalanceOf[holder][projectId] = creditBalance - count;
+        }
+
+        // Add the unclaimed project tokens to the recipient's balance.
+        creditBalanceOf[recipient][projectId] += count;
+
+        emit TransferCredits({
+            holder: holder, projectId: projectId, recipient: recipient, count: count, caller: msg.sender
+        });
+    }
+}

package/src/abstract/JBControlled.sol

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJBControlled} from "./../interfaces/IJBControlled.sol";
+import {IJBDirectory} from "./../interfaces/IJBDirectory.sol";
+
+/// @notice Provides a modifier for contracts with functionality that can only be accessed by a project's controller.
+abstract contract JBControlled is IJBControlled {
+    //*********************************************************************//
+    // --------------------------- custom errors -------------------------- //
+    //*********************************************************************//
+
+    error JBControlled_ControllerUnauthorized(address controller);
+
+    //*********************************************************************//
+    // ---------------------------- modifiers ---------------------------- //
+    //*********************************************************************//
+
+    /// @notice Only allows the controller of the specified project to proceed.
+    /// @param projectId The ID of the project.
+    modifier onlyControllerOf(uint256 projectId) {
+        _onlyControllerOf(projectId);
+        _;
+    }
+
+    //*********************************************************************//
+    // ---------------- public immutable stored properties --------------- //
+    //*********************************************************************//
+
+    /// @notice The directory of terminals and controllers for projects.
+    IJBDirectory public immutable override DIRECTORY;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    /// @param directory A contract storing directories of terminals and controllers for each project.
+    constructor(IJBDirectory directory) {
+        DIRECTORY = directory;
+    }
+
+    /// @notice Only allows the controller of the specified project to proceed.
+    function _onlyControllerOf(uint256 projectId) internal view {
+        if (address(DIRECTORY.controllerOf(projectId)) != msg.sender) {
+            revert JBControlled_ControllerUnauthorized(address(DIRECTORY.controllerOf(projectId)));
+        }
+    }
+}

package/src/abstract/JBPermissioned.sol

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Context} from "@openzeppelin/contracts/utils/Context.sol";
+
+import {IJBPermissioned} from "./../interfaces/IJBPermissioned.sol";
+import {IJBPermissions} from "./../interfaces/IJBPermissions.sol";
+
+/// @notice Modifiers to allow access to transactions based on which permissions the message's sender has.
+abstract contract JBPermissioned is Context, IJBPermissioned {
+    //*********************************************************************//
+    // --------------------------- custom errors -------------------------- //
+    //*********************************************************************//
+
+    error JBPermissioned_Unauthorized(address account, address sender, uint256 projectId, uint256 permissionId);
+
+    //*********************************************************************//
+    // ---------------- public immutable stored properties --------------- //
+    //*********************************************************************//
+
+    /// @notice A contract storing permissions.
+    IJBPermissions public immutable override PERMISSIONS;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    /// @param permissions A contract storing permissions.
+    constructor(IJBPermissions permissions) {
+        PERMISSIONS = permissions;
+    }
+
+    //*********************************************************************//
+    // -------------------------- internal views ------------------------- //
+    //*********************************************************************//
+
+    /// @notice Require the message sender to be the account or have the relevant permission.
+    /// @param account The account to allow.
+    /// @param projectId The project ID to check the permission under.
+    /// @param permissionId The required permission ID. The operator must have this permission within the specified
+    /// project ID.
+    function _requirePermissionFrom(address account, uint256 projectId, uint256 permissionId) internal view {
+        address sender = _msgSender();
+        if (
+            sender != account
+                && !PERMISSIONS.hasPermission({
+                    operator: sender,
+                    account: account,
+                    projectId: projectId,
+                    permissionId: permissionId,
+                    includeRoot: true,
+                    includeWildcardProjectId: true
+                })
+        ) revert JBPermissioned_Unauthorized(account, sender, projectId, permissionId);
+    }
+
+    /// @notice If the 'alsoGrantAccessIf' condition is truthy, proceed. Otherwise, require the message sender to be the
+    /// account or
+    /// have the relevant permission.
+    /// @param account The account to allow.
+    /// @param projectId The project ID to check the permission under.
+    /// @param permissionId The required permission ID. The operator must have this permission within the specified
+    /// project ID.
+    /// @param alsoGrantAccessIf An override condition which will allow access regardless of permissions.
+    function _requirePermissionAllowingOverrideFrom(
+        address account,
+        uint256 projectId,
+        uint256 permissionId,
+        bool alsoGrantAccessIf
+    )
+        internal
+        view
+    {
+        if (alsoGrantAccessIf) return;
+        _requirePermissionFrom({account: account, projectId: projectId, permissionId: permissionId});
+    }
+}

package/src/enums/JBApprovalStatus.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice A ruleset's approval status in a ruleset approval hook.
+enum JBApprovalStatus {
+    Empty,
+    Upcoming,
+    Active,
+    ApprovalExpected,
+    Approved,
+    Failed
+}

package/src/interfaces/IJBCashOutHook.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+import {JBAfterCashOutRecordedContext} from "./../structs/JBAfterCashOutRecordedContext.sol";
+
+/// @notice Hook called after a terminal's `cashOutTokensOf(...)` logic completes (if passed by the ruleset's data
+/// hook).
+interface IJBCashOutHook is IERC165 {
+    /// @notice Called by the terminal after a cash out has been recorded in the terminal store.
+    /// @dev Critical business logic should be protected by appropriate access control.
+    /// @param context The context passed in by the terminal, as a `JBAfterCashOutRecordedContext` struct.
+    function afterCashOutRecordedWith(JBAfterCashOutRecordedContext calldata context) external payable;
+}

package/src/interfaces/IJBCashOutTerminal.sol

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJBCashOutHook} from "./IJBCashOutHook.sol";
+import {IJBTerminal} from "./IJBTerminal.sol";
+import {JBAfterCashOutRecordedContext} from "../structs/JBAfterCashOutRecordedContext.sol";
+
+/// @notice A terminal that can be cashed out from.
+interface IJBCashOutTerminal is IJBTerminal {
+    event HookAfterRecordCashOut(
+        IJBCashOutHook indexed hook,
+        JBAfterCashOutRecordedContext context,
+        uint256 specificationAmount,
+        uint256 fee,
+        address caller
+    );
+    event CashOutTokens(
+        uint256 indexed rulesetId,
+        uint256 indexed rulesetCycleNumber,
+        uint256 indexed projectId,
+        address holder,
+        address beneficiary,
+        uint256 cashOutCount,
+        uint256 cashOutTaxRate,
+        uint256 reclaimAmount,
+        bytes metadata,
+        address caller
+    );
+
+    /// @notice Cashes out a holder's tokens for a project, reclaiming the token's proportional share of the project's
+    /// surplus.
+    /// @param holder The address whose tokens are being cashed out.
+    /// @param projectId The ID of the project whose tokens are being cashed out.
+    /// @param cashOutCount The number of project tokens to cash out.
+    /// @param tokenToReclaim The token to reclaim from the project's surplus.
+    /// @param minTokensReclaimed The minimum number of terminal tokens expected to be reclaimed.
+    /// @param beneficiary The address to send the reclaimed tokens to.
+    /// @param metadata Extra data to send to the data hook and cash out hooks.
+    /// @return reclaimAmount The amount of tokens reclaimed from the project's surplus.
+    function cashOutTokensOf(
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        address tokenToReclaim,
+        uint256 minTokensReclaimed,
+        address payable beneficiary,
+        bytes calldata metadata
+    )
+        external
+        returns (uint256 reclaimAmount);
+}

package/src/interfaces/IJBControlled.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJBDirectory} from "./IJBDirectory.sol";
+
+/// @notice A contract that is controlled by a project's controller via the directory.
+interface IJBControlled {
+    /// @notice The directory of terminals and controllers for projects.
+    function DIRECTORY() external view returns (IJBDirectory);
+}