@bananapus/core-v6 0.0.18 → 0.0.20

package/test/units/static/JBMultiTerminal/TestPreviewPayFor.sol

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {JBMultiTerminal} from "../../../../src/JBMultiTerminal.sol";
+import {IJBController} from "../../../../src/interfaces/IJBController.sol";
+import {IJBDirectory} from "../../../../src/interfaces/IJBDirectory.sol";
+import {IJBPayHook} from "../../../../src/interfaces/IJBPayHook.sol";
+import {IJBRulesetApprovalHook} from "../../../../src/interfaces/IJBRulesetApprovalHook.sol";
+import {IJBTerminalStore} from "../../../../src/interfaces/IJBTerminalStore.sol";
+import {JBConstants} from "../../../../src/libraries/JBConstants.sol";
+import {JBAccountingContext} from "../../../../src/structs/JBAccountingContext.sol";
+import {JBPayHookSpecification} from "../../../../src/structs/JBPayHookSpecification.sol";
+import {JBRuleset} from "../../../../src/structs/JBRuleset.sol";
+import {JBTokenAmount} from "../../../../src/structs/JBTokenAmount.sol";
+import {JBMultiTerminalSetup} from "./JBMultiTerminalSetup.sol";
+
+contract TestPreviewPayFor_Local is JBMultiTerminalSetup {
+    uint256 _projectId = 1;
+    uint256 _amount = 1e18;
+    address _token = JBConstants.NATIVE_TOKEN;
+    address _beneficiary = makeAddr("beneficiary");
+    address _payer = makeAddr("payer");
+    IJBController _controller = IJBController(makeAddr("controller"));
+
+    function setUp() public {
+        super.multiTerminalSetup();
+    }
+
+    function _setAccountingContext(address token, uint8 decimals, uint32 currency) internal {
+        bytes32 contextSlot = keccak256(abi.encode(_projectId, uint256(0)));
+        bytes32 slot = keccak256(abi.encode(token, contextSlot));
+        bytes32 packed = bytes32(uint256(uint160(token)) | (uint256(decimals) << 160) | (uint256(currency) << 168));
+        vm.store(address(_terminal), slot, packed);
+    }
+
+    function test_RevertsWhenTokenIsNotAccepted() external {
+        vm.prank(_payer);
+        vm.expectRevert(abi.encodeWithSelector(JBMultiTerminal.JBMultiTerminal_TokenNotAccepted.selector, _token));
+        JBMultiTerminal(address(_terminal)).previewPayFor(_projectId, _token, _amount, _beneficiary, "");
+    }
+
+    function test_ReturnsRulesetMintSplitAndHookSpecifications() external {
+        _setAccountingContext(_token, 18, uint32(uint160(_token)));
+
+        JBRuleset memory ruleset = JBRuleset({
+            cycleNumber: 1,
+            id: 1,
+            basedOnId: 0,
+            start: uint48(block.timestamp),
+            duration: 0,
+            weight: 0,
+            weightCutPercent: 0,
+            approvalHook: IJBRulesetApprovalHook(address(0)),
+            metadata: 0
+        });
+
+        JBPayHookSpecification[] memory specs = new JBPayHookSpecification[](1);
+        specs[0] =
+            JBPayHookSpecification({hook: IJBPayHook(makeAddr("hook")), noop: false, amount: 123, metadata: hex"1234"});
+
+        JBTokenAmount memory tokenAmount =
+            JBTokenAmount({token: _token, decimals: 18, currency: uint32(uint160(_token)), value: _amount});
+
+        mockExpect(
+            address(store),
+            abi.encodeCall(IJBTerminalStore.previewPayFrom, (_payer, tokenAmount, _projectId, _beneficiary, bytes(""))),
+            abi.encode(ruleset, 1000, specs)
+        );
+
+        mockExpect(
+            address(directory),
+            abi.encodeCall(IJBDirectory.controllerOf, (_projectId)),
+            abi.encode(address(_controller))
+        );
+
+        mockExpect(
+            address(_controller),
+            abi.encodeCall(IJBController.previewMintOf, (_projectId, 1000, true)),
+            abi.encode(750, 250)
+        );
+
+        vm.prank(_payer);
+        (
+            JBRuleset memory previewRuleset,
+            uint256 beneficiaryTokenCount,
+            uint256 reservedTokenCount,
+            JBPayHookSpecification[] memory previewSpecs
+        ) = JBMultiTerminal(address(_terminal)).previewPayFor(_projectId, _token, _amount, _beneficiary, "");
+
+        assertEq(previewRuleset.id, ruleset.id);
+        assertEq(beneficiaryTokenCount, 750);
+        assertEq(reservedTokenCount, 250);
+        assertEq(previewSpecs.length, 1);
+        assertEq(address(previewSpecs[0].hook), address(specs[0].hook));
+        assertEq(previewSpecs[0].amount, specs[0].amount);
+        assertEq(previewSpecs[0].metadata, specs[0].metadata);
+    }
+}

