@bananapus/suckers-v6 0.0.24 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JBSuckerRegistry.sol

@@ -11,6 +11,7 @@ import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol"
 import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {EnumerableMap} from "@openzeppelin/contracts/utils/structs/EnumerableMap.sol";
 
+import {JBDenominatedAmount} from "./structs/JBDenominatedAmount.sol";
 import {JBSuckerState} from "./enums/JBSuckerState.sol";
 import {IJBSucker} from "./interfaces/IJBSucker.sol";
 import {IJBSuckerDeployer} from "./interfaces/IJBSuckerDeployer.sol";
@@ -189,6 +190,95 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         }
     }
 
+    /// @notice The cumulative balance across all remote peer chains for a project, denominated in a given currency.
+    /// @dev Sums `peerChainBalanceOf` from each active sucker. Silently skips suckers that revert.
+    /// @param projectId The ID of the project.
+    /// @param decimals The decimal precision for the returned value.
+    /// @param currency The currency to normalize to.
+    /// @return balance The combined peer chain balance.
+    function remoteBalanceOf(
+        uint256 projectId,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        override
+        returns (uint256 balance)
+    {
+        address[] memory allSuckers = _suckersOf[projectId].keys();
+        for (uint256 i; i < allSuckers.length;) {
+            // slither-disable-next-line unused-return
+            (, uint256 val) = _suckersOf[projectId].tryGet(allSuckers[i]);
+            if (val == _SUCKER_EXISTS) {
+                // slither-disable-next-line calls-loop
+                try IJBSucker(allSuckers[i]).peerChainBalanceOf(decimals, currency) returns (
+                    JBDenominatedAmount memory amt
+                ) {
+                    balance += amt.value;
+                } catch {}
+            }
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @notice The cumulative surplus across all remote peer chains for a project, denominated in a given currency.
+    /// @dev Sums `peerChainSurplusOf` from each active sucker. Silently skips suckers that revert.
+    /// @param projectId The ID of the project.
+    /// @param decimals The decimal precision for the returned value.
+    /// @param currency The currency to normalize to.
+    /// @return surplus The combined peer chain surplus.
+    function remoteSurplusOf(
+        uint256 projectId,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        override
+        returns (uint256 surplus)
+    {
+        address[] memory allSuckers = _suckersOf[projectId].keys();
+        for (uint256 i; i < allSuckers.length;) {
+            // slither-disable-next-line unused-return
+            (, uint256 val) = _suckersOf[projectId].tryGet(allSuckers[i]);
+            if (val == _SUCKER_EXISTS) {
+                // slither-disable-next-line calls-loop
+                try IJBSucker(allSuckers[i]).peerChainSurplusOf(decimals, currency) returns (
+                    JBDenominatedAmount memory amt
+                ) {
+                    surplus += amt.value;
+                } catch {}
+            }
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @notice The cumulative total supply across all remote peer chains for a project.
+    /// @dev Sums `peerChainTotalSupply` from each active sucker. Silently skips suckers that revert.
+    /// @param projectId The ID of the project.
+    /// @return totalSupply The combined peer chain total supply.
+    function remoteTotalSupplyOf(uint256 projectId) external view override returns (uint256 totalSupply) {
+        address[] memory allSuckers = _suckersOf[projectId].keys();
+        for (uint256 i; i < allSuckers.length;) {
+            // slither-disable-next-line unused-return
+            (, uint256 val) = _suckersOf[projectId].tryGet(allSuckers[i]);
+            if (val == _SUCKER_EXISTS) {
+                // slither-disable-next-line calls-loop
+                try IJBSucker(allSuckers[i]).peerChainTotalSupply() returns (uint256 supply) {
+                    totalSupply += supply;
+                } catch {}
+            }
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
     //*********************************************************************//
     // ------------------------ internal views --------------------------- //
     //*********************************************************************//

package/src/interfaces/IJBSuckerRegistry.sol

@@ -76,6 +76,42 @@ interface IJBSuckerRegistry {
     /// @return The addresses of the suckers.
     function suckersOf(uint256 projectId) external view returns (address[] memory);
 
+    /// @notice The cumulative total supply across all remote peer chains for a project.
+    /// @dev Sums `peerChainTotalSupply` from each active sucker. Silently skips suckers that revert.
+    /// @param projectId The ID of the project.
+    /// @return totalSupply The combined peer chain total supply.
+    function remoteTotalSupplyOf(uint256 projectId) external view returns (uint256 totalSupply);
+
+    /// @notice The cumulative balance across all remote peer chains for a project, denominated in a given currency.
+    /// @dev Sums `peerChainBalanceOf` from each active sucker. Silently skips suckers that revert.
+    /// @param projectId The ID of the project.
+    /// @param decimals The decimal precision for the returned value.
+    /// @param currency The currency to normalize to.
+    /// @return balance The combined peer chain balance.
+    function remoteBalanceOf(
+        uint256 projectId,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256 balance);
+
+    /// @notice The cumulative surplus across all remote peer chains for a project, denominated in a given currency.
+    /// @dev Sums `peerChainSurplusOf` from each active sucker. Silently skips suckers that revert.
+    /// @param projectId The ID of the project.
+    /// @param decimals The decimal precision for the returned value.
+    /// @param currency The currency to normalize to.
+    /// @return surplus The combined peer chain surplus.
+    function remoteSurplusOf(
+        uint256 projectId,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        returns (uint256 surplus);
+
     /// @notice The ETH fee (in wei) paid into the fee project on each toRemote() call.
     /// @return The current fee.
     function toRemoteFee() external view returns (uint256);

package/src/libraries/JBRelayBeneficiary.sol

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+
+import {IJBSuckerRegistry} from "../interfaces/IJBSuckerRegistry.sol";
+
+/// @notice Library to resolve the relay beneficiary from metadata injected by a relay terminal or sucker.
+/// @dev When a sucker pays a project on behalf of a remote user, the sucker is both payer and beneficiary.
+/// The real user's address is embedded in the payment metadata under the `ID` key. Data hooks and pay hooks
+/// use this library to resolve the real beneficiary so that NFTs, credits, etc. accrue to the correct user.
+library JBRelayBeneficiary {
+    /// @notice The metadata ID used to identify the relay beneficiary entry.
+    /// @dev Global constant (not per-contract) because the metadata is injected by the sucker but read by
+    /// unrelated hooks. Using `keccak256("JB_RELAY_BENEFICIARY")` ensures no collisions with contract-specific IDs.
+    bytes4 constant ID = bytes4(keccak256("JB_RELAY_BENEFICIARY"));
+
+    /// @notice Resolve the effective beneficiary for a payment.
+    /// @dev Returns `beneficiary` unchanged if the payer is not a registered sucker or if no relay data is found.
+    /// @param payer The address that called `terminal.pay()` (i.e. `context.payer`).
+    /// @param beneficiary The beneficiary set in the payment context (i.e. `context.beneficiary`).
+    /// @param projectId The project being paid.
+    /// @param metadata The payment metadata (`context.payerMetadata` or `context.metadata`).
+    /// @param registry The sucker registry used to verify that `payer` is a legitimate sucker.
+    /// @return effectiveBeneficiary The resolved beneficiary — the relay address if valid, or the original.
+    function resolve(
+        address payer,
+        address beneficiary,
+        uint256 projectId,
+        bytes memory metadata,
+        IJBSuckerRegistry registry
+    )
+        internal
+        view
+        returns (address effectiveBeneficiary)
+    {
+        // Only trust relay metadata when the payer is a registered sucker for this project.
+        if (!registry.isSuckerOf(projectId, payer)) {
+            return beneficiary;
+        }
+
+        // Try to find relay beneficiary data in the metadata.
+        (bool found, bytes memory data) = JBMetadataResolver.getDataFor({id: ID, metadata: metadata});
+        if (!found || data.length < 32) {
+            return beneficiary;
+        }
+
+        // Decode the relay beneficiary address.
+        address relayBeneficiary = abi.decode(data, (address));
+        if (relayBeneficiary == address(0)) {
+            return beneficiary;
+        }
+
+        return relayBeneficiary;
+    }
+}

package/test/unit/deployer.t.sol

@@ -12,6 +12,7 @@ import "@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol";
 import "../../src/JBSucker.sol";
 import {IJBSuckerDeployer} from "../../src/interfaces/IJBSuckerDeployer.sol";
 import {IJBSuckerRegistry} from "../../src/interfaces/IJBSuckerRegistry.sol";
+import {JBDenominatedAmount} from "../../src/structs/JBDenominatedAmount.sol";
 
 // forge-lint: disable-next-line(unaliased-plain-import)
 import "../../src/deployers/JBOptimismSuckerDeployer.sol";
@@ -586,6 +587,150 @@ contract DeployerTests is Test, TestBaseWorkflow, IERC721Receiver {
         assertTrue(registry.isSuckerOf(projectId, address(sucker2)));
     }
 
+    // ------------------------------------------------------------------
+    // Remote aggregate view tests
+    // ------------------------------------------------------------------
+
+    /// @notice remoteTotalSupplyOf sums peerChainTotalSupply across active suckers.
+    function testRemoteTotalSupplyOf(ICCIPRouter _ccipRouter) public {
+        vm.assume(uint160(address(_ccipRouter)) > 100);
+        _assumeNotDeployed(address(_ccipRouter));
+        vm.etch(address(_ccipRouter), "0x1");
+
+        _allowMapping(projectId, address(registry));
+
+        // Deploy two suckers to different chains.
+        IJBSuckerDeployer deployer1 = _addToRegistry(_setupCCIPDeployer(10, 1, _ccipRouter));
+        IJBSucker sucker1 = _deployThroughRegistry(deployer1, projectId, bytes32("salt1"));
+
+        IJBSuckerDeployer deployer2 = _addToRegistry(_setupCCIPDeployer(42_161, 2, _ccipRouter));
+        IJBSucker sucker2 = _deployThroughRegistry(deployer2, projectId, bytes32("salt2"));
+
+        // Mock peerChainTotalSupply on each sucker.
+        vm.mockCall(address(sucker1), abi.encodeCall(IJBSucker.peerChainTotalSupply, ()), abi.encode(100e18));
+        vm.mockCall(address(sucker2), abi.encodeCall(IJBSucker.peerChainTotalSupply, ()), abi.encode(250e18));
+
+        assertEq(registry.remoteTotalSupplyOf(projectId), 350e18);
+    }
+
+    /// @notice remoteBalanceOf sums peerChainBalanceOf across active suckers.
+    function testRemoteBalanceOf(ICCIPRouter _ccipRouter) public {
+        vm.assume(uint160(address(_ccipRouter)) > 100);
+        _assumeNotDeployed(address(_ccipRouter));
+        vm.etch(address(_ccipRouter), "0x1");
+
+        _allowMapping(projectId, address(registry));
+
+        IJBSuckerDeployer deployer1 = _addToRegistry(_setupCCIPDeployer(10, 1, _ccipRouter));
+        IJBSucker sucker1 = _deployThroughRegistry(deployer1, projectId, bytes32("salt1"));
+
+        IJBSuckerDeployer deployer2 = _addToRegistry(_setupCCIPDeployer(42_161, 2, _ccipRouter));
+        IJBSucker sucker2 = _deployThroughRegistry(deployer2, projectId, bytes32("salt2"));
+
+        uint256 ethCurrency = uint256(uint160(JBConstants.NATIVE_TOKEN));
+
+        // Mock peerChainBalanceOf on each sucker.
+        vm.mockCall(
+            address(sucker1),
+            abi.encodeCall(IJBSucker.peerChainBalanceOf, (18, ethCurrency)),
+            abi.encode(JBDenominatedAmount({value: 5e18, currency: uint32(ethCurrency), decimals: 18}))
+        );
+        vm.mockCall(
+            address(sucker2),
+            abi.encodeCall(IJBSucker.peerChainBalanceOf, (18, ethCurrency)),
+            abi.encode(JBDenominatedAmount({value: 3e18, currency: uint32(ethCurrency), decimals: 18}))
+        );
+
+        assertEq(registry.remoteBalanceOf(projectId, 18, ethCurrency), 8e18);
+    }
+
+    /// @notice remoteSurplusOf sums peerChainSurplusOf across active suckers.
+    function testRemoteSurplusOf(ICCIPRouter _ccipRouter) public {
+        vm.assume(uint160(address(_ccipRouter)) > 100);
+        _assumeNotDeployed(address(_ccipRouter));
+        vm.etch(address(_ccipRouter), "0x1");
+
+        _allowMapping(projectId, address(registry));
+
+        IJBSuckerDeployer deployer1 = _addToRegistry(_setupCCIPDeployer(10, 1, _ccipRouter));
+        IJBSucker sucker1 = _deployThroughRegistry(deployer1, projectId, bytes32("salt1"));
+
+        IJBSuckerDeployer deployer2 = _addToRegistry(_setupCCIPDeployer(42_161, 2, _ccipRouter));
+        IJBSucker sucker2 = _deployThroughRegistry(deployer2, projectId, bytes32("salt2"));
+
+        uint256 ethCurrency = uint256(uint160(JBConstants.NATIVE_TOKEN));
+
+        // Mock peerChainSurplusOf on each sucker.
+        vm.mockCall(
+            address(sucker1),
+            abi.encodeCall(IJBSucker.peerChainSurplusOf, (18, ethCurrency)),
+            abi.encode(JBDenominatedAmount({value: 10e18, currency: uint32(ethCurrency), decimals: 18}))
+        );
+        vm.mockCall(
+            address(sucker2),
+            abi.encodeCall(IJBSucker.peerChainSurplusOf, (18, ethCurrency)),
+            abi.encode(JBDenominatedAmount({value: 7e18, currency: uint32(ethCurrency), decimals: 18}))
+        );
+
+        assertEq(registry.remoteSurplusOf(projectId, 18, ethCurrency), 17e18);
+    }
+
+    /// @notice Remote views return 0 for a project with no suckers.
+    function testRemoteViewsZeroWithNoSuckers() public view {
+        assertEq(registry.remoteTotalSupplyOf(projectId), 0);
+        assertEq(registry.remoteBalanceOf(projectId, 18, uint256(uint160(JBConstants.NATIVE_TOKEN))), 0);
+        assertEq(registry.remoteSurplusOf(projectId, 18, uint256(uint160(JBConstants.NATIVE_TOKEN))), 0);
+    }
+
+    /// @notice Remote views skip deprecated suckers.
+    function testRemoteViewsSkipDeprecatedSuckers(ICCIPRouter _ccipRouter) public {
+        vm.assume(uint160(address(_ccipRouter)) > 100);
+        _assumeNotDeployed(address(_ccipRouter));
+        vm.etch(address(_ccipRouter), "0x1");
+
+        _allowMapping(projectId, address(registry));
+
+        IJBSuckerDeployer deployer1 = _addToRegistry(_setupCCIPDeployer(10, 1, _ccipRouter));
+        IJBSucker sucker1 = _deployThroughRegistry(deployer1, projectId, bytes32("salt1"));
+
+        // Mock peerChainTotalSupply.
+        vm.mockCall(address(sucker1), abi.encodeCall(IJBSucker.peerChainTotalSupply, ()), abi.encode(100e18));
+
+        // Before deprecation: 100e18.
+        assertEq(registry.remoteTotalSupplyOf(projectId), 100e18);
+
+        // Deprecate and remove.
+        JBSucker(payable(address(sucker1))).setDeprecation(uint40(block.timestamp + 14 days));
+        vm.warp(block.timestamp + 14 days);
+        registry.removeDeprecatedSucker(projectId, address(sucker1));
+
+        // After deprecation: 0.
+        assertEq(registry.remoteTotalSupplyOf(projectId), 0);
+    }
+
+    /// @notice Remote views silently skip suckers that revert.
+    function testRemoteViewsSkipRevertingSuckers(ICCIPRouter _ccipRouter) public {
+        vm.assume(uint160(address(_ccipRouter)) > 100);
+        _assumeNotDeployed(address(_ccipRouter));
+        vm.etch(address(_ccipRouter), "0x1");
+
+        _allowMapping(projectId, address(registry));
+
+        // Deploy two suckers.
+        IJBSuckerDeployer deployer1 = _addToRegistry(_setupCCIPDeployer(10, 1, _ccipRouter));
+        IJBSucker sucker1 = _deployThroughRegistry(deployer1, projectId, bytes32("salt1"));
+
+        IJBSuckerDeployer deployer2 = _addToRegistry(_setupCCIPDeployer(42_161, 2, _ccipRouter));
+        IJBSucker sucker2 = _deployThroughRegistry(deployer2, projectId, bytes32("salt2"));
+
+        // sucker1 returns 100e18, sucker2 reverts.
+        vm.mockCall(address(sucker1), abi.encodeCall(IJBSucker.peerChainTotalSupply, ()), abi.encode(100e18));
+        vm.mockCallRevert(address(sucker2), abi.encodeCall(IJBSucker.peerChainTotalSupply, ()), "boom");
+
+        // Should still return 100e18 (sucker2's revert is silently skipped).
+        assertEq(registry.remoteTotalSupplyOf(projectId), 100e18);
+    }
+
     /// @notice This function is called when we create a JB project.
     function onERC721Received(address, address, uint256, bytes calldata) external pure returns (bytes4) {
         return IERC721Receiver.onERC721Received.selector;

package/test/unit/relay_beneficiary.t.sol

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import "forge-std/Test.sol";
+
+import {JBRelayBeneficiary} from "../../src/libraries/JBRelayBeneficiary.sol";
+import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+import {IJBSuckerRegistry} from "../../src/interfaces/IJBSuckerRegistry.sol";
+
+/// @notice Thin wrapper that exposes the internal library function for testing.
+contract RelayBeneficiaryHarness {
+    function resolve(
+        address payer,
+        address beneficiary,
+        uint256 projectId,
+        bytes memory metadata,
+        IJBSuckerRegistry registry
+    )
+        external
+        view
+        returns (address)
+    {
+        return JBRelayBeneficiary.resolve({
+            payer: payer, beneficiary: beneficiary, projectId: projectId, metadata: metadata, registry: registry
+        });
+    }
+}
+
+contract RelayBeneficiaryTest is Test {
+    RelayBeneficiaryHarness harness;
+    IJBSuckerRegistry registry;
+
+    address payer = address(0xAAA);
+    address beneficiary = address(0xBBB);
+    address relayAddress = address(0xCCC);
+    uint256 projectId = 1;
+
+    function setUp() public {
+        harness = new RelayBeneficiaryHarness();
+        registry = IJBSuckerRegistry(makeAddr("registry"));
+    }
+
+    /// @notice Helper: mock isSuckerOf to return the given value.
+    function _mockIsSucker(bool isSucker) internal {
+        vm.mockCall(
+            address(registry), abi.encodeCall(IJBSuckerRegistry.isSuckerOf, (projectId, payer)), abi.encode(isSucker)
+        );
+    }
+
+    /// @notice Helper: build metadata containing the relay beneficiary address.
+    function _buildMetadata(address relay) internal pure returns (bytes memory) {
+        return JBMetadataResolver.addToMetadata({
+            originalMetadata: bytes(""), idToAdd: JBRelayBeneficiary.ID, dataToAdd: abi.encode(relay)
+        });
+    }
+
+    // ------------------------------------------------------------------
+    // Tests
+    // ------------------------------------------------------------------
+
+    function test_resolve_returnsOriginalIfNotSucker() public {
+        _mockIsSucker(false);
+
+        bytes memory metadata = _buildMetadata(relayAddress);
+
+        address result = harness.resolve(payer, beneficiary, projectId, metadata, registry);
+        assertEq(result, beneficiary, "Should return original beneficiary when payer is not a sucker");
+    }
+
+    function test_resolve_returnsOriginalIfNoMetadata() public {
+        _mockIsSucker(true);
+
+        address result = harness.resolve(payer, beneficiary, projectId, bytes(""), registry);
+        assertEq(result, beneficiary, "Should return original beneficiary when metadata is empty");
+    }
+
+    function test_resolve_returnsOriginalIfMetadataNotFound() public {
+        _mockIsSucker(true);
+
+        // Build metadata with a different ID so the relay key is absent.
+        bytes4 otherId = bytes4(keccak256("SOME_OTHER_KEY"));
+        bytes memory metadata = JBMetadataResolver.addToMetadata({
+            originalMetadata: bytes(""), idToAdd: otherId, dataToAdd: abi.encode(relayAddress)
+        });
+
+        address result = harness.resolve(payer, beneficiary, projectId, metadata, registry);
+        assertEq(result, beneficiary, "Should return original beneficiary when relay key is not in metadata");
+    }
+
+    function test_resolve_returnsOriginalIfRelayBeneficiaryZero() public {
+        _mockIsSucker(true);
+
+        bytes memory metadata = _buildMetadata(address(0));
+
+        address result = harness.resolve(payer, beneficiary, projectId, metadata, registry);
+        assertEq(result, beneficiary, "Should return original beneficiary when relay address is zero");
+    }
+
+    function test_resolve_returnsRelayBeneficiary() public {
+        _mockIsSucker(true);
+
+        bytes memory metadata = _buildMetadata(relayAddress);
+
+        address result = harness.resolve(payer, beneficiary, projectId, metadata, registry);
+        assertEq(result, relayAddress, "Should return relay beneficiary from metadata");
+    }
+
+    function test_resolve_returnsOriginalIfDataTooShort() public {
+        _mockIsSucker(true);
+
+        // Manually craft metadata where the relay key exists but the data segment is shorter than 32 bytes.
+        //
+        // JBMetadataResolver format:
+        //   [0..31]  : 32-byte reserved header
+        //   [32..36] : bytes4 id + uint8 offset (lookup table entry)
+        //   [37]     : 0x00 terminator (no more entries)
+        //   [offset*32 ..] : data
+        //
+        // We place the ID at byte 32, with offset = 2 (data starts at byte 64).
+        // Then we only write 16 bytes of data instead of 32, making data.length < 32.
+        bytes memory metadata = new bytes(64 + 16); // 80 bytes total
+
+        // Write the relay ID at position 32 (first lookup entry).
+        bytes4 id = JBRelayBeneficiary.ID;
+        metadata[32] = id[0];
+        metadata[33] = id[1];
+        metadata[34] = id[2];
+        metadata[35] = id[3];
+        // Offset = 2 means data starts at byte 64.
+        metadata[36] = bytes1(uint8(2));
+        // Terminator at position 37 (next entry ID byte is 0).
+
+        // Write 16 bytes of non-zero data starting at byte 64 (less than 32 bytes).
+        for (uint256 i = 64; i < 80; i++) {
+            metadata[i] = bytes1(uint8(0xFF));
+        }
+
+        address result = harness.resolve(payer, beneficiary, projectId, metadata, registry);
+        assertEq(result, beneficiary, "Should return original beneficiary when relay data is too short");
+    }
+}