@bananapus/core-v6 0.0.9 → 0.0.10

package/src/interfaces/IJBRulesetDataHook.sol

@@ -14,29 +14,6 @@ import {JBRuleset} from "./../structs/JBRuleset.sol";
 /// @dev If a project's ruleset has `useDataHookForPay` or `useDataHookForCashOut` enabled, its `dataHook` is called by
 /// the terminal upon payments/cash outs (respectively).
 interface IJBRulesetDataHook is IERC165 {
-    /// @notice Returns whether an address has permission to mint a project's tokens on-demand.
-    /// @param projectId The ID of the project whose token can be minted.
-    /// @param ruleset The ruleset to check the token minting permission of.
-    /// @param addr The address to check the token minting permission of.
-    /// @return flag A flag indicating whether the address has permission.
-    function hasMintPermissionFor(
-        uint256 projectId,
-        JBRuleset memory ruleset,
-        address addr
-    )
-        external
-        view
-        returns (bool flag);
-
-    /// @notice Calculates data before a payment is recorded in the terminal store.
-    /// @param context The context passed to this data hook by the `pay(...)` function.
-    /// @return weight The new weight to use, overriding the ruleset's weight.
-    /// @return hookSpecifications The amount and data to send to pay hooks instead of adding to the terminal's balance.
-    function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
-        external
-        view
-        returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications);
-
     /// @notice Calculates data before a cash out is recorded in the terminal store.
     /// @param context The context passed to this data hook by the `cashOutTokensOf(...)` function.
     /// @return cashOutTaxRate The rate determining the reclaimable amount for a given surplus and token supply.
@@ -53,4 +30,27 @@ interface IJBRulesetDataHook is IERC165 {
             uint256 totalSupply,
             JBCashOutHookSpecification[] memory hookSpecifications
         );
+
+    /// @notice Calculates data before a payment is recorded in the terminal store.
+    /// @param context The context passed to this data hook by the `pay(...)` function.
+    /// @return weight The new weight to use, overriding the ruleset's weight.
+    /// @return hookSpecifications The amount and data to send to pay hooks instead of adding to the terminal's balance.
+    function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
+        external
+        view
+        returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications);
+
+    /// @notice Returns whether an address has permission to mint a project's tokens on-demand.
+    /// @param projectId The ID of the project whose token can be minted.
+    /// @param ruleset The ruleset to check the token minting permission of.
+    /// @param addr The address to check the token minting permission of.
+    /// @return flag A flag indicating whether the address has permission.
+    function hasMintPermissionFor(
+        uint256 projectId,
+        JBRuleset memory ruleset,
+        address addr
+    )
+        external
+        view
+        returns (bool flag);
 }

package/src/interfaces/IJBRulesets.sol

@@ -1,15 +1,31 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+import {IJBRulesetApprovalHook} from "./IJBRulesetApprovalHook.sol";
 import {JBApprovalStatus} from "./../enums/JBApprovalStatus.sol";
 import {JBRuleset} from "./../structs/JBRuleset.sol";
