@bananapus/core-v6 0.0.1

package/src/interfaces/IJBTerminal.sol

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+import {IJBPayHook} from "./IJBPayHook.sol";
+import {JBAccountingContext} from "../structs/JBAccountingContext.sol";
+import {JBAfterPayRecordedContext} from "../structs/JBAfterPayRecordedContext.sol";
+
+/// @notice A terminal that accepts payments and can be migrated.
+interface IJBTerminal is IERC165 {
+    event AddToBalance(
+        uint256 indexed projectId, uint256 amount, uint256 returnedFees, string memo, bytes metadata, address caller
+    );
+    event HookAfterRecordPay(
+        IJBPayHook indexed hook, JBAfterPayRecordedContext context, uint256 specificationAmount, address caller
+    );
+
+    event MigrateTerminal(
+        uint256 indexed projectId, address indexed token, IJBTerminal indexed to, uint256 amount, address caller
+    );
+    event Pay(
+        uint256 indexed rulesetId,
+        uint256 indexed rulesetCycleNumber,
+        uint256 indexed projectId,
+        address payer,
+        address beneficiary,
+        uint256 amount,
+        uint256 newlyIssuedTokenCount,
+        string memo,
+        bytes metadata,
+        address caller
+    );
+    event SetAccountingContext(uint256 indexed projectId, JBAccountingContext context, address caller);
+
+    /// @notice Returns the accounting context for a project's token.
+    /// @param projectId The ID of the project to get the accounting context of.
+    /// @param token The token to get the accounting context for.
+    /// @return The accounting context for the project's token.
+    function accountingContextForTokenOf(
+        uint256 projectId,
+        address token
+    )
+        external
+        view
+        returns (JBAccountingContext memory);
+
+    /// @notice Returns all accounting contexts for a project.
+    /// @param projectId The ID of the project to get the accounting contexts of.
+    /// @return The accounting contexts for the project.
+    function accountingContextsOf(uint256 projectId) external view returns (JBAccountingContext[] memory);
+
+    /// @notice Returns a project's current surplus for a set of accounting contexts.
+    /// @param projectId The ID of the project to get the surplus of.
+    /// @param accountingContexts The accounting contexts to include in the surplus calculation.
+    /// @param decimals The number of decimals to express the surplus with.
+    /// @param currency The currency to express the surplus in.
+    /// @return The project's current surplus.
+    function currentSurplusOf(
+        uint256 projectId,
+        JBAccountingContext[] memory accountingContexts,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Adds accounting contexts for a project's tokens.
+    /// @param projectId The ID of the project to add accounting contexts for.
+    /// @param accountingContexts The accounting contexts to add.
+    function addAccountingContextsFor(uint256 projectId, JBAccountingContext[] calldata accountingContexts) external;
+
+    /// @notice Adds funds to a project's balance.
+    /// @param projectId The ID of the project to add funds to.
+    /// @param token The token being added.
+    /// @param amount The amount of tokens being added.
+    /// @param shouldReturnHeldFees Whether held fees should be returned based on the amount added.
+    /// @param memo A memo to pass along to the emitted event.
+    /// @param metadata Extra data to pass along to the emitted event.
+    function addToBalanceOf(
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        bool shouldReturnHeldFees,
+        string calldata memo,
+        bytes calldata metadata
+    )
+        external
+        payable;
+
+    /// @notice Migrates a project's funds from this terminal to another.
+    /// @param projectId The ID of the project being migrated.
+    /// @param token The address of the token being migrated.
+    /// @param to The terminal to migrate to.
+    /// @return balance The amount of funds that were migrated.
+    function migrateBalanceOf(uint256 projectId, address token, IJBTerminal to) external returns (uint256 balance);
+
+    /// @notice Pays a project in a specified token.
+    /// @param projectId The ID of the project being paid.
+    /// @param token The token being paid in.
+    /// @param amount The amount of tokens being paid.
+    /// @param beneficiary The address to mint project tokens to.
+    /// @param minReturnedTokens The minimum number of project tokens expected in return.
+    /// @param memo A memo to pass along to the emitted event.
+    /// @param metadata Extra data to pass along to the pay hooks.
+    /// @return beneficiaryTokenCount The number of tokens minted for the beneficiary.
+    function pay(
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        address beneficiary,
+        uint256 minReturnedTokens,
+        string calldata memo,
+        bytes calldata metadata
+    )
+        external
+        payable
+        returns (uint256 beneficiaryTokenCount);
+}

package/src/interfaces/IJBTerminalStore.sol

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJBDirectory} from "./IJBDirectory.sol";
+import {IJBPrices} from "./IJBPrices.sol";
+import {IJBRulesets} from "./IJBRulesets.sol";
+import {IJBTerminal} from "./IJBTerminal.sol";
+import {JBAccountingContext} from "./../structs/JBAccountingContext.sol";
+import {JBCashOutHookSpecification} from "./../structs/JBCashOutHookSpecification.sol";
+import {JBPayHookSpecification} from "./../structs/JBPayHookSpecification.sol";
+import {JBRuleset} from "./../structs/JBRuleset.sol";
+import {JBTokenAmount} from "./../structs/JBTokenAmount.sol";
+
+/// @notice Manages the bookkeeping for payments, cash outs, payouts, and surplus allowance usage for terminals.
+interface IJBTerminalStore {
+    /// @notice The directory of terminals and controllers for projects.
+    function DIRECTORY() external view returns (IJBDirectory);
+
+    /// @notice The contract that stores prices for each project.
+    function PRICES() external view returns (IJBPrices);
+
+    /// @notice The contract storing and managing project rulesets.
+    function RULESETS() external view returns (IJBRulesets);
+
+    /// @notice Returns the balance of a terminal for a project and token.
+    /// @param terminal The terminal to get the balance of.
+    /// @param projectId The ID of the project to get the balance for.
+    /// @param token The token to get the balance of.
+    /// @return The balance.
+    function balanceOf(address terminal, uint256 projectId, address token) external view returns (uint256);
+
+    /// @notice Returns the amount of payout limit used by a terminal for a project in a given cycle.
+    /// @param terminal The terminal to get the used payout limit of.
+    /// @param projectId The ID of the project.
+    /// @param token The token the payout limit is denominated in.
+    /// @param rulesetCycleNumber The cycle number to get the used payout limit for.
+    /// @param currency The currency the payout limit is denominated in.
+    /// @return The amount of payout limit used.
+    function usedPayoutLimitOf(
+        address terminal,
+        uint256 projectId,
+        address token,
+        uint256 rulesetCycleNumber,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Returns the amount of surplus allowance used by a terminal for a project in a given ruleset.
+    /// @param terminal The terminal to get the used surplus allowance of.
+    /// @param projectId The ID of the project.
+    /// @param token The token the surplus allowance is denominated in.
+    /// @param rulesetId The ID of the ruleset to get the used surplus allowance for.
+    /// @param currency The currency the surplus allowance is denominated in.
+    /// @return The amount of surplus allowance used.
+    function usedSurplusAllowanceOf(
+        address terminal,
+        uint256 projectId,
+        address token,
+        uint256 rulesetId,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Returns the reclaimable surplus for a project given a cash-out count, total supply, and surplus.
+    /// @param projectId The ID of the project.
+    /// @param cashOutCount The number of tokens being cashed out.
+    /// @param totalSupply The total token supply.
+    /// @param surplus The project's surplus.
+    /// @return The reclaimable surplus amount.
+    function currentReclaimableSurplusOf(
+        uint256 projectId,
+        uint256 cashOutCount,
+        uint256 totalSupply,
+        uint256 surplus
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Returns the reclaimable surplus for a project across multiple terminals.
+    /// @param projectId The ID of the project.
+    /// @param cashOutCount The number of tokens being cashed out.
+    /// @param terminals The terminals to include in the surplus calculation.
+    /// @param accountingContexts The accounting contexts to include.
+    /// @param decimals The number of decimals to express the result with.
+    /// @param currency The currency to express the result in.
+    /// @return The reclaimable surplus amount.
+    function currentReclaimableSurplusOf(
+        uint256 projectId,
+        uint256 cashOutCount,
+        IJBTerminal[] calldata terminals,
+        JBAccountingContext[] calldata accountingContexts,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Returns the current surplus for a terminal and project.
+    /// @param terminal The terminal to get the surplus of.
+    /// @param projectId The ID of the project.
+    /// @param accountingContexts The accounting contexts to include.
+    /// @param decimals The number of decimals to express the result with.
+    /// @param currency The currency to express the result in.
+    /// @return The current surplus.
+    function currentSurplusOf(
+        address terminal,
+        uint256 projectId,
+        JBAccountingContext[] calldata accountingContexts,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Returns the current total surplus for a project across all terminals.
+    /// @param projectId The ID of the project.
+    /// @param decimals The number of decimals to express the result with.
+    /// @param currency The currency to express the result in.
+    /// @return The current total surplus.
+    function currentTotalSurplusOf(
+        uint256 projectId,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Records a balance addition for a project.
+    /// @param projectId The ID of the project.
+    /// @param token The token being added.
+    /// @param amount The amount being added.
+    function recordAddedBalanceFor(uint256 projectId, address token, uint256 amount) external;
+
+    /// @notice Records a payment to a project.
+    /// @param payer The address of the payer.
+    /// @param amount The amount being paid.
+    /// @param projectId The ID of the project being paid.
+    /// @param beneficiary The address to mint project tokens to.
+    /// @param metadata Extra data to pass along to the data hook.
+    /// @return ruleset The project's current ruleset.
+    /// @return tokenCount The number of project tokens minted.
+    /// @return hookSpecifications Any pay hook specifications from the data hook.
+    function recordPaymentFrom(
+        address payer,
+        JBTokenAmount memory amount,
+        uint256 projectId,
+        address beneficiary,
+        bytes calldata metadata
+    )
+        external
+        returns (JBRuleset memory ruleset, uint256 tokenCount, JBPayHookSpecification[] memory hookSpecifications);
+
+    /// @notice Records a payout from a project.
+    /// @param projectId The ID of the project paying out.
+    /// @param accountingContext The accounting context of the token being paid out.
+    /// @param amount The amount being paid out.
+    /// @param currency The currency the amount is denominated in.
+    /// @return ruleset The project's current ruleset.
+    /// @return amountPaidOut The amount paid out in the token's native decimals.
+    function recordPayoutFor(
+        uint256 projectId,
+        JBAccountingContext calldata accountingContext,
+        uint256 amount,
+        uint256 currency
+    )
+        external
+        returns (JBRuleset memory ruleset, uint256 amountPaidOut);
+
+    /// @notice Records a cash out from a project.
+    /// @param holder The address cashing out.
+    /// @param projectId The ID of the project being cashed out from.
+    /// @param cashOutCount The number of project tokens being cashed out.
+    /// @param accountingContext The accounting context of the token being reclaimed.
+    /// @param balanceAccountingContexts The accounting contexts to include in the balance calculation.
+    /// @param metadata Extra data to pass along to the data hook.
+    /// @return ruleset The project's current ruleset.
+    /// @return reclaimAmount The amount reclaimed.
+    /// @return cashOutTaxRate The cash out tax rate applied.
+    /// @return hookSpecifications Any cash out hook specifications from the data hook.
+    function recordCashOutFor(
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        JBAccountingContext calldata accountingContext,
+        JBAccountingContext[] calldata balanceAccountingContexts,
+        bytes calldata metadata
+    )
+        external
+        returns (
+            JBRuleset memory ruleset,
+            uint256 reclaimAmount,
+            uint256 cashOutTaxRate,
+            JBCashOutHookSpecification[] memory hookSpecifications
+        );
+
+    /// @notice Records a terminal migration for a project.
+    /// @param projectId The ID of the project being migrated.
+    /// @param token The token being migrated.
+    /// @return balance The balance that was migrated.
+    function recordTerminalMigration(uint256 projectId, address token) external returns (uint256 balance);
+
+    /// @notice Records surplus allowance usage for a project.
+    /// @param projectId The ID of the project using surplus allowance.
+    /// @param accountingContext The accounting context of the token being used.
+    /// @param amount The amount of surplus allowance to use.
+    /// @param currency The currency the amount is denominated in.
+    /// @return ruleset The project's current ruleset.
+    /// @return usedAmount The amount used in the token's native decimals.
+    function recordUsedAllowanceOf(
+        uint256 projectId,
+        JBAccountingContext calldata accountingContext,
+        uint256 amount,
+        uint256 currency
+    )
+        external
+        returns (JBRuleset memory ruleset, uint256 usedAmount);
+}

package/src/interfaces/IJBToken.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice A token that can be used by a project in the Juicebox ecosystem.
+interface IJBToken {
+    /// @notice Returns the balance of an account.
+    /// @param account The account to get the balance of.
+    /// @return The number of tokens owned by the account.
+    function balanceOf(address account) external view returns (uint256);
+
+    /// @notice Returns whether this token can be added to a given project.
+    /// @param projectId The ID of the project to check.
+    /// @return A flag indicating whether the token can be added.
+    function canBeAddedTo(uint256 projectId) external view returns (bool);
+
+    /// @notice Returns the number of decimals used by the token.
+    /// @return The number of decimals.
+    function decimals() external view returns (uint8);
+
+    /// @notice Returns the total supply of the token.
+    /// @return The total supply.
+    function totalSupply() external view returns (uint256);
+
+    /// @notice Initializes the token with a name, symbol, and owner.
+    /// @param name The token's name.
+    /// @param symbol The token's symbol.
+    /// @param owner The token contract's owner.
+    function initialize(string memory name, string memory symbol, address owner) external;
+
+    /// @notice Burns tokens from an account.
+    /// @param account The address to burn tokens from.
+    /// @param amount The amount of tokens to burn.
+    function burn(address account, uint256 amount) external;
+
+    /// @notice Mints tokens to an account.
+    /// @param account The address to mint tokens to.
+    /// @param amount The amount of tokens to mint.
+    function mint(address account, uint256 amount) external;
+}

package/src/interfaces/IJBTokenUriResolver.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice Resolves token URIs for project NFTs.
+interface IJBTokenUriResolver {
+    /// @notice Returns the token URI for a project.
+    /// @param projectId The ID of the project to get the token URI of.
+    /// @return tokenUri The token URI.
+    function getUri(uint256 projectId) external view returns (string memory tokenUri);
+}

package/src/interfaces/IJBTokens.sol

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJBToken} from "./IJBToken.sol";
+
+/// @notice Manages minting, burning, and balances of projects' tokens and token credits.
+interface IJBTokens {
+    event DeployERC20(
+        uint256 indexed projectId, IJBToken indexed token, string name, string symbol, bytes32 salt, address caller
+    );
+    event Burn(
+        address indexed holder,
+        uint256 indexed projectId,
+        uint256 count,
+        uint256 creditBalance,
+        uint256 tokenBalance,
+        address caller
+    );
+    event ClaimTokens(
+        address indexed holder,
+        uint256 indexed projectId,
+        uint256 creditBalance,
+        uint256 count,
+        address beneficiary,
+        address caller
+    );
+    event Mint(
+        address indexed holder, uint256 indexed projectId, uint256 count, bool tokensWereClaimed, address caller
+    );
+    event SetToken(uint256 indexed projectId, IJBToken indexed token, address caller);
+    event TransferCredits(
+        address indexed holder, uint256 indexed projectId, address indexed recipient, uint256 count, address caller
+    );
+
+    /// @notice Returns the credit balance for a holder and project.
+    /// @param holder The address to get the credit balance of.
+    /// @param projectId The ID of the project to get the credit balance for.
+    /// @return The credit balance.
+    function creditBalanceOf(address holder, uint256 projectId) external view returns (uint256);
+
+    /// @notice Returns the project ID associated with a token.
+    /// @param token The token to get the project ID of.
+    /// @return The project ID.
+    function projectIdOf(IJBToken token) external view returns (uint256);
+
+    /// @notice Returns the token for a project.
+    /// @param projectId The ID of the project to get the token of.
+    /// @return The project's token.
+    function tokenOf(uint256 projectId) external view returns (IJBToken);
+
+    /// @notice Returns the total credit supply for a project.
+    /// @param projectId The ID of the project to get the total credit supply of.
+    /// @return The total credit supply.
+    function totalCreditSupplyOf(uint256 projectId) external view returns (uint256);
+
+    /// @notice Returns the total balance (tokens + credits) for a holder and project.
+    /// @param holder The address to get the total balance of.
+    /// @param projectId The ID of the project to get the total balance for.
+    /// @return balance The combined token and credit balance.
+    function totalBalanceOf(address holder, uint256 projectId) external view returns (uint256 balance);
+
+    /// @notice Returns the total supply (tokens + credits) for a project.
+    /// @param projectId The ID of the project to get the total supply of.
+    /// @return The total supply.
+    function totalSupplyOf(uint256 projectId) external view returns (uint256);
+
+    /// @notice Burns tokens and/or credits from a holder's balance.
+    /// @param holder The address to burn tokens from.
+    /// @param projectId The ID of the project whose tokens are being burned.
+    /// @param count The number of tokens to burn.
+    function burnFrom(address holder, uint256 projectId, uint256 count) external;
+
+    /// @notice Claims tokens from a holder's credits into a beneficiary's account.
+    /// @param holder The address to claim credits from.
+    /// @param projectId The ID of the project whose tokens are being claimed.
+    /// @param count The number of tokens to claim.
+    /// @param beneficiary The address to send the claimed tokens to.
+    function claimTokensFor(address holder, uint256 projectId, uint256 count, address beneficiary) external;
+
+    /// @notice Deploys an ERC-20 token for a project.
+    /// @param projectId The ID of the project to deploy the ERC-20 for.
+    /// @param name The ERC-20's name.
+    /// @param symbol The ERC-20's symbol.
+    /// @param salt The salt used for deterministic clone deployment.
+    /// @return token The deployed token.
+    function deployERC20For(
+        uint256 projectId,
+        string calldata name,
+        string calldata symbol,
+        bytes32 salt
+    )
+        external
+        returns (IJBToken token);
+
+    /// @notice Mints tokens or credits for a holder.
+    /// @param holder The address to mint tokens for.
+    /// @param projectId The ID of the project whose tokens are being minted.
+    /// @param count The number of tokens to mint.
+    /// @return token The project's token, if one exists.
+    function mintFor(address holder, uint256 projectId, uint256 count) external returns (IJBToken token);
+
+    /// @notice Sets a project's token.
+    /// @param projectId The ID of the project to set the token of.
+    /// @param token The token to set.
+    function setTokenFor(uint256 projectId, IJBToken token) external;
+
+    /// @notice Transfers credits from one holder to another.
+    /// @param holder The address to transfer credits from.
+    /// @param projectId The ID of the project whose credits are being transferred.
+    /// @param recipient The address to transfer credits to.
+    /// @param count The number of credits to transfer.
+    function transferCreditsFrom(address holder, uint256 projectId, address recipient, uint256 count) external;
+}

package/src/libraries/JBCashOuts.sol

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+import {mulDiv} from "@prb/math/src/Common.sol";
+
+import {JBConstants} from "./JBConstants.sol";
+
+/// @notice Cash out calculations.
+library JBCashOuts {
+    /// @notice Thrown when the desired output cannot be achieved (e.g., cash out tax rate is 100%).
+    error JBCashOuts_DesiredOutputNotAchievable();
+
+    /// @notice Returns the amount of surplus terminal tokens which can be reclaimed based on the total surplus, the
+    /// number of tokens being cashed out, the total token supply, and the ruleset's cash out tax rate.
+    /// @param surplus The total amount of surplus terminal tokens.
+    /// @param cashOutCount The number of tokens being cashed out, as a fixed point number with 18 decimals.
+    /// @param totalSupply The total token supply, as a fixed point number with 18 decimals.
+    /// @param cashOutTaxRate The current ruleset's cash out tax rate.
+    /// @return reclaimableSurplus The amount of surplus tokens that can be reclaimed.
+    function cashOutFrom(
+        uint256 surplus,
+        uint256 cashOutCount,
+        uint256 totalSupply,
+        uint256 cashOutTaxRate
+    )
+        internal
+        pure
+        returns (uint256)
+    {
+        // If nothing is being cashed out, nothing can be reclaimed.
+        if (cashOutCount == 0) return 0;
+
+        // If the cash out tax rate is the max, no surplus can be reclaimed.
+        if (cashOutTaxRate == JBConstants.MAX_CASH_OUT_TAX_RATE) return 0;
+
+        // If the total supply is being cashed out, return the entire surplus.
+        if (cashOutCount >= totalSupply) return surplus;
+
+        // Get a reference to the linear proportion.
+        uint256 base = mulDiv(surplus, cashOutCount, totalSupply);
+
+        // These conditions are all part of the same curve.
+        // Edge conditions are separated to minimize the operations performed in those cases.
+        if (cashOutTaxRate == 0) {
+            return base;
+        }
+
+        return mulDiv(
+            base,
+            (JBConstants.MAX_CASH_OUT_TAX_RATE - cashOutTaxRate) + mulDiv(cashOutTaxRate, cashOutCount, totalSupply),
+            JBConstants.MAX_CASH_OUT_TAX_RATE
+        );
+    }
+
+    /// @notice Returns the minimum number of tokens that must be cashed out to receive at least `desiredOutput` of
+    /// surplus terminal tokens. This is the inverse of `cashOutFrom`.
+    /// @dev Due to integer rounding in `cashOutFrom`, the returned count may yield slightly more than `desiredOutput`.
+    /// When `desiredOutput >= surplus`, returns `totalSupply` (cashing out everything yields the full surplus).
+    /// @param surplus The total amount of surplus terminal tokens.
+    /// @param desiredOutput The minimum amount of surplus tokens the caller wants to receive.
+    /// @param totalSupply The total token supply, as a fixed point number with 18 decimals.
+    /// @param cashOutTaxRate The current ruleset's cash out tax rate.
+    /// @return count The minimum number of tokens to cash out.
+    function minCashOutCountFor(
+        uint256 surplus,
+        uint256 desiredOutput,
+        uint256 totalSupply,
+        uint256 cashOutTaxRate
+    )
+        internal
+        pure
+        returns (uint256)
+    {
+        // If no output is desired, no tokens need to be cashed out.
+        if (desiredOutput == 0) return 0;
+
+        // If the cash out tax rate is at maximum, no output is achievable.
+        if (cashOutTaxRate == JBConstants.MAX_CASH_OUT_TAX_RATE) {
+            revert JBCashOuts_DesiredOutputNotAchievable();
+        }
+
+        // If the desired output meets or exceeds the surplus, the entire supply must be cashed out.
+        if (desiredOutput >= surplus) return totalSupply;
+
+        // Linear case (no tax): out = surplus * c / totalSupply, so c = ceil(out * totalSupply / surplus).
+        if (cashOutTaxRate == 0) {
+            uint256 count = mulDiv(desiredOutput, totalSupply, surplus);
+            // Round up if the floor division undershoots.
+            if (mulDiv(surplus, count, totalSupply) < desiredOutput) count++;
+            return count;
+        }
+
+        // General case: binary search for the minimum c such that
+        // cashOutFrom(surplus, c, totalSupply, cashOutTaxRate) >= desiredOutput.
+        //
+        // The forward formula out = (S*c/T) * [(m-r) + r*c/T] / m is monotonically non-decreasing in c,
+        // so binary search is valid. We know:
+        //   - cashOutFrom(surplus, 0, totalSupply, r) = 0 < desiredOutput
+        //   - cashOutFrom(surplus, totalSupply, totalSupply, r) = surplus > desiredOutput
+        // so a valid answer always exists in [1, totalSupply].
+
+        uint256 lo = 1;
+        uint256 hi = totalSupply;
+
+        while (lo < hi) {
+            uint256 mid = lo + (hi - lo) / 2;
+            if (
+                cashOutFrom({
+                        surplus: surplus, cashOutCount: mid, totalSupply: totalSupply, cashOutTaxRate: cashOutTaxRate
+                    }) >= desiredOutput
+            ) {
+                hi = mid;
+            } else {
+                lo = mid + 1;
+            }
+        }
+
+        return lo;
+    }
+}

package/src/libraries/JBConstants.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice Global constants used across Juicebox contracts.
+library JBConstants {
+    /// @notice Each chain's native token address in Juicebox is represented by
+    /// 0x000000000000000000000000000000000000EEEe.
+    address public constant NATIVE_TOKEN = address(0x000000000000000000000000000000000000EEEe);
+    uint16 public constant MAX_RESERVED_PERCENT = 10_000;
+    uint16 public constant MAX_CASH_OUT_TAX_RATE = 10_000;
+    uint32 public constant MAX_WEIGHT_CUT_PERCENT = 1_000_000_000;
+    uint32 public constant SPLITS_TOTAL_PERCENT = 1_000_000_000;
+    uint16 public constant MAX_FEE = 1000;
+}

package/src/libraries/JBCurrencyIds.sol

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+library JBCurrencyIds {
+    uint32 public constant ETH = 1;
+    uint32 public constant USD = 2;
+}