@bananapus/core-v6 0.0.38 → 0.0.40

package/src/structs/JBAfterPayRecordedContext.sol

@@ -4,12 +4,12 @@ pragma solidity ^0.8.0;
 import {JBTokenAmount} from "./JBTokenAmount.sol";
 
 /// @custom:member payer The address the payment originated from.
-/// @custom:member projectId The ID of the project being paid.
-/// @custom:member rulesetId The ID of the ruleset the payment is being made during.
-/// @custom:member amount The payment's token amount. Includes the token being paid, the value, the number of decimals
+/// @custom:member projectId The ID of the project to pay.
+/// @custom:member rulesetId The ID of the ruleset the payment is made during.
+/// @custom:member amount The payment's token amount. Includes the token paid, the value, the number of decimals
 /// included, and the currency of the amount.
-/// @custom:member forwardedAmount The token amount being forwarded to the pay hook. Includes the token
-/// being paid, the value, the number of decimals included, and the currency of the amount.
+/// @custom:member forwardedAmount The token amount forwarded to the pay hook. Includes the token
+/// paid, the value, the number of decimals included, and the currency of the amount.
 /// @custom:member weight The current ruleset's weight (used to determine how many tokens should be minted).
 /// @custom:member newlyIssuedTokenCount The number of project tokens minted for the beneficiary.
 /// @custom:member beneficiary The address which receives any tokens this payment yields.

package/src/structs/JBBeforeCashOutRecordedContext.sol

@@ -5,17 +5,17 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 
 /// @notice Context sent from the terminal to the ruleset's data hook upon cash out.
 /// @custom:member terminal The terminal that is facilitating the cash out.
-/// @custom:member holder The holder of the tokens being cashed out.
-/// @custom:member projectId The ID of the project whose tokens are being cashed out.
-/// @custom:member rulesetId The ID of the ruleset the cash out is being made during.
-/// @custom:member cashOutCount The number of tokens being cashed out, as a fixed point number with 18 decimals.
-/// @custom:member totalSupply The total token supply being used for the calculation, as a fixed point number with 18
+/// @custom:member holder The holder of the tokens to cash out.
+/// @custom:member projectId The ID of the project cashing out tokens.
+/// @custom:member rulesetId The ID of the ruleset the cash out is made during.
+/// @custom:member cashOutCount The number of tokens to cash out, as a fixed point number with 18 decimals.
+/// @custom:member totalSupply The total token supply to use for the calculation, as a fixed point number with 18
 /// decimals.
 /// @custom:member surplus The surplus amount used for the calculation, as a fixed point number with 18 decimals.
 /// Includes the token of the surplus, the surplus value, the number of decimals
 /// included, and the currency of the surplus.
-/// @custom:member useTotalSurplus If surplus across all of a project's terminals is being used when making cash outs.
-/// @custom:member cashOutTaxRate The cash out tax rate of the ruleset the cash out is being made during.
+/// @custom:member useTotalSurplus If true, use surplus across all of a project's terminals when calculating cash outs.
+/// @custom:member cashOutTaxRate The cash out tax rate of the ruleset the cash out is made during.
 /// @custom:member beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Useful for data hooks
 /// that charge their own fees — they can skip fees when value stays in the protocol (e.g. project-to-project
 /// routing).

package/src/structs/JBBeforePayRecordedContext.sol

@@ -6,14 +6,14 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// @notice Context sent from the terminal to the ruleset's data hook upon payment.
 /// @custom:member terminal The terminal that is facilitating the payment.
 /// @custom:member payer The address that the payment originated from.
-/// @custom:member amount The payment's token amount, including the token being paid, the value, the number of decimals
+/// @custom:member amount The payment's token amount, including the token paid, the value, the number of decimals
 /// included, and the currency of the amount.
-/// @custom:member projectId The ID of the project being paid.
-/// @custom:member rulesetId The ID of the ruleset the payment is being made during.
+/// @custom:member projectId The ID of the project to pay.
+/// @custom:member rulesetId The ID of the ruleset the payment is made during.
 /// @custom:member beneficiary The specified address that should be the beneficiary of anything that this payment
 /// yields.
