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

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev291}/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.dev291}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev286
+Version: 4.0.0.dev291
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -463,7 +463,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 |

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

@@ -414,7 +414,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 |

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

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev286"
+version = "4.0.0.dev291"
 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.dev291}/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.dev291}/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.dev291}/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.dev291}/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.dev291}/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.dev291}/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.dev291}/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.dev291}/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.dev291}/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

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

@@ -128,10 +128,14 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "ExternalStateAssetRescuedArgs",
             "ExternalStateAssetRescuedEvent",
             "ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent",
+            "ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent",
+            "ExternalStateOperationFuseSweepSurplusEvent",
             "ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent",
             "ExternalStateBigChangeDetectedArgs",
             "ExternalStateBigChangeDetectedEvent",
             "ExternalStateCustodianTimestampUpdatedArgs",
+            "ExternalStateCustodianConfirmCountUpdatedArgs",
+            "ExternalStateOperationFuseSweepSurplusArgs",
             "ExternalStateError",
             "ExternalStateEvent",
             "ExternalStateEventArgs",
@@ -253,6 +257,7 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "PendingRequestJson",
             "PendingRequestsInfo",
             "PerformanceFeeData",
+            "CustodianMarker",
             "Period",
             "PlasmaVault",
             "PlasmaVaultAddress",
@@ -816,10 +821,14 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "ExternalStateAssetRescuedArgs",
             "ExternalStateAssetRescuedEvent",
             "ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent",
+            "ExternalStateBalanceFuseLastCustodianConfirmCountUpdatedEvent",
+            "ExternalStateOperationFuseSweepSurplusEvent",
             "ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent",
             "ExternalStateBigChangeDetectedArgs",
             "ExternalStateBigChangeDetectedEvent",
             "ExternalStateCustodianTimestampUpdatedArgs",
+            "ExternalStateCustodianConfirmCountUpdatedArgs",
+            "ExternalStateOperationFuseSweepSurplusArgs",
             "ExternalStateEvent",
             "ExternalStateEventArgs",
             "ExternalStateEventSpec",
@@ -1121,6 +1130,7 @@ _MODULE_PATH_SNAPSHOT: dict[str, frozenset[str]] = {
             "NodeStatus",
             "OperationId",
             "PayloadHash",
+            "CustodianMarker",
             "Period",
             "PlasmaVaultAddress",
             "PositionSetHash",

{ipor_fusion-4.0.0.dev286 → ipor_fusion-4.0.0.dev291}/tests/test_solidity_mirrors.py

@@ -22,8 +22,9 @@ from ipor_fusion.core.external_state_executor import ExternalStateExecutor
 from ipor_fusion.fuses import ExternalStateOperationFuse
 from ipor_fusion.market_ids import IporFusionMarkets
 
-# IPOR-Labs/ipor-fusion main as of 2026-09-10
-IPOR_FUSION_REF = "a1f79d6c3d0d426ace4df55ed0fb8ea340580739"
+# IPOR-Labs/ipor-fusion main as of 2026-10-21 (the contracts release
+# ipor-abi publishes)
+IPOR_FUSION_REF = "10f0f8e4031980b6f130d4f6460c6f8edfbcab32"
 
 _RAW_URL = "https://raw.githubusercontent.com/IPOR-Labs/ipor-fusion/{ref}/{path}"
 _LIBRARIES = "contracts/libraries"
@@ -50,12 +51,13 @@ def _parse_solidity_int(value: str) -> int:
 
 
 @cache
-def _solidity_source(path: str) -> str:
-    """The contract at `path` (repo-relative), at the pinned upstream commit.
+def _solidity_source(path: str, ref: str = IPOR_FUSION_REF) -> str:
+    """The contract at `path` (repo-relative), at the pinned upstream commit
+    (or ``ref``).
 
     Cached so gates reading the same file share one fetch; `cache` stores
     nothing on a raising path, so a transient failure still re-tries."""
-    url = _RAW_URL.format(ref=IPOR_FUSION_REF, path=path)
+    url = _RAW_URL.format(ref=ref, path=path)
     try:
         resp = requests.get(url, timeout=15)
     except requests.RequestException as exc:
@@ -82,7 +84,7 @@ def _solidity_constants(file_name: str) -> dict[str, int]:
 # a live deployment or a contracts feature branch). Each must be ABSENT
 # upstream at the pinned ref; once it lands, drop it here and bump
 # IPOR_FUSION_REF in the same change.
-_AHEAD_OF_UPSTREAM = {"CROSSCHAIN": 54, "HYPERCORE": 55}
+_AHEAD_OF_UPSTREAM: dict[str, int] = {}
 
 
 def _member_words(body: str) -> list[list[str]]: