@bananapus/core-v6 0.0.32 → 0.0.34

package/ADMINISTRATION.md

@@ -78,10 +78,10 @@ Admin privileges and their scope in nana-core-v6.
 - **How assigned:** Set at JBFeelessAddresses deployment via the Ownable constructor. Transferable via `Ownable.transferOwnership()`.
 - **Scope:** Protocol-wide. Controls which addresses are exempt from protocol fees.
 
-### JBERC20 Owner
+### JBERC20 Access Control
 
-- **How assigned:** Set to the `JBTokens` contract address when a project's ERC-20 is deployed or initialized.
-- **Scope:** Single token contract. Only the owner (JBTokens) can mint and burn tokens.
+- **How assigned:** The `TOKENS` reference is set to the `JBTokens` contract address during `initialize()`. `PERMISSIONS` and `PROJECTS` are constructor immutables inherited from `JBPermissioned` and the implementation contract respectively.
+- **Scope:** Single token contract. Only the `JBTokens` contract (via the `onlyTokens` modifier) can mint, burn, and update token metadata. Project owners or operators with the `SIGN_FOR_ERC20` permission can authorize ERC-1271 signatures.
 
 ### Omnichain Ruleset Operator
 
@@ -211,10 +211,11 @@ Admin privileges and their scope in nana-core-v6.
 
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|-------------|
-| `mint` | Contract owner (JBTokens) | N/A (onlyOwner) | Per token | Mints new tokens to an address. |
-| `burn` | Contract owner (JBTokens) | N/A (onlyOwner) | Per token | Burns tokens from an address. |
-| `initialize` | Anyone (once) | N/A | Per token | Initializes the token name, symbol, and owner. Can only be called once. |
-| `setMetadata` | Contract owner (JBTokens) | N/A (onlyOwner) | Per token | Updates the token's name and symbol. |
+| `mint` | JBTokens contract | N/A (onlyTokens) | Per token | Mints new tokens to an address. |
+| `burn` | JBTokens contract | N/A (onlyTokens) | Per token | Burns tokens from an address. |
+| `initialize` | Anyone (once) | N/A | Per token | Initializes the token name, symbol, and JBTokens contract reference. Can only be called once. |
+| `setMetadata` | JBTokens contract | N/A (onlyTokens) | Per token | Updates the token's name and symbol. |
+| `isValidSignature` | Anyone (view) | `SIGN_FOR_ERC20` | Per token | Validates ERC-1271 signatures for project owner or permitted operators. |
 
 ### JBTerminalStore
 

package/RISKS.md

@@ -174,7 +174,44 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 
 - `JBTerminalStore.recordAddedBalanceFor` has **no access control**. Any address can call it. The balance is keyed by `msg.sender` (the terminal address), so only a terminal can inflate its own recorded balance. This is safe as long as all terminals correctly track their actual holdings. A buggy or malicious terminal implementation could call `recordAddedBalanceFor` without actually receiving tokens, inflating the recorded balance above actual holdings.
 
