@bananapus/core-v6 0.0.18 → 0.0.19

package/src/interfaces/IJBTerminalStore.sol

@@ -65,6 +65,22 @@ interface IJBTerminalStore {
         view
         returns (uint256);
 
+    /// @notice Returns the reclaimable surplus for a project across all terminals using all accounting contexts.
+    /// @param projectId The ID of the project.
+    /// @param cashOutCount The number of tokens being cashed out.
+    /// @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 currentTotalReclaimableSurplusOf(
+        uint256 projectId,
+        uint256 cashOutCount,
+        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.
@@ -97,6 +113,60 @@ interface IJBTerminalStore {
         view
         returns (uint256);
 
+    /// @notice Simulates a cash out without modifying state.
+    /// @param terminal The terminal address to simulate the cash out from.
+    /// @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 beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address.
+    /// @param metadata Extra data to pass along to the data hook.
+    /// @return ruleset The project's current ruleset.
+    /// @return reclaimAmount The amount that would be reclaimed.
+    /// @return cashOutTaxRate The cash out tax rate that would be applied.
+    /// @return hookSpecifications Any cash out hook specifications from the data hook.
+    function previewCashOutFrom(
+        address terminal,
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        JBAccountingContext calldata accountingContext,
+        JBAccountingContext[] calldata balanceAccountingContexts,
+        bool beneficiaryIsFeeless,
+        bytes calldata metadata
+    )
+        external
+        view
+        returns (
+            JBRuleset memory ruleset,
+            uint256 reclaimAmount,
+            uint256 cashOutTaxRate,
+            JBCashOutHookSpecification[] memory hookSpecifications
+        );
+
+    /// @notice Simulates a payment without modifying state.
+    /// @param terminal The terminal address to simulate the payment from.
+    /// @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 that would be minted.
+    /// @return hookSpecifications Any pay hook specifications from the data hook.
+    function previewPayFrom(
+        address terminal,
+        address payer,
+        JBTokenAmount memory amount,
+        uint256 projectId,
+        address beneficiary,
+        bytes calldata metadata
+    )
+        external
+        view
+        returns (JBRuleset memory ruleset, uint256 tokenCount, JBPayHookSpecification[] memory hookSpecifications);
+
     /// @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.

package/test/fork/TestSequencerPriceFeedFork.sol

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {Test} from "forge-std/Test.sol";
+
+import {AggregatorV2V3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV2V3Interface.sol";
+import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol";
+
+import {JBChainlinkV3SequencerPriceFeed} from "../../src/JBChainlinkV3SequencerPriceFeed.sol";
+
+/// @notice Fork tests for JBChainlinkV3SequencerPriceFeed against the live Arbitrum sequencer uptime feed and
+/// ETH/USD Chainlink oracle.
+contract TestSequencerPriceFeedFork is Test {
+    // Chainlink feed addresses (Arbitrum mainnet).
+    address constant ARB_ETH_USD_FEED = 0x639Fe6ab55C921f74e7fac1ee960C0B6293ba612;
+    address constant ARB_SEQUENCER_FEED = 0xFdB631F5EE196F0ed6FAa767959853A9F217697D;
+
+    // Staleness threshold (1 hour).
+    uint256 constant THRESHOLD = 3600;
+
+    // Grace period after sequencer restart (1 hour).
+    uint256 constant GRACE_PERIOD = 3600;
+
+    // Pinned block for reproducibility (sequencer is up at this block).
+    uint256 constant FORK_BLOCK = 300_000_000;
+
+    JBChainlinkV3SequencerPriceFeed feed;
+
+    function setUp() public {
+        string memory rpc = vm.envOr("RPC_ARBITRUM_MAINNET", string(""));
+        if (bytes(rpc).length == 0) {
+            // Skip all tests if no Arbitrum RPC is configured.
+            return;
+        }
+
+        vm.createSelectFork(rpc, FORK_BLOCK);
+
+        feed = new JBChainlinkV3SequencerPriceFeed(
+            AggregatorV3Interface(ARB_ETH_USD_FEED),
+            THRESHOLD,
+            AggregatorV2V3Interface(ARB_SEQUENCER_FEED),
+            GRACE_PERIOD
+        );
+    }
+
+    // ------------------------------------------------------------------
+    // Helpers
+    // ------------------------------------------------------------------
+
+    modifier skipIfNoRpc() {
+        if (address(feed) == address(0)) {
+            return;
+        }
+        _;
+    }
+
+    // ------------------------------------------------------------------
+    // 1. Normal operation — valid price returned
+    // ------------------------------------------------------------------
+
+    /// @notice Under normal conditions (sequencer up, grace period elapsed), currentUnitPrice returns a sane price.
+    function test_normalOperation_returnsValidPrice() public skipIfNoRpc {
+        uint256 price18 = feed.currentUnitPrice(18);
+
+        // ETH price should be between $500 and $50,000.
+        assertGt(price18, 500e18, "ETH price too low");
+        assertLt(price18, 50_000e18, "ETH price too high");
+
+        // Cross-check against raw latestRoundData from the price feed.
+        (, int256 rawPrice,,,) = AggregatorV3Interface(ARB_ETH_USD_FEED).latestRoundData();
+        uint256 feedDecimals = AggregatorV3Interface(ARB_ETH_USD_FEED).decimals();
+        // forge-lint: disable-next-line(unsafe-typecast)
+        uint256 expected18 = uint256(rawPrice) * 10 ** (18 - feedDecimals);
+        assertEq(price18, expected18, "Price mismatch vs raw feed");
+    }
+
+    // ------------------------------------------------------------------
+    // 2. Sequencer down — reverts
+    // ------------------------------------------------------------------
+
+    /// @notice When the sequencer feed reports answer=1 (down), currentUnitPrice reverts.
+    function test_sequencerDown_reverts() public skipIfNoRpc {
+        // Mock the sequencer feed to report answer=1 (down).
+        // latestRoundData() selector = 0xfeaf968c
+        vm.mockCall(
+            ARB_SEQUENCER_FEED,
+            abi.encodeWithSelector(AggregatorV3Interface.latestRoundData.selector),
+            abi.encode(
+                uint80(1), // roundId
+                int256(1), // answer = 1 → sequencer down
+                block.timestamp - GRACE_PERIOD - 100, // startedAt (irrelevant when answer=1)
+                block.timestamp, // updatedAt
+                uint80(1) // answeredInRound
+            )
+        );
+
+        vm.expectRevert(
+            abi.encodeWithSelector(
+                JBChainlinkV3SequencerPriceFeed.JBChainlinkV3SequencerPriceFeed_SequencerDownOrRestarting.selector,
+                block.timestamp,
+                GRACE_PERIOD,
+                block.timestamp - GRACE_PERIOD - 100
+            )
+        );
+        feed.currentUnitPrice(18);
+    }
+
+    // ------------------------------------------------------------------
+    // 3. Grace period active — reverts
+    // ------------------------------------------------------------------
+
+    /// @notice When the sequencer just came back up (within grace period), currentUnitPrice reverts.
+    function test_gracePeriodActive_reverts() public skipIfNoRpc {
+        // Mock the sequencer feed: answer=0 (up) but startedAt is 1 second ago (within grace period).
+        uint256 startedAt = block.timestamp - 1;
+
+        vm.mockCall(
+            ARB_SEQUENCER_FEED,
+            abi.encodeWithSelector(AggregatorV3Interface.latestRoundData.selector),
+            abi.encode(
+                uint80(1), // roundId
+                int256(0), // answer = 0 → sequencer up
+                startedAt, // startedAt = very recent
+                block.timestamp, // updatedAt
+                uint80(1) // answeredInRound
+            )
+        );
+
+        vm.expectRevert(
+            abi.encodeWithSelector(
+                JBChainlinkV3SequencerPriceFeed.JBChainlinkV3SequencerPriceFeed_SequencerDownOrRestarting.selector,
+                block.timestamp,
+                GRACE_PERIOD,
+                startedAt
+            )
+        );
+        feed.currentUnitPrice(18);
+    }
+
+    // ------------------------------------------------------------------
+    // 4. Post-grace recovery — succeeds
+    // ------------------------------------------------------------------
+
+    /// @notice After the grace period has elapsed, currentUnitPrice succeeds again.
+    function test_postGraceRecovery_succeeds() public skipIfNoRpc {
+        // Mock the sequencer feed: answer=0 (up), startedAt is well before the grace period ended.
+        uint256 startedAt = block.timestamp - GRACE_PERIOD - 100;
+
+        vm.mockCall(
+            ARB_SEQUENCER_FEED,
+            abi.encodeWithSelector(AggregatorV3Interface.latestRoundData.selector),
+            abi.encode(
+                uint80(1), // roundId
+                int256(0), // answer = 0 → sequencer up
+                startedAt, // startedAt = well in the past
+                block.timestamp, // updatedAt
+                uint80(1) // answeredInRound
+            )
+        );
+
+        // The price feed itself is still the real Chainlink feed, so this should succeed.
+        uint256 price18 = feed.currentUnitPrice(18);
+
+        // Same sanity check: ETH price between $500 and $50,000.
+        assertGt(price18, 500e18, "ETH price too low after recovery");
+        assertLt(price18, 50_000e18, "ETH price too high after recovery");
+    }
+}

package/test/units/static/JBTerminalStore/TestCurrentReclaimableSurplusOf.sol

@@ -444,4 +444,219 @@ contract TestCurrentReclaimableSurplusOf_Local is JBTerminalStoreSetup {
         uint256 reclaimable = _store.currentReclaimableSurplusOf(_projectId, _tokenCount, 1e18, 1e18);
         assertEq(1e18, reclaimable);
     }
+
+    function test_GivenTotalReclaimableWithSurplus() external whenProjectHasBalance {
+        // it will default to all terminals and all accounting contexts and return the reclaimable surplus
+
+        // setup calldata
+        JBAccountingContext[] memory _contexts = new JBAccountingContext[](1);
+        _contexts[0] = JBAccountingContext({token: address(_token), decimals: 18, currency: _currency});
+
+        JBRulesetMetadata memory _metadata = JBRulesetMetadata({
+            reservedPercent: 0,
+            cashOutTaxRate: JBConstants.MAX_CASH_OUT_TAX_RATE / 2,
+            baseCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            pausePay: false,
+            pauseCreditTransfers: false,
+            allowOwnerMinting: false,
+            allowSetCustomToken: false,
+            allowTerminalMigration: false,
+            allowSetTerminals: false,
+            ownerMustSendPayouts: false,
+            allowSetController: false,
+            allowAddAccountingContext: true,
+            allowAddPriceFeed: false,
+            holdFees: false,
+            useTotalSurplusForCashOuts: false,
+            useDataHookForPay: false,
+            useDataHookForCashOut: false,
+            dataHook: address(0),
+            metadata: 0
+        });
+
+        uint256 _packedMetadata = JBRulesetMetadataResolver.packRulesetMetadata(_metadata);
+
+        // JBRulesets return calldata
+        JBRuleset memory _returnedRuleset = JBRuleset({
+            cycleNumber: uint48(block.timestamp),
+            id: uint48(block.timestamp),
+            basedOnId: 0,
+            start: uint48(block.timestamp),
+            duration: uint32(block.timestamp + 1000),
+            weight: 1e18,
+            weightCutPercent: 0,
+            approvalHook: IJBRulesetApprovalHook(address(0)),
+            metadata: _packedMetadata
+        });
+
+        // mock call to JBRulesets currentOf
+        mockExpect(address(rulesets), abi.encodeCall(IJBRulesets.currentOf, (_projectId)), abi.encode(_returnedRuleset));
+
+        // mock call to JBDirectory controllerOf
+        mockExpect(address(directory), abi.encodeCall(IJBDirectory.controllerOf, (_projectId)), abi.encode(_controller));
+
+        uint256 _supply = 1e19;
+        uint256 _surplus = 1e18;
+        uint256 _cashoutAmount = 1e18;
+
+        // mock JBDirectory terminalsOf to return the terminal
+        IJBTerminal[] memory _terminals = new IJBTerminal[](1);
+        _terminals[0] = _terminal;
+        mockExpect(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (_projectId)), abi.encode(_terminals));
+
+        // surplus call to the terminal (empty accounting contexts passed through)
+        JBAccountingContext[] memory _emptyContexts = new JBAccountingContext[](0);
+        mockExpect(
+            address(_terminal),
+            abi.encodeCall(IJBTerminal.currentSurplusOf, (_projectId, _emptyContexts, 18, _currency)),
+            abi.encode(_surplus)
+        );
+
+        // mock JBController totalTokenSupplyWithReservedTokensOf
+        mockExpect(
+            address(_controller),
+            abi.encodeCall(IJBController.totalTokenSupplyWithReservedTokensOf, (_projectId)),
+            abi.encode(_supply)
+        );
+
+        // Call the new convenience function (no terminals, no accounting contexts).
+        uint256 reclaimable = _store.currentTotalReclaimableSurplusOf(_projectId, _cashoutAmount, 18, _currency);
+
+        // Should match the 6-param overload result.
+        uint256 assumed =
+            JBCashOuts.cashOutFrom(_surplus, _cashoutAmount, _supply, JBConstants.MAX_CASH_OUT_TAX_RATE / 2);
+
+        assertEq(assumed, reclaimable);
+    }
+
+    function test_GivenTotalReclaimableWithZeroSurplus() external {
+        // it will return zero when there is no surplus
+
+        JBAccountingContext[] memory _emptyContexts = new JBAccountingContext[](0);
+
+        // JBRulesets return calldata
+        JBRuleset memory _returnedRuleset = JBRuleset({
+            cycleNumber: uint48(block.timestamp),
+            id: uint48(block.timestamp),
+            basedOnId: 0,
+            start: uint48(block.timestamp),
+            duration: uint32(block.timestamp + 1000),
+            weight: 1e18,
+            weightCutPercent: 0,
+            approvalHook: IJBRulesetApprovalHook(address(0)),
+            metadata: 0
+        });
+
+        // mock call to JBRulesets currentOf
+        mockExpect(address(rulesets), abi.encodeCall(IJBRulesets.currentOf, (_projectId)), abi.encode(_returnedRuleset));
+
+        // mock JBDirectory terminalsOf to return the terminal
+        IJBTerminal[] memory _terminals = new IJBTerminal[](1);
+        _terminals[0] = _terminal;
+        mockExpect(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (_projectId)), abi.encode(_terminals));
+
+        // mock current surplus as zero
+        mockExpect(
+            address(_terminal),
+            abi.encodeCall(IJBTerminal.currentSurplusOf, (_projectId, _emptyContexts, 18, _currency)),
+            abi.encode(0)
+        );
+
+        uint256 reclaimable = _store.currentTotalReclaimableSurplusOf(_projectId, _tokenCount, 18, _currency);
+        assertEq(0, reclaimable);
+    }
+
+    function test_GivenTotalReclaimableMatchesSixParamOverload() external whenProjectHasBalance {
+        // it will produce the same result as calling the 6-param overload with empty arrays
+
+        JBAccountingContext[] memory _emptyContexts = new JBAccountingContext[](0);
+
+        JBRulesetMetadata memory _metadata = JBRulesetMetadata({
+            reservedPercent: 0,
+            cashOutTaxRate: JBConstants.MAX_CASH_OUT_TAX_RATE / 2,
+            baseCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            pausePay: false,
+            pauseCreditTransfers: false,
+            allowOwnerMinting: false,
+            allowSetCustomToken: false,
+            allowTerminalMigration: false,
+            allowSetTerminals: false,
+            ownerMustSendPayouts: false,
+            allowSetController: false,
+            allowAddAccountingContext: true,
+            allowAddPriceFeed: false,
+            holdFees: false,
+            useTotalSurplusForCashOuts: false,
+            useDataHookForPay: false,
+            useDataHookForCashOut: false,
+            dataHook: address(0),
+            metadata: 0
+        });
+
+        uint256 _packedMetadata = JBRulesetMetadataResolver.packRulesetMetadata(_metadata);
+
+        JBRuleset memory _returnedRuleset = JBRuleset({
+            cycleNumber: uint48(block.timestamp),
+            id: uint48(block.timestamp),
+            basedOnId: 0,
+            start: uint48(block.timestamp),
+            duration: uint32(block.timestamp + 1000),
+            weight: 1e18,
+            weightCutPercent: 0,
+            approvalHook: IJBRulesetApprovalHook(address(0)),
+            metadata: _packedMetadata
+        });
+
+        uint256 _supply = 1e19;
+        uint256 _surplus = 5e17;
+        uint256 _cashoutAmount = 1e18;
+
+        IJBTerminal[] memory _terminals = new IJBTerminal[](1);
+        _terminals[0] = _terminal;
+
+        // The new overload calls the 6-param via `this`, so JBRulesets.currentOf gets called twice.
+        // Mock it to return the same ruleset both times.
+        mockExpect(address(rulesets), abi.encodeCall(IJBRulesets.currentOf, (_projectId)), abi.encode(_returnedRuleset));
+
+        mockExpect(address(directory), abi.encodeCall(IJBDirectory.controllerOf, (_projectId)), abi.encode(_controller));
+
+        mockExpect(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (_projectId)), abi.encode(_terminals));
+
+        mockExpect(
+            address(_terminal),
+            abi.encodeCall(IJBTerminal.currentSurplusOf, (_projectId, _emptyContexts, 18, _currency)),
+            abi.encode(_surplus)
+        );
+
+        mockExpect(
+            address(_controller),
+            abi.encodeCall(IJBController.totalTokenSupplyWithReservedTokensOf, (_projectId)),
+            abi.encode(_supply)
+        );
+
+        // Call the new convenience function.
+        uint256 reclaimableDefault = _store.currentTotalReclaimableSurplusOf(_projectId, _cashoutAmount, 18, _currency);
+
+        // Re-mock for the 6-param call (mocks are consumed).
+        mockExpect(address(rulesets), abi.encodeCall(IJBRulesets.currentOf, (_projectId)), abi.encode(_returnedRuleset));
+        mockExpect(address(directory), abi.encodeCall(IJBDirectory.controllerOf, (_projectId)), abi.encode(_controller));
+        mockExpect(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (_projectId)), abi.encode(_terminals));
+        mockExpect(
+            address(_terminal),
+            abi.encodeCall(IJBTerminal.currentSurplusOf, (_projectId, _emptyContexts, 18, _currency)),
+            abi.encode(_surplus)
+        );
+        mockExpect(
+            address(_controller),
+            abi.encodeCall(IJBController.totalTokenSupplyWithReservedTokensOf, (_projectId)),
+            abi.encode(_supply)
+        );
+
+        // Call the 6-param overload with empty arrays.
+        uint256 reclaimableExplicit = _store.currentReclaimableSurplusOf(
+            _projectId, _cashoutAmount, new IJBTerminal[](0), new JBAccountingContext[](0), 18, _currency
+        );
+
+        assertEq(reclaimableDefault, reclaimableExplicit);
+    }
 }