ipor-fusion 4.0.0.dev279__tar.gz → 4.0.0.dev282__tar.gz

{ipor_fusion-4.0.0.dev279 → ipor_fusion-4.0.0.dev282}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev279
+Version: 4.0.0.dev282
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py

{ipor_fusion-4.0.0.dev279 → ipor_fusion-4.0.0.dev282}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev279"
+version = "4.0.0.dev282"
 description = "The IPOR Fusion SDK for Python"
 authors = [
     { name = "Adam Mydlarz", email = "amydlarz@gmail.com" },

{ipor_fusion-4.0.0.dev279 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/fuses/universal.py

@@ -14,14 +14,18 @@ from ipor_fusion.types import Amount, FuseAddress
 class UniversalTokenSwapperAbi(Enum):
     """ABI revision of the deployed UniversalTokenSwapperFuse contract.
 
-    Deployed fuses are immutable, so both revisions coexist across chains:
-    older deployments (e.g. Base) accept only the LEGACY signature, newer
-    ones (e.g. HyperEVM, markets 12 and 1202) only the MIN_AMOUNT_OUT one.
-    Pick the member matching the fuse address this instance is bound to.
+    Deployed fuses are immutable, so the revisions coexist across chains:
+    older deployments (e.g. Base) accept only the LEGACY signature, the
+    HyperEVM ones (markets 12 and 1202) only the MIN_AMOUNT_OUT one, and the
+    Arbitrum fuses of the 2026-10-21 contracts release (markets 12 and 1202)
+    only TOKENS_TO_RETURN, which adds the tokens the swap calls may leave in
+    the executor. Pick the member matching the fuse address this instance is
+    bound to.
     """
 
     LEGACY = auto()
     MIN_AMOUNT_OUT = auto()
+    TOKENS_TO_RETURN = auto()
 
 
 class UniversalTokenSwapperSubstrates:
@@ -73,7 +77,11 @@ class UniversalTokenSwapperFuse(Fuse):
         targets: list[ChecksumAddress],
         data: list[bytes],
         min_amount_out: Amount | None = None,
+        tokens_to_return: list[ChecksumAddress] | None = None,
     ) -> FuseAction:
+        """``tokens_to_return`` (TOKENS_TO_RETURN only): intermediate or extra
+        output tokens the swap calls may leave in the executor, each a granted
+        Token substrate; the executor returns them to the vault."""
         self._validate_address(token_in, "token_in")
         self._validate_address(token_out, "token_out")
         self._validate_amount(amount_in, "amount_in")
@@ -81,6 +89,13 @@ class UniversalTokenSwapperFuse(Fuse):
             raise ValueError(
                 f"targets and data must have the same length, got {len(targets)} and {len(data)}"
             )
+        if (
+            tokens_to_return is not None
+            and self._abi is not UniversalTokenSwapperAbi.TOKENS_TO_RETURN
+        ):
+            raise ValueError(
+                "tokens_to_return requires abi=UniversalTokenSwapperAbi.TOKENS_TO_RETURN"
+            )
         if self._abi is UniversalTokenSwapperAbi.LEGACY:
             if min_amount_out is not None:
                 raise ValueError(
@@ -92,11 +107,27 @@ class UniversalTokenSwapperFuse(Fuse):
             )
         if min_amount_out is None:
             raise ValueError(
-                "min_amount_out is required with abi=UniversalTokenSwapperAbi.MIN_AMOUNT_OUT"
+                f"min_amount_out is required with abi=UniversalTokenSwapperAbi.{self._abi.name}"
                 " (pass 0 to rely on the vault-side slippage cap only)"
             )
         self._validate_non_negative(min_amount_out, "min_amount_out")
+        if self._abi is UniversalTokenSwapperAbi.MIN_AMOUNT_OUT:
+            return self._action_raw(
+                "enter((address,address,uint256,uint256,(address[],bytes[])))",
+                [[token_in, token_out, amount_in, min_amount_out, [targets, data]]],
+            )
+        returned = list(tokens_to_return or [])
+        for index, token in enumerate(returned):
+            self._validate_address(token, f"tokens_to_return[{index}]")
         return self._action_raw(
-            "enter((address,address,uint256,uint256,(address[],bytes[])))",
-            [[token_in, token_out, amount_in, min_amount_out, [targets, data]]],
+            "enter((address,address,uint256,uint256,(address[],bytes[],address[])))",
+            [
+                [
+                    token_in,
+                    token_out,
+                    amount_in,
+                    min_amount_out,
+                    [targets, data, returned],
+                ]
+            ],
         )

{ipor_fusion-4.0.0.dev279 → ipor_fusion-4.0.0.dev282}/tests/test_fuse_encoding.py

@@ -816,6 +816,78 @@ class TestUniversalTokenSwapperFuse:
         assert decoded_tuple[3] == 4900
         assert decoded_tuple[4][1][0] == b"\xaa\xbb"
 
+    def test_swap_tokens_to_return_abi(self):
+        """The Arbitrum fuses of the 2026-10-21 release (markets 12 and 1202,
+        0xD42940B4… and 0x9d74A79b…) carry only this selector."""
+        action = UniversalTokenSwapperFuse(
+            FUSE_ADDR, abi=UniversalTokenSwapperAbi.TOKENS_TO_RETURN
+        ).swap(
+            token_in=TOKEN_A,
+            token_out=TOKEN_B,
+            amount_in=5000,
+            targets=[TOKEN_A],
+            data=[b"\xaa\xbb"],
+            min_amount_out=4900,
+            tokens_to_return=[TOKEN_B],
+        )
+        signature = (
+            "enter((address,address,uint256,uint256,(address[],bytes[],address[])))"
+        )
+        assert action.data[:4] == _selector(signature)
+        assert _selector(signature).hex() == "3b2607a8"
+        (decoded_tuple,) = decode(
+            ["(address,address,uint256,uint256,(address[],bytes[],address[]))"],
+            action.data[4:],
+        )
+        assert decoded_tuple[3] == 4900
+        assert decoded_tuple[4][1][0] == b"\xaa\xbb"
+        assert [t.lower() for t in decoded_tuple[4][2]] == [TOKEN_B_LOW]
+        empty = UniversalTokenSwapperFuse(
+            FUSE_ADDR, abi=UniversalTokenSwapperAbi.TOKENS_TO_RETURN
+        ).swap(
+            token_in=TOKEN_A,
+            token_out=TOKEN_B,
+            amount_in=1,
+            targets=[],
+            data=[],
+            min_amount_out=0,
+        )
+        assert (
+            decode(
+                ["(address,address,uint256,uint256,(address[],bytes[],address[]))"],
+                empty.data[4:],
+            )[0][4][2]
+            == ()
+        )
+
+    def test_tokens_to_return_abi_requires_min_amount_out(self):
+        with pytest.raises(
+            ValueError, match="abi=UniversalTokenSwapperAbi.TOKENS_TO_RETURN"
+        ):
+            UniversalTokenSwapperFuse(
+                FUSE_ADDR, abi=UniversalTokenSwapperAbi.TOKENS_TO_RETURN
+            ).swap(
+                token_in=TOKEN_A,
+                token_out=TOKEN_B,
+                amount_in=1,
+                targets=[],
+                data=[],
+            )
+
+    def test_tokens_to_return_needs_its_abi(self):
+        with pytest.raises(ValueError, match="TOKENS_TO_RETURN"):
+            UniversalTokenSwapperFuse(
+                FUSE_ADDR, abi=UniversalTokenSwapperAbi.MIN_AMOUNT_OUT
+            ).swap(
+                token_in=TOKEN_A,
+                token_out=TOKEN_B,
+                amount_in=1,
+                targets=[],
+                data=[],
+                min_amount_out=0,
+                tokens_to_return=[TOKEN_B],
+            )
+
     def test_swap_min_amount_out_zero_allowed(self):
         action = UniversalTokenSwapperFuse(
             FUSE_ADDR, abi=UniversalTokenSwapperAbi.MIN_AMOUNT_OUT