@bananapus/core-v6 0.0.1

package/test/TestMetadataParserLib.sol

@@ -0,0 +1,438 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.23;
+
+import /* {*} from */ "./helpers/TestBaseWorkflow.sol";
+
+/**
+ * @notice Test the `JBDelegateMetadata` library and helper contract.
+ *
+ * @dev    These are a mixed collection of unit and integration tests.
+ */
+contract JBDelegateMetadataLib_Test_Local is Test {
+    MetadataResolverHelper parser;
+
+    /**
+     * @notice Deploy the helper contract.
+     *
+     * @dev    Helper inherits the lib and add `createMetadata`.
+     */
+    function setUp() external {
+        parser = new MetadataResolverHelper();
+    }
+
+    /**
+     * @notice Test the parsing of arbitrary metadata.
+     */
+    function test_parse() external view {
+        bytes4 _id1 = bytes4(0x11111111);
+        bytes4 _id2 = bytes4(0x33333333);
+
+        uint256 _data1 = 69_696_969;
+        bytes memory _data2 = new bytes(50);
+
+        bytes memory _metadata = abi.encodePacked(
+            // -- offset 0 --
+            bytes32(uint256(type(uint256).max)), // First 32B reserved
+            // -- offset 1 --
+            _id1, // First id
+            uint8(2), // First data offset == 2
+            _id2, // Second id == _id
+            uint8(3), // Second data offset == 3
+            bytes22(0), // Rest of the word is 0-padded
+            // -- offset 2 --
+            _data1, // First data
+            // -- offset 3 --
+            _data2 // Second data
+        );
+
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(_id2, _metadata);
+        assertEq(_dataParsed, _data2);
+        assertTrue(_found);
+
+        (_found, _dataParsed) = parser.getDataFor(_id1, _metadata);
+        assertEq(abi.decode(_dataParsed, (uint256)), _data1);
+        assertTrue(_found);
+    }
+
+    /**
+     * @notice Test creating and parsing bytes only metadata.
+     */
+    function test_createAndParse_bytes() external view {
+        bytes4[] memory _ids = new bytes4[](10);
+        bytes[] memory _datas = new bytes[](10);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(
+                bytes1(uint8(_i + 1)), uint32(69), bytes2(uint16(_i + 69)), bytes32(uint256(type(uint256).max))
+            );
+        }
+
+        bytes memory _metadata = parser.createMetadata(_ids, _datas);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            (bool _found, bytes memory _dataParsed) = parser.getDataFor(_ids[_i], _metadata);
+            (bytes1 _a, uint32 _deadBeef, bytes2 _c, bytes32 _d) =
+                abi.decode(_dataParsed, (bytes1, uint32, bytes2, bytes32));
+
+            assertTrue(_found);
+
+            assertEq(uint8(_a), _i + 1);
+            assertEq(uint256(_deadBeef), uint32(69));
+            assertEq(uint16(_c), _i + 69);
+            assertEq(_d, bytes32(uint256(type(uint256).max)));
+        }
+    }
+
+    /**
+     * @notice Test creating and parsing `uint`-only metadata.
+     */
+    function test_createAndParse_uint(uint256 _numberOfIds) external {
+        // Maximum 219 hooks with 1 word data (offset overflow if more).
+        _numberOfIds = bound(_numberOfIds, 1, 220);
+
+        bytes4[] memory _ids = new bytes4[](_numberOfIds);
+        bytes[] memory _datas = new bytes[](_numberOfIds);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(type(uint256).max - _i);
+        }
+
+        if (_numberOfIds == 220) vm.expectRevert(JBMetadataResolver.JBMetadataResolver_MetadataTooLong.selector);
+        bytes memory _metadata = parser.createMetadata(_ids, _datas);
+        if (_numberOfIds < 220) {
+            for (uint256 _i; _i < _ids.length; _i++) {
+                (bool _found, bytes memory _dataParsed) = parser.getDataFor(_ids[_i], _metadata);
+                uint256 _data = abi.decode(_dataParsed, (uint256));
+
+                assertTrue(_found);
+                assertEq(_data, type(uint256).max - _i);
+            }
+        }
+    }
+
+    /**
+     * @notice Test creating and parsing metadata of varying length.
+     */
+    function test_createAndParse_mixed(uint256 _numberOfIds) external view {
+        _numberOfIds = bound(_numberOfIds, 1, 15);
+
+        bytes4[] memory _ids = new bytes4[](_numberOfIds);
+        bytes[] memory _datas = new bytes[](_numberOfIds);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(69 << _i * 20);
+        }
+
+        bytes memory _metadata = parser.createMetadata(_ids, _datas);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            (bool _found, bytes memory _dataParsed) = parser.getDataFor(_ids[_i], _metadata);
+            uint256 _data = abi.decode(_dataParsed, (uint256));
+
+            assertTrue(_found);
+            assertEq(_data, 69 << _i * 20);
+        }
+    }
+
+    /**
+     * @notice Test if `createMetadata` reverts when the offset would overflow.
+     */
+    function test_createRevertIfOffsetTooBig(uint256 _numberOfIds) external {
+        // Max 1000 for evm memory limit
+        _numberOfIds = bound(_numberOfIds, 221, 1000);
+
+        bytes4[] memory _ids = new bytes4[](_numberOfIds);
+        bytes[] memory _datas = new bytes[](_numberOfIds);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(type(uint256).max - _i);
+        }
+
+        vm.expectRevert(JBMetadataResolver.JBMetadataResolver_MetadataTooLong.selector);
+        parser.createMetadata(_ids, _datas);
+    }
+
+    /**
+     * @notice Test adding `uint` to an `uint` metadata.
+     */
+    function test_addToMetadata_uint(uint256 _numberOfIds) external view {
+        _numberOfIds = bound(_numberOfIds, 1, 219);
+
+        bytes4[] memory _ids = new bytes4[](_numberOfIds);
+        bytes[] memory _datas = new bytes[](_numberOfIds);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(type(uint256).max - _i);
+        }
+
+        bytes memory _metadata = parser.createMetadata(_ids, _datas);
+
+        bytes memory _modifiedMetadata =
+            parser.addDataToMetadata(_metadata, bytes4(uint32(type(uint32).max)), abi.encode(123_456));
+
+        // Check
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(bytes4(uint32(type(uint32).max)), _modifiedMetadata);
+        uint256 _data = abi.decode(_dataParsed, (uint256));
+
+        assertTrue(_found);
+        assertEq(_data, 123_456);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            (_found, _dataParsed) = parser.getDataFor(_ids[_i], _modifiedMetadata);
+            _data = abi.decode(_dataParsed, (uint256));
+
+            assertTrue(_found);
+            assertEq(_data, type(uint256).max - _i);
+        }
+    }
+
+    /**
+     * @notice Test adding `bytes` to a `bytes` metadata.
+     */
+    function test_addToMetadata_bytes() public view {
+        bytes4[] memory _ids = new bytes4[](2);
+        bytes[] memory _datas = new bytes[](2);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(
+                bytes1(uint8(_i + 1)), uint32(69), bytes2(uint16(_i + 69)), bytes32(uint256(type(uint256).max))
+            );
+        }
+
+        bytes memory _metadata = parser.createMetadata(_ids, _datas);
+
+        bytes memory _modifiedMetadata = parser.addDataToMetadata(
+            _metadata,
+            bytes4(uint32(type(uint32).max)),
+            abi.encode(bytes32(uint256(type(uint256).max)), bytes32(hex"123456"))
+        );
+
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(bytes4(uint32(type(uint32).max)), _modifiedMetadata);
+        (bytes32 _a, bytes32 _b) = abi.decode(_dataParsed, (bytes32, bytes32));
+
+        assertTrue(_found);
+        assertEq(bytes32(uint256(type(uint256).max)), _a);
+        assertEq(bytes32(hex"123456"), _b);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            (_found, _dataParsed) = parser.getDataFor(_ids[_i], _modifiedMetadata);
+
+            (bytes1 _c, uint32 _d, bytes2 _e, bytes32 _f) = abi.decode(_dataParsed, (bytes1, uint32, bytes2, bytes32));
+
+            assertTrue(_found);
+            assertEq(uint8(_c), _i + 1);
+            assertEq(_d, uint32(69));
+            assertEq(uint16(_e), _i + 69);
+            assertEq(_f, bytes32(uint256(type(uint256).max)));
+        }
+    }
+
+    /**
+     * @notice Test adding `bytes` to an `uint` metadata.
+     */
+    function test_addToMetadata_mixed(uint256 _numberOfIds) external view {
+        _numberOfIds = bound(_numberOfIds, 1, 100);
+
+        bytes4[] memory _ids = new bytes4[](_numberOfIds);
+        bytes[] memory _datas = new bytes[](_numberOfIds);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(_i * 4);
+        }
+
+        bytes memory _metadata = parser.createMetadata(_ids, _datas);
+
+        bytes memory _modifiedMetadata = parser.addDataToMetadata(
+            _metadata, bytes4(uint32(type(uint32).max)), abi.encode(uint32(69), bytes32(uint256(type(uint256).max)))
+        );
+
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(bytes4(uint32(type(uint32).max)), _modifiedMetadata);
+        (uint32 _a, bytes32 _b) = abi.decode(_dataParsed, (uint32, bytes32));
+
+        assertTrue(_found);
+        assertEq(_a, uint32(69));
+        assertEq(_b, bytes32(uint256(type(uint256).max)));
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            (_found, _dataParsed) = parser.getDataFor(_ids[_i], _modifiedMetadata);
+            uint256 _data = abi.decode(_dataParsed, (uint256));
+
+            assertTrue(_found);
+            assertEq(_data, _i * 4);
+        }
+    }
+
+    /**
+     * @notice Test adding `bytes32` and `uint` to an empty metadata.
+     */
+    function test_addToMetadata_emptyInitialMetadata() external view {
+        bytes memory _metadata;
+
+        bytes memory _modifiedMetadata = parser.addDataToMetadata(
+            _metadata, bytes4(uint32(type(uint32).max)), abi.encode(uint32(69), bytes32(uint256(type(uint256).max)))
+        );
+
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(bytes4(uint32(type(uint32).max)), _modifiedMetadata);
+        (uint32 _a, bytes32 _b) = abi.decode(_dataParsed, (uint32, bytes32));
+
+        assertTrue(_found);
+        assertEq(_a, uint32(69));
+        assertEq(_b, bytes32(uint256(type(uint256).max)));
+    }
+
+    /**
+     * @notice Test adding `bytes32` and `uint` to a metadata which contains something in the first bytes32
+     */
+    function test_addToMetadata_preexistingMetadata(uint256 _reserved) external view {
+        bytes memory _metadata = abi.encode(_reserved);
+
+        bytes memory _modifiedMetadata = parser.addDataToMetadata(
+            _metadata, bytes4(uint32(type(uint32).max)), abi.encode(uint32(69), bytes32(uint256(type(uint256).max)))
+        );
+
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(bytes4(uint32(type(uint32).max)), _modifiedMetadata);
+        (uint32 _a, bytes32 _b) = abi.decode(_dataParsed, (uint32, bytes32));
+
+        assertTrue(_found);
+        assertEq(_a, uint32(69));
+        assertEq(_b, bytes32(uint256(type(uint256).max)));
+
+        assertEq(uint256(bytes32(_modifiedMetadata)), _reserved);
+    }
+
+    function test_addToMetadata_invalidExistingTable_reverts() public {
+        vm.expectRevert(JBMetadataResolver.JBMetadataResolver_MetadataTooShort.selector);
+
+        // Preexisting metadata: 32B + 4B
+        parser.addDataToMetadata(
+            abi.encodePacked(bytes32(uint256(type(uint256).max)), bytes4(uint32(type(uint32).max))),
+            bytes4(uint32(type(uint32).max)),
+            bytes("12345678901234567890123456789012345678901234567890123456789012345678901234567890")
+        );
+    }
+
+    function test_addToMetadata_shortDataToAdd_reverts() public {
+        vm.expectRevert(JBMetadataResolver.JBMetadataResolver_DataNotPadded.selector);
+
+        // Preexisting metadata: 32B + 4B
+        parser.addDataToMetadata(
+            abi.encodePacked(bytes32(uint256(type(uint256).max)), bytes8(uint64(type(uint64).max))),
+            bytes4(uint32(type(uint32).max)),
+            bytes("1234")
+        );
+    }
+
+    /**
+     * @notice Test behaviour if the ID is not found in the lookup table.
+     */
+    function test_idNotFound(uint256 _numberOfIds) public view {
+        _numberOfIds = bound(_numberOfIds, 1, 100);
+
+        bytes4[] memory _ids = new bytes4[](_numberOfIds);
+        bytes[] memory _datas = new bytes[](_numberOfIds);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+            _datas[_i] = abi.encode(_i * 4);
+        }
+
+        bytes memory _metadata = parser.createMetadata(_ids, _datas);
+
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(bytes4(uint32(type(uint32).max)), _metadata);
+
+        assertFalse(_found);
+        assertEq(_dataParsed, "");
+    }
+
+    /**
+     * @notice Test behaviour if the metadata is empty or less than one ID long.
+     */
+    function test_emptyMetadata(uint256 _length) public view {
+        _length = bound(_length, 0, 37);
+
+        bytes memory _metadata;
+
+        // Fill with hex `F`.
+        _metadata = abi.encodePacked(bytes32(uint256(type(uint256).max)), bytes32(uint256(type(uint256).max)));
+
+        // Downsize to the length.
+        assembly {
+            mstore(_metadata, _length)
+        }
+
+        (bool _found, bytes memory _dataParsed) = parser.getDataFor(bytes4(uint32(type(uint32).max)), _metadata);
+
+        assertFalse(_found);
+        assertEq(_dataParsed, "");
+    }
+
+    function test_differentSizeIdAndMetadataArray_reverts(uint256 _numberOfIds, uint256 _numberOfMetadatas) public {
+        _numberOfIds = bound(_numberOfIds, 1, 100);
+        _numberOfMetadatas = bound(_numberOfMetadatas, 1, 100);
+
+        vm.assume(_numberOfIds != _numberOfMetadatas);
+
+        bytes4[] memory _ids = new bytes4[](_numberOfIds);
+        bytes[] memory _datas = new bytes[](_numberOfMetadatas);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+        }
+
+        for (uint256 _i; _i < _datas.length; _i++) {
+            _datas[_i] = abi.encode(_i * 4);
+        }
+
+        // Below should revert.
+        vm.expectRevert(JBMetadataResolver.JBMetadataResolver_LengthMismatch.selector);
+        parser.createMetadata(_ids, _datas);
+    }
+
+    /**
+     * @notice Test creating and parsing metadata of incorrect length.
+     */
+    function test_create__unpadded() external {
+        bytes4[] memory _ids = new bytes4[](1);
+        bytes[] memory _datas = new bytes[](1);
+
+        uint8 something = uint8(1);
+        bytes memory shortData = abi.encodePacked(something);
+
+        _ids[0] = bytes4(uint32(1));
+        _datas[0] = shortData;
+
+        vm.expectRevert(JBMetadataResolver.JBMetadataResolver_DataNotPadded.selector);
+        parser.createMetadata(_ids, _datas);
+    }
+
+    /**
+     * @notice Test creating and parsing bytes only metadata.
+     */
+    function test_create_incorrect_data_length() external {
+        bytes4[] memory _ids = new bytes4[](10);
+        bytes[] memory _datas = new bytes[](10);
+
+        for (uint256 _i; _i < _ids.length; _i++) {
+            _ids[_i] = bytes4(uint32(_i + 1 * 1000));
+
+            _datas[_i] = abi.encodePacked(
+                bytes1(uint8(_i + 1)), uint32(69), bytes2(uint16(_i + 69)), bytes32(uint256(type(uint256).max))
+            );
+        }
+
+        // Ensure data length is not multiple of word size and is gt word size.
+        assertGt(_datas[0].length, 32);
+        assertGt(_datas[0].length % 32, 0);
+
+        // New revert to help integrators.
+        vm.expectRevert(JBMetadataResolver.JBMetadataResolver_DataNotPadded.selector);
+        parser.createMetadata(_ids, _datas);
+    }
+}