-import {IJBRulesetApprovalHook} from "./IJBRulesetApprovalHook.sol";
 
 /// @notice Manages rulesets and queuing for projects.
 interface IJBRulesets {
+    /// @notice A ruleset was initialized from a base ruleset.
+    /// @param rulesetId The ID of the initialized ruleset.
+    /// @param projectId The ID of the project the ruleset belongs to.
+    /// @param basedOnId The ID of the base ruleset the new ruleset was derived from.
+    /// @param caller The address that initialized the ruleset.
     event RulesetInitialized(
         uint256 indexed rulesetId, uint256 indexed projectId, uint256 indexed basedOnId, address caller
     );
+
+    /// @notice A ruleset was queued for a project.
+    /// @param rulesetId The ID of the queued ruleset.
+    /// @param projectId The ID of the project the ruleset was queued for.
+    /// @param duration The duration of the ruleset in seconds.
+    /// @param weight The weight of the ruleset.
+    /// @param weightCutPercent The percent by which the weight decreases each cycle.
+    /// @param approvalHook The approval hook for the ruleset.
+    /// @param metadata The packed ruleset metadata.
+    /// @param mustStartAtOrAfter The earliest time the ruleset can start.
+    /// @param caller The address that queued the ruleset.
     event RulesetQueued(
         uint256 indexed rulesetId,
         uint256 indexed projectId,
@@ -22,12 +38,26 @@ interface IJBRulesets {
         address caller
     );
 
+    /// @notice A ruleset's weight cache was updated.
+    /// @param projectId The ID of the project whose weight cache was updated.
+    /// @param weight The cached weight value.
+    /// @param weightCutMultiple The weight cut multiple used for caching.
+    /// @param caller The address that updated the weight cache.
     event WeightCacheUpdated(uint256 projectId, uint112 weight, uint256 weightCutMultiple, address caller);
 
-    /// @notice Returns the ID of the latest ruleset queued for a project.
-    /// @param projectId The ID of the project to get the latest ruleset ID of.
-    /// @return The latest ruleset ID.
-    function latestRulesetIdOf(uint256 projectId) external view returns (uint256);
+    /// @notice Returns an array of rulesets for a project, sorted from latest to earliest.
+    /// @param projectId The ID of the project to get rulesets of.
+    /// @param startingId The ID of the ruleset to begin with. If 0, the latest ruleset is used.
+    /// @param size The maximum number of rulesets to return.
+    /// @return rulesets The array of rulesets.
+    function allOf(
+        uint256 projectId,
+        uint256 startingId,
+        uint256 size
+    )
+        external
+        view
+        returns (JBRuleset[] memory rulesets);
 
     /// @notice Returns the approval status of the latest queued ruleset relative to the current ruleset.
     /// @param projectId The ID of the project to check.
@@ -39,21 +69,6 @@ interface IJBRulesets {
     /// @return ruleset The current ruleset.
     function currentOf(uint256 projectId) external view returns (JBRuleset memory ruleset);
 
-    /// @notice Derives the cycle number from the base ruleset's parameters and a given start time.
-    /// @param baseRulesetCycleNumber The cycle number of the base ruleset.
-    /// @param baseRulesetStart The start time of the base ruleset.
-    /// @param baseRulesetDuration The duration of the base ruleset.
-    /// @param start The start time to derive the cycle number for.
-    /// @return The derived cycle number.
-    function deriveCycleNumberFrom(
-        uint256 baseRulesetCycleNumber,
-        uint256 baseRulesetStart,
-        uint256 baseRulesetDuration,
-        uint256 start
-    )
-        external
-        returns (uint256);
-
     /// @notice Derives the start time from the base ruleset's parameters.
     /// @param baseRulesetStart The start time of the base ruleset.
     /// @param baseRulesetDuration The duration of the base ruleset.
@@ -105,25 +120,31 @@ interface IJBRulesets {
         view
         returns (JBRuleset memory ruleset, JBApprovalStatus approvalStatus);
 
-    /// @notice Returns an array of rulesets for a project, sorted from latest to earliest.
-    /// @param projectId The ID of the project to get rulesets of.
-    /// @param startingId The ID of the ruleset to begin with. If 0, the latest ruleset is used.
-    /// @param size The maximum number of rulesets to return.
-    /// @return rulesets The array of rulesets.
-    function allOf(
-        uint256 projectId,
-        uint256 startingId,
-        uint256 size
-    )
-        external
-        view
-        returns (JBRuleset[] memory rulesets);
+    /// @notice Returns the ID of the latest ruleset queued for a project.
+    /// @param projectId The ID of the project to get the latest ruleset ID of.
+    /// @return The latest ruleset ID.
+    function latestRulesetIdOf(uint256 projectId) external view returns (uint256);
 
     /// @notice Returns the upcoming ruleset for a project.
     /// @param projectId The ID of the project to get the upcoming ruleset of.
     /// @return ruleset The upcoming ruleset.
     function upcomingOf(uint256 projectId) external view returns (JBRuleset memory ruleset);
 
+    /// @notice Derives the cycle number from the base ruleset's parameters and a given start time.
+    /// @param baseRulesetCycleNumber The cycle number of the base ruleset.
+    /// @param baseRulesetStart The start time of the base ruleset.
+    /// @param baseRulesetDuration The duration of the base ruleset.
+    /// @param start The start time to derive the cycle number for.
+    /// @return The derived cycle number.
+    function deriveCycleNumberFrom(
+        uint256 baseRulesetCycleNumber,
+        uint256 baseRulesetStart,
+        uint256 baseRulesetDuration,
+        uint256 start
+    )
+        external
+        returns (uint256);
+
     /// @notice Queues a new ruleset for a project.
     /// @param projectId The ID of the project to queue the ruleset for.
     /// @param duration The duration of the ruleset in seconds.

package/src/interfaces/IJBSplits.sol

@@ -6,6 +6,12 @@ import {JBSplitGroup} from "./../structs/JBSplitGroup.sol";
 
 /// @notice Stores and manages splits for each project.
 interface IJBSplits {
+    /// @notice A split was set for a project.
+    /// @param projectId The ID of the project the split was set for.
+    /// @param rulesetId The ID of the ruleset the split is active in.
+    /// @param groupId The ID of the split group.
+    /// @param split The split that was set.
+    /// @param caller The address that set the split.
     event SetSplit(
         uint256 indexed projectId, uint256 indexed rulesetId, uint256 indexed groupId, JBSplit split, address caller
     );

package/src/interfaces/IJBTerminal.sol

@@ -9,16 +9,47 @@ import {JBAfterPayRecordedContext} from "../structs/JBAfterPayRecordedContext.so
 
 /// @notice A terminal that accepts payments and can be migrated.
 interface IJBTerminal is IERC165 {
+    /// @notice Funds were added to a project's balance.
+    /// @param projectId The ID of the project that received the funds.
+    /// @param amount The amount of tokens added.
+    /// @param returnedFees The amount of fees returned.
+    /// @param memo A memo associated with the addition.
+    /// @param metadata Extra metadata associated with the addition.
+    /// @param caller The address that added the funds.
     event AddToBalance(
         uint256 indexed projectId, uint256 amount, uint256 returnedFees, string memo, bytes metadata, address caller
     );
+
+    /// @notice A pay hook was called after a payment was recorded.
+    /// @param hook The pay hook that was called.
+    /// @param context The context passed to the hook.
+    /// @param specificationAmount The amount specified for the hook.
+    /// @param caller The address that called the pay function.
     event HookAfterRecordPay(
         IJBPayHook indexed hook, JBAfterPayRecordedContext context, uint256 specificationAmount, address caller
     );
 
+    /// @notice A project's balance was migrated to another terminal.
+    /// @param projectId The ID of the project that was migrated.
+    /// @param token The token that was migrated.
+    /// @param to The terminal the balance was migrated to.
+    /// @param amount The amount of tokens migrated.
+    /// @param caller The address that called the migrate function.
     event MigrateTerminal(
         uint256 indexed projectId, address indexed token, IJBTerminal indexed to, uint256 amount, address caller
     );
+
+    /// @notice A payment was made to a project.
+    /// @param rulesetId The ID of the ruleset during the payment.
+    /// @param rulesetCycleNumber The cycle number of the ruleset during the payment.
+    /// @param projectId The ID of the project that received the payment.
+    /// @param payer The address that made the payment.
+    /// @param beneficiary The address that received the project tokens.
+    /// @param amount The amount of tokens paid.
+    /// @param newlyIssuedTokenCount The number of project tokens minted.
+    /// @param memo A memo associated with the payment.
+    /// @param metadata Extra metadata associated with the payment.
+    /// @param caller The address that called the pay function.
     event Pay(
         uint256 indexed rulesetId,
         uint256 indexed rulesetCycleNumber,
@@ -31,6 +62,11 @@ interface IJBTerminal is IERC165 {
         bytes metadata,
         address caller
     );
+
+    /// @notice An accounting context was set for a project's token.
+    /// @param projectId The ID of the project the accounting context was set for.
+    /// @param context The accounting context that was set.
+    /// @param caller The address that set the accounting context.
     event SetAccountingContext(uint256 indexed projectId, JBAccountingContext context, address caller);
 
     /// @notice Returns the accounting context for a project's token.

package/src/interfaces/IJBTerminalStore.sol

@@ -29,42 +29,6 @@ interface IJBTerminalStore {
     /// @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.
@@ -133,12 +97,75 @@ interface IJBTerminalStore {
         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 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 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 payment to a project.
     /// @param payer The address of the payer.
     /// @param amount The amount being paid.
@@ -174,33 +201,6 @@ interface IJBTerminalStore {
         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.

package/src/interfaces/IJBToken.sol

@@ -21,17 +21,17 @@ interface IJBToken {
     /// @return The total supply.
     function totalSupply() external view returns (uint256);
 
+    /// @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 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.

package/src/interfaces/IJBTokens.sol

@@ -5,9 +5,13 @@ 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
-    );
+    /// @notice Tokens or credits were burned from a holder's balance.
+    /// @param holder The address whose tokens were burned.
+    /// @param projectId The ID of the project whose tokens were burned.
+    /// @param count The number of tokens burned.
+    /// @param creditBalance The holder's remaining credit balance after the burn.
+    /// @param tokenBalance The holder's remaining token balance after the burn.
+    /// @param caller The address that called the burn function.
     event Burn(
         address indexed holder,
         uint256 indexed projectId,
@@ -16,6 +20,14 @@ interface IJBTokens {
         uint256 tokenBalance,
         address caller
     );
+
+    /// @notice Credits were claimed as ERC-20 tokens.
+    /// @param holder The address whose credits were claimed.
+    /// @param projectId The ID of the project whose tokens were claimed.
+    /// @param creditBalance The holder's remaining credit balance after the claim.
+    /// @param count The number of tokens claimed.
+    /// @param beneficiary The address that received the claimed tokens.
+    /// @param caller The address that called the claim function.
     event ClaimTokens(
         address indexed holder,
         uint256 indexed projectId,
@@ -24,10 +36,40 @@ interface IJBTokens {
         address beneficiary,
         address caller
     );
+
+    /// @notice An ERC-20 token was deployed for a project.
+    /// @param projectId The ID of the project the token was deployed for.
+    /// @param token The deployed token.
+    /// @param name The token's name.
+    /// @param symbol The token's symbol.
+    /// @param salt The salt used for deterministic deployment.
+    /// @param caller The address that deployed the token.
+    event DeployERC20(
+        uint256 indexed projectId, IJBToken indexed token, string name, string symbol, bytes32 salt, address caller
+    );
+
+    /// @notice Tokens or credits were minted for a holder.
+    /// @param holder The address that received the minted tokens.
+    /// @param projectId The ID of the project whose tokens were minted.
+    /// @param count The number of tokens minted.
+    /// @param tokensWereClaimed Whether the tokens were claimed as ERC-20 tokens.
+    /// @param caller The address that called the mint function.
     event Mint(
         address indexed holder, uint256 indexed projectId, uint256 count, bool tokensWereClaimed, address caller
     );
+
+    /// @notice A project's token was set.
+    /// @param projectId The ID of the project whose token was set.
+    /// @param token The token that was set.
+    /// @param caller The address that set the token.
     event SetToken(uint256 indexed projectId, IJBToken indexed token, address caller);
+
+    /// @notice Credits were transferred from one holder to another.
+    /// @param holder The address that transferred the credits.
+    /// @param projectId The ID of the project whose credits were transferred.
+    /// @param recipient The address that received the credits.
+    /// @param count The number of credits transferred.
+    /// @param caller The address that called the transfer function.
     event TransferCredits(
         address indexed holder, uint256 indexed projectId, address indexed recipient, uint256 count, address caller
     );
@@ -48,17 +90,17 @@ interface IJBTokens {
     /// @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 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 supply (tokens + credits) for a project.
     /// @param projectId The ID of the project to get the total supply of.
     /// @return The total supply.

package/test/TestDurationUnderflow.sol

@@ -110,8 +110,9 @@ contract TestDurationUnderflow is TestBaseWorkflow {
     }
 
     /// @notice Normal case: duration < block.timestamp. No underflow even without the fix.
-    function test_harness_normalDuration_noUnderflow() public view {
-        // block_timestamp = 1643802347 >> 7 days. Normal case.
+    function test_harness_normalDuration_noUnderflow() public {
+        // Warp to a realistic timestamp so that `block.timestamp - 30 days` doesn't underflow.
+        vm.warp(1_643_802_347);
         JBRuleset memory base =
             _makeBaseRuleset({start: uint48(block.timestamp - 30 days), duration: uint32(7 days), weight: 1000e18});