ipor-fusion 4.0.0.dev286__tar.gz → 4.0.0.dev293__tar.gz

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/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.dev286 → ipor_fusion-4.0.0.dev293}/MIGRATION_4.md

@@ -427,6 +427,28 @@ the modules are internal.
   `MAX_MARK_ORACLE_DEVIATION_BPS`, `NAV_JUMP_FLOOR_USD6` (7..11); `decode_substrate`
   decodes them instead of flagging them as errors.
 
+#### ExternalState: two executor builds, one custodian marker
+
+The 2026-10-21 contracts release (on Arbitrum in `ipor-abi`) changes what the
+balance fuse and the pre-hook compare to detect an unprocessed custodian
+update: the executor's confirm count instead of the last confirmed update's
+timestamp. HyperEVM, Base and Ethereum still publish the earlier build, so both
+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()`
+  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)`,
+  `proposal_base_balance(account)`, `ExternalStateOperationFuse.sweep_surplus(asset)`,
+  and the events `ExternalStateBalanceFuseLastCustodianConfirmCountUpdated` and
+  `ExternalStateOperationFuseSweepSurplus` (the released balance fuse no longer
+  emits `...LastCustodianTimestampUpdated`; it stays registered for the earlier
+  build).
+
 **Removed.**
 
 - `IporFusionMarkets.RWA`: market 50 is `IporFusionMarkets.EXTERNAL_STATE`.

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev286
+Version: 4.0.0.dev293
 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
@@ -463,7 +464,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | `PriceOracleMiddleware` | Asset price feeds |
 | `PriceOracleMiddlewareManager` | Per-vault price-source overrides |
 | `ExternalStateExecutor` | NAV propose/confirm for off-vault capital (market 50); the executor's thresholds (`staleness_max`, `big_change_bps`, `dust_threshold`, `min_update_interval`), the live aggregate (`get_balance_fuse_snapshot`) and the pre-hook's staleness clock (`get_oldest_update_timestamp`) |
-| `read_external_state`, `ExternalStateVaultState` | The market's vault-scoped state from the vault's ERC-7201 storage at one block: executor, the balance fuse's cached total, the custodian timestamp it last checked and the pause flag the pre-hook enforces (no getter exposes them) |
+| `read_external_state`, `ExternalStateVaultState` | The market's vault-scoped state from the vault's ERC-7201 storage at one block: executor, the balance fuse's cached total, the custodian marker it last checked (a timestamp on the earlier executor build, the confirm count on the 2026-10-21 one) and the pause flag the pre-hook enforces (no getter exposes them) |
 | `decode_external_state_event`, `EXTERNAL_STATE_TOPICS` | The ExternalState events the vault emits (big change, cache updates, unpause, rescue, executor creation and deployment, operation enter/exit), decoded by topic with their raw log identity; a malformed listed log raises |
 | `erc20_balance_slot`, `VaultSimulator.with_erc20_balance` | Fund any address with any ERC-20 in a simulation by a storage override (slot found by probing), no holder to impersonate |
 | `ERC20` | Token reads and approvals |
@@ -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.dev286 → ipor_fusion-4.0.0.dev293}/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
@@ -414,7 +415,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | `PriceOracleMiddleware` | Asset price feeds |
 | `PriceOracleMiddlewareManager` | Per-vault price-source overrides |
 | `ExternalStateExecutor` | NAV propose/confirm for off-vault capital (market 50); the executor's thresholds (`staleness_max`, `big_change_bps`, `dust_threshold`, `min_update_interval`), the live aggregate (`get_balance_fuse_snapshot`) and the pre-hook's staleness clock (`get_oldest_update_timestamp`) |