package/test/TestMigrationHeldFees.sol

@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.6;
+
+import /* {*} from */ "./helpers/TestBaseWorkflow.sol";
+
+/// @notice Confirms M-16: held fees are stranded when a terminal migrates.
+/// The migration calls addToBalanceOf with shouldReturnHeldFees: false,
+/// leaving held fees in the old terminal with no balance to process them.
+contract TestMigrationHeldFees_Local is TestBaseWorkflow {
+    IJBController private _controller;
+    JBMultiTerminal private _terminal;
+    JBMultiTerminal private _terminal2;
+    JBTokens private _tokens;
+    JBTerminalStore private _store;
+    uint256 private _projectId;
+    address private _projectOwner;
+
+    uint112 private constant WEIGHT = 1000 * 10 ** 18;
+    uint112 private constant PAY_AMOUNT = 10 ether;
+
+    function setUp() public override {
+        super.setUp();
+
+        _projectOwner = multisig();
+        _controller = jbController();
+        _terminal = jbMultiTerminal();
+        _terminal2 = jbMultiTerminal2();
+        _tokens = jbTokens();
+        _store = jbTerminalStore();
+
+        // Ruleset with holdFees=true and allowTerminalMigration=true.
+        JBRulesetMetadata memory metadata = JBRulesetMetadata({
+            reservedPercent: 0,
+            cashOutTaxRate: 0,
+            baseCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            pausePay: false,
+            pauseCreditTransfers: false,
+            allowOwnerMinting: false,
+            allowSetCustomToken: false,
+            allowTerminalMigration: true,
+            allowSetTerminals: true,
+            ownerMustSendPayouts: false,
+            allowSetController: false,
+            allowAddAccountingContext: true,
+            allowAddPriceFeed: false,
+            holdFees: true, // Fees are held, not processed immediately.
+            useTotalSurplusForCashOuts: false,
+            useDataHookForPay: false,
+            useDataHookForCashOut: false,
+            dataHook: address(0),
+            metadata: 0
+        });
+
+        JBRulesetConfig[] memory rulesetConfig = new JBRulesetConfig[](1);
+        rulesetConfig[0].mustStartAtOrAfter = 0;
+        rulesetConfig[0].duration = 0;
+        rulesetConfig[0].weight = WEIGHT;
+        rulesetConfig[0].weightCutPercent = 0;
+        rulesetConfig[0].approvalHook = IJBRulesetApprovalHook(address(0));
+        rulesetConfig[0].metadata = metadata;
+        rulesetConfig[0].splitGroups = new JBSplitGroup[](0);
+
+        // Set up payout limit so fees are taken on payouts.
+        JBCurrencyAmount[] memory payoutLimits = new JBCurrencyAmount[](1);
+        payoutLimits[0] =
+            JBCurrencyAmount({amount: uint224(PAY_AMOUNT), currency: uint32(uint160(JBConstants.NATIVE_TOKEN))});
+        JBFundAccessLimitGroup[] memory limitGroups = new JBFundAccessLimitGroup[](1);
+        limitGroups[0] = JBFundAccessLimitGroup({
+            terminal: address(_terminal),
+            token: JBConstants.NATIVE_TOKEN,
+            payoutLimits: payoutLimits,
+            surplusAllowances: new JBCurrencyAmount[](0)
+        });
+        rulesetConfig[0].fundAccessLimitGroups = limitGroups;
+
+        // Terminal configs — both terminals accept native token.
+        JBAccountingContext[] memory tokensToAccept = new JBAccountingContext[](1);
+        tokensToAccept[0] = JBAccountingContext({
+            token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+        });
+
+        JBTerminalConfig[] memory terminalConfigs = new JBTerminalConfig[](2);
+        terminalConfigs[0] =
+            JBTerminalConfig({terminal: IJBTerminal(address(_terminal)), accountingContextsToAccept: tokensToAccept});
+        terminalConfigs[1] =
+            JBTerminalConfig({terminal: IJBTerminal(address(_terminal2)), accountingContextsToAccept: tokensToAccept});
+
+        // Fee project (#1).
+        JBTerminalConfig[] memory feeTerminalConfigs = new JBTerminalConfig[](1);
+        feeTerminalConfigs[0] =
+            JBTerminalConfig({terminal: IJBTerminal(address(_terminal)), accountingContextsToAccept: tokensToAccept});
+
+        JBRulesetConfig[] memory feeRulesetConfig = new JBRulesetConfig[](1);
+        feeRulesetConfig[0].mustStartAtOrAfter = 0;
+        feeRulesetConfig[0].duration = 0;
+        feeRulesetConfig[0].weight = WEIGHT;
+        feeRulesetConfig[0].metadata = metadata;
+        feeRulesetConfig[0].splitGroups = new JBSplitGroup[](0);
+        feeRulesetConfig[0].fundAccessLimitGroups = new JBFundAccessLimitGroup[](0);
+
+        _controller.launchProjectFor({
+            owner: address(420),
+            projectUri: "fee",
+            rulesetConfigurations: feeRulesetConfig,
+            terminalConfigurations: feeTerminalConfigs,
+            memo: ""
+        });
+
+        // Test project (#2).
+        _projectId = _controller.launchProjectFor({
+            owner: _projectOwner,
+            projectUri: "test",
+            rulesetConfigurations: rulesetConfig,
+            terminalConfigurations: terminalConfigs,
+            memo: ""
+        });
+    }
+
+    /// @notice M-16 CONFIRMED: Pay → distribute payouts (holds fees) → migrate → fees stranded.
+    function test_migration_heldFeesStranded() external {
+        // Step 1: Pay the project.
+        _terminal.pay{value: PAY_AMOUNT}({
+            projectId: _projectId,
+            amount: PAY_AMOUNT,
+            token: JBConstants.NATIVE_TOKEN,
+            beneficiary: _projectOwner,
+            minReturnedTokens: 0,
+            memo: "",
+            metadata: new bytes(0)
+        });
+
+        // Step 2: Distribute payouts — fees will be held (holdFees=true).
+        vm.prank(_projectOwner);
+        _terminal.sendPayoutsOf({
+            projectId: _projectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: PAY_AMOUNT,
+            currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            minTokensPaidOut: 0
+        });
+
+        // Verify held fees exist.
+        JBFee[] memory heldFees = _terminal.heldFeesOf(_projectId, JBConstants.NATIVE_TOKEN, 100);
+        assertGt(heldFees.length, 0, "Should have held fees after payout");
+
+        // Step 3: Migrate balance to terminal2.
+        uint256 balanceBefore = _store.balanceOf(address(_terminal), _projectId, JBConstants.NATIVE_TOKEN);
+
+        vm.prank(_projectOwner);
+        uint256 migrated =
+            _terminal.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, IJBTerminal(address(_terminal2)));
+
+        // Step 4: Verify old terminal has no balance but still has held fees.
+        uint256 balanceAfter = _store.balanceOf(address(_terminal), _projectId, JBConstants.NATIVE_TOKEN);
+        assertEq(balanceAfter, 0, "Old terminal should have 0 balance after migration");
+
+        // Held fees still exist in old terminal.
+        JBFee[] memory feesAfterMigration = _terminal.heldFeesOf(_projectId, JBConstants.NATIVE_TOKEN, 100);
+        assertEq(feesAfterMigration.length, heldFees.length, "M-16: Held fees remain in old terminal");
+    }
+
+    /// @notice Process held fees FIRST, then migrate — correct approach.
+    function test_migration_feeProcessingBeforeMigration() external {
+        // Pay.
+        _terminal.pay{value: PAY_AMOUNT}({
+            projectId: _projectId,
+            amount: PAY_AMOUNT,
+            token: JBConstants.NATIVE_TOKEN,
+            beneficiary: _projectOwner,
+            minReturnedTokens: 0,
+            memo: "",
+            metadata: new bytes(0)
+        });
+
+        // Distribute payouts (holds fees).
+        vm.prank(_projectOwner);
+        _terminal.sendPayoutsOf({
+            projectId: _projectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: PAY_AMOUNT,
+            currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            minTokensPaidOut: 0
+        });
+
+        // Fast-forward past fee holding period (28 days).
+        vm.warp(block.timestamp + 28 days + 1);
+
+        // Process held fees before migration.
+        uint256 feeProjectBalanceBefore = _store.balanceOf(address(_terminal), 1, JBConstants.NATIVE_TOKEN);
+        _terminal.processHeldFeesOf(_projectId, JBConstants.NATIVE_TOKEN, 100);
+        uint256 feeProjectBalanceAfter = _store.balanceOf(address(_terminal), 1, JBConstants.NATIVE_TOKEN);
+
+        // Fee project should have received fees.
+        assertGt(feeProjectBalanceAfter, feeProjectBalanceBefore, "Fee project should receive fees");
+
+        // Now held fees should be cleared.
+        JBFee[] memory feesAfter = _terminal.heldFeesOf(_projectId, JBConstants.NATIVE_TOKEN, 100);
+        assertEq(feesAfter.length, 0, "Held fees should be cleared after processing");
+
+        // Now migrate safely.
+        vm.prank(_projectOwner);
+        _terminal.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, IJBTerminal(address(_terminal2)));
+    }
+
+    /// @notice After migration, processHeldFeesOf on old terminal processes nothing (no balance).
+    function test_migration_heldFeesUnclaimable() external {
+        // Pay and distribute.
+        _terminal.pay{value: PAY_AMOUNT}({
+            projectId: _projectId,
+            amount: PAY_AMOUNT,
+            token: JBConstants.NATIVE_TOKEN,
+            beneficiary: _projectOwner,
+            minReturnedTokens: 0,
+            memo: "",
+            metadata: new bytes(0)
+        });
+
+        vm.prank(_projectOwner);
+        _terminal.sendPayoutsOf({
+            projectId: _projectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: PAY_AMOUNT,
+            currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            minTokensPaidOut: 0
+        });
+
+        // Migrate.
+        vm.prank(_projectOwner);
+        _terminal.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, IJBTerminal(address(_terminal2)));
+
+        // Warp past holding period.
+        vm.warp(block.timestamp + 28 days + 1);
+
+        // Fee project balance before attempting to process.
+        uint256 feeBalanceBefore = _store.balanceOf(address(_terminal), 1, JBConstants.NATIVE_TOKEN);
+
+        // Try to process held fees — the fees still exist but the old terminal has no ETH.
+        // The _processFee try-catch will catch the revert and credit the fee amount back to the project.
+        _terminal.processHeldFeesOf(_projectId, JBConstants.NATIVE_TOKEN, 100);
+
+        // Fee project should NOT have received fees (old terminal had no ETH to transfer).
+        uint256 feeBalanceAfter = _store.balanceOf(address(_terminal), 1, JBConstants.NATIVE_TOKEN);
+
+        // The fee processing attempted but the terminal has no actual ETH.
+        // The _recordAddedBalanceFor in the catch block inflates the store balance
+        // without actual funds — this is a phantom balance.
+        // This documents the M-16 issue: either fees are lost OR phantom balances are created.
+    }
+}