-/// @custom:member weight The weight of the ruleset during which the payment is being made.
-/// @custom:member reservedPercent The reserved percent of the ruleset the payment is being made during.
+/// @custom:member weight The weight of the ruleset during which the payment is made.
+/// @custom:member reservedPercent The reserved percent of the ruleset the payment is made during.
 /// @custom:member metadata Extra data specified by the payer.
 struct JBBeforePayRecordedContext {
     address terminal;

package/src/structs/JBFundAccessLimitGroup.sol

@@ -3,23 +3,16 @@ pragma solidity ^0.8.0;
 
 import {JBCurrencyAmount} from "./JBCurrencyAmount.sol";
 
-/// @dev Payout limit example: if the `amount` is 5, the `currency` is 1 (USD), and the terminal's token is ETH, then
-/// the project can pay out 5 USD worth of ETH during a ruleset.
-/// @dev Surplus allowance example: if the `amount` is 5, the `currency` is 1 (USD), and the terminal's token is ETH,
-/// then the project can pay out 5 USD worth of ETH from its surplus during a ruleset. A project's surplus is its
-/// balance minus its current combined payout limit.
-/// @dev If a project has multiple payout limits or surplus allowances, they are all available. They can all be used
-/// during a single ruleset.
-/// @dev The payout limits' and surplus allowances' fixed point amounts have the same number of decimals as the
-/// terminal.
-/// @custom:member terminal The terminal that the payout limits and surplus allowances apply to.
-/// @custom:member token The token that the payout limits and surplus allowances apply to within the `terminal`.
-/// @custom:member payoutLimits An array of payout limits. The payout limits cumulatively dictate the maximum value of
-/// `token`s a project can pay out from its balance in a terminal during a ruleset. Each payout limit can have a unique
-/// currency and amount.
-/// @custom:member surplusAllowances An array of surplus allowances. The surplus allowances cumulatively dictates the
-/// maximum value of `token`s a project can pay out from its surplus (balance less payouts) in a terminal during a
-/// ruleset. Each surplus allowance can have a unique currency and amount.
+/// @notice Defines how much a project can withdraw from a specific terminal and token each funding cycle.
+/// @dev Example — payout limit of 5 USD in an ETH terminal: the project can distribute up to 5 USD worth of ETH to
+/// its splits per cycle. Example — surplus allowance of 5 USD: the project owner can pull up to 5 USD worth of ETH
+/// from the surplus (balance above payout limits).
+/// @dev Multiple limits in different currencies are additive — each can be used independently within one cycle.
+/// @dev Amounts use the same decimal precision as the terminal token (e.g. 18 for ETH, 6 for USDC).
+/// @custom:member terminal The terminal address these limits apply to.
+/// @custom:member token The token address within that terminal these limits apply to.
+/// @custom:member payoutLimits Maximum amounts distributable to splits per cycle, each in a specific currency.
+/// @custom:member surplusAllowances Maximum amounts withdrawable from surplus per cycle, each in a specific currency.
 struct JBFundAccessLimitGroup {
     address terminal;
     address token;

package/src/structs/JBPermissionsData.sol

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member operator The address that permissions are being given to.
-/// @custom:member projectId The ID of the project the operator is being given permissions for. Operators only have
+/// @custom:member operator The address to give permissions to.
+/// @custom:member projectId The ID of the project to give the operator permissions for. Operators only have
 /// permissions under this project's scope. An ID of 0 is a wildcard, which gives an operator permissions across all
 /// projects.
-/// @custom:member permissionIds The IDs of the permissions being given. See the `JBPermissionIds` library.
+/// @custom:member permissionIds The IDs of the permissions to grant. See the `JBPermissionIds` library.
 struct JBPermissionsData {
     address operator;
     uint64 projectId;

package/src/structs/JBRuleset.sol

@@ -3,32 +3,24 @@ pragma solidity ^0.8.0;
 
 import {IJBRulesetApprovalHook} from "./../interfaces/IJBRulesetApprovalHook.sol";
 
-/// @dev `JBRuleset` timestamps are unix timestamps (seconds since 00:00 January 1st, 1970 UTC).
-/// @custom:member cycleNumber The ruleset's cycle number. Each ruleset's `cycleNumber` is the previous ruleset's
-/// `cycleNumber` plus one. Each project's first ruleset has a `cycleNumber` of 1.
-/// @custom:member id The ruleset's ID, which is a timestamp of when this ruleset's rules were initialized. The
-/// `rulesetId` stays the same for rulesets that automatically cycle over from a manually queued ruleset.
-/// @custom:member basedOnId The `rulesetId` of the ruleset which was active when this ruleset was created.
-/// @custom:member start The timestamp from which this ruleset is considered active.
-/// @custom:member duration The number of seconds the ruleset lasts for. After this duration, a new ruleset will start.
-/// The project owner can queue new rulesets at any time, which will take effect once the current ruleset's duration is
-/// over. If the `duration` is 0, newly queued rulesets will take effect immediately. If a ruleset ends and there are no
-/// new rulesets queued, the current ruleset cycles over to another one with the same properties but a new `start`
-/// timestamp and a `weight` reduced by the ruleset's `weightCutPercent`.
-/// @custom:member weight A fixed point number with 18 decimals which is typically used by payment terminals to
-/// determine how many tokens should be minted when a payment is received. This can be used by other contracts for
-/// arbitrary calculations.
-/// @custom:member weightCutPercent The percentage by which to reduce the `weight` each time a new ruleset starts.
-/// `weight`
-/// is
-/// a percentage out of `JBConstants.MAX_WEIGHT_CUT_PERCENT`. If it's 0, the next ruleset will have the same `weight` by
-/// default. If it's 90%, the next ruleset's `weight` will be 10% smaller. If a ruleset explicitly sets a new `weight`,
-/// the `weightCutPercent` doesn't apply.
-/// @custom:member approvalHook An address of a contract that says whether a queued ruleset should be approved or
-/// rejected. If a
-/// ruleset is rejected, it won't go into effect. An approval hook can be used to create rules which dictate how a
-/// project owner can change their ruleset over time.
-/// @custom:member metadata Extra data associated with a ruleset which can be used by other contracts.
+/// @notice A ruleset defines how a project behaves during a period of time — token issuance rate, cash-out terms,
+/// payout rules, and permissions. Rulesets cycle automatically: when one expires, the next queued (and approved) one
+/// takes effect. If nothing is queued, the current ruleset auto-cycles with decayed weight.
+/// @dev Timestamps are unix timestamps (seconds since epoch).
+/// @custom:member cycleNumber Which cycle this is (starts at 1, increments each cycle).
+/// @custom:member id The ruleset's ID — the unix timestamp when it was first stored. Stays the same across
+/// auto-cycles.
+/// @custom:member basedOnId The ID of the ruleset that was active when this one was created (forms a linked list).
+/// @custom:member start When this ruleset became/becomes active.
+/// @custom:member duration How many seconds the ruleset lasts. 0 = no auto-cycling (must be explicitly replaced).
+/// @custom:member weight Tokens minted per unit paid (18 decimals). The terminal divides payment amount by weight to
+/// determine token issuance. Higher weight = more tokens per unit of payment.
+/// @custom:member weightCutPercent How much to reduce weight each cycle (out of 1,000,000,000). 100,000,000 = 10% cut
+/// per cycle. 0 = no decay. Only applies when a cycle auto-rolls without an explicitly queued replacement.
+/// @custom:member approvalHook A contract that gates whether queued rulesets can take effect (e.g. `JBDeadline` for
+/// minimum notice periods). If the hook rejects a queued ruleset, the current one continues.
+/// @custom:member metadata Packed 256-bit field containing reservedPercent, cashOutTaxRate, baseCurrency, boolean
+/// flags, data hook address, and custom metadata. Decoded by `JBRulesetMetadataResolver`.
 struct JBRuleset {
     uint48 cycleNumber;
     uint48 id;

package/src/structs/JBRulesetConfig.sol

@@ -6,31 +6,19 @@ import {JBFundAccessLimitGroup} from "./JBFundAccessLimitGroup.sol";
 import {JBRulesetMetadata} from "./JBRulesetMetadata.sol";
 import {JBSplitGroup} from "./JBSplitGroup.sol";
 
-/// @custom:member mustStartAtOrAfter The earliest time the ruleset can start.
-/// @custom:member duration The number of seconds the ruleset lasts for, after which a new ruleset will start. A
-/// duration of 0 means that the ruleset will stay active until the project owner explicitly issues a reconfiguration,
-/// at which point a new ruleset will immediately start with the updated properties. If the duration is greater than 0,
-/// a project owner cannot make changes to a ruleset's parameters while it is active – any proposed changes will apply
-/// to the subsequent ruleset. If no changes are proposed, a ruleset rolls over to another one with the same properties
-/// but new `start` timestamp and a cut `weight`.
-/// @custom:member weight A fixed point number with 18 decimals that contracts can use to base arbitrary calculations
-/// on. For example, payment terminals can use this to determine how many tokens should be minted when a payment is
-/// received.
-/// @custom:member weightCutPercent A percent by how much the `weight` of the subsequent ruleset should be reduced, if
-/// the
-/// project owner hasn't queued the subsequent ruleset with an explicit `weight`. If it's 0, each ruleset will have
-/// equal weight. If the number is 90%, the next ruleset will have a 10% smaller weight. This weight is out of
-/// `JBConstants.MAX_WEIGHT_CUT_PERCENT`.
-/// @custom:member approvalHook An address of a contract that says whether a proposed ruleset should be accepted or
-/// rejected. It
-/// can be used to create rules around how a project owner can change ruleset parameters over time.
-/// @custom:member metadata Metadata specifying the controller-specific parameters that a ruleset can have. These
-/// properties cannot change until the next ruleset starts.
-/// @custom:member splitGroups An array of splits to use for any number of groups while the ruleset is active.
-/// @custom:member fundAccessLimitGroups An array of structs which dictate the amount of funds a project can access from
-/// its balance in each payment terminal while the ruleset is active. Amounts are fixed point numbers using the same
-/// number of decimals as the corresponding terminal. The `_payoutLimit` and `_surplusAllowance` parameters must fit in
-/// a `uint232`.
+/// @notice The configuration passed to `JBController.launchRulesetsFor` or `queueRulesetsOf` to define a new ruleset.
+/// Includes the economic parameters (weight, duration, decay), the metadata (permissions and hooks), the split
+/// recipients, and the fund access limits.
+/// @custom:member mustStartAtOrAfter The earliest timestamp the ruleset can begin. Pass 0 to start immediately after
+/// the previous ruleset ends.
+/// @custom:member duration How long the ruleset lasts in seconds. 0 = stays active until explicitly replaced.
+/// @custom:member weight Tokens minted per unit of payment (18 decimals). Pass 1 to inherit decayed weight from the
+/// previous ruleset. Pass 0 for no token issuance.
+/// @custom:member weightCutPercent Decay rate per cycle (out of 1,000,000,000). 100,000,000 = 10% cut. 0 = no decay.
+/// @custom:member approvalHook Contract that must approve the *next* queued ruleset for it to take effect.
+/// @custom:member metadata The ruleset's behavioral flags and parameters (see `JBRulesetMetadata`).
+/// @custom:member splitGroups How payouts and reserved tokens are distributed during this ruleset.
+/// @custom:member fundAccessLimitGroups How much the project can withdraw from each terminal per cycle.
 struct JBRulesetConfig {
     uint48 mustStartAtOrAfter;
     uint32 duration;

package/src/structs/JBRulesetMetadata.sol

@@ -1,38 +1,31 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member reservedPercent The reserved percent of the ruleset. This number is a percentage calculated out of
-/// `JBConstants.MAX_RESERVED_PERCENT`.
-/// @custom:member cashOutTaxRate The cash out tax rate of the ruleset. This number is a percentage calculated out of
-/// `JBConstants.MAX_CASH_OUT_TAX_RATE`.
-/// @custom:member baseCurrency The currency on which to base the ruleset's weight. By convention, this is
-/// `uint32(uint160(tokenAddress))` for tokens, or a constant ID from e.g. `JBCurrencyIds` for other currencies.
-/// @custom:member pausePay A flag indicating if the pay functionality should be paused during the ruleset.
-/// @custom:member pauseCreditTransfers A flag indicating if the project token transfer functionality should be paused
-/// during the funding cycle.
-/// @custom:member allowOwnerMinting A flag indicating if the project owner or an operator with the `MINT_TOKENS`
-/// permission from the owner should be allowed to mint project tokens on demand during this ruleset.
-/// @custom:member allowTerminalMigration A flag indicating if migrating terminals should be allowed during this
-/// ruleset.
-/// @custom:member allowSetTerminals A flag indicating if a project's terminals can be added or removed.
-/// @custom:member allowSetController A flag indicating if a project's controller can be changed.
-/// @custom:member allowAddAccountingContext A flag indicating if a project can add new accounting contexts for its
-/// terminals to use.
-/// @custom:member allowAddPriceFeed A flag indicating if a project can add new price feeds to calculate exchange rates
-/// between its tokens.
-/// @custom:member ownerMustSendPayouts A flag indicating if privileged payout distribution should be
-/// enforced, otherwise payouts can be distributed by anyone.
-/// @custom:member holdFees A flag indicating if fees should be held during this ruleset.
-/// @custom:member useTotalSurplusForCashOuts A flag indicating if cash outs should use the project's balance held
-/// in all terminals instead of the project's local terminal balance from which the cash out is being fulfilled.
-/// @custom:member useDataHookForPay A flag indicating if the data hook should be used for pay transactions during this
-/// ruleset.
-/// @custom:member useDataHookForCashOut A flag indicating if the data hook should be used for cash out transactions
-/// during
-/// this ruleset.
-/// @custom:member dataHook The data hook to use during this ruleset.
-/// @custom:member metadata Metadata of the metadata, only the 14 least significant bits can be used, the 2 most
-/// significant bits are disregarded.
+/// @notice Human-readable configuration for a ruleset's behavioral flags and parameters. This struct is packed into
+/// 256 bits for on-chain storage (see `JBRulesetMetadataResolver` for the packing layout).
+/// @custom:member reservedPercent Percentage of newly minted tokens set aside for the reserved token split group
+/// (0–10,000 basis points). 5,000 = 50% reserved.
+/// @custom:member cashOutTaxRate Tax applied when holders cash out tokens (0–10,000 basis points). Higher rate = less
+/// reclaim per token. 0 = proportional, 10,000 = no reclaim (100% tax).
+/// @custom:member baseCurrency The currency used to interpret the ruleset's weight for token issuance. Convention:
+/// `uint32(uint160(tokenAddress))` for tokens, or `JBCurrencyIds.ETH`/`JBCurrencyIds.USD` for well-known currencies.
+/// @custom:member pausePay If `true`, the project cannot receive payments during this ruleset.
+/// @custom:member pauseCreditTransfers If `true`, token credit transfers are disabled during this ruleset.
+/// @custom:member allowOwnerMinting If `true`, the project owner (or MINT_TOKENS operator) can mint tokens on demand.
+/// @custom:member allowSetCustomToken If `true`, the project can set a custom ERC-20 token via `setTokenFor`.
+/// @custom:member allowTerminalMigration If `true`, terminals can be migrated to new implementations.
+/// @custom:member allowSetTerminals If `true`, the project's terminal list can be modified.
+/// @custom:member allowSetController If `true`, the project's controller can be changed.
+/// @custom:member allowAddAccountingContext If `true`, new token accounting contexts can be added to terminals.
+/// @custom:member allowAddPriceFeed If `true`, the project can register new price feeds in `JBPrices`.
+/// @custom:member ownerMustSendPayouts If `true`, only the project owner can trigger payout distribution.
+/// @custom:member holdFees If `true`, fees are accumulated but not processed until a future ruleset (or manually).
+/// @custom:member useTotalSurplusForCashOuts If `true`, cash-out calculations use surplus across all terminals (not
+/// just the one to cash out from).
+/// @custom:member useDataHookForPay If `true`, the data hook is called before recording payments.
+/// @custom:member useDataHookForCashOut If `true`, the data hook is called before recording cash outs.
+/// @custom:member dataHook Contract called before pay/cash-out to potentially override token counts or add hooks.
+/// @custom:member metadata 14 bits of application-specific metadata (upper 2 bits are ignored).
 struct JBRulesetMetadata {
     uint16 reservedPercent;
     uint16 cashOutTaxRate;

package/src/structs/JBSplitHookContext.sol

@@ -3,8 +3,8 @@ pragma solidity ^0.8.0;
 
 import {JBSplit} from "./JBSplit.sol";
 
-/// @custom:member token The token being sent to the split hook.
-/// @custom:member amount The amount being sent to the split hook, as a fixed point number.
+/// @custom:member token The token to send to the split hook.
+/// @custom:member amount The amount to send to the split hook, as a fixed point number.
 /// @custom:member decimals The number of decimals in the amount.
 /// @custom:member projectId The project the split belongs to.
 /// @custom:member groupId The group the split belongs to. By convention, this ID is `uint256(uint160(tokenAddress))`