package/test/units/static/JBMultiTerminal/TestProcessHeldFeesOf.sol

@@ -59,10 +59,18 @@ contract TestProcessHeldFeesOf_Local is JBTest {
     IPermit2 public permit2 = IPermit2(makeAddr("permit2"));
     address trustedForwarder = makeAddr("forwarder");
 
+    uint256 _feeProjectId = 1;
     uint256 _projectId = 2;
     address _mockToken = makeAddr("token");
     address _beneficiary = makeAddr("beneficiary");
 
+    function _setAccountingContext(uint256 projectId, address token, uint8 decimals, uint32 currency) internal {
+        bytes32 contextSlot = keccak256(abi.encode(projectId, uint256(0)));
+        bytes32 slot = keccak256(abi.encode(token, contextSlot));
+        bytes32 packed = bytes32(uint256(uint160(token)) | (uint256(decimals) << 160) | (uint256(currency) << 168));
+        vm.store(address(_terminal), slot, packed);
+    }
+
     function setUp() public {
         // Constructor will call to find directory and rulesets from the terminal store
         mockExpect(address(store), abi.encodeCall(IJBTerminalStore.DIRECTORY, ()), abi.encode(address(directory)));
@@ -118,6 +126,9 @@ contract TestProcessHeldFeesOf_Local is JBTest {
         // The fee amount that will be calculated from the held amount
         uint256 expectedFeeAmount = JBFees.feeAmountFrom({amountBeforeFee: heldAmount, feePercent: _terminal.FEE()});
 
+        // Set up accounting context for the fee beneficiary project (project 1) so _pay can build the token amount.
+        _setAccountingContext(_feeProjectId, _mockToken, 0, uint32(uint160(_mockToken)));
+
         // Mock the directory call to find the fee terminal - return _terminal itself so it uses internal _pay
         mockExpect(
             address(directory),
@@ -128,8 +139,6 @@ contract TestProcessHeldFeesOf_Local is JBTest {
         // Mock executeProcessFee: when the terminal calls itself, it will call recordPaymentFrom on the store.
         // Since executeProcessFee is external and calls pay on the feeTerminal (which is _terminal itself),
         // we need to mock the internal pay path: recordPaymentFrom on the store.
-        // The token amount struct for the fee payment
-        // Note: accounting context for project 1 on _mockToken is unset, so decimals=0 and currency=0.
         vm.mockCall(
             address(store),
             abi.encodeWithSelector(IJBTerminalStore.recordPaymentFrom.selector),

package/test/units/static/JBRulesets/TestCurrentOf.sol

@@ -191,12 +191,13 @@ contract TestCurrentOf_Local is JBRulesetsSetup {
     {
         // it will return the ruleset the pending approval ruleset is basedOn
 
-        uint256 _firstRulesetId = block.timestamp;
-        uint256 _rulesetWithHookId = block.timestamp + 1;
+        // Capture IDs from actual storage (avoid via_ir reordering of block.timestamp).
+        uint256 _firstRulesetId = _rulesets.currentOf(_projectId).id;
+        uint256 _rulesetWithHookId = _firstRulesetId + 1;
 
         JBRuleset memory _queuedRuleset = _rulesets.getRulesetOf(_projectId, _rulesetWithHookId);
 
-        vm.warp(block.timestamp + 3 days);
+        vm.warp(_firstRulesetId + 3 days);
 
         // mock approvalStatusOf to return Pending
         mockExpect(
@@ -215,12 +216,13 @@ contract TestCurrentOf_Local is JBRulesetsSetup {
     {
         // it will return the basedOn of the latest ruleset
 
-        uint256 _firstRulesetId = block.timestamp;
-        uint256 _rulesetWithHookId = block.timestamp + 1;
+        // Capture IDs from actual storage (avoid via_ir reordering of block.timestamp).
+        uint256 _firstRulesetId = _rulesets.currentOf(_projectId).id;
+        uint256 _rulesetWithHookId = _firstRulesetId + 1;
 
         JBRuleset memory _queuedRuleset = _rulesets.getRulesetOf(_projectId, _rulesetWithHookId);
 
-        vm.warp(block.timestamp + 4 days);
+        vm.warp(_firstRulesetId + 4 days);
 
         // mock approvalStatusOf to return Pending
         mockExpect(

package/test/units/static/JBRulesets/TestRulesets.sol

@@ -403,7 +403,8 @@ contract TestJBRulesetsUnits_Local is JBTest {
             mustStartAtOrAfter: _mustStartAt
         });
 
-        uint256 firstId = block.timestamp;
+        // Capture firstId from actual storage (avoid via_ir reordering of block.timestamp).
+        uint256 firstId = _rulesets.latestRulesetIdOf(_projectId);
 
         // Mock call to approval hook duration
         bytes memory _encodedDurationCall = abi.encodeCall(IJBRulesetApprovalHook.DURATION, ());
@@ -412,9 +413,9 @@ contract TestJBRulesetsUnits_Local is JBTest {
         mockExpect(address(_mockApprovalHook), _encodedDurationCall, _willReturnDuration);
 
         // avoid overwrite
-        vm.warp(block.timestamp + 1);
+        vm.warp(firstId + 1);
 
-        uint256 latestId = block.timestamp;
+        uint256 latestId;
 
         // Send: Anotha One! Call from this contract as it's been mock authorized above.
         _rulesets.queueFor({
@@ -424,12 +425,14 @@ contract TestJBRulesetsUnits_Local is JBTest {
             weightCutPercent: _weightCutPercent,
             approvalHook: _mockApprovalHook,
             metadata: _packedWithApprovalHook,
-            mustStartAtOrAfter: block.timestamp
+            mustStartAtOrAfter: 0
         });
 
+        // Capture latestId from storage (avoid via_ir reordering of block.timestamp).
+        latestId = _rulesets.latestRulesetIdOf(_projectId);
+
         // avoid overwrite
-        vm.warp(block.timestamp + 2 days);
-        uint256 previouslyApprovedDurationEnds = block.timestamp + 3 days - 2 days - 1;
+        vm.warp(latestId + 2 days);
 
         // Get the ruleset.
         JBRuleset memory latesetQueuedRuleset = _rulesets.getRulesetOf(_projectId, latestId);
@@ -449,16 +452,14 @@ contract TestJBRulesetsUnits_Local is JBTest {
             weightCutPercent: _weightCutPercent,
             approvalHook: _mockApprovalHook,
             metadata: _packedWithApprovalHook,
-            mustStartAtOrAfter: block.timestamp
+            mustStartAtOrAfter: 0
         });
 
-        latestId = block.timestamp;
+        latestId = _rulesets.latestRulesetIdOf(_projectId);
         latesetQueuedRuleset = _rulesets.getRulesetOf(_projectId, latestId);
 
         // avoid overwrite
-        vm.warp(block.timestamp + 1);
-
-        previouslyApprovedDurationEnds = block.timestamp + 6 days - 2 days - 2;
+        vm.warp(latestId + 1);
 
         // Mock call to approvalStatusOf and return an approvalExpected status
         _encodedApprovalCall = abi.encodeCall(IJBRulesetApprovalHook.approvalStatusOf, (1, latesetQueuedRuleset));
@@ -474,15 +475,14 @@ contract TestJBRulesetsUnits_Local is JBTest {
             weightCutPercent: _weightCutPercent,
             approvalHook: _mockApprovalHook,
             metadata: _packedWithApprovalHook,
-            mustStartAtOrAfter: block.timestamp
+            mustStartAtOrAfter: 0
         });
 
-        latestId = block.timestamp;
+        latestId = _rulesets.latestRulesetIdOf(_projectId);
         latesetQueuedRuleset = _rulesets.getRulesetOf(_projectId, latestId);
 
         // avoid overwrite
-        vm.warp(block.timestamp + 1);
-        previouslyApprovedDurationEnds = block.timestamp + 6 days - 2 days - 3;
+        vm.warp(latestId + 1);
 
         // Mock call to approvalStatusOf and return a failed status
         _encodedApprovalCall = abi.encodeCall(IJBRulesetApprovalHook.approvalStatusOf, (1, latesetQueuedRuleset));
@@ -498,16 +498,14 @@ contract TestJBRulesetsUnits_Local is JBTest {
             weightCutPercent: _weightCutPercent,
             approvalHook: _mockApprovalHook,
             metadata: _packedWithApprovalHook,
-            mustStartAtOrAfter: block.timestamp
+            mustStartAtOrAfter: 0
         });
 
-        latestId = block.timestamp;
+        latestId = _rulesets.latestRulesetIdOf(_projectId);
         latesetQueuedRuleset = _rulesets.getRulesetOf(_projectId, latestId);
 
         // avoid overwrite
-        vm.warp(block.timestamp + 1);
-
-        previouslyApprovedDurationEnds = block.timestamp + 6 days - 2 days - 4;
+        vm.warp(latestId + 1);
 
         // Mock call to approvalStatusOf and return an empty status
         _encodedApprovalCall = abi.encodeCall(IJBRulesetApprovalHook.approvalStatusOf, (1, latesetQueuedRuleset));
@@ -523,14 +521,17 @@ contract TestJBRulesetsUnits_Local is JBTest {
             weightCutPercent: _weightCutPercent,
             approvalHook: _mockApprovalHook,
             metadata: _packedWithApprovalHook,
-            mustStartAtOrAfter: block.timestamp
+            mustStartAtOrAfter: 0
         });
 
-        JBRuleset[] memory queuedRulesetsOf = _rulesets.allOf(_projectId, block.timestamp, 3);
+        // Capture final latestId from storage.
+        latestId = _rulesets.latestRulesetIdOf(_projectId);
+
+        JBRuleset[] memory queuedRulesetsOf = _rulesets.allOf(_projectId, latestId, 3);
 
-        // check: 2 rulesets will be enqueued, we just overwrote the last queued
+        // check: 3 rulesets will be enqueued
         assertEq(queuedRulesetsOf.length, 3);
-        assertEq(queuedRulesetsOf[0].id, block.timestamp);
+        assertEq(queuedRulesetsOf[0].id, latestId);
 
         // check first timestamp
         assertEq(queuedRulesetsOf[2].id, firstId);

package/test/units/static/JBRulesets/TestUpcomingRulesetOf.sol

@@ -457,8 +457,6 @@ contract TestUpcomingOf_Local is JBRulesetsSetup {
     function test_baseRulesetDurationDNEQZero() external {
         // it will simulate a ruleset basedOn
 
-        uint256 ogTimestamp = block.timestamp;
-
         // put code at hook address
         vm.etch(address(_mockApprovalHook), abi.encode(1));
 
@@ -476,20 +474,6 @@ contract TestUpcomingOf_Local is JBRulesetsSetup {
 
         mockExpect(address(directory), _encodedCall, _willReturn);
 
-        // Setup: expect ruleset event (RulesetQueued) is emitted
-        vm.expectEmit();
-        emit IJBRulesets.RulesetQueued(
-            block.timestamp,
-            _projectId,
-            _duration,
-            _weight,
-            _weightCutPercent,
-            _mockApprovalHook,
-            _packedWithApprovalHook,
-            block.timestamp,
-            address(this)
-        );
-
         // Send: Call from this contract as it's been mock authorized above.
         _rulesets.queueFor({
             projectId: _projectId,
@@ -501,6 +485,9 @@ contract TestUpcomingOf_Local is JBRulesetsSetup {
             mustStartAtOrAfter: _mustStartAt
         });
 
+        // Capture the first ruleset's id from storage (avoid via_ir reordering of block.timestamp).
+        uint256 ogTimestamp = _rulesets.currentOf(_projectId).id;
+
         // mock call to hook duration
         mockExpect(
             address(_mockApprovalHook), abi.encodeCall(IJBRulesetApprovalHook.DURATION, ()), abi.encode(_hookDuration)
@@ -517,7 +504,7 @@ contract TestUpcomingOf_Local is JBRulesetsSetup {
             mustStartAtOrAfter: 0
         });
 
-        vm.warp(block.timestamp + 3 days);
+        vm.warp(ogTimestamp + 3 days);
 
         uint256 _latestQueuedId = _rulesets.latestRulesetIdOf(_projectId);
         JBRuleset memory _queuedRuleset = _rulesets.getRulesetOf(_projectId, _latestQueuedId);

package/test/units/static/JBSurplus/TestSurplusFuzz.sol

@@ -1,14 +1,18 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.26;
 
+import {IJBCashOutTerminal} from "../../../../src/interfaces/IJBCashOutTerminal.sol";
 import {IJBTerminal} from "../../../../src/interfaces/IJBTerminal.sol";
 import {JBAccountingContext} from "../../../../src/structs/JBAccountingContext.sol";
+import {JBCashOutHookSpecification} from "../../../../src/structs/JBCashOutHookSpecification.sol";
+import {JBPayHookSpecification} from "../../../../src/structs/JBPayHookSpecification.sol";
+import {JBRuleset} from "../../../../src/structs/JBRuleset.sol";
 import {ERC165, IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 import {JBTest} from "../../../helpers/JBTest.sol";
 import {JBSurplus} from "../../../../src/libraries/JBSurplus.sol";
 
 /// @notice Mock terminal that returns a fixed surplus for testing JBSurplus.
-contract MockSurplusTerminal is ERC165, IJBTerminal {
+contract MockSurplusTerminal is ERC165, IJBCashOutTerminal {
     uint256 public surplusAmount;
 
     constructor(uint256 _surplus) {
@@ -30,7 +34,8 @@ contract MockSurplusTerminal is ERC165, IJBTerminal {
     }
 
     function supportsInterface(bytes4 interfaceId) public view override(ERC165, IERC165) returns (bool) {
-        return interfaceId == type(IJBTerminal).interfaceId || super.supportsInterface(interfaceId);
+        return interfaceId == type(IJBTerminal).interfaceId || interfaceId == type(IJBCashOutTerminal).interfaceId
+            || super.supportsInterface(interfaceId);
     }
 
     // Stub implementations for IJBTerminal
@@ -41,6 +46,31 @@ contract MockSurplusTerminal is ERC165, IJBTerminal {
         returns (JBAccountingContext memory)
     {}
     function accountingContextsOf(uint256) external pure override returns (JBAccountingContext[] memory) {}
+    function previewCashOutFrom(
+        address,
+        uint256,
+        uint256,
+        address,
+        address payable,
+        bytes calldata
+    )
+        external
+        pure
+        override
+        returns (JBRuleset memory, uint256, uint256, JBCashOutHookSpecification[] memory)
+    {}
+    function previewPayFor(
+        uint256,
+        address,
+        uint256,
+        address,
+        bytes calldata
+    )
+        external
+        pure
+        override
+        returns (JBRuleset memory, uint256, uint256, JBPayHookSpecification[] memory)
+    {}
     function addAccountingContextsFor(uint256, JBAccountingContext[] calldata) external override {}
     function addToBalanceOf(
         uint256,
@@ -75,6 +105,23 @@ contract MockSurplusTerminal is ERC165, IJBTerminal {
     {
         return 0;
     }
+
+    function cashOutTokensOf(
+        address,
+        uint256,
+        uint256,
+        address,
+        uint256,
+        address payable,
+        bytes calldata
+    )
+        external
+        pure
+        override
+        returns (uint256)
+    {
+        return 0;
+    }
 }
 
 /// @notice Fuzz tests for the JBSurplus library.

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);
+    }
 }