ipor-fusion 4.0.0.dev291__tar.gz → 4.0.0.dev295__tar.gz

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/AGENTS.md

@@ -154,6 +154,15 @@ the lifecycle matrix follows that.
   `commit-lint.yml` fails a PR whose commit subjects or title break it. Never
   hand-bump `project.version`; the release workflow stamps it and re-locks
   `uv.lock`.
+- Preview features (`ipor_fusion.crosschain` with its subpackages, and
+  `ipor_fusion.hypercore`) keep no backward compatibility: they follow the
+  current official contracts only, and support for retired deployments (the
+  pilot executors and factories, canaries) is removed rather than kept beside
+  them. From 4.1 on, a breaking change confined to them ships as `feat`/`fix`
+  without `!` or a `BREAKING CHANGE:` footer, so it never forces a major
+  release; anything it changes outside those packages (the top level, the
+  `vault info` document, the CLI and MCP) is still breaking by the usual rules.
+  4.0 itself keeps its MIGRATION_4.md entries for them, for 3.x users.
 - This repository is public, and commit messages also ship in `CHANGELOG.md`
   inside the wheel. No issue-tracker keys (`IL-` plus a number), internal hosts,
   dashboard links or private repository names in commits, branch names, PR
@@ -207,7 +216,8 @@ the lifecycle matrix follows that.
   path. Adding or removing a
   name updates the snapshots in `tests/test_public_api.py` (every `__all__`, and
   the names each public module keeps by path); moving a name out of a public
-  module leaves a re-export there. A removal or rename is a breaking change.
+  module leaves a re-export there. A removal or rename is a breaking change,
+  except inside a preview package (see Conventions).
   A project type used in a public signature or field is exported too
   (`tests/test_public_type_reachability.py`). The package is `py.typed`, so public APIs stay fully
   annotated.

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/MIGRATION_4.md

@@ -438,8 +438,12 @@ exist; the comparison is equality either way.
 - `ExternalStateVaultState.last_checked_custodian_timestamp` is
   `last_checked_custodian_marker` and `BalanceFuseSnapshot.last_custodian_update_timestamp`
   is `custodian_marker`, both a `CustodianMarker` (an opaque value the
-  contracts only compare for equality): a timestamp on an earlier executor, the
-  confirm count on a released one. `ExternalStateExecutor.confirm_count()`
+  contracts only compare for equality): a unix timestamp on an earlier
+  executor, a confirmation count on a released one.
+  `ExternalStateVaultState.custodian_marker_kind` (`CustodianMarkerKind`, read
+  from the executor at the snapshot block; `None` without an executor) and
+  `ExternalStateExecutor.read_custodian_marker_kind(ctx)` say which; never
+  compare a count with a clock. `ExternalStateExecutor.confirm_count()`
   exists only on the released executor (it reverts on an earlier one), and
   `last_custodian_update_timestamp()` reads the timestamp on both.
 - New on the released build: `ExternalStateExecutor.unforwarded_credit(asset)`,

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev291
+Version: 4.0.0.dev295
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -418,7 +418,8 @@ release; adding one does not.
 - **Preview features** (`PREVIEW_FEATURES` in `ipor_fusion.about`) export only
   from their own subpackages, `ipor_fusion.crosschain` (with `crosschain.fuses`,
   `crosschain.ccip` and `crosschain.stargate`) and `ipor_fusion.hypercore`, never
