ipor-fusion 4.0.0.dev30__tar.gz → 4.0.0.dev35__tar.gz

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/AGENTS.md

@@ -285,7 +285,9 @@ or examples.
   `MarketId`, ...) name the unit, and nothing scales by decimals.
 - Ids and addresses are nominal in every signature: `ChainId`, `MarketId` (each
   `IporFusionMarkets` member is one), `RoleId | Roles`, `ChecksumAddress`;
-  `HexAddress` only for the lowercase addresses decoded from substrates. Raw input
+  `HexAddress` only for the lowercase addresses decoded from substrates;
+  `MorphoBlueMarketId` is always `0x` + 64 lowercase hex, built by
+  `parse_morpho_market_id`. Raw input
   is parsed once at the boundary (click param types, MCP tools, the user config).
   `src/`, `examples/` and `tests/typed_client/` are checked with
   `reportArgumentType` on, so a bare `int`/`str` passed for one fails pyright; the

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/PKG-INFO

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

@@ -100,12 +100,21 @@ from ipor_fusion.fuses import (
 from ipor_fusion.fuses.hypercore import (
     SPOT_DEX,
     USDC_SYSTEM_ADDRESS,
+    USDC_TOKEN_INDEX,
     TimeInForce,
     read_index_of,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.readers.hypercore import HyperCoreReader
-from ipor_fusion.types import Amount, ChainId, MarketId, Period, Shares
+from ipor_fusion.types import (
+    Amount,
+    ChainId,
+    HyperCoreAsset,
+    HyperCoreClientOrderId,
+    MarketId,
+    Period,
+    Shares,
+)
 
 log = logging.getLogger("composed_hypercore_flow_arbitrum_hyperevm")
 
@@ -181,7 +190,7 @@ BRIDGE_LATENCY = Period(2 * 60)
 # ── The trade the live cycle ran ─────────────────────────────────────────────
 # xyz is HIP-3 perp dex 1; xyz:NVDA is action asset 100_000 + 1 * 10_000 + 2.
 XYZ_DEX = 1
-XYZ_NVDA_ASSET = 110_002
+XYZ_NVDA_ASSET = HyperCoreAsset(110_002)
 # Core amounts are Core wei: 8 decimals for USDC; sizes carry 8 implied
 # decimals too (0.05 NVDA = 5_000_000), prices 8 implied decimals.
 CORE_WEI = 10**8
@@ -410,9 +419,9 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
     state = read_hypercore_vault_state(ctx, HYPERCORE_VAULT, HYPERCORE_BALANCE_FUSE)
     reader = HyperCoreReader(ctx)
     pending = bool(state.pending and state.pending.pending)
-    spot = reader.spot_balance(HYPERCORE_VAULT, 0).call()
+    spot = reader.spot_balance(HYPERCORE_VAULT, USDC_TOKEN_INDEX).call()
     spot_available = _available_spot_wei(spot.total, spot.hold)
-    usdc_info = reader.token_info(0).call()
+    usdc_info = reader.token_info(USDC_TOKEN_INDEX).call()
     evm_step = 10 ** max(int(usdc_info.wei_decimals) - 6, 0)
     xyz_equity_usd6 = int(
         reader.account_margin_summary(XYZ_DEX, HYPERCORE_VAULT).call().account_value
@@ -454,7 +463,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
             web3_hype,
             vault,
             "bridge_to_core",
-            deposit_fuse.enter(token_index=0, amount=BRIDGE_AMOUNT_USDC),
+            deposit_fuse.enter(token_index=USDC_TOKEN_INDEX, amount=BRIDGE_AMOUNT_USDC),
             override=override,
             note="14 USDC EVM -> Core spot through the CoreDepositWallet; vault USDC balance overridden for the preview",
         )
@@ -472,7 +481,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
                     destination=HYPERCORE_VAULT,
                     source_dex=SPOT_DEX,
                     destination_dex=XYZ_DEX,
-                    token_index=0,
+                    token_index=USDC_TOKEN_INDEX,
                     amount_wei=to_dex,
                 ),
                 override=None,
@@ -511,7 +520,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
                 limit_px=limit_buy,
                 sz=ORDER_SIZE,
                 tif=TimeInForce.IOC,
-                cloid=1,
+                cloid=HyperCoreClientOrderId(1),
             ),
             override=None,
             note=f"buy 0.05 xyz:NVDA, limit {limit_buy} (mark +1 %), notional {notional_usd6} USD6 under the cap {max_notional_usd6}",
