ipor-fusion 4.0.0.dev162__tar.gz → 4.0.0.dev164__tar.gz

{ipor_fusion-4.0.0.dev162 → ipor_fusion-4.0.0.dev164}/MIGRATION_4.md

@@ -847,15 +847,31 @@ that only some entries carry is `NotRequired` (a balance fuse's `pct_of_total` a
   `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`.
+- Decoded events are discriminated unions. `ExternalStateEvent` and `HyperCoreEvent`
+  are type aliases over one frozen dataclass per event (`ExternalStateUnpausedEvent`,
+  `HyperCoreDepositFuseEnterEvent`, ...), each with `name: Literal["<event>"]` and
+  `args` typed as that event's TypedDict (`ExternalStateUnpausedArgs`, ...). Comparing
+  `name` narrows the event and its `args`, with no key test:
+
+  ```python
+  for event in external_state_events(receipt):
+      if event.name == "ExternalStateUnpaused":
+          event.args["signer"]  # ChecksumAddress
+  match hc_event:
+      case HyperCoreDepositFuseEnterEvent(args=args):
+          args["evmAsset"]
+  ```
+
+  Without that comparison `event.args["signer"]` does not type-check.
+  `isinstance(x, ExternalStateEvent)` still works (the alias is a union); the events
+  are no longer built positionally (`ExternalStateEvent(...)` is not a class: build
+  the event's own class with keywords, its `name` is preset).
+  `EXTERNAL_STATE_EVENT_CLASSES` / `HYPERCORE_EVENT_CLASSES` map an event name to its
+  class; they replace `EXTERNAL_STATE_EVENT_ARGS` / `HYPERCORE_EVENT_ARGS`, which are
+  removed. An event's args TypedDict is its class's `args` annotation:
+  `typing.get_type_hints(EXTERNAL_STATE_EVENT_CLASSES[name])["args"]`. Values carry nominal types (`Amount`, `MarketId`, `FuseAddress`,
+  `HyperCoreTokenIndex`, `PayloadHash`, web3's `Timestamp`, ...), and
+  `HyperCoreEvent.fuse` is a `FuseAddress | None` on every event.
 - `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.

{ipor_fusion-4.0.0.dev162 → ipor_fusion-4.0.0.dev164}/PKG-INFO

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

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

{ipor_fusion-4.0.0.dev162 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/__init__.py

@@ -316,43 +316,68 @@ from ipor_fusion.fuses import (
     system_address,
 )
 from ipor_fusion.fuses.external_state_events import (
-    EXTERNAL_STATE_EVENT_ARGS,
+    EXTERNAL_STATE_EVENT_CLASSES,
     EXTERNAL_STATE_EVENT_SPECS,
     EXTERNAL_STATE_EVENTS,
     EXTERNAL_STATE_TOPICS,
     ExternalStateAssetRescuedArgs,
+    ExternalStateAssetRescuedEvent,
+    ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent,
+    ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent,
     ExternalStateBigChangeDetectedArgs,
+    ExternalStateBigChangeDetectedEvent,
     ExternalStateCustodianTimestampUpdatedArgs,
     ExternalStateEvent,
     ExternalStateEventArgs,
     ExternalStateEventSpec,
     ExternalStateExecutorArgs,
+    ExternalStateExecutorCreatedEvent,
+    ExternalStateExecutorDeployedEvent,
     ExternalStateOperationArgs,
+    ExternalStateOperationFuseEnterEvent,
+    ExternalStateOperationFuseExitEvent,
     ExternalStateTotalBalanceUpdatedArgs,
     ExternalStateUnpausedArgs,
+    ExternalStateUnpausedEvent,
     decode_external_state_event,
     external_state_event_name,
     external_state_events,
 )
 from ipor_fusion.fuses.hypercore_events import (
-    HYPERCORE_EVENT_ARGS,
+    HYPERCORE_EVENT_CLASSES,
     HyperCoreActionEnqueuedArgs,
+    HyperCoreActionEnqueuedEvent,
     HyperCoreActionSettledArgs,
+    HyperCoreActionSettledEvent,
     HyperCoreBuilderFeeFuseEnterArgs,
+    HyperCoreBuilderFeeFuseEnterEvent,
     HyperCoreCancelByCloidArgs,
     HyperCoreCancelByOidArgs,
+    HyperCoreCancelFuseCancelByCloidEvent,
+    HyperCoreCancelFuseCancelByOidEvent,
     HyperCoreDepositFuseEnterArgs,
+    HyperCoreDepositFuseEnterEvent,
     HyperCoreEventArgs,
     HyperCoreMarginFuseEnterArgs,
+    HyperCoreMarginFuseEnterEvent,
     HyperCoreObserverSetChangedArgs,
+    HyperCoreObserverSetChangedEvent,
     HyperCoreObserverSetProposedArgs,
+    HyperCoreObserverSetProposedEvent,
     HyperCoreOrderFuseEnterArgs,
+    HyperCoreOrderFuseEnterEvent,
     HyperCoreRecoveryExecutedArgs,
+    HyperCoreRecoveryExecutedEvent,
     HyperCoreRecoveryProposedArgs,
+    HyperCoreRecoveryProposedEvent,
     HyperCoreReportedActionSettledArgs,
+    HyperCoreReportedActionSettledEvent,
     HyperCoreReportSubmittedArgs,
+    HyperCoreReportSubmittedEvent,
     HyperCoreSendFuseSendAssetArgs,
+    HyperCoreSendFuseSendAssetEvent,
     HyperCoreSendFuseSpotSendArgs,
+    HyperCoreSendFuseSpotSendEvent,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.market_info import (
@@ -591,7 +616,16 @@ __all__ = [
     "EXTERNAL_STATE_EVENTS",
     "EXTERNAL_STATE_TOPICS",
     "ExternalStateEvent",
-    "EXTERNAL_STATE_EVENT_ARGS",
+    "EXTERNAL_STATE_EVENT_CLASSES",
+    "ExternalStateBigChangeDetectedEvent",
+    "ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent",
+    "ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent",
+    "ExternalStateUnpausedEvent",
+    "ExternalStateAssetRescuedEvent",
+    "ExternalStateExecutorCreatedEvent",
+    "ExternalStateOperationFuseEnterEvent",
+    "ExternalStateOperationFuseExitEvent",
+    "ExternalStateExecutorDeployedEvent",
     "ExternalStateAssetRescuedArgs",
     "ExternalStateBigChangeDetectedArgs",
     "ExternalStateCustodianTimestampUpdatedArgs",
@@ -608,7 +642,23 @@ __all__ = [
     "HYPERCORE_EVENTS",
     "HYPERCORE_EVENT_SPECS",
     "HyperCoreEvent",
-    "HYPERCORE_EVENT_ARGS",
+    "HYPERCORE_EVENT_CLASSES",
+    "HyperCoreDepositFuseEnterEvent",
+    "HyperCoreMarginFuseEnterEvent",
+    "HyperCoreSendFuseSpotSendEvent",
+    "HyperCoreSendFuseSendAssetEvent",
+    "HyperCoreOrderFuseEnterEvent",
+    "HyperCoreCancelFuseCancelByOidEvent",
+    "HyperCoreCancelFuseCancelByCloidEvent",
+    "HyperCoreBuilderFeeFuseEnterEvent",
+    "HyperCoreActionEnqueuedEvent",
+    "HyperCoreActionSettledEvent",
+    "HyperCoreReportedActionSettledEvent",
+    "HyperCoreReportSubmittedEvent",
+    "HyperCoreObserverSetProposedEvent",
+    "HyperCoreObserverSetChangedEvent",
+    "HyperCoreRecoveryProposedEvent",
+    "HyperCoreRecoveryExecutedEvent",
     "HyperCoreActionEnqueuedArgs",
     "HyperCoreActionSettledArgs",
     "HyperCoreBuilderFeeFuseEnterArgs",

{ipor_fusion-4.0.0.dev162 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/fuses/__init__.py

@@ -50,28 +50,44 @@ from ipor_fusion.fuses.hypercore import (
     system_address,
 )
 from ipor_fusion.fuses.hypercore_events import (
-    HYPERCORE_EVENT_ARGS,
+    HYPERCORE_EVENT_CLASSES,
     HYPERCORE_EVENT_SPECS,
     HYPERCORE_EVENTS,
     HyperCoreActionEnqueuedArgs,
+    HyperCoreActionEnqueuedEvent,
     HyperCoreActionSettledArgs,
+    HyperCoreActionSettledEvent,
     HyperCoreBuilderFeeFuseEnterArgs,
+    HyperCoreBuilderFeeFuseEnterEvent,
     HyperCoreCancelByCloidArgs,
     HyperCoreCancelByOidArgs,
+    HyperCoreCancelFuseCancelByCloidEvent,
+    HyperCoreCancelFuseCancelByOidEvent,
     HyperCoreDepositFuseEnterArgs,
+    HyperCoreDepositFuseEnterEvent,
     HyperCoreEvent,
     HyperCoreEventArgs,
     HyperCoreEventSpec,
     HyperCoreMarginFuseEnterArgs,
+    HyperCoreMarginFuseEnterEvent,
     HyperCoreObserverSetChangedArgs,
+    HyperCoreObserverSetChangedEvent,
     HyperCoreObserverSetProposedArgs,
+    HyperCoreObserverSetProposedEvent,
     HyperCoreOrderFuseEnterArgs,
+    HyperCoreOrderFuseEnterEvent,
     HyperCoreRecoveryExecutedArgs,
+    HyperCoreRecoveryExecutedEvent,
     HyperCoreRecoveryProposedArgs,
+    HyperCoreRecoveryProposedEvent,
     HyperCoreReportedActionSettledArgs,
+    HyperCoreReportedActionSettledEvent,
     HyperCoreReportSubmittedArgs,
+    HyperCoreReportSubmittedEvent,
     HyperCoreSendFuseSendAssetArgs,
+    HyperCoreSendFuseSendAssetEvent,
     HyperCoreSendFuseSpotSendArgs,
+    HyperCoreSendFuseSpotSendEvent,
     decode_hypercore_event,
     find_hypercore_events,
     hypercore_event_name,
@@ -112,7 +128,23 @@ __all__ = [
     "HYPERCORE_EVENTS",
     "HYPERCORE_EVENT_SPECS",
     "HyperCoreEvent",
-    "HYPERCORE_EVENT_ARGS",
+    "HYPERCORE_EVENT_CLASSES",
+    "HyperCoreDepositFuseEnterEvent",
+    "HyperCoreMarginFuseEnterEvent",
+    "HyperCoreSendFuseSpotSendEvent",
+    "HyperCoreSendFuseSendAssetEvent",
+    "HyperCoreOrderFuseEnterEvent",
+    "HyperCoreCancelFuseCancelByOidEvent",
+    "HyperCoreCancelFuseCancelByCloidEvent",
+    "HyperCoreBuilderFeeFuseEnterEvent",
+    "HyperCoreActionEnqueuedEvent",
+    "HyperCoreActionSettledEvent",
+    "HyperCoreReportedActionSettledEvent",
+    "HyperCoreReportSubmittedEvent",
+    "HyperCoreObserverSetProposedEvent",
+    "HyperCoreObserverSetChangedEvent",
+    "HyperCoreRecoveryProposedEvent",
+    "HyperCoreRecoveryExecutedEvent",
     "HyperCoreActionEnqueuedArgs",
     "HyperCoreActionSettledArgs",
     "HyperCoreBuilderFeeFuseEnterArgs",

{ipor_fusion-4.0.0.dev162 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/fuses/external_state_events.py

@@ -22,9 +22,9 @@ raises ``ExternalStateEventDecodeError``.
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass
-from typing import TypeAlias, TypedDict, cast
+from typing import Literal, TypeAlias, TypedDict, cast
 
 from eth_abi import decode
 from eth_abi.exceptions import DecodingError
@@ -165,8 +165,7 @@ class ExternalStateOperationArgs(TypedDict):
     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``).
+#: The parameters of one ExternalState event, by its Solidity names.
 ExternalStateEventArgs: TypeAlias = (
     ExternalStateBigChangeDetectedArgs
     | ExternalStateCustodianTimestampUpdatedArgs
@@ -177,23 +176,6 @@ ExternalStateEventArgs: TypeAlias = (
     | 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
@@ -204,9 +186,10 @@ EXTERNAL_STATE_TOPICS: tuple[str, ...] = tuple(
 )
 
 
-@dataclass(frozen=True, slots=True)
-class ExternalStateEvent:
-    """One decoded ExternalState log with its raw identity."""
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _ExternalStateEventBase:
+    """One decoded ExternalState log with its raw identity; each event is a
+    subclass that pins ``name`` to a literal and ``args`` to its shape."""
 
     name: str
     emitter: ChecksumAddress
@@ -216,6 +199,94 @@ class ExternalStateEvent:
     log_index: int | None = None
 
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateBigChangeDetectedEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateBigChangeDetected"] = "ExternalStateBigChangeDetected"
+    args: ExternalStateBigChangeDetectedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent(
+    _ExternalStateEventBase
+):
+    name: Literal["ExternalStateBalanceFuseLastCustodianTimestampUpdated"] = (
+        "ExternalStateBalanceFuseLastCustodianTimestampUpdated"
+    )
+    args: ExternalStateCustodianTimestampUpdatedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateBalanceFuseLastTotalBalanceUpdated"] = (
+        "ExternalStateBalanceFuseLastTotalBalanceUpdated"
+    )
+    args: ExternalStateTotalBalanceUpdatedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateUnpausedEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateUnpaused"] = "ExternalStateUnpaused"
+    args: ExternalStateUnpausedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateAssetRescuedEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateAssetRescued"] = "ExternalStateAssetRescued"
+    args: ExternalStateAssetRescuedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateExecutorCreatedEvent(_ExternalStateEventBase):
+    name: Literal["ExecutorCreated"] = "ExecutorCreated"
+    args: ExternalStateExecutorArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateOperationFuseEnterEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateOperationFuseEnter"] = "ExternalStateOperationFuseEnter"
+    args: ExternalStateOperationArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateOperationFuseExitEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateOperationFuseExit"] = "ExternalStateOperationFuseExit"
+    args: ExternalStateOperationArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalStateExecutorDeployedEvent(_ExternalStateEventBase):
+    name: Literal["ExternalStateExecutorDeployed"] = "ExternalStateExecutorDeployed"
+    args: ExternalStateExecutorArgs
+
+
+#: One decoded ExternalState event; ``event.name == "..."`` narrows it, and
+#: its ``args``, to that event's class.
+ExternalStateEvent: TypeAlias = (
+    ExternalStateBigChangeDetectedEvent
+    | ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent
+    | ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent
+    | ExternalStateUnpausedEvent
+    | ExternalStateAssetRescuedEvent
+    | ExternalStateExecutorCreatedEvent
+    | ExternalStateOperationFuseEnterEvent
+    | ExternalStateOperationFuseExitEvent
+    | ExternalStateExecutorDeployedEvent
+)
+
+#: Event name -> its event class (``args`` annotation: its TypedDict).
+EXTERNAL_STATE_EVENT_CLASSES: dict[str, type[ExternalStateEvent]] = {
+    "ExternalStateBigChangeDetected": ExternalStateBigChangeDetectedEvent,
+    "ExternalStateBalanceFuseLastCustodianTimestampUpdated": ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent,
+    "ExternalStateBalanceFuseLastTotalBalanceUpdated": ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent,
+    "ExternalStateUnpaused": ExternalStateUnpausedEvent,
+    "ExternalStateAssetRescued": ExternalStateAssetRescuedEvent,
+    "ExecutorCreated": ExternalStateExecutorCreatedEvent,
+    "ExternalStateOperationFuseEnter": ExternalStateOperationFuseEnterEvent,
+    "ExternalStateOperationFuseExit": ExternalStateOperationFuseExitEvent,
+    "ExternalStateExecutorDeployed": ExternalStateExecutorDeployedEvent,
+}
+
+
 def _as_bytes(value: object, what: str) -> bytes:
     """Raw log bytes from what a node or an indexer serves: bytes-like
     (bytes, bytearray, HexBytes) or ``0x``-prefixed hex text. Anything else —
@@ -310,15 +381,11 @@ 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
-    # 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)
-        },
-    )
+    # Each value is narrowed to its ABI type.
+    args = {
+        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")
@@ -326,8 +393,12 @@ def decode_external_state_event(  # proctor: ignore[primitives-untyped-dict]
         emitter = Web3.to_checksum_address(address)
     except ValueError as exc:
         raise ExternalStateEventDecodeError(f"{spec.name}: emitter") from exc
-    return ExternalStateEvent(
-        name=spec.name,
+    # The class's args TypedDict is the spec's shape (pinned by the tests), so
+    # the decoded dict is that class's args.
+    event_class = cast(
+        Callable[..., ExternalStateEvent], EXTERNAL_STATE_EVENT_CLASSES[spec.name]
+    )
+    return event_class(
         emitter=emitter,
         args=args,
         block_number=_as_quantity(log.get("blockNumber"), "blockNumber"),

{ipor_fusion-4.0.0.dev162 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/fuses/hypercore_events.py

@@ -14,8 +14,9 @@ Status: preview, not production. The contracts behind it are under active develo
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
-from typing import TypeAlias, TypedDict, cast
+from typing import Literal, TypeAlias, TypedDict, cast
 
 from eth_abi import decode
 from eth_typing import ChecksumAddress
@@ -287,8 +288,7 @@ class HyperCoreRecoveryExecutedArgs(TypedDict):
     reasonHash: bytes
 
 
-#: The parameters of one HyperCore event; tell the shapes apart by
-#: ``HyperCoreEvent.name`` or a key (``"evmAsset" in args``).
+#: The parameters of one HyperCore event.
 HyperCoreEventArgs: TypeAlias = (
     HyperCoreDepositFuseEnterArgs
     | HyperCoreMarginFuseEnterArgs
@@ -308,26 +308,6 @@ HyperCoreEventArgs: TypeAlias = (
     | HyperCoreRecoveryExecutedArgs
 )
 
-#: Event name -> the TypedDict its ``args`` is.
-HYPERCORE_EVENT_ARGS: dict[str, type] = {
-    "HyperCoreDepositFuseEnter": HyperCoreDepositFuseEnterArgs,
-    "HyperCoreMarginFuseEnter": HyperCoreMarginFuseEnterArgs,
-    "HyperCoreSendFuseSpotSend": HyperCoreSendFuseSpotSendArgs,
-    "HyperCoreSendFuseSendAsset": HyperCoreSendFuseSendAssetArgs,
-    "HyperCoreOrderFuseEnter": HyperCoreOrderFuseEnterArgs,
-    "HyperCoreCancelFuseCancelByOid": HyperCoreCancelByOidArgs,
-    "HyperCoreCancelFuseCancelByCloid": HyperCoreCancelByCloidArgs,
-    "HyperCoreBuilderFeeFuseEnter": HyperCoreBuilderFeeFuseEnterArgs,
-    "HyperCoreActionEnqueued": HyperCoreActionEnqueuedArgs,
-    "HyperCoreActionSettled": HyperCoreActionSettledArgs,
-    "HyperCoreReportedActionSettled": HyperCoreReportedActionSettledArgs,
-    "ReportSubmitted": HyperCoreReportSubmittedArgs,
-    "ObserverSetProposed": HyperCoreObserverSetProposedArgs,
-    "ObserverSetChanged": HyperCoreObserverSetChangedArgs,
-    "RecoveryProposed": HyperCoreRecoveryProposedArgs,
-    "RecoveryExecuted": HyperCoreRecoveryExecutedArgs,
-}
-
 #: topic0 -> spec, for every HyperCore event.
 HYPERCORE_EVENTS: dict[bytes, HyperCoreEventSpec] = {
     spec.topic: spec for spec in HYPERCORE_EVENT_SPECS
@@ -340,9 +320,10 @@ HYPERCORE_FUSE_EVENTS = frozenset(
 )
 
 
-@dataclass(frozen=True, slots=True)
-class HyperCoreEvent:
-    """One decoded HyperCore log."""
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _HyperCoreEventBase:
+    """One decoded HyperCore log; each event is a subclass that pins ``name``
+    to a literal and ``args`` to its shape."""
 
     name: str
     emitter: ChecksumAddress
@@ -357,6 +338,146 @@ class HyperCoreEvent:
         return self.args["version"]
 
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreDepositFuseEnterEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreDepositFuseEnter"] = "HyperCoreDepositFuseEnter"
+    args: HyperCoreDepositFuseEnterArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreMarginFuseEnterEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreMarginFuseEnter"] = "HyperCoreMarginFuseEnter"
+    args: HyperCoreMarginFuseEnterArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreSendFuseSpotSendEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreSendFuseSpotSend"] = "HyperCoreSendFuseSpotSend"
+    args: HyperCoreSendFuseSpotSendArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreSendFuseSendAssetEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreSendFuseSendAsset"] = "HyperCoreSendFuseSendAsset"
+    args: HyperCoreSendFuseSendAssetArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreOrderFuseEnterEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreOrderFuseEnter"] = "HyperCoreOrderFuseEnter"
+    args: HyperCoreOrderFuseEnterArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreCancelFuseCancelByOidEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreCancelFuseCancelByOid"] = "HyperCoreCancelFuseCancelByOid"
+    args: HyperCoreCancelByOidArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreCancelFuseCancelByCloidEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreCancelFuseCancelByCloid"] = (
+        "HyperCoreCancelFuseCancelByCloid"
+    )
+    args: HyperCoreCancelByCloidArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreBuilderFeeFuseEnterEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreBuilderFeeFuseEnter"] = "HyperCoreBuilderFeeFuseEnter"
+    args: HyperCoreBuilderFeeFuseEnterArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreActionEnqueuedEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreActionEnqueued"] = "HyperCoreActionEnqueued"
+    args: HyperCoreActionEnqueuedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreActionSettledEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreActionSettled"] = "HyperCoreActionSettled"
+    args: HyperCoreActionSettledArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreReportedActionSettledEvent(_HyperCoreEventBase):
+    name: Literal["HyperCoreReportedActionSettled"] = "HyperCoreReportedActionSettled"
+    args: HyperCoreReportedActionSettledArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreReportSubmittedEvent(_HyperCoreEventBase):
+    name: Literal["ReportSubmitted"] = "ReportSubmitted"
+    args: HyperCoreReportSubmittedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreObserverSetProposedEvent(_HyperCoreEventBase):
+    name: Literal["ObserverSetProposed"] = "ObserverSetProposed"
+    args: HyperCoreObserverSetProposedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreObserverSetChangedEvent(_HyperCoreEventBase):
+    name: Literal["ObserverSetChanged"] = "ObserverSetChanged"
+    args: HyperCoreObserverSetChangedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreRecoveryProposedEvent(_HyperCoreEventBase):
+    name: Literal["RecoveryProposed"] = "RecoveryProposed"
+    args: HyperCoreRecoveryProposedArgs
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HyperCoreRecoveryExecutedEvent(_HyperCoreEventBase):
+    name: Literal["RecoveryExecuted"] = "RecoveryExecuted"
+    args: HyperCoreRecoveryExecutedArgs
+
+
+#: One decoded HyperCore event; ``event.name == "..."`` narrows it, and its
+#: ``args``, to that event's class.
+HyperCoreEvent: TypeAlias = (
+    HyperCoreDepositFuseEnterEvent
+    | HyperCoreMarginFuseEnterEvent
+    | HyperCoreSendFuseSpotSendEvent
+    | HyperCoreSendFuseSendAssetEvent
+    | HyperCoreOrderFuseEnterEvent
+    | HyperCoreCancelFuseCancelByOidEvent
+    | HyperCoreCancelFuseCancelByCloidEvent
+    | HyperCoreBuilderFeeFuseEnterEvent
+    | HyperCoreActionEnqueuedEvent
+    | HyperCoreActionSettledEvent
+    | HyperCoreReportedActionSettledEvent
+    | HyperCoreReportSubmittedEvent
+    | HyperCoreObserverSetProposedEvent
+    | HyperCoreObserverSetChangedEvent
+    | HyperCoreRecoveryProposedEvent
+    | HyperCoreRecoveryExecutedEvent
+)
+
+#: Event name -> its event class (``args`` annotation: its TypedDict).
+HYPERCORE_EVENT_CLASSES: dict[str, type[HyperCoreEvent]] = {
+    "HyperCoreDepositFuseEnter": HyperCoreDepositFuseEnterEvent,
+    "HyperCoreMarginFuseEnter": HyperCoreMarginFuseEnterEvent,
+    "HyperCoreSendFuseSpotSend": HyperCoreSendFuseSpotSendEvent,
+    "HyperCoreSendFuseSendAsset": HyperCoreSendFuseSendAssetEvent,
+    "HyperCoreOrderFuseEnter": HyperCoreOrderFuseEnterEvent,
+    "HyperCoreCancelFuseCancelByOid": HyperCoreCancelFuseCancelByOidEvent,
+    "HyperCoreCancelFuseCancelByCloid": HyperCoreCancelFuseCancelByCloidEvent,
+    "HyperCoreBuilderFeeFuseEnter": HyperCoreBuilderFeeFuseEnterEvent,
+    "HyperCoreActionEnqueued": HyperCoreActionEnqueuedEvent,
+    "HyperCoreActionSettled": HyperCoreActionSettledEvent,
+    "HyperCoreReportedActionSettled": HyperCoreReportedActionSettledEvent,
+    "ReportSubmitted": HyperCoreReportSubmittedEvent,
+    "ObserverSetProposed": HyperCoreObserverSetProposedEvent,
+    "ObserverSetChanged": HyperCoreObserverSetChangedEvent,
+    "RecoveryProposed": HyperCoreRecoveryProposedEvent,
+    "RecoveryExecuted": HyperCoreRecoveryExecutedEvent,
+}
+
+
 def hypercore_event_name(topic: bytes | str) -> str | None:
     """The HyperCore event behind ``topic0``, or None for any other log."""
     raw = (
@@ -377,17 +498,17 @@ def decode_hypercore_event(log: LogReceipt) -> HyperCoreEvent | None:
     if spec is None:
         return None
     values = decode([abi_type for abi_type, _ in spec.params], bytes(log["data"]))
-    # Each value is narrowed to its ABI type; the key set is the spec's, which
-    # HYPERCORE_EVENT_ARGS mirrors (pinned by the tests).
-    args = cast(
-        HyperCoreEventArgs,
-        {
-            name: abi_value(abi_type, value)
-            for (abi_type, name), value in zip(spec.params, values, strict=True)
-        },
+    # Each value is narrowed to its ABI type.
+    args = {
+        name: abi_value(abi_type, value)
+        for (abi_type, name), value in zip(spec.params, values, strict=True)
+    }
+    # The class's args TypedDict is the spec's shape (pinned by the tests), so
+    # the decoded dict is that class's args.
+    event_class = cast(
+        Callable[..., HyperCoreEvent], HYPERCORE_EVENT_CLASSES[spec.name]
     )
-    return HyperCoreEvent(
-        name=spec.name,
+    return event_class(
         emitter=Web3.to_checksum_address(log["address"]),
         args=args,
         log_index=log.get("logIndex"),