-  from the top level, and may change in a minor release. Their exception classes
+  from the top level, and keep no backward compatibility: a minor release may
+  change or remove them (see [Preview features](#preview-features-ipor_fusioncrosschain-ipor_fusionhypercore)). Their exception classes
   stay in `ipor_fusion.errors`, and the `vault info` document's HyperCore blocks
   (`HyperCoreJson`, ...) stay with the document.
 - **Third-party types** are not re-exported: import `ChecksumAddress` and
@@ -488,7 +489,10 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 ### Preview features (`ipor_fusion.crosschain`, `ipor_fusion.hypercore`)
 
 Not production (see the note at the top) and outside the stable top level:
-import these from their subpackage, and expect changes in a minor release.
+import these from their subpackage. They track the current official contracts
+only, with no backward compatibility: from 4.1 on, a minor release may change or
+remove any of these names and drops support for retired deployments (such as
+the pilot executors and factories). Pin an exact version if you depend on them.
 
 | Name | Purpose |
 |------|---------|

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/README.md

@@ -369,7 +369,8 @@ release; adding one does not.
 - **Preview features** (`PREVIEW_FEATURES` in `ipor_fusion.about`) export only
   from their own subpackages, `ipor_fusion.crosschain` (with `crosschain.fuses`,
   `crosschain.ccip` and `crosschain.stargate`) and `ipor_fusion.hypercore`, never
-  from the top level, and may change in a minor release. Their exception classes
+  from the top level, and keep no backward compatibility: a minor release may
+  change or remove them (see [Preview features](#preview-features-ipor_fusioncrosschain-ipor_fusionhypercore)). Their exception classes
   stay in `ipor_fusion.errors`, and the `vault info` document's HyperCore blocks
   (`HyperCoreJson`, ...) stay with the document.
 - **Third-party types** are not re-exported: import `ChecksumAddress` and
@@ -439,7 +440,10 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 ### Preview features (`ipor_fusion.crosschain`, `ipor_fusion.hypercore`)
 
 Not production (see the note at the top) and outside the stable top level:
-import these from their subpackage, and expect changes in a minor release.
+import these from their subpackage. They track the current official contracts
+only, with no backward compatibility: from 4.1 on, a minor release may change or
+remove any of these names and drops support for retired deployments (such as
+the pilot executors and factories). Pin an exact version if you depend on them.
 
 | Name | Purpose |
 |------|---------|

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/pyproject.toml

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

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/src/ipor_fusion/__init__.py

@@ -42,6 +42,7 @@ from ipor_fusion.core.erc20 import ERC20
 from ipor_fusion.core.external_state_executor import (
     BalanceFuseSnapshot,
     BalanceProposal,
+    CustodianMarkerKind,
     ExternalStateExecutor,
     ExternalStateVaultState,
     read_external_state,
@@ -545,6 +546,7 @@ __all__ = [
     "CloneArgs",
     "ExternalStateExecutor",
     "BalanceFuseSnapshot",
+    "CustodianMarkerKind",
     "ExternalStateVaultState",
     "read_external_state",
     "erc20_balance_slot",

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/src/ipor_fusion/about.py

@@ -41,7 +41,8 @@ PREVIEW_FEATURES: tuple[PreviewFeature, ...] = (
 PREVIEW_STATEMENT = (
     "Preview, not production: the contracts are under active development, the "
     "mainnet deployments are a proof of concept and IPOR Labs canaries, and "
-    "interfaces may change between minor versions."
+    "interfaces may change or be removed between minor versions, with no "
+    "backward compatibility."
 )
 
 _DISTRIBUTION = "ipor-fusion"

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/src/ipor_fusion/core/__init__.py

@@ -18,6 +18,7 @@ from ipor_fusion.core.erc20 import ERC20
 from ipor_fusion.core.external_state_executor import (
     BalanceFuseSnapshot,
     BalanceProposal,
+    CustodianMarkerKind,
     ExternalStateExecutor,
     ExternalStateVaultState,
     read_external_state,
@@ -122,6 +123,7 @@ __all__ = [
     "BalanceFuseSnapshot",
     "BalanceProposal",
     "ExternalStateExecutor",
+    "CustodianMarkerKind",
     "ExternalStateVaultState",
     "read_external_state",
     "Fuse",

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/src/ipor_fusion/core/external_state_executor.py

@@ -18,13 +18,15 @@ from __future__ import annotations
 
 from collections.abc import Iterable
 from dataclasses import dataclass, replace
+from enum import Enum
 
 from eth_abi import decode, encode
 from eth_abi.exceptions import DecodingError
 from eth_typing import ChecksumAddress
-from eth_utils import keccak
+from eth_utils import function_signature_to_4byte_selector, keccak
 from hexbytes import HexBytes
 from web3 import Web3
+from web3.exceptions import ContractLogicError
 from web3.types import BlockIdentifier, Timestamp
 
 from ipor_fusion.core.context import Web3Context
@@ -118,6 +120,35 @@ def _require_matching_hash(
         )
 
 
+class CustodianMarkerKind(Enum):
+    """What an executor's custodian marker counts: the last confirmed update's
+    unix timestamp (executors before the 2026-10-21 contracts release) or the
+    number of confirmed updates (executors of that release)."""
+
+    TIMESTAMP = "timestamp"
+    CONFIRM_COUNT = "confirm_count"
+
+
+_CONFIRM_COUNT_SELECTOR = function_signature_to_4byte_selector("confirmCount()")
+
+
+def _read_marker_kind(
+    ctx: Web3Context, executor: ChecksumAddress, block: BlockIdentifier
+) -> CustodianMarkerKind:
+    """Decided from the executor, not guessed from a value: a released
+    executor answers ``confirmCount()``, an earlier one has no such function
+    and the call reverts. Any other failure raises."""
+    try:
+        raw = ctx.call(executor, _CONFIRM_COUNT_SELECTOR, block)
+    except ContractLogicError:
+        return CustodianMarkerKind.TIMESTAMP
+    if len(raw) != 32:
+        raise ExternalStateError(
+            f"confirmCount() of {executor} returned {len(raw)} bytes, not a uint256"
+        )
+    return CustodianMarkerKind.CONFIRM_COUNT
+
+
 @dataclass(frozen=True, slots=True)
 class ExternalStateVaultState:
     """The external-state market's vault-scoped state, read from the vault's
@@ -136,7 +167,9 @@ class ExternalStateVaultState:
     and not the pre-hook's staleness clock, which is
     `ExternalStateExecutor.get_oldest_update_timestamp`. The fuse and the
     pre-hook only compare it for equality with
-    `BalanceFuseSnapshot.custodian_marker`; `paused` is the flag
+    `BalanceFuseSnapshot.custodian_marker`. `custodian_marker_kind` says
+    which, read from the executor at the same block (``None`` without an
+    executor); `paused` is the flag
     the balance fuse sets on a big change and `ExternalStateUnpauseFuse` clears
     with an atomist signature. `ExternalStatePausePreHook` blocks the vault's
     gated user operations while the flag is set, and also, flag or not, while
@@ -148,6 +181,7 @@ class ExternalStateVaultState:
     executor: ChecksumAddress | None
     last_total_balance: Amount
     last_checked_custodian_marker: CustodianMarker
+    custodian_marker_kind: CustodianMarkerKind | None
     paused: bool
     block: int
 
@@ -232,10 +266,14 @@ def read_external_state(
         raise ExternalStateError(
             f"malformed pause flag in the external-state storage of {checksum}"
         )
+    executor = Web3.to_checksum_address(f"0x{words[0]:040x}") if words[0] else None
     return ExternalStateVaultState(
-        executor=Web3.to_checksum_address(f"0x{words[0]:040x}") if words[0] else None,
+        executor=executor,
         last_total_balance=Amount(words[1]),
         last_checked_custodian_marker=CustodianMarker(words[2]),
+        custodian_marker_kind=(
+            _read_marker_kind(ctx, executor, read_at) if executor else None
+        ),
         paused=words[3] == 1,
         block=block,
     )
@@ -365,6 +403,11 @@ class ExternalStateExecutor(ContractWrapper):
             )
         )
 
+    def read_custodian_marker_kind(self, ctx: Web3Context) -> CustodianMarkerKind:
+        """Whether this executor's custodian marker is a timestamp or a
+        confirm count, at ``ctx``'s default block (see `CustodianMarkerKind`)."""
+        return _read_marker_kind(ctx, self._require_address(), ctx.default_block)
+
     def confirm_count(self) -> Call[CustodianMarker]:
         """Executors of the 2026-10-21 contracts release only: the count of
         confirmed custodian updates across every balance account, the marker

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/src/ipor_fusion/mcp/models.py

@@ -1176,8 +1176,9 @@ class PreviewFeatureModel(_Base):
         default="preview",
         description="Always 'preview': not production. The contracts are under "
         "active development, the mainnet deployments are a proof of concept "
-        "and IPOR Labs canaries, and interfaces may change between minor "
-        "versions. Route no production capital through these features.",
+        "and IPOR Labs canaries, and interfaces may change or be removed "
+        "between minor versions, with no backward compatibility. Route no "
+        "production capital through these features.",
     )
 
 

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/tests/test_external_state_executor.py

@@ -13,6 +13,7 @@ from eth_typing import ChecksumAddress
 from eth_utils import keccak
 from hexbytes import HexBytes
 from web3 import Web3
+from web3.exceptions import ContractLogicError
 from web3.types import Timestamp
 
 from ipor_fusion.core.external_state_executor import (
@@ -1182,8 +1183,12 @@ class TestReadExternalState:
     BLOCKS = {"safe": 4_804_990, "finalized": 4_804_900, "earliest": 0}
     HASH = "0x" + "ab" * 32
 
-    def _ctx(self, words, default_block="latest", head=4_805_000):
+    def _ctx(self, words, default_block="latest", head=4_805_000, confirm_count=None):
         ctx = MagicMock()
+        if confirm_count is None:
+            ctx.call.side_effect = ContractLogicError("execution reverted")
+        else:
+            ctx.call.return_value = HexBytes(confirm_count.to_bytes(32, "big"))
         ctx.default_block = default_block
         blocks = dict(self.BLOCKS, latest=head)
         blocks[self.HASH] = 4_700_123
@@ -1194,6 +1199,30 @@ class TestReadExternalState:
         ctx.get_storage_at.side_effect = lambda vault, slot, block=None: by_slot[slot]
         return ctx
 
+    def test_the_marker_kind_is_read_from_the_executor_at_the_same_block(self):
+        from ipor_fusion import CustodianMarkerKind, read_external_state
+
+        earlier = read_external_state(
+            self._ctx([int(EXECUTOR_ADDR, 16), 1, 1_791_458_983, 0]), VAULT_ADDR
+        )
+        assert earlier.custodian_marker_kind is CustodianMarkerKind.TIMESTAMP
+        ctx = self._ctx([int(EXECUTOR_ADDR, 16), 1, 7, 0], confirm_count=7)
+        released = read_external_state(ctx, VAULT_ADDR)
+        assert released.custodian_marker_kind is CustodianMarkerKind.CONFIRM_COUNT
+        to, data, block = ctx.call.call_args.args
+        assert data == Web3.keccak(text="confirmCount()")[:4]
+        assert block == 4_805_000
+        none = read_external_state(self._ctx([0, 0, 0, 0]), VAULT_ADDR)
+        assert none.custodian_marker_kind is None
+
+    def test_a_failed_kind_read_raises(self):
+        from ipor_fusion import read_external_state
+
+        ctx = self._ctx([int(EXECUTOR_ADDR, 16), 1, 7, 0])
+        ctx.call.side_effect = ConnectionError("rpc down")
+        with pytest.raises(ConnectionError):
+            read_external_state(ctx, VAULT_ADDR)
+
     def test_reads_the_four_slots_at_one_resolved_block(self):
         from ipor_fusion import read_external_state
 

{ipor_fusion-4.0.0.dev291 → ipor_fusion-4.0.0.dev295}/tests/test_public_api.py

@@ -153,6 +153,7 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "ExternalStateTotalBalanceUpdatedArgs",
             "ExternalStateUnpausedArgs",
             "ExternalStateUnpausedEvent",
+            "CustodianMarkerKind",
             "ExternalStateVaultState",
             "Fee",
             "FeeAccount",
@@ -531,6 +532,7 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "CloneArgs",
             "ERC20",
             "ExternalStateExecutor",
+            "CustodianMarkerKind",
             "ExternalStateVaultState",
             "FeeAccount",
             "FeeManager",