@@ -528,7 +537,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
                 limit_px=limit_sell,
                 sz=ORDER_SIZE,
                 tif=TimeInForce.IOC,
-                cloid=2,
+                cloid=HyperCoreClientOrderId(2),
                 reduce_only=True,
             ),
             override=None,
@@ -551,7 +560,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
                     destination=HYPERCORE_VAULT,
                     source_dex=XYZ_DEX,
                     destination_dex=SPOT_DEX,
-                    token_index=0,
+                    token_index=USDC_TOKEN_INDEX,
                     amount_wei=from_dex,
                 ),
                 override=None,
@@ -586,7 +595,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
                     destination=Web3.to_checksum_address(USDC_SYSTEM_ADDRESS),
                     source_dex=SPOT_DEX,
                     destination_dex=SPOT_DEX,
-                    token_index=0,
+                    token_index=USDC_TOKEN_INDEX,
                     amount_wei=to_evm,
                 ),
                 override=None,

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/examples/external_state_margin_leg_base.py

@@ -95,7 +95,7 @@ from ipor_fusion.core import FusionFactory
 from ipor_fusion.core.fusion_factory import FusionInstance
 from ipor_fusion.fuses import ExternalStateOperationFuse
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import Amount, ChainId, MarketId, Period, Shares
+from ipor_fusion.types import Amount, ChainId, MarketId, Period, ProposalHash, Shares
 
 log = logging.getLogger("external_state_margin_leg_base")
 
@@ -288,7 +288,7 @@ RELEASE_OFFSET = REQUEST_OFFSET + RELEASE_DELAY
 DEMO_OFFSET = RELEASE_OFFSET + DEMO_DELAY
 
 # A hash that is deliberately not the pending proposal's, for the rejection demo.
-WRONG_PROPOSAL_HASH = b"\xde\xad" + b"\x00" * 30
+WRONG_PROPOSAL_HASH = ProposalHash(b"\xde\xad" + b"\x00" * 30)
 
 # ── Derived from deployed signatures (NOT tunable) ───────────────────────────
 # Each of these is keccak over a signature the deployed contracts declare.

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/pyproject.toml

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

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/src/ipor_fusion/__init__.py