-| `read_external_state`, `ExternalStateVaultState` | The market's vault-scoped state from the vault's ERC-7201 storage at one block: executor, the balance fuse's cached total, the custodian timestamp it last checked and the pause flag the pre-hook enforces (no getter exposes them) |
+| `read_external_state`, `ExternalStateVaultState` | The market's vault-scoped state from the vault's ERC-7201 storage at one block: executor, the balance fuse's cached total, the custodian marker it last checked (a timestamp on the earlier executor build, the confirm count on the 2026-10-21 one) and the pause flag the pre-hook enforces (no getter exposes them) |
 | `decode_external_state_event`, `EXTERNAL_STATE_TOPICS` | The ExternalState events the vault emits (big change, cache updates, unpause, rescue, executor creation and deployment, operation enter/exit), decoded by topic with their raw log identity; a malformed listed log raises |
 | `erc20_balance_slot`, `VaultSimulator.with_erc20_balance` | Fund any address with any ERC-20 in a simulation by a storage override (slot found by probing), no holder to impersonate |
 | `ERC20` | Token reads and approvals |
@@ -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.dev286 → ipor_fusion-4.0.0.dev293}/pyproject.toml

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

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/src/ipor_fusion/__init__.py

@@ -196,10 +196,12 @@ from ipor_fusion.fuses.external_state_event_decoding import (
     EXTERNAL_STATE_TOPICS,
     ExternalStateAssetRescuedArgs,
     ExternalStateAssetRescuedEvent,
+    ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent,
     ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent,
     ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent,
     ExternalStateBigChangeDetectedArgs,
     ExternalStateBigChangeDetectedEvent,
+    ExternalStateCustodianConfirmCountUpdatedArgs,
     ExternalStateCustodianTimestampUpdatedArgs,
     ExternalStateEvent,
     ExternalStateEventArgs,
@@ -210,6 +212,8 @@ from ipor_fusion.fuses.external_state_event_decoding import (
     ExternalStateOperationArgs,
     ExternalStateOperationFuseEnterEvent,
     ExternalStateOperationFuseExitEvent,
+    ExternalStateOperationFuseSweepSurplusArgs,
+    ExternalStateOperationFuseSweepSurplusEvent,
     ExternalStateTotalBalanceUpdatedArgs,
     ExternalStateUnpausedArgs,
     ExternalStateUnpausedEvent,
@@ -333,6 +337,7 @@ from ipor_fusion.types import (
     AssetSource,
     ChainId,
     Check,
+    CustodianMarker,
     Decimals,
     Fee,
     FuseAddress,
@@ -437,6 +442,8 @@ __all__ = [
     "EXTERNAL_STATE_EVENT_CLASSES",
     "ExternalStateBigChangeDetectedEvent",
     "ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent",
+    "ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent",
+    "ExternalStateOperationFuseSweepSurplusEvent",
     "ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent",
     "ExternalStateUnpausedEvent",
     "ExternalStateAssetRescuedEvent",
@@ -447,6 +454,8 @@ __all__ = [
     "ExternalStateAssetRescuedArgs",
     "ExternalStateBigChangeDetectedArgs",
     "ExternalStateCustodianTimestampUpdatedArgs",
+    "ExternalStateCustodianConfirmCountUpdatedArgs",
+    "ExternalStateOperationFuseSweepSurplusArgs",
     "ExternalStateEventArgs",
     "ExternalStateExecutorArgs",
     "ExternalStateOperationArgs",
@@ -664,6 +673,7 @@ __all__ = [
     "format_amount",
     "format_shares",
     "Price",
+    "CustodianMarker",
     "Period",
     "MAX_UINT256",
     "ZERO_ADDRESS",

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/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.dev286 → ipor_fusion-4.0.0.dev293}/src/ipor_fusion/core/external_state_executor.py

@@ -35,6 +35,7 @@ from ipor_fusion.types import (
     ZERO_ADDRESS,
     Amount,
     ChainId,
+    CustodianMarker,
     Period,
     PlasmaVaultAddress,
     ProposalHash,
@@ -127,10 +128,15 @@ class ExternalStateVaultState:
     `last_total_balance` is the balance fuse's cache of the executor's total in
     raw underlying units, as of the fuse's last refresh -- not the live total,
     which `ExternalStateExecutor.get_balance_fuse_snapshot` reads;
-    `last_checked_custodian_timestamp` is the executor custodian timestamp the
-    balance fuse last processed -- not necessarily the latest custodian update
+    `last_checked_custodian_marker` is the executor's custodian marker the
+    balance fuse last processed -- the last confirmed custodian update's block
+    timestamp on executors of the contracts before the 2026-10-21 release, the
+    executor's confirm count (`ExternalStateExecutor.confirm_count`) on the
+    executors of that release; either way not necessarily the latest update
     and not the pre-hook's staleness clock, which is
-    `ExternalStateExecutor.get_oldest_update_timestamp`; `paused` is the flag
+    `ExternalStateExecutor.get_oldest_update_timestamp`. The fuse and the
+    pre-hook only compare it for equality with
+    `BalanceFuseSnapshot.custodian_marker`; `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
@@ -141,7 +147,7 @@ class ExternalStateVaultState:
 
     executor: ChecksumAddress | None
     last_total_balance: Amount
-    last_checked_custodian_timestamp: Timestamp
+    last_checked_custodian_marker: CustodianMarker
     paused: bool
     block: int
 
@@ -150,11 +156,14 @@ class ExternalStateVaultState:
 class BalanceFuseSnapshot:
     """`ExternalStateExecutor.getBalanceFuseSnapshot()`: the live sum of the
     tracked balances in raw underlying units, the cached big-change threshold
-    in basis points and the timestamp of the last confirmed custodian update."""
+    in basis points and the custodian marker: the last confirmed custodian
+    update's timestamp on executors before the 2026-10-21 contracts release,
+    the confirm count on the executors of that release (two confirms in one
+    block then still differ)."""
 
     total_balance: Amount
     big_change_bps: int
-    last_custodian_update_timestamp: Timestamp
+    custodian_marker: CustodianMarker
 
 
 def _storage_word(raw: bytes) -> int:
@@ -226,7 +235,7 @@ def read_external_state(
     return ExternalStateVaultState(
         executor=Web3.to_checksum_address(f"0x{words[0]:040x}") if words[0] else None,
         last_total_balance=Amount(words[1]),
-        last_checked_custodian_timestamp=Timestamp(words[2]),
+        last_checked_custodian_marker=CustodianMarker(words[2]),
         paused=words[3] == 1,
         block=block,
     )
@@ -344,18 +353,63 @@ class ExternalStateExecutor(ContractWrapper):
 
     def get_balance_fuse_snapshot(self) -> Call[BalanceFuseSnapshot]:
         """The live aggregate the balance fuse reads: the sum of the tracked
-        balances, the big-change threshold and the last confirmed custodian
-        update timestamp, in one call. Pin the context's block to the one
+        balances, the big-change threshold and the custodian marker, in one
+        call. Pin the context's block to the one
         `read_external_state` returned to compare live against cached."""
         return self._view(
             "getBalanceFuseSnapshot()",
             output_types=["uint256", "uint256", "uint256"],
         ).map(
             lambda values: BalanceFuseSnapshot(
-                Amount(values[0]), int(values[1]), Timestamp(values[2])
+                Amount(values[0]), int(values[1]), CustodianMarker(values[2])
             )
         )
 
+    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
+        `get_balance_fuse_snapshot` reports. An earlier executor has no such
+        function and the call reverts."""
+        return self._view(
+            "confirmCount()", output_types=["uint256"], decoder=CustodianMarker
+        )
+
+    def last_custodian_update_timestamp(self) -> Call[Timestamp]:
+        """Block timestamp of the last confirmed custodian update on any
+        balance account."""
+        return self._view(
+            "lastCustodianUpdateTimestamp()",
+            output_types=["uint256"],
+            decoder=Timestamp,
+        )
+
+    def unforwarded_credit(self, asset: ChecksumAddress) -> Call[Amount]:
+        """Executors of the 2026-10-21 contracts release only: tokens of
+        `asset` credited through the vault path that have not left the
+        executor. The executor's `asset` balance above it is surplus (a
+        donation or a payout sent straight to the executor):
+        `ExternalStateOperationFuse.sweep_surplus` moves it to the vault, and
+        custodians should not propose while it exists unless they know whether
+        their report counts it."""
+        return self._view(
+            "unforwardedCredit(address)",
+            asset,
+            output_types=["uint256"],
+            decoder=Amount,
+        )
+
+    def proposal_base_balance(self, balance_account: ChecksumAddress) -> Call[Amount]:
+        """Executors of the 2026-10-21 contracts release only: the account
+        balance when the pending proposal was made. `confirmBalance` reverts
+        `ExternalStateExecutorBalanceChangedSinceProposal` once the balance
+        differs from it (an alpha flow ran in between): propose again."""
+        return self._view(
+            "proposalBaseBalance(address)",
+            balance_account,
+            output_types=["uint256"],
+            decoder=Amount,
+        )
+
     def get_oldest_update_timestamp(self) -> Call[Timestamp]:
         """The pre-hook's staleness clock: the oldest non-zero `lastUpdated`
         across the balance accounts, 0 when no account was ever updated. The

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/src/ipor_fusion/fuses/__init__.py

@@ -30,10 +30,12 @@ from ipor_fusion.fuses.external_state_event_decoding import (
     EXTERNAL_STATE_TOPICS,
     ExternalStateAssetRescuedArgs,
     ExternalStateAssetRescuedEvent,
+    ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent,
     ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent,
     ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent,
     ExternalStateBigChangeDetectedArgs,
     ExternalStateBigChangeDetectedEvent,
+    ExternalStateCustodianConfirmCountUpdatedArgs,
     ExternalStateCustodianTimestampUpdatedArgs,
     ExternalStateEvent,
     ExternalStateEventArgs,
@@ -44,6 +46,8 @@ from ipor_fusion.fuses.external_state_event_decoding import (
     ExternalStateOperationArgs,
     ExternalStateOperationFuseEnterEvent,
     ExternalStateOperationFuseExitEvent,
+    ExternalStateOperationFuseSweepSurplusArgs,
+    ExternalStateOperationFuseSweepSurplusEvent,
     ExternalStateTotalBalanceUpdatedArgs,
     ExternalStateUnpausedArgs,
     ExternalStateUnpausedEvent,
@@ -146,10 +150,14 @@ __all__ = [
     "ExternalStateAssetRescuedArgs",
     "ExternalStateAssetRescuedEvent",
     "ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent",
+    "ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent",
+    "ExternalStateOperationFuseSweepSurplusEvent",
     "ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent",
     "ExternalStateBigChangeDetectedArgs",
     "ExternalStateBigChangeDetectedEvent",
     "ExternalStateCustodianTimestampUpdatedArgs",
+    "ExternalStateCustodianConfirmCountUpdatedArgs",
+    "ExternalStateOperationFuseSweepSurplusArgs",
     "ExternalStateEvent",
     "ExternalStateEventArgs",
     "ExternalStateEventSpec",

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/src/ipor_fusion/fuses/external_state.py

@@ -92,6 +92,17 @@ class ExternalStateOperationFuse(Fuse):
         """
         return self._action_raw("createExecutor()", [])
 
+    def sweep_surplus(self, asset: ChecksumAddress) -> FuseAction:
+        """Operation fuses of the 2026-10-21 contracts release only: move to
+        the vault the executor's ``asset`` balance above its unforwarded
+        credit (tokens that did not arrive through the vault path, such as a
+        donation), emitting ``ExternalStateOperationFuseSweepSurplus``. The
+        swept tokens enter NAV at once only when ``asset`` is the underlying.
+        Use it for tokens the confirmed custodian report no longer counts; a
+        payout it still counts is booked with ``exit`` instead."""
+        self._validate_address(asset, "asset")
+        return self._action_raw("sweepSurplus(address)", [asset])
+
     def _build(
         self,
         method: str,

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/src/ipor_fusion/fuses/external_state_event_decoding.py

@@ -65,6 +65,10 @@ EXTERNAL_STATE_EVENT_SPECS: tuple[ExternalStateEventSpec, ...] = (
         "ExternalStateBalanceFuseLastCustodianTimestampUpdated",
         (("uint256", "oldTimestamp"), ("uint256", "newTimestamp")),
     ),
+    ExternalStateEventSpec(
+        "ExternalStateBalanceFuseLastCustodianConfirmCountUpdated",
+        (("uint256", "oldConfirmCount"), ("uint256", "newConfirmCount")),
+    ),
     ExternalStateEventSpec(
         "ExternalStateBalanceFuseLastTotalBalanceUpdated",
         (("uint256", "oldTotalBalance"), ("uint256", "newTotalBalance")),
@@ -106,6 +110,10 @@ EXTERNAL_STATE_EVENT_SPECS: tuple[ExternalStateEventSpec, ...] = (
             ("uint256", "actionsCount"),
         ),
     ),
+    ExternalStateEventSpec(
+        "ExternalStateOperationFuseSweepSurplus",
+        (("address", "version"), ("address", "asset"), ("uint256", "amount")),
+    ),
     # ExternalStateExecutorStorageLib
     ExternalStateEventSpec(
         "ExternalStateExecutorDeployed",
@@ -127,6 +135,24 @@ class ExternalStateCustodianTimestampUpdatedArgs(TypedDict):
     newTimestamp: Timestamp
 
 
+class ExternalStateCustodianConfirmCountUpdatedArgs(TypedDict):
+    """``ExternalStateBalanceFuseLastCustodianConfirmCountUpdated`` (balance
+    fuses of the 2026-10-21 contracts release; earlier ones emit the
+    timestamp event)."""
+
+    oldConfirmCount: int
+    newConfirmCount: int
+
+
+class ExternalStateOperationFuseSweepSurplusArgs(TypedDict):
+    """``ExternalStateOperationFuseSweepSurplus``: ``amount`` of ``asset``
+    swept from the executor to the vault."""
+
+    version: FuseAddress
+    asset: ChecksumAddress
+    amount: Amount
+
+
 class ExternalStateTotalBalanceUpdatedArgs(TypedDict):
     """``ExternalStateBalanceFuseLastTotalBalanceUpdated``."""
 
@@ -213,6 +239,24 @@ class ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent(
     args: ExternalStateCustodianTimestampUpdatedArgs
 
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent(
+    _ExternalStateEventBase
+):
+    name: Literal["ExternalStateBalanceFuseLastCustodianConfirmCountUpdated"] = (
+        "ExternalStateBalanceFuseLastCustodianConfirmCountUpdated"
+    )
+    args: ExternalStateCustodianConfirmCountUpdatedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateOperationFuseSweepSurplusEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateOperationFuseSweepSurplus"] = (
+        "ExternalStateOperationFuseSweepSurplus"
+    )
+    args: ExternalStateOperationFuseSweepSurplusArgs
+
+
 @dataclass(frozen=True, slots=True, kw_only=True)
 class ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent(_ExternalStateEventBase):
     name: Literal["ExternalStateBalanceFuseLastTotalBalanceUpdated"] = (
@@ -262,6 +306,8 @@ class ExternalStateExecutorDeployedEvent(_ExternalStateEventBase):
 ExternalStateEvent: TypeAlias = (
     ExternalStateBigChangeDetectedEvent
     | ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent
+    | ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent
+    | ExternalStateOperationFuseSweepSurplusEvent
     | ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent
     | ExternalStateUnpausedEvent
     | ExternalStateAssetRescuedEvent
@@ -275,6 +321,8 @@ ExternalStateEvent: TypeAlias = (
 EXTERNAL_STATE_EVENT_CLASSES: dict[str, type[ExternalStateEvent]] = {
     "ExternalStateBigChangeDetected": ExternalStateBigChangeDetectedEvent,
     "ExternalStateBalanceFuseLastCustodianTimestampUpdated": ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent,
+    "ExternalStateBalanceFuseLastCustodianConfirmCountUpdated": ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent,
+    "ExternalStateOperationFuseSweepSurplus": ExternalStateOperationFuseSweepSurplusEvent,
     "ExternalStateBalanceFuseLastTotalBalanceUpdated": ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent,
     "ExternalStateUnpaused": ExternalStateUnpausedEvent,
     "ExternalStateAssetRescued": ExternalStateAssetRescuedEvent,

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/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.dev286 → ipor_fusion-4.0.0.dev293}/src/ipor_fusion/types.py

@@ -17,6 +17,11 @@ RoleId = NewType("RoleId", int)
 ChainId = NewType("ChainId", int)
 # An 18-decimal fixed-point fraction: 10**18 is 1, i.e. 100% (a market limit).
 Wad = NewType("Wad", int)
+# The ExternalState executor's custodian marker the balance fuse and pre-hook
+# compare for equality only: the last confirmed update's block timestamp on an
+# executor before the 2026-10-21 contracts release, the confirm count on one of
+# that release. Opaque: never compare it with a clock or do arithmetic on it.
+CustodianMarker = NewType("CustodianMarker", int)
 # A Morpho Blue market id (bytes32) in its canonical spelling: "0x" and 64
 # lowercase hex digits, as the Morpho API reports it. Build one with
 # parse_morpho_market_id.

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/tests/test_external_state_events.py

@@ -7,7 +7,7 @@ import re
 import pytest
 from _event_args import assert_event_class_mirrors_spec
 from eth_abi import encode
-from test_solidity_mirrors import _solidity_source
+from test_solidity_mirrors import IPOR_FUSION_REF, _solidity_source
 from web3 import Web3
 
 from ipor_fusion import (
@@ -28,6 +28,17 @@ _SOURCES = (
     "contracts/fuses/external_state/ExternalStateOperationFuse.sol",
     "contracts/fuses/external_state/lib/ExternalStateExecutorStorageLib.sol",
 )
+# Both published builds: the release pinned in test_solidity_mirrors (Arbitrum)
+# and the earlier one HyperEVM, Base and Ethereum still publish. The released
+# balance fuse declares its events in a library of its own.
+_EARLIER_REF = "a1f79d6c3d0d426ace4df55ed0fb8ea340580739"
+_BUILDS = (
+    (
+        IPOR_FUSION_REF,
+        (*_SOURCES, "contracts/fuses/external_state/lib/ExternalStateBigChangeLib.sol"),
+    ),
+    (_EARLIER_REF, _SOURCES),
+)
 _EVENT_RE = re.compile(r"\bevent\s+(\w+)\s*\(([^)]*)\)\s*;", re.S)
 
 VAULT = "0xdBEe6621Febce4C51Fa9DD1dB12dCd9d4CC3e7b9"
@@ -35,9 +46,18 @@ SIGNER = "0x00000000000000000000000000000000000000a5"
 
 
 def _declared():
+    """Every event either build declares; a name both declare must agree."""
+    out = {}
+    for ref, paths in _BUILDS:
+        for name, params in _declared_at(ref, paths).items():
+            assert out.setdefault(name, params) == params, name
+    return out
+
+
+def _declared_at(ref, paths):
     out = {}
-    for path in _SOURCES:
-        for name, body in _EVENT_RE.findall(_solidity_source(path)):
+    for path in paths:
+        for name, body in _EVENT_RE.findall(_solidity_source(path, ref)):
             params = []
             for raw in [p.strip() for p in body.split(",") if p.strip()]:
                 words = raw.split()

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/tests/test_external_state_executor.py

@@ -1203,7 +1203,7 @@ class TestReadExternalState:
 
         assert state.executor == EXECUTOR_ADDR
         assert state.last_total_balance == 32_928_135
-        assert state.last_checked_custodian_timestamp == 1_791_458_983
+        assert state.last_checked_custodian_marker == 1_791_458_983
         assert state.paused is True
         assert state.block == 4_805_000  # "latest" resolved once, before the reads
         assert [c.args for c in ctx.get_storage_at.call_args_list] == [
@@ -1256,7 +1256,7 @@ class TestReadExternalState:
             self._ctx([0, (1 << 256) - 1, (1 << 256) - 1, 0]), VAULT_ADDR
         )
         assert top.last_total_balance == (1 << 256) - 1
-        assert top.last_checked_custodian_timestamp == (1 << 256) - 1
+        assert top.last_checked_custodian_marker == (1 << 256) - 1
 
     def test_a_pinned_context_block_is_used_as_is(self):
         from ipor_fusion import read_external_state
@@ -1267,7 +1267,7 @@ class TestReadExternalState:
 
         assert state.block == 4_700_000
         assert state.executor is None and state.paused is False
-        assert (state.last_total_balance, state.last_checked_custodian_timestamp) == (
+        assert (state.last_total_balance, state.last_checked_custodian_marker) == (
             0,
             0,
         )
@@ -1292,7 +1292,7 @@ class TestReadExternalState:
             5,
             True,
         )
-        assert state.last_checked_custodian_timestamp == 0
+        assert state.last_checked_custodian_marker == 0
 
     def test_malformed_words_raise_instead_of_passing_as_values(self):
         from ipor_fusion import read_external_state
@@ -1320,6 +1320,8 @@ class TestExecutorViews:
             ("dust_threshold", "dustThreshold()"),
             ("min_update_interval", "minUpdateInterval()"),
             ("get_oldest_update_timestamp", "getOldestUpdateTimestamp()"),
+            ("confirm_count", "confirmCount()"),
+            ("last_custodian_update_timestamp", "lastCustodianUpdateTimestamp()"),
         ],
     )
     def test_uint256_views(self, method, signature):
@@ -1338,3 +1340,18 @@ class TestExecutorViews:
         assert call.decoder is not None
         snap = call.decoder((32_928_135, 50_000, 1_791_458_983))
         assert snap == BalanceFuseSnapshot(32_928_135, 50_000, 1_791_458_983)
+        # a 2026-10-21 executor reports its confirm count in the same slot
+        assert call.decoder((32_928_135, 50_000, 7)).custodian_marker == 7
+
+    @pytest.mark.parametrize(
+        ("method", "signature"),
+        [
+            ("unforwarded_credit", "unforwardedCredit(address)"),
+            ("proposal_base_balance", "proposalBaseBalance(address)"),
+        ],
+    )
+    def test_released_executor_per_address_views(self, method, signature):
+        executor = ExternalStateExecutor(EXECUTOR_ADDR)
+        call = getattr(executor, method)(EXECUTOR_ADDR)
+        assert bytes(call.data)[:4] == Web3.keccak(text=signature)[:4]
+        assert call.output_types == ("uint256",)

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev293}/tests/test_fuse_encoding.py

@@ -1777,6 +1777,13 @@ class TestExternalStateOperationFuse:
                 actions=[(ZERO_ADDRESS, b"\x00")],
             )
 
+    def test_sweep_surplus_encodes_the_asset(self):
+        action = ExternalStateOperationFuse(FUSE_ADDR).sweep_surplus(TOKEN_A)
+        assert action.data[:4] == _selector("sweepSurplus(address)")
+        assert decode(["address"], action.data[4:])[0].lower() == TOKEN_A.lower()
+        with pytest.raises(ValueError, match="asset"):
+            ExternalStateOperationFuse(FUSE_ADDR).sweep_surplus(ZERO_ADDRESS)
+
     def test_create_executor_is_bare_selector(self):
         action = ExternalStateOperationFuse(FUSE_ADDR).create_executor()
         assert action.fuse == FUSE_ADDR