ipor-fusion 4.0.0.dev156__tar.gz → 4.0.0.dev159__tar.gz

{ipor_fusion-4.0.0.dev156 → ipor_fusion-4.0.0.dev159}/MIGRATION_4.md

@@ -787,6 +787,7 @@ untyped code needs none of this section.
 | `build_morpho_blue_market_json` | `MorphoBlueMarketJson` |
 | `build_meta_morpho_json` | `MetaMorphoV1Json \| MetaMorphoV2Json`, told apart by `doc["version"]` |
 | `RoleAccount.to_dict` | `RoleAccountJson` |
+| `OracleMapping.to_dict` / `OracleNode.to_dict` | `OracleMappingJson` / `OracleNodeJson` |
 
 Every nested block has its own TypedDict (`FeesJson`, `WithdrawManagerJson`,
 `BalanceFuseJson`, `ReconciliationJson`, `HyperCoreJson`, `MorphoSupplyingVaultJson`,
@@ -813,6 +814,24 @@ that only some entries carry is `NotRequired` (a balance fuse's `pct_of_total` a
   age) or `DeploymentErrorJson` (`{"error": ...}`) or `None`; `share_price` is
   `SharePriceJson` (`asset`, and `usd` when the asset is priced); `dependency_graph`
   is `DependencyGraphJson` (`edges`, `update_reach`, `update_groups`).
+- `OracleNode.source_detail` is `SourceDetailJson`, one TypedDict per feed kind
+  (`ChainlinkDetailJson`, `DualXrefDetailJson`, `Erc4626DetailJson`,
+  `MorphoFeedDetailJson`, `MiddlewareFallbackDetailJson`; importable from
+  `ipor_fusion` and `ipor_fusion.readers`). Narrow by a key before reading a
+  kind-specific one: `if detail is not None and "aggregator" in detail:
+  detail["description"]`.
+- Event `args` are typed per event kind: `ExternalStateEvent.args` is
+  `ExternalStateEventArgs` and `HyperCoreEvent.args` is `HyperCoreEventArgs`, a union
+  of one TypedDict per event (`ExternalStateUnpausedArgs`,
+  `HyperCoreDepositFuseEnterArgs`, ...; `EXTERNAL_STATE_EVENT_ARGS` /
+  `HYPERCORE_EVENT_ARGS` map an event name to its shape). Values carry nominal types
+  (`Amount`, `MarketId`, `FuseAddress`, `HyperCoreTokenIndex`, `PayloadHash`, web3's
+  `Timestamp`, ...). `event.args["signer"]` no longer type-checks on its own: narrow
+  with a key test (`if "signer" in event.args:`). `HyperCoreEvent.fuse` is a
+  `FuseAddress | None`.
+- `RawLog` (the log shape `ExternalStateExecutor.parse_balance_proposed` /
+  `find_balance_proposed` accept) is `Mapping[str, object]`, not `Mapping[str, Any]`;
+  a web3 `LogReceipt` still fits it.
 
 ## Behavior changes
 

{ipor_fusion-4.0.0.dev156 → ipor_fusion-4.0.0.dev159}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev156
+Version: 4.0.0.dev159
 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.dev156 → ipor_fusion-4.0.0.dev159}/pyproject.toml

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

{ipor_fusion-4.0.0.dev156 → ipor_fusion-4.0.0.dev159}/src/ipor_fusion/__init__.py

@@ -314,15 +314,44 @@ from ipor_fusion.fuses import (
     system_address,
 )
 from ipor_fusion.fuses.external_state_events import (
+    EXTERNAL_STATE_EVENT_ARGS,
     EXTERNAL_STATE_EVENT_SPECS,
     EXTERNAL_STATE_EVENTS,
     EXTERNAL_STATE_TOPICS,
+    ExternalStateAssetRescuedArgs,
+    ExternalStateBigChangeDetectedArgs,
+    ExternalStateCustodianTimestampUpdatedArgs,
     ExternalStateEvent,
+    ExternalStateEventArgs,
     ExternalStateEventSpec,
+    ExternalStateExecutorArgs,
+    ExternalStateOperationArgs,
+    ExternalStateTotalBalanceUpdatedArgs,
+    ExternalStateUnpausedArgs,
     decode_external_state_event,
     external_state_event_name,
     external_state_events,
 )