@@ -318,16 +318,24 @@ from ipor_fusion.types import (
     Decimals,
     DeploymentRequestId,
     Fee,
+    HyperCoreActionId,
+    HyperCoreAsset,
+    HyperCoreClientOrderId,
+    HyperCoreOrderId,
+    HyperCoreTokenIndex,
     Liquidity,
     MappingStatus,
+    MarginTableId,
     MarketId,
     MessageId,
     MorphoBlueMarketId,
     NodeStatus,
     OperationId,
+    PayloadHash,
     Period,
     PositionSetHash,
     Price,
+    ProposalHash,
     ProposalId,
     ReturnRequestId,
     RoleId,
@@ -336,6 +344,8 @@ from ipor_fusion.types import (
     Tick,
     TokenId,
     TransferId,
+    TxHash,
+    parse_morpho_market_id,
 )
 from ipor_fusion.validation import (
     Erc20Holding,
@@ -605,6 +615,16 @@ __all__ = [
     "RoleId",
     "ChainId",
     "MorphoBlueMarketId",
+    "HyperCoreActionId",
+    "HyperCoreAsset",
+    "HyperCoreClientOrderId",
+    "HyperCoreOrderId",
+    "HyperCoreTokenIndex",
+    "MarginTableId",
+    "PayloadHash",
+    "ProposalHash",
+    "TxHash",
+    "parse_morpho_market_id",
     "AssetId",
     "CommandId",
     "DeploymentRequestId",

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/src/ipor_fusion/cli/market_cmd.py

@@ -42,7 +42,7 @@ from ipor_fusion.readers.morpho import (
     MorphoReader,
     morpho_blue_address,
 )
-from ipor_fusion.types import ChainId, MorphoBlueMarketId
+from ipor_fusion.types import ChainId, MorphoBlueMarketId, parse_morpho_market_id
 from ipor_fusion.vault_info import BLOCK_EXPLORER_URLS
 
 
@@ -54,12 +54,10 @@ class MarketIdType(click.ParamType):
     def convert(self, value, param, ctx):  # type: ignore[override]
         if not isinstance(value, str):
             self.fail(f"expected string, got {type(value).__name__}", param, ctx)
-        raw = value.strip().removeprefix("0x").removeprefix("0X")
-        if len(raw) != 64 or not all(c in "0123456789abcdefABCDEF" for c in raw):
-            self.fail(
-                f"invalid Morpho market ID (expected 32-byte hex): {value}", param, ctx
-            )
-        return raw.lower()
+        try:
+            return parse_morpho_market_id(value)
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
 
 
 MARKET_ID = MarketIdType()
@@ -106,7 +104,7 @@ def market() -> None:
     help="Emit machine-readable JSON instead of a table.",
 )
 def morpho_blue(
-    market_id: str,
+    market_id: MorphoBlueMarketId,
     chain_id: ChainId,
     block: int | None,
     no_api: bool,
@@ -127,7 +125,7 @@ def morpho_blue(
     if block is not None:
         ctx.default_block = block
     reader = MorphoReader(ctx, morpho_blue_address(chain_id))
-    mid = MorphoBlueMarketId(market_id)
+    mid = market_id
     params, state = reader.require_market(mid)
     rates = reader.rates_from(state, params)
 
@@ -171,7 +169,7 @@ def morpho_blue(
 
 
 def _print_market(
-    market_id: str,
+    market_id: MorphoBlueMarketId,
     chain_id: ChainId,
     params: MorphoMarketParams,
     state: MorphoMarket,
@@ -181,11 +179,11 @@ def _print_market(
     chain_name = CHAIN_NAMES.get(chain_id, str(chain_id))
     explorer = BLOCK_EXPLORER_URLS.get(chain_id, "")
     liquidity = state.total_supply_assets - state.total_borrow_assets
-    click.secho(f"Morpho Blue market 0x{market_id}", bold=True)
+    click.secho(f"Morpho Blue market {market_id}", bold=True)
     click.echo(f"  Chain:           {chain_name} (id {chain_id})")
     if explorer:
         click.echo(
-            f"  App:             https://app.morpho.org/{chain_name}/market/0x{market_id}"
+            f"  App:             https://app.morpho.org/{chain_name}/market/{market_id}"
         )
     click.echo(f"  Loan token:      {params.loan_token}")
     click.echo(f"  Collateral:      {params.collateral_token}")
@@ -332,7 +330,7 @@ def _print_reallocate_hint(params: MorphoMarketParams) -> None:
 @click.option(
     "--market",
     "market_filter",
-    type=str,
+    type=MARKET_ID,
     default=None,
     help="Filter caps/allocations to a single Morpho Blue market ID.",
 )
@@ -346,7 +344,7 @@ def _print_reallocate_hint(params: MorphoMarketParams) -> None:
 def meta_morpho(
     vault_address: ChecksumAddress,
     chain_id: ChainId,
-    market_filter: str | None,
+    market_filter: MorphoBlueMarketId | None,
     json_output: bool,
 ) -> None:
     """Inspect a MetaMorpho V1 or Morpho Vault V2 by address.
@@ -361,22 +359,18 @@ def meta_morpho(
     except MorphoApiError as exc:
         raise click.UsageError(str(exc)) from exc
 
-    market_filter_norm = (
-        ("0x" + market_filter.removeprefix("0x").lower()) if market_filter else None
-    )
-
     if json_output:
         click.echo(json_lib.dumps(build_meta_morpho_json(info, chain_id), indent=2))
         return
 
     if isinstance(info, VaultV2Info):
-        _print_vault_v2(info, chain_id, market_filter_norm)
+        _print_vault_v2(info, chain_id, market_filter)
     else:
-        _print_vault_v1(info, chain_id, market_filter_norm)
+        _print_vault_v1(info, chain_id, market_filter)
 
 
 def _print_vault_v2(
-    vault: VaultV2Info, chain_id: ChainId, market_filter: str | None
+    vault: VaultV2Info, chain_id: ChainId, market_filter: MorphoBlueMarketId | None
 ) -> None:
     chain_name = CHAIN_NAMES.get(chain_id, str(chain_id))
     click.secho(f"Morpho Vault V2 — {vault.name} ({vault.symbol})", bold=True)
@@ -433,9 +427,7 @@ def _print_vault_v2(
     market_caps = [c for c in vault.caps if c.cap_type == "MarketV1"]
     other_caps = [c for c in vault.caps if c.cap_type != "MarketV1"]
     if market_filter:
-        market_caps = [
-            c for c in market_caps if (c.market_id or "").lower() == market_filter
-        ]
+        market_caps = [c for c in market_caps if c.market_id == market_filter]
 
     click.secho(f"Morpho Blue market caps ({len(market_caps)}):", bold=True)
     _print_market_caps(market_caps, vault.asset_symbol, vault.asset_decimals)
@@ -508,7 +500,7 @@ def _print_other_caps(
 
 
 def _print_vault_v1(
-    vault: VaultV1Info, chain_id: ChainId, market_filter: str | None
+    vault: VaultV1Info, chain_id: ChainId, market_filter: MorphoBlueMarketId | None
 ) -> None:
     chain_name = CHAIN_NAMES.get(chain_id, str(chain_id))
     public_allocator = PUBLIC_ALLOCATOR_ADDRESSES.get(chain_id)
@@ -552,7 +544,7 @@ def _print_vault_v1(
 
     allocations = vault.allocations
     if market_filter:
-        allocations = [a for a in allocations if a.market_id.lower() == market_filter]
+        allocations = [a for a in allocations if a.market_id == market_filter]
     click.secho(f"Allocations ({len(allocations)}):", bold=True)
     if not allocations:
         click.echo("  (none)")

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/src/ipor_fusion/core/context.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 
 from eth_account import Account
-from eth_typing import ChecksumAddress
+from eth_typing import ChecksumAddress, HexStr
 from hexbytes import HexBytes
 from requests import ConnectionError as RequestsConnectionError
 from requests import HTTPError, Timeout
@@ -25,7 +25,7 @@ from ipor_fusion.core.logs import (
     get_logs_adaptive,
 )
 from ipor_fusion.errors import LogSourceUnavailable, TransactionError, get_revert_reason
-from ipor_fusion.types import ChainId
+from ipor_fusion.types import ChainId, TxHash
 
 # web3 retries every allowlisted method on any HTTP error, a 400 included;
 # a too-wide eth_getLogs answered with HTTP 400/413 or a query timeout would be
@@ -229,7 +229,7 @@ class Web3Context:
             reason = get_revert_reason(self.web3, tx_hash, receipt)
             raise TransactionError(
                 "Transaction failed",
-                tx_hash=tx_hash.hex(),
+                tx_hash=TxHash(HexStr(tx_hash.to_0x_hex())),
                 revert_reason=reason,
             )
         return receipt

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/src/ipor_fusion/core/external_state_executor.py

@@ -32,7 +32,7 @@ from web3.types import BlockIdentifier, TxReceipt
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.contract import Call, ContractWrapper
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import ZERO_ADDRESS, Amount, ChainId, MarketId
+from ipor_fusion.types import ZERO_ADDRESS, Amount, ChainId, MarketId, ProposalHash
 
 if TYPE_CHECKING:
     from ipor_fusion.core.plasma_vault import PlasmaVault
@@ -79,12 +79,12 @@ class BalanceProposal:
     value: Amount
     nonce: int
     proposed_at: int
-    proposal_hash: bytes
+    proposal_hash: ProposalHash
 
 
 def _hash_of(
     proposal: BalanceProposal, *, executor: ChecksumAddress, chain_id: ChainId
-) -> bytes:
+) -> ProposalHash:
     """`proposal`'s canonical hash, as `confirmBalance` recomputes it.
 
     The sole mapping from a proposal's fields onto `proposal_hash` arguments,
@@ -132,7 +132,7 @@ class NavMark:
 
     proposed_at: int
     nonce: int
-    proposal_hash: bytes
+    proposal_hash: ProposalHash
     propose_receipt: TxReceipt
     confirm_receipt: TxReceipt
     refresh_receipt: TxReceipt | None
@@ -463,7 +463,7 @@ class ExternalStateExecutor(ContractWrapper):
                 value=Amount(value),
                 nonce=nonce,
                 proposed_at=proposed_at,
-                proposal_hash=b"",
+                proposal_hash=ProposalHash(b""),
             )
             return replace(
                 unstamped,
@@ -516,7 +516,7 @@ class ExternalStateExecutor(ContractWrapper):
         return self._write("proposeBalance(address,uint256)", balance_account, value)
 
     def confirm_balance(
-        self, balance_account: ChecksumAddress, proposal_hash: bytes
+        self, balance_account: ChecksumAddress, proposal_hash: ProposalHash
     ) -> Call[None]:
         """CUSTODIAN-only: confirm the pending proposal for `balance_account`.
         Must be sent by a custodian other than the proposer, and `proposal_hash`
@@ -561,7 +561,7 @@ class ExternalStateExecutor(ContractWrapper):
         proposer: ChecksumAddress,
         proposed_at: int,
         nonce: int,
-    ) -> bytes:
+    ) -> ProposalHash:
         """The confirm hash that `confirmBalance` verifies against:
         ``keccak(abi.encode(executor, chainId, balanceAccount, value, proposer,
         proposedAt, nonce))``.
@@ -571,26 +571,28 @@ class ExternalStateExecutor(ContractWrapper):
         event, never a fresh `nonce()` read -- see `nonce`. Pure -- no chain
         access -- so callers can pre-compute or verify a hash offline.
         """
-        return keccak(
-            encode(
-                [
-                    "address",
-                    "uint256",
-                    "address",
-                    "uint256",
-                    "address",
-                    "uint64",
-                    "uint256",
-                ],
-                [
-                    Web3.to_checksum_address(executor),
-                    int(chain_id),
-                    Web3.to_checksum_address(balance_account),
-                    int(value),
-                    Web3.to_checksum_address(proposer),
-                    int(proposed_at),
-                    int(nonce),
-                ],
+        return ProposalHash(
+            keccak(
+                encode(
+                    [
+                        "address",
+                        "uint256",
+                        "address",
+                        "uint256",
+                        "address",
+                        "uint64",
+                        "uint256",
+                    ],
+                    [
+                        Web3.to_checksum_address(executor),
+                        int(chain_id),
+                        Web3.to_checksum_address(balance_account),
+                        int(value),
+                        Web3.to_checksum_address(proposer),
+                        int(proposed_at),
+                        int(nonce),
+                    ],
+                )
             )
         )
 

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/src/ipor_fusion/errors.py

@@ -11,6 +11,8 @@ from eth_utils import function_signature_to_4byte_selector
 from web3 import Web3
 from web3.types import TxReceipt
 
+from ipor_fusion.types import TxHash
+
 log = logging.getLogger(__name__)
 
 PANIC_CODES: dict[int, str] = {
@@ -237,7 +239,7 @@ class TransactionError(IporFusionError):
     def __init__(
         self,
         message: str,
-        tx_hash: str | None = None,
+        tx_hash: TxHash | None = None,
         revert_reason: str | None = None,
     ):
         self.tx_hash = tx_hash

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/src/ipor_fusion/explorer.py

@@ -10,10 +10,10 @@ import time
 from urllib.parse import urlencode
 from urllib.request import urlopen
 
-from eth_typing import HexAddress
+from eth_typing import HexAddress, HexStr
 
 from ipor_fusion.cache import load_contract_cache, update_contract_cache
-from ipor_fusion.types import ChainId
+from ipor_fusion.types import ChainId, TxHash
 
 ETHERSCAN_V2_URL = "https://api.etherscan.io/v2/api"
 
@@ -57,7 +57,7 @@ def get_contract_name(
 
 def get_deployment_tx(
     chain_id: ChainId, address: HexAddress, api_key: str | None = None
-) -> tuple[str | None, str | None]:
+) -> tuple[TxHash | None, str | None]:
     """Return ``(tx_hash, error)`` for a contract deployment.
 
     ``error`` is a short machine-readable code when ``tx_hash`` is None and the
@@ -69,7 +69,7 @@ def get_deployment_tx(
 
 def _fetch_contract_creation_tx(
     chain_id: ChainId, address: HexAddress, api_key: str | None = None
-) -> tuple[str | None, str | None]:
+) -> tuple[TxHash | None, str | None]:
     if chain_id not in SUPPORTED_CHAINS:
         return None, "chain-not-supported"
     if not api_key:
@@ -91,7 +91,8 @@ def _fetch_contract_creation_tx(
             with urlopen(url, timeout=10) as resp:  # noqa: S310
                 data = json.loads(resp.read().decode())
             if data.get("status") == "1" and data.get("result"):
-                return data["result"][0].get("txHash"), None  # type: ignore[no-any-return]
+                tx_hash = data["result"][0].get("txHash")
+                return (TxHash(HexStr(tx_hash)) if tx_hash else None), None
             result_text = str(data.get("result", "")).lower()
             if "free api access is not supported" in result_text:
                 return None, "etherscan-paid-tier-required"

{ipor_fusion-4.0.0.dev30 → ipor_fusion-4.0.0.dev35}/src/ipor_fusion/fuses/external_state_events.py

@@ -28,10 +28,12 @@ from typing import Any
 
 from eth_abi import decode
 from eth_abi.exceptions import DecodingError
-from eth_typing import ChecksumAddress
+from eth_typing import ChecksumAddress, HexStr
 from web3 import Web3
 from web3.types import TxReceipt
 
+from ipor_fusion.types import TxHash
+
 
 @dataclass(frozen=True, slots=True)
 class ExternalStateEventSpec:
@@ -134,7 +136,7 @@ class ExternalStateEvent:
     emitter: ChecksumAddress
     args: dict[str, Any]
     block_number: int | None = None
-    transaction_hash: str | None = None
+    transaction_hash: TxHash | None = None
     log_index: int | None = None
 
 
@@ -191,10 +193,10 @@ def external_state_event_name(topic: bytes | str) -> str | None:
     return spec.name if spec else None
 
 
-def _hex(value: Any) -> str | None:
+def _hex(value: Any) -> TxHash | None:
     if value is None:
         return None
-    return "0x" + _as_bytes(value, "transactionHash").hex()
+    return TxHash(HexStr("0x" + _as_bytes(value, "transactionHash").hex()))
 
 
 def decode_external_state_event(log: Mapping[str, Any]) -> ExternalStateEvent | None: