ipor-fusion 4.0.0.dev144__tar.gz → 4.0.0.dev146__tar.gz

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/AGENTS.md

@@ -441,7 +441,8 @@ are not validated.
 ## Domain rules (verified against the contracts)
 
 - `fetch_vault_data(ctx, vault, *, block=, lending=, metadata=)` is the snapshot:
-  it resolves one block (``block``, else a numeric `ctx.default_block`, else latest),
+  it resolves one block (``block``, else `ctx.default_block` with a tag or hash resolved to its
+  number, else latest),
   runs every read on `ctx.at_block(block)` (log scans end there too) and returns
   everything validation and the ``vault info`` document need, so neither reads the
   chain. The chain is `ctx.chain_id`; ``lending=False`` skips lending health, the

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/MIGRATION_4.md

@@ -94,7 +94,7 @@ placeholder wrapper.
   `aggregate3(calls)` still returns the raw `Call`), `VaultSimulator`,
   `CrosschainSimulator` and `OracleMappingReader(ctx, oracle)`.
 - Resolvers that probe the chain stay eager and return context-free wrappers:
-  `price_oracle_middleware(ctx, oracle)`, `resolve_access_manager(ctx, vault)`,
+  `price_oracle_middleware(ctx, address)`, `resolve_access_manager(ctx, vault)`,
   `ExternalStateExecutor.for_vault(ctx, vault)`. A resolved oracle carries the ABI
   found on that chain and block; resolve again for another one.
 - Crosschain lanes own both contexts: `CcipLane` / `StargateLane` take `hub_ctx=` and
@@ -113,9 +113,9 @@ placeholder wrapper.
   do not see a CCIP recall or tell a parked command from a pending one. `CrosschainTransport.executor(address)`
   and `.dispatcher(address)` no longer take a context.
 - Chain-bound decoding takes the chain explicitly:
-  `ExternalStateExecutor.pending_proposals(account, *, chain_id)`,
+  `ExternalStateExecutor.pending_proposals(balance_account, *, chain_id)`,
   `parse_balance_proposed(log, *, chain_id)` and
-  `find_balance_proposed(logs, account=None, *, chain_id)` require it (3.x fell back
+  `find_balance_proposed(logs, balance_account=None, *, chain_id)` require it (3.x fell back
   to the wrapper's context). The decoder captures it, so `.call(ctx)`, `Multicall3`
   and `VaultSimulator.observe` stamp the same hash for the same bytes, whatever
   context executes them. Pass `ctx.chain_id` for the chain you read from.
@@ -134,7 +134,7 @@ placeholder wrapper.
 | `call.build_transaction(block=b)`, `call.estimate_gas(block=b)` | `call.build_transaction(ctx, block=b)`, `call.estimate_gas(ctx, block=b)` |
 | `call.ctx` | gone: keep the context yourself |
 | `Multicall3(ctx, address)` | `Multicall3(ctx, address=address)` |
-| `executor.pending_proposals(account)` | `executor.pending_proposals(account, chain_id=ctx.chain_id)` |
+| `executor.pending_proposals(balance_account)` | `executor.pending_proposals(balance_account, chain_id=ctx.chain_id)` |
 | `executor.parse_balance_proposed(log)` / `find_balance_proposed(logs)` | `...(log, chain_id=...)` / `...(logs, chain_id=...)` |
 | `CcipLane(executor=, dispatcher=, spoke_chain_id=, ...)` | `CcipLane(hub_ctx=, spoke_ctx=, executor=, dispatcher=, ...)` (same for `StargateLane`) |
 | `transport.executor(ctx, address)` / `transport.dispatcher(ctx, address)` | `transport.executor(address)` / `transport.dispatcher(address)` |
@@ -174,7 +174,8 @@ The vault read is one pinned snapshot, and the chain is always the context's:
 
 - `fetch_vault_data(ctx, vault, *, block=None, lending=True, metadata=True)` takes
   the vault address (not a `PlasmaVault`) and no `chain_id`. It resolves one block
-  (`block`, else a numeric `ctx.default_block`, else the latest) and runs every
+  (`block`, else `ctx.default_block`, with a `safe` / `finalized` tag or a block hash
+  resolved to its number, else the latest) and runs every
   read, log scans included, on `ctx.at_block(block)`; `ctx` is not modified. In 3.x
   `block_number` only selected the block reported in `VaultData`, and the reads ran
   wherever `ctx` pointed. The old `chain_id=0` switch is `lending=False`;
@@ -289,6 +290,8 @@ fails at run time:
   keyword.
 - `encode_oft_compose_msg(*, nonce=, src_eid=, amount_ld=, compose_msg=)` takes
   keyword arguments only.
+- `build_oracle_mapping(ctx, vault, *, effective_block, max_depth=6)` takes
+  `effective_block` and `max_depth` by keyword.
 - The vault parameter is named `vault` throughout: `validate_vault`,
   `fetch_deployment_info`, `fetch_vault_lending_health`, `build_oracle_mapping`,
   `read_external_state`, `ExternalStateExecutor.for_vault`, `read_hypercore_nav`,
@@ -434,8 +437,8 @@ are cached in a `ContractCache`, injected instead of always written to `~/.cache
   explicitly (default: the file cache); pass `cache=ctx.cache` to share the
   context's policy. The CLI's text and JSON output name contracts through the
   context's cache.
-- `build_vault_info_json(data)` without `resolve_name` names no contract (every
-  `contract` is `"?"`) instead of reading names from the on-disk cache; pass
+- `build_vault_info_json(data)` without `resolve_name` names no contract (fuse and
+  balance-fuse entries show `contract` as `"?"`, substrate entries omit it) instead of reading names from the on-disk cache; pass
   `resolve_name=partial(get_contract_name, chain_id, api_key=..., cache=ctx.cache)`
   for the CLI's document.
 - `ipor_fusion.cache` is a public module now and exports `ContractCache`,
@@ -536,13 +539,18 @@ converted amounts `Amount`. A custom `VaultState` annotates the same.
 `PlasmaVault.total_supply()`, `balance_of()` and `get_total_supply_cap()` return
 `Shares` (vault shares), and `transfer` / `approve` / `transfer_from` /
 `set_total_supply_cap` take `Shares`; `ERC20` keeps `Amount`.
+`Reconciliation` amounts (`balance_fuses_total`, `underlying_on_vault`,
+`erc20_direct_total`, `sum`, `on_chain_total_assets`, `delta`,
+`pending_withdrawals`, `implied_market_total`, `market_storage_divergence`) are
+`Amount`. `FusionInstance.asset_decimals` / `underlying_token_decimals` are
+`Decimals`. `VaultSimulator.current_time` is a `Timestamp`.
 
 **Vault data and helpers.** `ensure_supported_chain` takes `ChainId`.
 `fetch_unpriceable_priced_tokens` takes the oracle and underlying as
 `ChecksumAddress`. `resolve_token_symbol`, `resolve_token_decimals`,
 `get_contract_name` and `get_deployment_tx` take `HexAddress` (a checksum address
-fits), and the `resolve_name` / `resolve_symbol` callbacks receive one (a callback
-typed for `str` still fits). Market-keyed data is keyed by `MarketId`:
+fits), and the `resolve_name` callback receives one (a callback typed for `str`
+still fits). Market-keyed data is keyed by `MarketId`:
 `VaultData.market_substrates`, `dependency_graph`, `morpho_positions`,
 `aave_positions`, `market_balances`; the `VaultState` protocol,
 `fetch_vault_lending_health`, `fetch_unpriceable_priced_tokens` and the
@@ -566,8 +574,8 @@ The Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient`
 `MarketId`; `Erc20Holding.address` is `HexAddress`, and `SubstrateInfo.address` is
 `HexAddress | None`. `LegacyPriceOracleMiddleware` takes `base_currency_decimals:
 Decimals`, and `PriceOracleMiddleware.base_currency_decimals()` returns
-`Call[Decimals]`. `get_logs_adaptive(chain_id=)` and `LogSource.get_logs` take
-`ChainId`; `quote_ccip_native_fee(block=)` and
+`Call[Decimals]`. `get_logs_adaptive(chain_id=)` takes `ChainId | None` and
+`LogSource.get_logs` a `ChainId`; `quote_ccip_native_fee(block=)` and
 `OracleMappingReader.asset_source_events` take a `BlockIdentifier`.
 
 **Address roles.** `PlasmaVault(address)`,
@@ -602,7 +610,8 @@ by `ChainId` (`HYPEREVM_CHAIN_ID` is one) and `explorer.SUPPORTED_CHAINS` is a
 type-checks; `PUBLIC_ALLOCATOR_ADDRESSES` values are `ChecksumAddress`.
 
 **Markets, substrates and access.** Every `IporFusionMarkets` member is a `MarketId`.
-`decode_substrate`, `market_name`, `format_market_label` take `MarketId`.
+`market_name` and `format_market_label` take `MarketId`, `decode_substrate` a
+`MarketId | None`.
 `AccessManager.has_role`, `grant_role`, `revoke_role` and `read_accounts_with_role`
 take `RoleId | Roles`; `RoleAccount.role_id` is `RoleId`.
 
@@ -630,7 +639,12 @@ on CCIP, `active_return` → `OperationId`, `asset_id`, `tracked_position_set_ha
 `CcipObservation`, `OutboundMessage`, `CcipMessageSent`, `Any2EVMMessage`,
 `VerifierResult`, `Packet.guid`, `TaxiMessage`, `StargateChain`; and the helpers
 `fetch_verifier_result(message_id=)`, `lz_receive_calldata(guid=)` and
-`lz_compose_calldata(guid=)` take a `MessageId`. Decoded event values
+`lz_compose_calldata(guid=)` take a `MessageId`. Lane times are typed:
+`last_approved_observed_at()` returns a `Timestamp` and `staleness_max()` (with
+`STALENESS_MAX` / `BALANCE_STALENESS_MAX` on the executors) a `Period`, and so do
+the `LaneHubState` fields; `attestation(remote_timestamp=, expiry=)` and
+`BalanceObservation` take `Timestamp`, `needs_attestation(now=, margin=)` a
+`Timestamp` and a `Period`. Decoded event values
 (`ccip_events` → `CcipEvent.values`) stay a generic mapping: convert a value
 before passing it on.
 
@@ -657,20 +671,22 @@ HyperCore ids; `HyperCorePerpAssetInfo`, `HyperCorePerpMarket`, `HyperCoreSpotLe
 
 **External state.** `ExternalStateExecutor.proposal_hash` returns and `confirm_balance`
 takes a `ProposalHash`; `BalanceProposal.proposal_hash` is a `ProposalHash`;
-`ExternalStateEvent.transaction_hash` is a `TxHash`.
+`ExternalStateEvent.transaction_hash` is a `TxHash | None`.
 `ExternalStateVaultState.last_checked_custodian_timestamp`,
 `BalanceFuseSnapshot.last_custodian_update_timestamp`, `BalanceProposal.proposed_at`,
 `last_updated()` and `get_oldest_update_timestamp()` are web3's `Timestamp`, and
 `ExternalStateExecutor.proposal_hash(proposed_at=)` takes one.
 
-**Errors and explorer.** `TransactionError(tx_hash=)` takes a `TxHash`,
+**Errors and explorer.** `TransactionError(tx_hash=)` takes a `TxHash | None`,
 `LogScanError(address=)` a `ChecksumAddress`; `get_revert_reason` takes a `TxHash`;
 `get_deployment_tx` returns a `TxHash` (a malformed hash from Etherscan is reported
 as the error `malformed-tx-hash`).
 
 **MCP response models** (Python constructors only; the JSON schemas are unchanged
 except as listed under [Behavior changes](#behavior-changes)): `chain_id` fields are
-`ChainId`, `role_id` `RoleId`, `market_id` `MarketId`. Calling an MCP tool function
+`ChainId`, `role_id` `RoleId`, `market_id` `MarketId` (except
+`LendingMarketHealth.market_id`, which stays `str | int`: a Morpho market id is a
+string). Calling an MCP tool function
 directly from Python takes `ChainId`.
 
 ## Behavior changes

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev144
+Version: 4.0.0.dev146
 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.dev144 → ipor_fusion-4.0.0.dev146}/examples/composed_hypercore_flow_arbitrum_hyperevm.py

@@ -68,7 +68,7 @@ from typing import Any, NamedTuple
 from eth_abi.abi import encode as abi_encode
 from eth_utils import keccak
 from web3 import Web3
-from web3.types import BlockIdentifier, RPCEndpoint
+from web3.types import BlockIdentifier, RPCEndpoint, Timestamp
 
 from ipor_fusion import (
     ERC20,
@@ -791,7 +791,7 @@ def _attest(flow: _Tail, tag: str, observation_label: str, *, hub_idle: int = 0)
         observation,
         remote_block=flow.spoke.current_block_number,
         remote_timestamp=flow.spoke.current_time,
-        expiry=flow.hub.current_time + PROPOSAL_TTL,
+        expiry=Timestamp(flow.hub.current_time + PROPOSAL_TTL),
     )
     # SIMULATION ONLY: two keyless addresses driven from one process; live
     # they are two signers, which is the point of the two-key design.

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/examples/crosschain_ccip_usdc_arbitrum_hyperevm.py

@@ -66,6 +66,7 @@ import sys
 from typing import NamedTuple
 
 from web3 import Web3
+from web3.types import Timestamp
 
 from ipor_fusion import (
     ERC20,
@@ -431,7 +432,7 @@ def _attest(flow: _Flow, tag: str, observation_label: str, *, hub_idle: int = 0)
         observation,
         remote_block=flow.spoke.current_block_number,
         remote_timestamp=flow.spoke.current_time,
-        expiry=flow.hub.current_time + PROPOSAL_TTL,
+        expiry=Timestamp(flow.hub.current_time + PROPOSAL_TTL),
     )
     # SIMULATION ONLY: the proposer and the approver are two addresses with no
     # keys here, driven from one process. Live they are two separate signers,

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/pyproject.toml

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

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/cli/vault_cmd.py

@@ -449,7 +449,9 @@ def oracle_mapping(
         raise click.UsageError(str(exc)) from exc
 
     try:
-        mapping = build_oracle_mapping(ctx, vault_address, effective_block, max_depth)
+        mapping = build_oracle_mapping(
+            ctx, vault_address, effective_block=effective_block, max_depth=max_depth
+        )
     except UnsupportedVaultVersionError as exc:
         raise click.ClickException(str(exc)) from exc
 

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/core/fusion_factory.py

@@ -35,6 +35,7 @@ from web3.types import TxReceipt
 from ipor_fusion.core.contract import Call, ContractWrapper
 from ipor_fusion.types import (
     AccessManagerAddress,
+    Decimals,
     Period,
     PlasmaVaultAddress,
     parse_access_manager_address,
@@ -64,10 +65,10 @@ class FusionInstance:
     version: int
     asset_name: str
     asset_symbol: str
-    asset_decimals: int
+    asset_decimals: Decimals
     underlying_token: ChecksumAddress
     underlying_token_symbol: str
-    underlying_token_decimals: int
+    underlying_token_decimals: Decimals
     initial_owner: ChecksumAddress
     plasma_vault: PlasmaVaultAddress
     plasma_vault_base: ChecksumAddress
@@ -118,10 +119,10 @@ _INSTANCE_FIELDS: dict[str, Callable[[Any], Any]] = {
     "version": _integer,
     "asset_name": _text,
     "asset_symbol": _text,
-    "asset_decimals": _integer,
+    "asset_decimals": lambda value: Decimals(_integer(value)),
     "underlying_token": _address,
     "underlying_token_symbol": _text,
-    "underlying_token_decimals": _integer,
+    "underlying_token_decimals": lambda value: Decimals(_integer(value)),
     "initial_owner": _address,
     "plasma_vault": lambda value: parse_plasma_vault_address(_text(value)),
     "plasma_vault_base": _address,
@@ -185,10 +186,10 @@ def _fusion_instance_decoder(values: tuple) -> FusionInstance:
         version=version,
         asset_name=asset_name,
         asset_symbol=asset_symbol,
-        asset_decimals=asset_decimals,
+        asset_decimals=Decimals(asset_decimals),
         underlying_token=addr(underlying_token),
         underlying_token_symbol=underlying_token_symbol,
-        underlying_token_decimals=underlying_token_decimals,
+        underlying_token_decimals=Decimals(underlying_token_decimals),
         initial_owner=addr(initial_owner),
         plasma_vault=PlasmaVaultAddress(addr(plasma_vault)),
         plasma_vault_base=addr(plasma_vault_base),
@@ -347,10 +348,10 @@ class FusionFactory(ContractWrapper):
             version=int(values[1]),
             asset_name=values[2],
             asset_symbol=values[3],
-            asset_decimals=int(values[4]),
+            asset_decimals=Decimals(int(values[4])),
             underlying_token=Web3.to_checksum_address(values[5]),
             underlying_token_symbol=values[6],
-            underlying_token_decimals=int(values[7]),
+            underlying_token_decimals=Decimals(int(values[7])),
             initial_owner=Web3.to_checksum_address(values[8]),
             plasma_vault=PlasmaVaultAddress(Web3.to_checksum_address(values[9])),
             plasma_vault_base=Web3.to_checksum_address(values[10]),

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/core/simulation.py

@@ -10,7 +10,7 @@ from eth_typing import ChecksumAddress
 from eth_utils import keccak
 from hexbytes import HexBytes
 from web3 import Web3
-from web3.types import BlockIdentifier, Nonce, RPCEndpoint
+from web3.types import BlockIdentifier, Nonce, RPCEndpoint, Timestamp
 from web3.utils.address import get_create_address
 
 from ipor_fusion.core.contract import Call, _encode_calldata
@@ -221,13 +221,13 @@ class VaultSimulator:
         return any(block.calls for block in self._blocks)
 
     @property
-    def current_time(self) -> int:
+    def current_time(self) -> Timestamp:
         """Timestamp of the latest sent block or an explicit pending time.
 
         A pending block without an explicit time will run 12 seconds later
         once it contains a call.
         """
-        return self._current_time()
+        return Timestamp(self._current_time())
 
     @property
     def current_block_number(self) -> int:

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/crosschain/ccip/contracts.py

@@ -26,6 +26,7 @@ from ipor_fusion.types import (
     CommandId,
     MessageId,
     OperationId,
+    Period,
     PlasmaVaultAddress,
     PositionSetHash,
     ProposalId,
@@ -143,8 +144,10 @@ class CcipCrosschainExecutor(CrosschainExecutor):
     def decimal_conversion_rate(self) -> Call[int]:
         return self._view("DECIMAL_CONVERSION_RATE()", output_types=["uint256"])
 
-    def balance_staleness_max(self) -> Call[int]:
-        return self._view("BALANCE_STALENESS_MAX()", output_types=["uint256"])
+    def balance_staleness_max(self) -> Call[Period]:
+        return self._view(
+            "BALANCE_STALENESS_MAX()", output_types=["uint256"], decoder=Period
+        )
 
     def ccip_route(self, chain_id: ChainId) -> Call[CcipRouteConfig]:
         return self._view(

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/crosschain/ccip/lane.py

@@ -22,7 +22,7 @@ from ipor_fusion.crosschain.fuses.ccip import (
 )
 from ipor_fusion.crosschain.lane import CrosschainLane, LaneFuses, LaneObservation
 from ipor_fusion.crosschain.messages import CommandStatus, CrosschainTransportKind
-from ipor_fusion.types import Amount, ProposalId
+from ipor_fusion.types import Amount, Period, ProposalId
 
 
 class CcipLane(CrosschainLane):
@@ -89,7 +89,7 @@ class CcipLane(CrosschainLane):
             ),
         )
 
-    def staleness_max(self) -> Call[int]:
+    def staleness_max(self) -> Call[Period]:
         return self.executor.balance_staleness_max()
 
     def default_send(self, *, token: bool) -> CcipSendParams:

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/crosschain/contracts.py

@@ -16,6 +16,7 @@ from dataclasses import dataclass
 
 from eth_typing import ChecksumAddress
 from web3 import Web3
+from web3.types import Timestamp
 
 from ipor_fusion.core.contract import Call, ContractWrapper
 from ipor_fusion.crosschain.messages import CommandStatus
@@ -42,8 +43,8 @@ class BalanceObservation:
     settled_balance: Amount
     state_version: int
     remote_block: int
-    remote_timestamp: int
-    expiry: int
+    remote_timestamp: Timestamp
+    expiry: Timestamp
     tracked_position_set_hash: PositionSetHash
 
     def as_tuple(self) -> tuple:
@@ -160,9 +161,12 @@ class CrosschainExecutor(ContractWrapper):
     def chain_blocked(self, chain_id: ChainId) -> Call[bool]:
         return self._view("chainBlocked(uint256)", chain_id, output_types=["bool"])
 
-    def last_approved_observed_at(self, chain_id: ChainId) -> Call[int]:
+    def last_approved_observed_at(self, chain_id: ChainId) -> Call[Timestamp]:
         return self._view(
-            "lastApprovedObservedAt(uint256)", chain_id, output_types=["uint64"]
+            "lastApprovedObservedAt(uint256)",
+            chain_id,
+            output_types=["uint64"],
+            decoder=Timestamp,
         )
 
     def approve_balance(self, proposal_id: ProposalId) -> Call[None]:

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/crosschain/lane.py

@@ -34,6 +34,7 @@ from typing import Any, ClassVar, cast
 
 from eth_abi import decode
 from eth_typing import ChecksumAddress
+from web3.types import Timestamp
 
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.contract import Call
@@ -52,7 +53,14 @@ from ipor_fusion.crosschain.fuses.base import (
 )
 from ipor_fusion.crosschain.logs import log_address, log_bytes, log_topic0
 from ipor_fusion.crosschain.messages import Command, CrosschainTransportKind
-from ipor_fusion.types import Amount, ChainId, FuseAddress, PositionSetHash, ProposalId
+from ipor_fusion.types import (
+    Amount,
+    ChainId,
+    FuseAddress,
+    Period,
+    PositionSetHash,
+    ProposalId,
+)
 
 
 @dataclass(frozen=True, slots=True)
@@ -73,6 +81,7 @@ class LaneObservation:
 # set pinned to the number the tag resolves to once keeps the tag's meaning.
 # "pending" names no mined block and is left as is.
 _MOVING_BLOCK_TAGS = frozenset({"latest", "safe", "finalized"})
+_NO_MARGIN = Period(0)
 
 
 @dataclass(frozen=True, slots=True)
@@ -86,8 +95,8 @@ class LaneHubState:
     idle_ledger: Amount
     dispatcher_ready: bool
     chain_blocked: bool
-    last_approved_observed_at: int
-    staleness_max: int
+    last_approved_observed_at: Timestamp
+    staleness_max: Period
     remote_state_version: int
     has_active_command: bool
     pending_transfer_count: int
@@ -233,7 +242,7 @@ class CrosschainLane(ABC):
     def chain_blocked(self) -> Call[bool]:
         return self.executor.chain_blocked(self.spoke_chain_id)
 
-    def last_approved_observed_at(self) -> Call[int]:
+    def last_approved_observed_at(self) -> Call[Timestamp]:
         """Remote timestamp of the approved observation NAV freshness is
         measured from; 0 before the first attestation."""
         return self.executor.last_approved_observed_at(self.spoke_chain_id)
@@ -279,8 +288,8 @@ class CrosschainLane(ABC):
         observation: LaneObservation,
         *,
         remote_block: int,
-        remote_timestamp: int,
-        expiry: int,
+        remote_timestamp: Timestamp,
+        expiry: Timestamp,
     ) -> BalanceObservation:
         """The proposal for ``observation``, read on the spoke at
         ``remote_block`` / ``remote_timestamp`` and valid on the hub until
@@ -297,7 +306,7 @@ class CrosschainLane(ABC):
             tracked_position_set_hash=observation.tracked_position_set_hash,
         )
 
-    def needs_attestation(self, *, now: int, margin: int = 0) -> bool:
+    def needs_attestation(self, *, now: Timestamp, margin: Period = _NO_MARGIN) -> bool:
         """Whether a keeper should propose now (up to seven reads on the hub):
         the settled bucket is non-zero, no transfer or command receipt is in
         flight, and the approved observation is missing or older than
@@ -362,7 +371,7 @@ class CrosschainLane(ABC):
         """Bind ``min_received`` into the transport's send parameters."""
 
     @abstractmethod
-    def staleness_max(self) -> Call[int]:
+    def staleness_max(self) -> Call[Period]:
         """Seconds an approved observation keeps the settled bucket in NAV
         (``STALENESS_MAX`` on Stargate, ``BALANCE_STALENESS_MAX`` on CCIP)."""
 

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/crosschain/stargate/contracts.py

@@ -24,6 +24,7 @@ from ipor_fusion.types import (
     CommandId,
     DeploymentRequestId,
     LayerZeroEid,
+    Period,
     PlasmaVaultAddress,
     PositionSetHash,
     ProposalId,
@@ -111,8 +112,8 @@ class StargateCrosschainExecutor(CrosschainExecutor):
     def local_chain_id(self) -> Call[ChainId]:
         return self._view("LOCAL_CHAIN_ID()", output_types=["uint256"], decoder=ChainId)
 
-    def staleness_max(self) -> Call[int]:
-        return self._view("STALENESS_MAX()", output_types=["uint256"])
+    def staleness_max(self) -> Call[Period]:
+        return self._view("STALENESS_MAX()", output_types=["uint256"], decoder=Period)
 
     def deployment_ttl(self) -> Call[int]:
         return self._view("DEPLOYMENT_TTL()", output_types=["uint256"])

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/crosschain/stargate/lane.py

@@ -25,7 +25,7 @@ from ipor_fusion.crosschain.stargate.contracts import (
     StargateCrosschainExecutor,
 )
 from ipor_fusion.crosschain.stargate.layerzero import OptionsBuilder
-from ipor_fusion.types import Amount
+from ipor_fusion.types import Amount, Period
 
 
 class StargateLane(CrosschainLane):
@@ -73,7 +73,7 @@ class StargateLane(CrosschainLane):
             fuses=fuses,
         )
 
-    def staleness_max(self) -> Call[int]:
+    def staleness_max(self) -> Call[Period]:
         return self.executor.staleness_max()
 
     def default_send(self, *, token: bool) -> StargateSendParams:

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/mcp/server.py

@@ -398,7 +398,7 @@ def vault_oracle_mapping(
 
     resolve_access_manager(ctx, checksum)
 
-    mapping = build_oracle_mapping(ctx, checksum, effective_block)
+    mapping = build_oracle_mapping(ctx, checksum, effective_block=effective_block)
     return OracleMappingResponse.from_mapping(mapping)
 
 

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/readers/lending_health.py

@@ -94,7 +94,7 @@ class LendingMarketHealth:
     """Health status of a single lending market position.
 
     `substrate_id` identifies the underlying market within the IPOR market_id:
-    - Morpho: the 64-char hex morpho market id (one row per substrate).
+    - Morpho: the morpho market id (`0x` + 64 lowercase hex) (one row per substrate).
     - Aave V3: None — Aave health is account-level, aggregated across reserves.
     - Aave V4: the Spoke address — account-level per Spoke, across its reserves.
     """

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/readers/oracle_mapping.py

@@ -428,6 +428,7 @@ def _enumerate_assets(
 def build_oracle_mapping(
     ctx: Web3Context,
     vault: PlasmaVaultAddress,
+    *,
     effective_block: int,
     max_depth: int = 6,
 ) -> OracleMapping:

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/validation.py

@@ -165,29 +165,29 @@ class Reconciliation:
     only; ``erc20_direct_total`` is informational and never added to it.
     """
 
-    balance_fuses_total: int
+    balance_fuses_total: Amount
     balance_fuses_total_usd: float
-    underlying_on_vault: int
+    underlying_on_vault: Amount
     underlying_on_vault_usd: float
-    erc20_direct_total: int
+    erc20_direct_total: Amount
     erc20_direct_total_usd: float
-    sum: int
+    sum: Amount
     sum_usd: float
-    on_chain_total_assets: int
+    on_chain_total_assets: Amount
     on_chain_total_assets_usd: float | None
-    delta: int
+    delta: Amount
     delta_usd: float
     delta_percent: float
     # sharesToRelease of the WithdrawManager converted to assets.
-    pending_withdrawals: int
+    pending_withdrawals: Amount
     pending_withdrawals_usd: float
     # totalAssets minus idle underlying: the global market total the vault
     # stores, which per-market caches drift from after partial refreshes.
-    implied_market_total: int
+    implied_market_total: Amount
 
     @property
-    def market_storage_divergence(self) -> int:
-        return self.balance_fuses_total - self.implied_market_total
+    def market_storage_divergence(self) -> Amount:
+        return Amount(self.balance_fuses_total - self.implied_market_total)
 
 
 @dataclass(frozen=True)
@@ -288,10 +288,10 @@ def _reconcile(state: VaultState) -> Reconciliation:
     decimals = state.asset_decimals
     price = state.asset_price_usd
 
-    balance_fuses_total = 0
+    balance_fuses_total = Amount(0)
     balance_fuses_usd = 0.0
     for balance in market_balances.values():
-        balance_fuses_total += balance
+        balance_fuses_total = Amount(balance_fuses_total + balance)
         if price is not None:
             balance_fuses_usd += (balance / 10**decimals) * price
 
@@ -300,17 +300,17 @@ def _reconcile(state: VaultState) -> Reconciliation:
     if underlying > 0 and price:
         underlying_usd = (underlying / 10**decimals) * price
 
-    total = balance_fuses_total + underlying
+    total = Amount(balance_fuses_total + underlying)
     total_usd = balance_fuses_usd + underlying_usd
     on_chain = state.total_assets
-    delta = total - on_chain
+    delta = Amount(total - on_chain)
     delta_usd = abs(total_usd - (on_chain / 10**decimals * price)) if price else 0
     delta_percent = abs(delta / on_chain * 100) if on_chain else 0.0
 
     # totalAssets reads the global market total while balance fuses report
     # per-market caches; they diverge after withdrawals with sharesToRelease,
     # which refresh only the markets the instant-withdrawal fuses touch.
-    pending = 0
+    pending = Amount(0)
     pending_usd = 0.0
     queue = state.withdraw_manager_data
     if queue and queue.shares_to_release > 0:
@@ -336,7 +336,7 @@ def _reconcile(state: VaultState) -> Reconciliation:
         delta_percent=delta_percent,
         pending_withdrawals=pending,
         pending_withdrawals_usd=pending_usd,
-        implied_market_total=max(0, on_chain - underlying),
+        implied_market_total=Amount(max(0, on_chain - underlying)),
     )
 
 

{ipor_fusion-4.0.0.dev144 → ipor_fusion-4.0.0.dev146}/src/ipor_fusion/vault_data.py

@@ -532,6 +532,16 @@ def _fetch_lending_reads(
     )
 
 
+def _pinned_default_block(ctx: Web3Context) -> int | None:
+    """The number ``ctx.default_block`` names, or None for the latest block."""
+    default = ctx.default_block
+    if isinstance(default, int):
+        return default
+    if default in ("latest", "pending"):
+        return None
+    return ctx.web3.eth.get_block(default)["number"]
+
+
 def fetch_vault_data(
     ctx: Web3Context,
     vault: PlasmaVaultAddress,
@@ -541,8 +551,8 @@ def fetch_vault_data(
     metadata: bool = True,
 ) -> VaultData:
     """Read the vault's state at one block: ``block``, else the context's
-    default block when that is a number, else the latest block, resolved once
-    up front. Every read, log scans included, runs on a copy of ``ctx`` pinned
+    default block (a ``safe`` / ``finalized`` tag or a block hash is resolved
+    to its number), else the latest block, resolved once up front. Every read, log scans included, runs on a copy of ``ctx`` pinned
     to that block (`Web3Context.at_block`); ``ctx`` itself is not modified.
     The chain is ``ctx.chain_id``.
 
@@ -561,8 +571,8 @@ def fetch_vault_data(
     # Fail fast with a client-mappable typed error instead of letting the
     # fetch die deep in the stack on chains the tooling is not validated on.
     ensure_supported_chain(ctx.chain_id)
-    if block is None and isinstance(ctx.default_block, int):
-        block = ctx.default_block
+    if block is None:
+        block = _pinned_default_block(ctx)
     resolved_block = ctx.web3.eth.block_number if block is None else block
     is_latest = block is None
     ctx = ctx.at_block(resolved_block)