+from ipor_fusion.fuses.hypercore_events import (
+    HYPERCORE_EVENT_ARGS,
+    HyperCoreActionEnqueuedArgs,
+    HyperCoreActionSettledArgs,
+    HyperCoreBuilderFeeFuseEnterArgs,
+    HyperCoreCancelByCloidArgs,
+    HyperCoreCancelByOidArgs,
+    HyperCoreDepositFuseEnterArgs,
+    HyperCoreEventArgs,
+    HyperCoreMarginFuseEnterArgs,
+    HyperCoreObserverSetChangedArgs,
+    HyperCoreObserverSetProposedArgs,
+    HyperCoreOrderFuseEnterArgs,
+    HyperCoreRecoveryExecutedArgs,
+    HyperCoreRecoveryProposedArgs,
+    HyperCoreReportedActionSettledArgs,
+    HyperCoreReportSubmittedArgs,
+    HyperCoreSendFuseSendAssetArgs,
+    HyperCoreSendFuseSpotSendArgs,
+)
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.market_info import (
     MetaMorphoAdapterJson,
@@ -422,6 +451,20 @@ from ipor_fusion.readers import (
     read_hypercore_transfer_snapshot,
     read_hypercore_vault_state,
 )
+from ipor_fusion.readers.oracle_mapping_nodes import (
+    AggregatorDetailJson,
+    AggregatorFeedDetailJson,
+    ChainlinkDetailJson,
+    DualXrefDetailJson,
+    Erc4626DetailJson,
+    MiddlewareFallbackDetailJson,
+    MorphoFeedDetailJson,
+    OracleAssetJson,
+    OracleMappingJson,
+    OracleNodeJson,
+    OraclePriceJson,
+    SourceDetailJson,
+)
 from ipor_fusion.substrates import (
     SubstrateInfo,
     decode_substrate,
@@ -546,6 +589,15 @@ __all__ = [
     "EXTERNAL_STATE_EVENTS",
     "EXTERNAL_STATE_TOPICS",
     "ExternalStateEvent",
+    "EXTERNAL_STATE_EVENT_ARGS",
+    "ExternalStateAssetRescuedArgs",
+    "ExternalStateBigChangeDetectedArgs",
+    "ExternalStateCustodianTimestampUpdatedArgs",
+    "ExternalStateEventArgs",
+    "ExternalStateExecutorArgs",
+    "ExternalStateOperationArgs",
+    "ExternalStateTotalBalanceUpdatedArgs",
+    "ExternalStateUnpausedArgs",
     "ExternalStateEventDecodeError",
     "ExternalStateEventSpec",
     "decode_external_state_event",
@@ -554,6 +606,24 @@ __all__ = [
     "HYPERCORE_EVENTS",
     "HYPERCORE_EVENT_SPECS",
     "HyperCoreEvent",
+    "HYPERCORE_EVENT_ARGS",
+    "HyperCoreActionEnqueuedArgs",
+    "HyperCoreActionSettledArgs",
+    "HyperCoreBuilderFeeFuseEnterArgs",
+    "HyperCoreCancelByCloidArgs",
+    "HyperCoreCancelByOidArgs",
+    "HyperCoreDepositFuseEnterArgs",
+    "HyperCoreEventArgs",
+    "HyperCoreMarginFuseEnterArgs",
+    "HyperCoreObserverSetChangedArgs",
+    "HyperCoreObserverSetProposedArgs",
+    "HyperCoreOrderFuseEnterArgs",
+    "HyperCoreRecoveryExecutedArgs",
+    "HyperCoreRecoveryProposedArgs",
+    "HyperCoreReportSubmittedArgs",
+    "HyperCoreReportedActionSettledArgs",
+    "HyperCoreSendFuseSendAssetArgs",
+    "HyperCoreSendFuseSpotSendArgs",
     "HyperCoreEventSpec",
     "decode_hypercore_event",
     "find_hypercore_events",
@@ -945,6 +1015,18 @@ __all__ = [
     "OracleAsset",
     "OracleMapping",
     "OracleNode",
+    "AggregatorDetailJson",
+    "AggregatorFeedDetailJson",
+    "ChainlinkDetailJson",
+    "DualXrefDetailJson",
+    "Erc4626DetailJson",
+    "MiddlewareFallbackDetailJson",
+    "MorphoFeedDetailJson",
+    "OracleAssetJson",
+    "OracleMappingJson",
+    "OracleNodeJson",
+    "OraclePriceJson",
+    "SourceDetailJson",
     "OraclePrice",
     "build_oracle_mapping",
     "OracleMappingReader",

{ipor_fusion-4.0.0.dev156 → ipor_fusion-4.0.0.dev159}/src/ipor_fusion/cli/oracle_mapping_view.py

@@ -24,21 +24,25 @@ def _format_wad_price(price: OraclePrice | None) -> str:
 
 def _print_feed_line(node: OracleNode) -> None:
     """The feed's self-declared units — key for confirming what a value means."""
-    detail = node.source_detail or {}
+    detail = node.source_detail
     if node.source_type in (TYPE_CHAINLINK, TYPE_CHAINLINK_STYLE):
-        if detail.get("description"):
+        if detail is not None and "aggregator" in detail and detail["description"]:
             click.echo(f"    Feed:   {detail['description']}")
         else:
             # only chainlink_style can land here — the confirmed tier
             # requires a non-empty description
             click.secho("    Feed:   (no description)", fg="yellow")
-    elif node.source_type == TYPE_DUAL_XREF:
+    elif (
+        node.source_type == TYPE_DUAL_XREF
+        and detail is not None
+        and "asset_x" in detail
+    ):
         rendered = [
             # quoted — the descriptions themselves contain " / "
             f'"{d}"' if d else click.style("(no description)", fg="yellow")
             for d in (
-                (detail.get(key) or {}).get("description")
-                for key in ("asset_x_asset_y_feed", "asset_y_usd_feed")
+                detail["asset_x_asset_y_feed"]["description"],
+                detail["asset_y_usd_feed"]["description"],
             )
         ]
         click.echo(f"    Feed:   {' × '.join(rendered)}")

{ipor_fusion-4.0.0.dev156 → ipor_fusion-4.0.0.dev159}/src/ipor_fusion/core/external_state_executor.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, replace
-from typing import Any
+from typing import TypeAlias
 
 from eth_abi import decode, encode
 from eth_abi.exceptions import DecodingError
@@ -44,8 +44,9 @@ from ipor_fusion.types import (
 # (HexBytes fields, checksummed address), and a raw JSON-RPC or
 # `eth_simulateV1` row (0x-hex strings, lowercase address). Looser than
 # `web3.types.LogReceipt`, which the rest of `core/` uses, because those rows
-# carry neither its field types nor all of its required keys.
-RawLog = Mapping[str, Any]
+# carry neither its field types nor all of its required keys. Every field is
+# read as `object` and narrowed; a `LogReceipt` is one of these mappings.
+RawLog: TypeAlias = Mapping[str, object]
 
 
 def _log_emitter(log: RawLog) -> ChecksumAddress | None:
@@ -55,7 +56,7 @@ def _log_emitter(log: RawLog) -> ChecksumAddress | None:
     matched against an expected emitter, and a caller scanning foreign rows
     should skip such a log rather than have the scan abort on it."""
     emitter = log.get("address")
-    if emitter is None:
+    if not isinstance(emitter, str | bytes):
         return None
     try:
         return Web3.to_checksum_address(emitter)
@@ -590,11 +591,14 @@ class ExternalStateExecutor(ContractWrapper):
         event -- the rule `_log_emitter` already applies to an unreadable
         address, and it keeps a raise meaning "ours, but the payload is broken".
         """
-        topics = log.get("topics") or ()
-        if not topics:
+        topics = log.get("topics")
+        if not isinstance(topics, list | tuple) or not topics:
+            return False
+        topic = topics[0]
+        if not isinstance(topic, str | bytes | bytearray):
             return False
         try:
-            return HexBytes(topics[0]) == cls._BALANCE_PROPOSED_TOPIC
+            return HexBytes(topic) == cls._BALANCE_PROPOSED_TOPIC
         except (ValueError, TypeError):
             return False
 
@@ -652,6 +656,10 @@ class ExternalStateExecutor(ContractWrapper):
         data = log.get("data")
         if data is None:
             raise ExternalStateError("BalanceProposed log carries no data")
+        if not isinstance(data, str | bytes | bytearray):
+            raise ExternalStateError(
+                f"malformed BalanceProposed data: {type(data).__name__}"
+            )
         try:
             # Unpacked in the order `BalanceProposed` declares them; all six
             # are unindexed, so topics carries topic0 alone.

{ipor_fusion-4.0.0.dev156 → ipor_fusion-4.0.0.dev159}/src/ipor_fusion/fuses/__init__.py

@@ -50,10 +50,28 @@ from ipor_fusion.fuses.hypercore import (
     system_address,
 )
 from ipor_fusion.fuses.hypercore_events import (
+    HYPERCORE_EVENT_ARGS,
     HYPERCORE_EVENT_SPECS,
     HYPERCORE_EVENTS,
+    HyperCoreActionEnqueuedArgs,
+    HyperCoreActionSettledArgs,
+    HyperCoreBuilderFeeFuseEnterArgs,
+    HyperCoreCancelByCloidArgs,
+    HyperCoreCancelByOidArgs,
+    HyperCoreDepositFuseEnterArgs,
     HyperCoreEvent,
+    HyperCoreEventArgs,
     HyperCoreEventSpec,
+    HyperCoreMarginFuseEnterArgs,
+    HyperCoreObserverSetChangedArgs,
+    HyperCoreObserverSetProposedArgs,
+    HyperCoreOrderFuseEnterArgs,
+    HyperCoreRecoveryExecutedArgs,
+    HyperCoreRecoveryProposedArgs,
+    HyperCoreReportedActionSettledArgs,
+    HyperCoreReportSubmittedArgs,
+    HyperCoreSendFuseSendAssetArgs,
+    HyperCoreSendFuseSpotSendArgs,
     decode_hypercore_event,
     find_hypercore_events,
     hypercore_event_name,
@@ -94,6 +112,24 @@ __all__ = [
     "HYPERCORE_EVENTS",
     "HYPERCORE_EVENT_SPECS",
     "HyperCoreEvent",
+    "HYPERCORE_EVENT_ARGS",
+    "HyperCoreActionEnqueuedArgs",
+    "HyperCoreActionSettledArgs",
+    "HyperCoreBuilderFeeFuseEnterArgs",
+    "HyperCoreCancelByCloidArgs",
+    "HyperCoreCancelByOidArgs",
+    "HyperCoreDepositFuseEnterArgs",
+    "HyperCoreEventArgs",
+    "HyperCoreMarginFuseEnterArgs",
+    "HyperCoreObserverSetChangedArgs",
+    "HyperCoreObserverSetProposedArgs",
+    "HyperCoreOrderFuseEnterArgs",
+    "HyperCoreRecoveryExecutedArgs",
+    "HyperCoreRecoveryProposedArgs",
+    "HyperCoreReportSubmittedArgs",
+    "HyperCoreReportedActionSettledArgs",
+    "HyperCoreSendFuseSendAssetArgs",
+    "HyperCoreSendFuseSpotSendArgs",
     "HyperCoreEventSpec",
     "decode_hypercore_event",
     "find_hypercore_events",

ipor_fusion-4.0.0.dev159/src/ipor_fusion/fuses/events.py

@@ -0,0 +1,45 @@
+from eth_abi import decode
+from eth_typing import ChecksumAddress
+from web3 import Web3
+from web3.types import TxReceipt
+
+
+def extract_events(
+    receipt: TxReceipt,
+    event_signature: str,
+    abi_types: list[str],
+    dataclass_type,
+):
+    sig_hash = Web3.keccak(text=event_signature)
+    events = []
+    for log in receipt["logs"]:
+        if log["topics"][0] == sig_hash:
+            decoded = decode(abi_types, log["data"])
+            events.append(
+                dataclass_type(
+                    *(
+                        Web3.to_checksum_address(value) if abi == "address" else value
+                        for abi, value in zip(abi_types, decoded, strict=True)
+                    )
+                )
+            )
+    return events
+
+
+def abi_value(abi_type: str, value: object) -> int | bool | bytes | ChecksumAddress:
+    """One ``eth_abi``-decoded event parameter as the Python type its ABI type
+    decodes to: an address checksummed, a ``uintN`` / ``intN`` an int, a
+    ``bool`` a bool, a ``bytesN`` bytes. Anything else raises ``TypeError``."""
+    if abi_type == "address" and isinstance(value, str):
+        return Web3.to_checksum_address(value)
+    if abi_type == "bool" and isinstance(value, bool):
+        return value
+    if (
+        abi_type.startswith(("uint", "int"))
+        and isinstance(value, int)
+        and not isinstance(value, bool)
+    ):
+        return value
+    if abi_type.startswith("bytes") and isinstance(value, bytes):
+        return value
+    raise TypeError(f"{abi_type} decoded as {type(value).__name__}")

{ipor_fusion-4.0.0.dev156 → ipor_fusion-4.0.0.dev159}/src/ipor_fusion/fuses/external_state_events.py

@@ -24,16 +24,17 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass
-from typing import Any
+from typing import TypeAlias, TypedDict, cast
 
 from eth_abi import decode
 from eth_abi.exceptions import DecodingError
 from eth_typing import ChecksumAddress
 from web3 import Web3
-from web3.types import TxReceipt
+from web3.types import Timestamp, TxReceipt
 
 from ipor_fusion.errors import ExternalStateEventDecodeError
-from ipor_fusion.types import TxHash, parse_tx_hash
+from ipor_fusion.fuses.events import abi_value
+from ipor_fusion.types import Amount, FuseAddress, MarketId, TxHash, parse_tx_hash
 
 
 @dataclass(frozen=True, slots=True)
@@ -114,6 +115,85 @@ EXTERNAL_STATE_EVENT_SPECS: tuple[ExternalStateEventSpec, ...] = (
     ),
 )
 
+
+class ExternalStateBigChangeDetectedArgs(TypedDict):
+    previousTotal: Amount
+    newTotal: Amount
+    thresholdBps: int
+
+
+class ExternalStateCustodianTimestampUpdatedArgs(TypedDict):
+    """``ExternalStateBalanceFuseLastCustodianTimestampUpdated``."""
+
+    oldTimestamp: Timestamp
+    newTimestamp: Timestamp
+
+
+class ExternalStateTotalBalanceUpdatedArgs(TypedDict):
+    """``ExternalStateBalanceFuseLastTotalBalanceUpdated``."""
+
+    oldTotalBalance: Amount
+    newTotalBalance: Amount
+
+
+class ExternalStateUnpausedArgs(TypedDict):
+    signer: ChecksumAddress
+    confirmedTotalBalance: Amount
+    nonce: int
+
+
+class ExternalStateAssetRescuedArgs(TypedDict):
+    asset: ChecksumAddress
+
+
+class ExternalStateExecutorArgs(TypedDict):
+    """``ExecutorCreated`` and ``ExternalStateExecutorDeployed``."""
+
+    executor: ChecksumAddress
+    marketId: MarketId
+
+
+class ExternalStateOperationArgs(TypedDict):
+    """``ExternalStateOperationFuseEnter`` and ``ExternalStateOperationFuseExit``;
+    ``version`` is the operation fuse's address."""
+
+    version: FuseAddress
+    asset: ChecksumAddress
+    amount: Amount
+    balanceAccount: ChecksumAddress
+    valueInUnderlying: Amount
+    actionsCount: int
+
+
+#: The parameters of one ExternalState event, by its Solidity names; tell the
+#: shapes apart by ``ExternalStateEvent.name`` or a key (``"signer" in args``).
+ExternalStateEventArgs: TypeAlias = (
+    ExternalStateBigChangeDetectedArgs
+    | ExternalStateCustodianTimestampUpdatedArgs
+    | ExternalStateTotalBalanceUpdatedArgs
+    | ExternalStateUnpausedArgs
+    | ExternalStateAssetRescuedArgs
+    | ExternalStateExecutorArgs
+    | ExternalStateOperationArgs
+)
+
+#: Event name -> the TypedDict its ``args`` is.
+EXTERNAL_STATE_EVENT_ARGS: dict[str, type] = {
+    "ExternalStateBigChangeDetected": ExternalStateBigChangeDetectedArgs,
+    "ExternalStateBalanceFuseLastCustodianTimestampUpdated": (
+        ExternalStateCustodianTimestampUpdatedArgs
+    ),
+    "ExternalStateBalanceFuseLastTotalBalanceUpdated": (
+        ExternalStateTotalBalanceUpdatedArgs
+    ),
+    "ExternalStateUnpaused": ExternalStateUnpausedArgs,
+    "ExternalStateAssetRescued": ExternalStateAssetRescuedArgs,
+    "ExecutorCreated": ExternalStateExecutorArgs,
+    "ExternalStateOperationFuseEnter": ExternalStateOperationArgs,
+    "ExternalStateOperationFuseExit": ExternalStateOperationArgs,
+    "ExternalStateExecutorDeployed": ExternalStateExecutorArgs,
+}
+
 #: topic0 -> spec, for every ExternalState event the vault emits.
 EXTERNAL_STATE_EVENTS: dict[bytes, ExternalStateEventSpec] = {
     spec.topic: spec for spec in EXTERNAL_STATE_EVENT_SPECS
@@ -130,7 +210,7 @@ class ExternalStateEvent:
 
     name: str
     emitter: ChecksumAddress
-    args: dict[str, Any]
+    args: ExternalStateEventArgs
     block_number: int | None = None
     transaction_hash: TxHash | None = None
     log_index: int | None = None
@@ -230,10 +310,15 @@ def decode_external_state_event(  # proctor: ignore[primitives-untyped-dict]
         values = decode([abi_type for abi_type, _ in spec.params], raw)
     except DecodingError as exc:
         raise ExternalStateEventDecodeError(f"{spec.name}: {exc}") from exc
-    args = {
-        name: Web3.to_checksum_address(value) if abi_type == "address" else value
-        for (abi_type, name), value in zip(spec.params, values, strict=True)
-    }
+    # Each value is narrowed to its ABI type; the key set is the spec's, which
+    # EXTERNAL_STATE_EVENT_ARGS mirrors (pinned by the tests).
+    args = cast(
+        ExternalStateEventArgs,
+        {
+            name: abi_value(abi_type, value)
+            for (abi_type, name), value in zip(spec.params, values, strict=True)
+        },
+    )
     address = log.get("address")
     if not isinstance(address, str | bytes):
         raise ExternalStateEventDecodeError(f"{spec.name}: emitter")