-## 8. Invariants to Verify
+## 8. Accepted Behaviors
+
+### 8.1 Cross-terminal surplus is an explicit trust boundary
+
+When a project enables `useTotalSurplusForCashOuts`, core intentionally stops treating a single terminal's local
+balance as the full economic truth and instead trusts every registered terminal's reported surplus. This means a
+project can get richer cash-out pricing from value held elsewhere, but it also means a bad or economically
+incompatible terminal can distort the aggregate. This is accepted because cross-terminal projects explicitly opt into
+shared treasury semantics; the alternative is forcing every terminal to behave as an isolated silo. Projects should
+only enable this mode when all participating terminals are mutually trusted and economically compatible.
+
+### 8.2 Held-fee forgiveness on failed fee routing is fail-open by design
+
+Core intentionally prefers liveness over strict protocol fee collection. If project `#1` cannot accept a fee payment,
+`_processFee` returns the fee amount to the originating project's balance instead of locking funds. For held fees,
+`processHeldFeesOf` advances the queue before retrying the payment, so a failed held-fee processing attempt
+permanently forgives that fee. This is accepted because a broken fee route should not brick project treasury flows.
+The tradeoff is explicit revenue leakage for the fee beneficiary when the fee route is unavailable or incompletely
+wired.
+
+### 8.3 Surplus allowance is ruleset-scoped, not implicit-cycle-scoped
+
+`usedSurplusAllowanceOf` is keyed by terminal, project, token, ruleset, and currency rather than by an independently
+incrementing "cycle" counter. For projects whose rulesets roll forward implicitly without a new ruleset ID, allowance
+usage carries forward until a new ruleset actually takes effect. This is accepted because surplus allowance is meant
+to be tied to the active ruleset's economics, not to a synthetic cycle abstraction layered on top of an unchanged
+ruleset. Integrators that expect per-cycle resets should queue distinct rulesets instead of relying on implicit
+rollover.
+
+### 8.4 Core deployment alone leaves fee routing fail-open until periphery wiring completes
+
+Core contracts are intentionally deployable before project `#1` is fully operational. Until the fee project's
+controller, terminals, and accounting contexts are wired, fee-bearing flows remain fail-open: fees are forgiven back
+to the originating project rather than trapped. This is accepted because deployment sequencing across repos is staged,
+and the protocol prioritizes keeping project flows live during rollout over enforcing fee collection before the fee
+beneficiary is ready.
+
+## 9. Invariants to Verify
 
 These should hold at all times and are the most productive targets for formal verification or invariant testing:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-core-v6'"
   },
   "dependencies": {
-    "@bananapus/permission-ids-v6": "^0.0.15",
+    "@bananapus/permission-ids-v6": "^0.0.17",
     "@chainlink/contracts": "^1.5.0",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.1",

package/references/entrypoints.md

@@ -21,7 +21,7 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `JBSplits` | Split configurations per project/ruleset/group. Packed storage for gas efficiency. |
 | `JBFundAccessLimits` | Payout limits and surplus allowances per project/ruleset/terminal/token. |
 | `JBPrices` | Price feed registry with project-specific and protocol-wide default feeds. Immutable once set. |
-| `JBERC20` | Cloneable ERC-20 with Votes + Permit. Owned by `JBTokens`. Deployed via `Clones.clone()`. |
+| `JBERC20` | Cloneable ERC-20 with Votes + Permit + ERC-1271. Controlled by `JBTokens` via `onlyTokens`. Deployed via `Clones.clone()`. |
 | `JBFeelessAddresses` | Allowlist for fee-exempt addresses. |
 | `JBChainlinkV3PriceFeed` | Chainlink AggregatorV3 price feed with staleness threshold. Rejects negative/zero prices, incomplete rounds (`updatedAt == 0`), and stale answers carried from previous rounds (`answeredInRound < roundId`). |
 | `JBChainlinkV3SequencerPriceFeed` | L2 sequencer-aware Chainlink feed (Optimism/Arbitrum) with grace period after restart. Treats any non-zero sequencer answer as down (`answer != 0`). |

package/script/Deploy.s.sol

@@ -85,7 +85,8 @@ contract Deploy is Script, Sphinx {
             trustedForwarder: TRUSTED_FORWARDER
         });
         JBTokens tokens = new JBTokens{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}({
-            directory: directory, token: new JBERC20{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}()
+            directory: directory,
+            token: new JBERC20{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}(permissions, projects)
         });
 
         new JBFundAccessLimits{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}(directory);

package/src/JBERC20.sol

@@ -1,27 +1,50 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
 import {ERC20Permit, Nonces} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";
 import {ERC20Votes} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol";
+import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+import {IERC1271} from "@openzeppelin/contracts/interfaces/IERC1271.sol";
 import {Nonces} from "@openzeppelin/contracts/utils/Nonces.sol";
 
+import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
+import {JBPermissioned} from "./abstract/JBPermissioned.sol";
+import {IJBPermissions} from "./interfaces/IJBPermissions.sol";
+import {IJBProjects} from "./interfaces/IJBProjects.sol";
 import {IJBToken} from "./interfaces/IJBToken.sol";
+import {IJBTokens} from "./interfaces/IJBTokens.sol";
 
 /// @notice An ERC-20 token that can be used by a project in `JBTokens` and `JBController`.
 /// @dev By default, a project uses "credits" to track balances. Once a project sets their `IJBToken` using
 /// `JBController.deployERC20For(...)` or `JBController.setTokenFor(...)`, credits can be redeemed to claim tokens.
 /// @dev `JBController.deployERC20For(...)` deploys a `JBERC20` contract and sets it as the project's token.
-contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
+contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
     error JBERC20_AlreadyInitialized();
+    error JBERC20_Unauthorized();
 
     //*********************************************************************//
-    // --------------------- internal stored properties ------------------ //
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    /// @notice The projects contract used to resolve project ownership.
+    IJBProjects public immutable PROJECTS;
+
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    /// @notice The JBTokens contract that owns this token.
+    /// @dev Set via `initialize` because JBERC20 is deployed before JBTokens (circular dependency).
+    // forge-lint: disable-next-line(mixed-case-variable)
+    IJBTokens public TOKENS;
+
+    //*********************************************************************//
+    // -------------------- private stored properties -------------------- //
     //*********************************************************************//
 
     /// @notice The token's name.
@@ -38,8 +61,29 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
 
     /// @dev Set `_name` on the implementation contract to prevent it from being initialized directly.
     /// Clones start with empty `_name`, so `initialize(...)` works only on clones.
-    constructor() Ownable(address(this)) ERC20("invalid", "invalid") ERC20Permit("JBToken") {
+    /// @param permissions The permissions contract.
+    /// @param projects The projects contract.
+    constructor(
+        IJBPermissions permissions,
+        IJBProjects projects
+    )
+        ERC20("invalid", "invalid")
+        ERC20Permit("JBToken")
+        JBPermissioned(permissions)
+    {
         _name = "invalid";
+        PROJECTS = projects;
+    }
+
+    //*********************************************************************//
+    // --------------------------- modifiers ---------------------------- //
+    //*********************************************************************//
+
+    /// @notice Only the JBTokens contract can call this function.
+    // forge-lint: disable-next-line(unwrapped-modifier-logic)
+    modifier onlyTokens() {
+        if (msg.sender != address(TOKENS)) revert JBERC20_Unauthorized();
+        _;
     }
 
     //*********************************************************************//
@@ -47,51 +91,32 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
     //*********************************************************************//
 
     /// @notice Burn some outstanding tokens.
-    /// @dev Can only be called by this contract's owner.
+    /// @dev Can only be called by the JBTokens contract.
     /// @param account The address to burn tokens from.
     /// @param amount The amount of tokens to burn, as a fixed point number with 18 decimals.
-    function burn(address account, uint256 amount) external override onlyOwner {
+    function burn(address account, uint256 amount) external override onlyTokens {
         return _burn({account: account, value: amount});
     }
 
     /// @notice Mints more of this token.
-    /// @dev Can only be called by this contract's owner.
+    /// @dev Can only be called by the JBTokens contract.
     /// @param account The address to mint the new tokens to.
     /// @param amount The amount of tokens to mint, as a fixed point number with 18 decimals.
-    function mint(address account, uint256 amount) external override onlyOwner {
+    function mint(address account, uint256 amount) external override onlyTokens {
         return _mint({account: account, value: amount});
     }
 
     /// @notice Sets the token's name and symbol.
-    /// @dev Can only be called by this contract's owner.
+    /// @dev Can only be called by the JBTokens contract.
     /// @param name_ The new name.
     /// @param symbol_ The new symbol.
-    function setMetadata(string memory name_, string memory symbol_) external override onlyOwner {
-        _name = name_;
-        _symbol = symbol_;
-    }
-
-    //*********************************************************************//
-    // ----------------------- public transactions ----------------------- //
-    //*********************************************************************//
-
-    /// @notice Initializes the token.
-    /// @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) public override {
-        // Prevent re-initialization by reverting if a name is already set or if the provided name is empty.
-        if (bytes(_name).length != 0 || bytes(name_).length == 0) revert JBERC20_AlreadyInitialized();
-
+    function setMetadata(string memory name_, string memory symbol_) external override onlyTokens {
         _name = name_;
         _symbol = symbol_;
-
-        // Transfer ownership to the owner.
-        _transferOwnership(owner);
     }
 
     //*********************************************************************//
-    // ------------------------- external views -------------------------- //
+    // ----------------------- external views ---------------------------- //
     //*********************************************************************//
 
     /// @notice This token can only be added to a project when its created by the `JBTokens` contract.
@@ -99,6 +124,35 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
         return false;
     }
 
+    /// @notice Validates a signature on behalf of this token contract (ERC-1271).
+    /// @dev Allows the project owner or an operator with `SIGN_FOR_ERC20` permission to sign messages on behalf of
+    /// this token. Useful for Etherscan contract verification and other off-chain signature flows.
+    /// @param hash The hash of the data being signed.
+    /// @param signature The signature to validate.
+    /// @return magicValue `0x1626ba7e` if the signature is valid, `0xffffffff` otherwise.
+    function isValidSignature(bytes32 hash, bytes memory signature) external view override returns (bytes4 magicValue) {
+        // Recover the signer from the signature. Return invalid if recovery fails.
+        // slither-disable-next-line unused-return
+        (address signer, ECDSA.RecoverError error,) = ECDSA.tryRecover(hash, signature);
+        if (error != ECDSA.RecoverError.NoError) return 0xffffffff;
+
+        // Get the project ID this token belongs to.
+        uint256 projectId = TOKENS.projectIdOf(IJBToken(address(this)));
+
+        // Get the project owner (the NFT holder).
+        address projectOwner = PROJECTS.ownerOf(projectId);
+
+        // Valid if the signer is the project owner or has the SIGN_FOR_ERC20 permission.
+        if (_hasPermissionFrom({
+                operator: signer,
+                account: projectOwner,
+                projectId: projectId,
+                permissionId: JBPermissionIds.SIGN_FOR_ERC20
+            })) return IERC1271.isValidSignature.selector;
+
+        return 0xffffffff;
+    }
+
     //*********************************************************************//
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
@@ -137,6 +191,23 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
         return super.totalSupply();
     }
 
+    //*********************************************************************//
+    // ----------------------- public transactions ----------------------- //
+    //*********************************************************************//
+
+    /// @notice Initializes the token.
+    /// @param name_ The token's name.
+    /// @param symbol_ The token's symbol.
+    /// @param tokens The JBTokens contract that manages this token.
+    function initialize(string memory name_, string memory symbol_, address tokens) public override {
+        // Prevent re-initialization by reverting if a name is already set or if the provided name is empty.
+        if (bytes(_name).length != 0 || bytes(name_).length == 0) revert JBERC20_AlreadyInitialized();
+
+        _name = name_;
+        _symbol = symbol_;
+        TOKENS = IJBTokens(tokens);
+    }
+
     //*********************************************************************//
     // ---------------------- internal transactions ---------------------- //
     //*********************************************************************//