ipor-fusion 4.0.0.dev171__tar.gz → 4.0.0.dev185__tar.gz

{ipor_fusion-4.0.0.dev171 → ipor_fusion-4.0.0.dev185}/.github/workflows/python-publish.yml

@@ -133,6 +133,11 @@ jobs:
         run: uv run ruff check ./
         id: static-code-analyze
 
+      - name: Type check
+        if: inputs.static-code-analysis-enabled
+        run: uv run pyright
+        id: type-check
+
       - name: Version release (semantic)
         if: inputs.publish-enabled && !inputs.skip-version-bump && !inputs.dev-build
         id: release

{ipor_fusion-4.0.0.dev171 → ipor_fusion-4.0.0.dev185}/AGENTS.md

@@ -26,7 +26,7 @@ repository-local work that does not require protocol context.
 uv sync --all-extras --locked                                 # install, same as CI
 uv run ruff format ./                                         # format (CI runs --check)
 uv run ruff check ./                                          # lint: bandit S, C901 max-complexity 10, PLR limits
-uv run pyright                                                # types, basic mode, src + tests
+uv run pyright                                                # types, basic mode, src + tests + examples + scripts
 uv run pytest                                                 # all tests + coverage gate (fail_under = 95)
 uv run pytest -m "cli or mcp" --no-cov                        # fast offline subset
 uv run pytest --run-readiness -m readiness --no-cov -rA       # opt-in live Ethereum-hub POC checks
@@ -40,8 +40,12 @@ uv lock --check                                               # uv.lock in sync
 `fusion market morpho-blue|meta-morpho --json`, `fusion vault oracle-mapping
 --json` and the matching MCP tools (`vault_info`, `market_morpho_blue`,
 `market_meta_morpho`, `vault_oracle_mapping`, called through the server) is pinned
-in `tests/fixtures/*_golden/` (`tests/_golden.py`, the `*_golden.py` tests), from
-recorded inputs and no network. A change to any of them fails those tests;
+in `tests/fixtures/*_golden/` (`tests/_golden.py`, the `*_golden.py` tests), with
+no network. Most scenarios render synthetic snapshots (a hand-built `VaultData` or
+fixed reader answers over a fake chain) to cover every rendering branch;
+`test_vault_info_fetched_golden.py` runs `fetch_vault_data` unpatched over a fake
+JSON-RPC provider (`tests/_fake_rpc.py`) to pin the whole fetch-to-output path. A
+change to any of them fails those tests;
 regenerate with `UPDATE_GOLDEN=1` only when the change is intended and review the
 fixture diff. Without it the tests only compare.
 
@@ -252,14 +256,19 @@ the lifecycle matrix follows that.
   prefer a storage or view read over a scan, as `read_balance_fuses` and
   `read_withdraw_manager_address` do), `plasma_vault`, `access`, `withdraw_manager`, `rewards_manager`, `fee_manager`,
   `simulation` (`VaultSimulator`, eth_simulateV1, `erc20_balance_slot` and ERC-20 balance
-  overrides), `oracle`, `fusion_factory`,
+  overrides), `simulation_result` (the run's records, `SimulatedLog`, and the parsing
+  of the node's response), `oracle`, `fusion_factory`,
   `external_state_executor` (NAV marks for market 50), `erc20`, `fuse_action`
   (`FuseAction`), `fuse` (the `Fuse` base, `StakeFuse`, the shared validators and
   substrate packers), `address` (`_validate_not_zero_address`). `core` imports neither
   `fuses` nor `crosschain` (`tests/test_sdk_layering.py`)
 - `fuses/` — per-protocol fuse encoders (aave_v3, async_action, compound_v3,
   erc4626, euler_v2, external_state, fluid_instadapp, gearbox_v3, merkl, morpho, ramses_v2,
-  uniswap_v3, universal, `events.py`); `base.py` re-exports the `core/fuse.py` base and validators,
+  uniswap_v3, universal); `events.py` (`extract_events`, `abi_value` and the raw-log
+  event decoder both event families share), `external_state_event_decoding.py` and
+  `hypercore_event_decoding.py` (the ExternalState and HyperCore event specs, classes
+  and decoders; internal modules, the names are exported from `ipor_fusion.fuses`);
+  `base.py` re-exports the `core/fuse.py` base and validators,
   `FuseAction` and `ZERO_ADDRESS` (from `types`). A fuse is a value: equality and
   hash cover its class and every attribute it stores
 - `crosschain/` — crosschain Plasma Vaults (executor on the hub chain, dispatcher at
@@ -389,9 +398,12 @@ or examples.
   `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
+  `src/`, `examples/`, `scripts/` and `tests/typed_client/` are checked with
   `reportArgumentType` on, so a bare `int`/`str` passed for one fails pyright; the
-  other tests keep it off and pass literals.
+  other tests keep it off and pass literals. The same roots turn on
+  `reportMissingTypeArgument` and `reportUnknownParameterType`: spell every type
+  argument (`tuple[int, str]` for a decoded ABI tuple, `Call[object]` where the
+  result is ignored, `RawLog` for a raw log), never a bare generic.
 - Addresses: fuse, factory and manager addresses per chain come from
   `ipor-abi` `addresses.json`; a fuse must be registered on the vault
   (`PlasmaVault.get_fuses()`) and its market granted substrates before an

{ipor_fusion-4.0.0.dev171 → ipor_fusion-4.0.0.dev185}/MIGRATION_4.md

@@ -23,41 +23,58 @@ the details, and each change is described once, in its section.
 Work through these in order; each is what breaks first at run time after the one
 before it is fixed.
 
-1. **Wrappers are built from an address; execution takes the context.**
+1. **Removed and renamed imports fail first, at import.** The crosschain encoders
+   left `ipor_fusion.fuses.crosschain` for `ipor_fusion.crosschain.fuses` (no shim);
+   the event decoder modules `ipor_fusion.fuses.external_state_events` and
+   `ipor_fusion.fuses.hypercore_events` are renamed `external_state_event_decoding`
+   and `hypercore_event_decoding` (import their names from `ipor_fusion` or
+   `ipor_fusion.fuses`); `IporFusionMarkets.RWA`, `MORPHO_BLUE_ADDRESS`, the 3.x cache
+   functions, `read_erc20_holdings`, `ExternalStateExecutor.mark_nav` and `NavMark`
+   are gone. See [Moved, removed and reshaped](#moved-removed-and-reshaped).
+2. **Wrappers are built from an address; execution takes the context.**
    `PlasmaVault(vault)`, `ERC20(token)`, `AccessManager(manager)`; then
    `.call(ctx)`, `.send(ctx)`, `.build_transaction(ctx)`, `.estimate_gas(ctx)`. See
    [Context-free wrappers](#context-free-wrappers).
-2. **Methods that read the chain to answer are `read_*(ctx, ...)`**:
+3. **Methods that read the chain to answer are `read_*(ctx, ...)`**:
    `vault.get_balance_fuses()` is `vault.read_balance_fuses(ctx)`,
    `access_manager.owner()` is `read_owner(ctx)`. See
    [Renamed methods](#renamed-methods).
-3. **Pin a block with `ctx = ctx.at_block(n)`.** Assigning `ctx.default_block`
+4. **Pin a block with `ctx = ctx.at_block(n)`.** Assigning `ctx.default_block`
    raises `AttributeError`. See [Vault reads and validation](#vault-reads-and-validation).
-4. **The vault read is one snapshot.** `fetch_vault_data(ctx, vault, *, block=None,
+5. **The vault read is one snapshot.** `fetch_vault_data(ctx, vault, *, block=None,
    lending=True, metadata=True)` takes the vault address and the chain from `ctx`;
    `validate_vault_state(state)` and `build_vault_info_json(data, *,
    resolve_name=None)` are pure. See [Vault reads and validation](#vault-reads-and-validation).
-5. **Moved and removed names.** The crosschain encoders left
-   `ipor_fusion.fuses.crosschain` (no shim); `IporFusionMarkets.RWA`,
-   `MORPHO_BLUE_ADDRESS`, the 3.x cache functions, `read_erc20_holdings`,
-   `ExternalStateExecutor.mark_nav` and `NavMark` are gone; several functions take
+6. **Simulations return typed observations.** `sim.observe("label", call)` raises
+   `TypeError`: `read = sim.observe(call, label="label")` returns a
+   `SimulationObservation`, read as `read.value` after `run()`;
+   `SimulationResult.get`, `SimulationResult.observations` and
+   `SimulatedCallResult.decoded` are removed (`AttributeError`). `label` is
+   keyword-only on `observe`, `add_call`, `add_transaction` and `deploy_contract`.
+   A failed `run()` leaves every observation unresolved instead of holding the
+   previous run's value. The result records are frozen, logs are `SimulatedLog`
+   records, and a failed call always carries an `error`. See
+   [Typed batches and simulation observations](#typed-batches-and-simulation-observations)
+   and [Behavior changes](#behavior-changes).
+7. **Options by keyword and other reshaped signatures.** Several functions take
    their options by keyword or renamed a parameter. See
    [Moved, removed and reshaped](#moved-removed-and-reshaped).
-6. **Errors.** Every SDK exception derives from `IporFusionError`; some raises changed
-   class (empty call results, crosschain discovery, simulation, Morpho API). See
-   [Errors](#errors).
-7. **Cache and request limit.** `Web3Context.from_url` bounds requests in flight at
+8. **Errors.** Every SDK exception derives from `IporFusionError`; some raises changed
+   class (empty call results, crosschain discovery, simulation, Morpho API, malformed
+   HyperCore logs). See [Errors](#errors).
+9. **Cache and request limit.** `Web3Context.from_url` bounds requests in flight at
    8 (`max_concurrent_requests`; `InFlightLimit` to share a bound, `None` to lift
    it), and the contract cache is injected per context (`NullCache()` keeps
    nothing). See [Contract cache and request limit](#contract-cache-and-request-limit).
-8. **Typed callers** (pyright, mypy, Pylance): ids, addresses and amounts are
-   nominal types. Wrap literals and raw values, `ChainId(8453)`, `Period(0)`,
-   `Amount(n)`, `parse_fuse_address(...)`; values the SDK returns already carry
-   their type. See [Nominal types](#nominal-types).
-9. **Typed JSON documents.** `build_vault_info_json` and the `fusion market`
-   builders return TypedDicts (`VaultInfoJson`, ...); code annotating them
-   `dict[str, Any]` switches to the TypedDict or `Mapping[str, object]`. See
-   [Typed JSON documents](#typed-json-documents).
+10. **Typed callers** (pyright, mypy, Pylance): ids, addresses and amounts are
+    nominal types. Wrap literals and raw values, `ChainId(8453)`, `Period(0)`,
+    `Amount(n)`, `parse_fuse_address(...)`; values the SDK returns already carry
+    their type. See [Nominal types](#nominal-types).
+11. **Typed JSON documents and events.** `build_vault_info_json` and the `fusion
+    market` builders return TypedDicts (`VaultInfoJson`, ...); code annotating them
+    `dict[str, Any]` switches to the TypedDict or `Mapping[str, object]`. Decoded
+    events are discriminated unions narrowed by `event.name`. See
+    [Typed JSON documents](#typed-json-documents) and [Decoded events](#decoded-events).
 
 Then read [Behavior changes](#behavior-changes): they apply to every caller,
 type-checked or not.
@@ -174,7 +191,13 @@ assets.value, fuses.value, name.value
 instead of the simulator, so it no longer chains, and its label is optional (it
 names the read in `result.calls` and in failures). After `run()`,
 `observation.value` is the read decoded as its `Call` decodes it, from the latest
-run; `observation.result` is its `SimulatedCallResult`.
+run; `observation.result` is its `SimulatedCallResult`. Every `run()` unresolves the
+observations when it starts and resolves them only once the whole response has
+parsed: after a failed run (a transport error, an RPC error, a malformed response,
+raised as `SimulationRunError` for the last two) reading one raises `RuntimeError`
+until a run succeeds. `label` is keyword-only on `add_call` and `add_transaction`
+too, as on `observe` and `deploy_contract`: `sim.add_call(call, from_, "label")`
+raises `TypeError`, pass `label="label"`.
 `CrosschainSimulator.observe(chain_id, call, *, label=None)` returns the same,
 resolved by every relay round. `SimulationResult.get`, `SimulationResult.observations`
 and `SimulatedCallResult.decoded` are removed: a list of results of many types has no
@@ -189,9 +212,16 @@ sim.run()
 after.value - before.value
 ```
 
-`Call` is a frozen dataclass and covariant in its result type: assigning to a
-field raises, and a `Call[Amount]` is a `Call[int]` and a `Call[object]`, so a
-`Sequence[Call[object]]` takes any calls without a cast.
+`Call` is a frozen, hashable dataclass and covariant in its result type:
+assigning to a field raises, `output_types` is stored as a tuple (whatever sequence
+it was built with, so compare it with a tuple), and a `Call[Amount]` is a
+`Call[int]` and a `Call[object]`, so a `Sequence[Call[object]]` takes any calls
+without a cast. `add_call` and `execute_call` take a `Call[object]`.
+
+The logs of a simulated call (`SimulatedCallResult.logs`,
+`SimulationResult.execute_logs`) are `SimulatedLog` TypedDicts: `address`, `topics`
+and `data` as the node's `0x` text, plus its block and transaction identity fields
+when it sends them. Other keys a node adds are not kept.
 
 ### Renamed methods
 
@@ -214,6 +244,7 @@ field raises, and a `Call[Amount]` is a `Call[int]` and a `Call[object]`, so a
 | `AaveV3FuseReader.pool()` | `AaveV3FuseReader.read_pool(ctx)` |
 | `PlasmaVault.read(target, data)` / `read_as(target, data, ...)` | `PlasmaVault.universal_read(target, data)` / `universal_read_decoded(target, data, ...)` (they build a Call; `read_*` names only methods that execute) |
 | `read_index_of(asset)` | `precompile_index_of(asset)` (it reads nothing) |
+| `EulerSwapStaticParams.to_tuple()` (and `EulerSwapDynamicParams`, `EulerSwapInitialState`, `EulerV2BatchItem`) | `.as_tuple()`, a typed tuple instead of a list |
 | `ctx.default_block = n` | `ctx = ctx.at_block(n)` |
 
 A service that caches wrappers per chain can now share one wrapper across chains and
@@ -406,9 +437,15 @@ is the wrong one.
 - `Call.call(ctx)` and `Call.decode()` on a write-only `Call` raise `ValueError`, not
   `RuntimeError`. `CrosschainSimulator.relay` raises `ValueError`, not
   `RuntimeError`, for a message to a chain that was not added.
-- `VaultSimulator.run` (provider error from `eth_simulateV1`, or a result count that
-  does not match the queued calls) and `CrosschainSimulator.relay` (not settled within
-  `max_rounds`) raise the new `SimulationRunError`, still a `RuntimeError`.
+- `VaultSimulator.run` (provider error from `eth_simulateV1`, a result count that
+  does not match the queued calls, or a response not in the documented shape, which
+  raised `KeyError`, `TypeError` or `ValueError` before: a call result without a
+  `0x0`/`0x1` `status`, which 3.x read as a success, or `logs` that is not a list) and
+  `CrosschainSimulator.relay` (not settled within `max_rounds`) raise the new
+  `SimulationRunError`, still a `RuntimeError`.
+- `decode_hypercore_event` raises the new `HyperCoreEventDecodeError` (a
+  `ValueError`) for a log whose topic it recognizes but whose other parts are
+  malformed; see [Decoded events](#decoded-events).
 - The Morpho API client raises `MorphoApiError` for every answer it cannot use and
   every transport failure, never `KeyError`, `TypeError` or `ValueError`:
   - a required market id or address (market and V1 allocation ids, V1 flow-cap ids,
@@ -855,34 +892,58 @@ 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"]`.
-- 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.
+  `find_balance_proposed`, the event decoders and the crosschain log helpers
+  accept) is `Mapping[str, object]`, not `Mapping[str, Any]`; a web3 `LogReceipt`
+  still fits it.
+- `Command.decode_action_data()` returns `tuple[object, ...]`: narrow each value
+  (an `int`, a lowercase hex `str` address or `bytes`, by the action) before use.
+- `CrosschainLane.proposal_id_from_receipt(receipt)` is typed to take web3's
+  `TxReceipt`; for a raw JSON-RPC or minimal `{"logs": ...}` receipt call
+  `lane.proposal_id_from_logs(receipt["logs"])`, which takes any `RawLog`s.
+
+## Decoded events
+
+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. 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. Every name is importable from `ipor_fusion` and
+from `ipor_fusion.fuses`.
+
+The two families share one input contract. `decode_external_state_event(log)` and
+`decode_hypercore_event(log)` take a web3 receipt log or a raw JSON-RPC / indexer
+mapping (hex text topics, data, hashes and quantities) and return `None` when topic0
+is not one of theirs, or cannot be a topic; once the topic is recognized, a malformed
+part raises `ExternalStateEventDecodeError` / `HyperCoreEventDecodeError` (both an
+`IporFusionError` and a `ValueError`). `external_state_event_name(topic)` and
+`hypercore_event_name(topic)` return `None` for any other topic or a value that
+cannot be one. For HyperCore this changes 3.x: `decode_hypercore_event` took only a
+receipt log with bytes topics and let eth_abi's errors through,
+`hypercore_event_name` raised on bad hex and also matched hex text without `0x`
+(which now returns `None`: pass `"0x" + topic.hex()` or `HexBytes(topic).to_0x_hex()`),
+and `log_index` was passed through as given (a hex string from a raw log); the events now also carry `block_number` and
+`transaction_hash`, like the ExternalState ones.
 
 ## Behavior changes
 

{ipor_fusion-4.0.0.dev171 → ipor_fusion-4.0.0.dev185}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev171
+Version: 4.0.0.dev185
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -123,7 +123,7 @@ alt="Release">
 > vault read is one pinned snapshot, and several modules and names moved. A 3.x call
 > such as `PlasmaVault(ctx, address)` fails only when it runs, so a broad
 > `except Exception` can hide it. Follow the ordered checklist in
-> [MIGRATION_4.md, *Start here*](MIGRATION_4.md#start-here).
+> [MIGRATION_4.md, *Start here*](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/MIGRATION_4.md#start-here).
 
 ## Quickstart
 
@@ -298,7 +298,7 @@ resources `fusion://glossary`, `fusion://architecture`, `fusion://invariants` an
 
 ## Agent skills
 
-[`skills/ipor-deploy-vault/SKILL.md`](skills/ipor-deploy-vault/SKILL.md) teaches a
+[`skills/ipor-deploy-vault/SKILL.md`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/skills/ipor-deploy-vault/SKILL.md) teaches a
 coding agent the full clone → roles → market → access posture → deposit → execute
 walk, with the invariants and the revert selectors, before it writes vault code.
 Its body is `fusion://invariants` and `fusion://quickstart` from `ipor_fusion.guide`
@@ -318,7 +318,7 @@ npx skills add IPOR-Labs/ipor-fusion.py -g -a codex      # or gemini-cli, cursor
 
 ## Common errors
 
-Reverts on the deploy-and-configure path, keyed by selector so a failed transaction is greppable. This table and the full invariants ship in the wheel as [`ipor_fusion.guide`](src/ipor_fusion/guide/invariants.md), which `fusion-mcp` serves as `fusion://invariants`.
+Reverts on the deploy-and-configure path, keyed by selector so a failed transaction is greppable. This table and the full invariants ship in the wheel as [`ipor_fusion.guide`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/src/ipor_fusion/guide/invariants.md), which `fusion-mcp` serves as `fusion://invariants`.
 
 | Selector | Revert | What happened | Fix |
 |---|---|---|---|
@@ -334,7 +334,7 @@ Configuration order on a fresh vault: `add_fuses` → `grant_market_substrates`
 
 A flash-loan fuse also needs `update_callback_handler(handler, sender, selector)` before its first `execute`: Morpho Blue calls back `onMorphoFlashLoan(uint256,bytes)`, the Euler EVC `onEulerFlashLoan(bytes)`, and an unregistered callback reverts `HandlerNotFound()`.
 
-The full clone → configure → deposit → execute sequence is exercised in [`tests/test_simulate_vault_from_scratch_base.py`](tests/test_simulate_vault_from_scratch_base.py).
+The full clone → configure → deposit → execute sequence is exercised in [`tests/test_simulate_vault_from_scratch_base.py`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/tests/test_simulate_vault_from_scratch_base.py).
 
 Custom errors of the crosschain contracts decode by name: importing
 `ipor_fusion.crosschain` registers their signatures (`CROSSCHAIN_ERROR_SIGNATURES`),
@@ -346,22 +346,22 @@ raises `SimulationError` naming the first failed call.
 ## Vault construction examples
 
 Runnable, canonical examples for building and configuring a vault from scratch live in
-[`examples`](examples). They preview and simulate through `eth_simulateV1` — nothing is
+[`examples`](https://github.com/IPOR-Labs/ipor-fusion.py/tree/main/examples). They preview and simulate through `eth_simulateV1` — nothing is
 ever signed or broadcast.
 
-- [Simple Aave V3 supply vault](examples/simple_aave_v3_supply_base.py) — start here for vault
+- [Simple Aave V3 supply vault](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/simple_aave_v3_supply_base.py) — start here for vault
   creation, role bootstrap, and configuring a single supported market.
-- [Advanced Euler V2 credit-market vault](examples/advanced_euler_v2_credit_market_base.py) —
+- [Advanced Euler V2 credit-market vault](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/advanced_euler_v2_credit_market_base.py) —
   continue here for composing multiple functional fuses, typed Euler substrates and sub-accounts,
   and an ordered collateral → borrow → repay → unwind lifecycle.
-- [External-state margin leg](examples/external_state_margin_leg_base.py) — a vault whose capital
+- [External-state margin leg](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/external_state_margin_leg_base.py) — a vault whose capital
   sits off-chain: typed market-50 substrates, a dual-custodian propose/confirm marking the NAV,
   the scheduled-withdrawal prep an alpha performs, and a mismatched confirmation being rejected.
-- [Crosschain CCIP lifecycle](examples/crosschain_ccip_usdc_arbitrum_hyperevm.py) (preview feature) — a vault
+- [Crosschain CCIP lifecycle](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/crosschain_ccip_usdc_arbitrum_hyperevm.py) (preview feature) — a vault
   whose capital works on another chain: supply USDC from an Arbitrum hub to a HyperEVM spoke
   over CCIP, attest the remote balance with two keys, deposit and redeem on the spoke, recall
   and claim, driven through `CrosschainLane` and relayed by `CrosschainSimulator`.
-- [Composed HyperCore flow](examples/composed_hypercore_flow_arbitrum_hyperevm.py) (preview feature) — the
+- [Composed HyperCore flow](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/composed_hypercore_flow_arbitrum_hyperevm.py) (preview feature) — the
   same hub funding a HyperCore vault (market 55) that trades on Hyperliquid Core: the Core leg
   (bridge, dex transfer, order, close, exit) built from the vault's substrate grants and estimated
   with `eth_estimateGas` at head (EVM acceptance only, Core executes later), the REDEEM sized by the vault's EVM exit ceiling behind the executor's
@@ -448,6 +448,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | `ExternalStateExecutor` | NAV propose/confirm for off-vault capital (market 50); the executor's thresholds (`staleness_max`, `big_change_bps`, `dust_threshold`, `min_update_interval`), the live aggregate (`get_balance_fuse_snapshot`) and the pre-hook's staleness clock (`get_oldest_update_timestamp`) |
 | `read_external_state`, `ExternalStateVaultState` | The market's vault-scoped state from the vault's ERC-7201 storage at one block: executor, the balance fuse's cached total, the custodian timestamp it last checked and the pause flag the pre-hook enforces (no getter exposes them) |
 | `decode_external_state_event`, `EXTERNAL_STATE_TOPICS` | The ExternalState events the vault emits (big change, cache updates, unpause, rescue, executor creation and deployment, operation enter/exit), decoded by topic with their raw log identity; a malformed listed log raises |
+| `decode_hypercore_event`, `hypercore_events` | **Preview.** The HyperCore fuse, pending-library, settlement and reporter events, decoded by topic with their raw log identity under the same input contract; a malformed listed log raises `HyperCoreEventDecodeError` |
 | `StargateCrosschainExecutor`, `CcipCrosschainExecutor` | **Preview.** Crosschain executor reads and attestation (`propose_balance`, `approve_balance`) |
 | `StargateCrosschainDispatcher`, `CcipCrosschainDispatcher` | Remote dispatcher state (`observation`, tracked idle, command lane) |
 | `StargateCrosschainFactory`, `CcipCrosschainFactory` | Executor creation and route/asset configuration reads |
@@ -475,11 +476,11 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | Universal | `UniversalTokenSwapperFuse` |
 | Off-vault capital | `AsyncActionFuse` (market 40), `ExternalStateOperationFuse` (market 50) |
 | Crosschain (preview) | `StargateCrosschainSupplyFuse`, `StargateCrosschainCommandFuse`, `CcipCrosschainSupplyFuse`, `CcipCrosschainCommandFuse`, `CrosschainClaimFuse` (market 54); transport-agnostic bases `CrosschainSupplyFuse` / `CrosschainCommandFuse` with `StargateSendParams` / `CcipSendParams`, plus `Command`, `CrosschainSubstrateLib`, `OptionsBuilder` |
+| HyperCore (Hyperliquid, market 55, preview) | `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` |
 
 The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Use
 `crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` for that deployment;
 `open_lane` discovers the vault's actual market grants rather than assuming 54.
-| HyperCore (Hyperliquid, market 55, preview) | `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` |
 
 ### Readers (`ipor_fusion.readers`)
 
@@ -543,7 +544,7 @@ cp .env.example .env
 # Edit .env with ARBITRUM_PROVIDER_URL, ETHEREUM_PROVIDER_URL, BASE_PROVIDER_URL
 ```
 
-Contributor and coding-agent instructions (commands, conventions, invariants, domain rules) live in [AGENTS.md](AGENTS.md).
+Contributor and coding-agent instructions (commands, conventions, invariants, domain rules) live in [AGENTS.md](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/AGENTS.md).
 
 ## Examples
 

{ipor_fusion-4.0.0.dev171 → ipor_fusion-4.0.0.dev185}/README.md

@@ -75,7 +75,7 @@ alt="Release">
 > vault read is one pinned snapshot, and several modules and names moved. A 3.x call
 > such as `PlasmaVault(ctx, address)` fails only when it runs, so a broad
 > `except Exception` can hide it. Follow the ordered checklist in
-> [MIGRATION_4.md, *Start here*](MIGRATION_4.md#start-here).
+> [MIGRATION_4.md, *Start here*](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/MIGRATION_4.md#start-here).
 
 ## Quickstart
 
@@ -250,7 +250,7 @@ resources `fusion://glossary`, `fusion://architecture`, `fusion://invariants` an
 
 ## Agent skills
 
-[`skills/ipor-deploy-vault/SKILL.md`](skills/ipor-deploy-vault/SKILL.md) teaches a
+[`skills/ipor-deploy-vault/SKILL.md`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/skills/ipor-deploy-vault/SKILL.md) teaches a
 coding agent the full clone → roles → market → access posture → deposit → execute
 walk, with the invariants and the revert selectors, before it writes vault code.
 Its body is `fusion://invariants` and `fusion://quickstart` from `ipor_fusion.guide`
@@ -270,7 +270,7 @@ npx skills add IPOR-Labs/ipor-fusion.py -g -a codex      # or gemini-cli, cursor
 
 ## Common errors
 
-Reverts on the deploy-and-configure path, keyed by selector so a failed transaction is greppable. This table and the full invariants ship in the wheel as [`ipor_fusion.guide`](src/ipor_fusion/guide/invariants.md), which `fusion-mcp` serves as `fusion://invariants`.
+Reverts on the deploy-and-configure path, keyed by selector so a failed transaction is greppable. This table and the full invariants ship in the wheel as [`ipor_fusion.guide`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/src/ipor_fusion/guide/invariants.md), which `fusion-mcp` serves as `fusion://invariants`.
 
 | Selector | Revert | What happened | Fix |
 |---|---|---|---|
@@ -286,7 +286,7 @@ Configuration order on a fresh vault: `add_fuses` → `grant_market_substrates`
 
 A flash-loan fuse also needs `update_callback_handler(handler, sender, selector)` before its first `execute`: Morpho Blue calls back `onMorphoFlashLoan(uint256,bytes)`, the Euler EVC `onEulerFlashLoan(bytes)`, and an unregistered callback reverts `HandlerNotFound()`.
 
-The full clone → configure → deposit → execute sequence is exercised in [`tests/test_simulate_vault_from_scratch_base.py`](tests/test_simulate_vault_from_scratch_base.py).
+The full clone → configure → deposit → execute sequence is exercised in [`tests/test_simulate_vault_from_scratch_base.py`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/tests/test_simulate_vault_from_scratch_base.py).
 
 Custom errors of the crosschain contracts decode by name: importing
 `ipor_fusion.crosschain` registers their signatures (`CROSSCHAIN_ERROR_SIGNATURES`),
@@ -298,22 +298,22 @@ raises `SimulationError` naming the first failed call.
 ## Vault construction examples
 
 Runnable, canonical examples for building and configuring a vault from scratch live in
-[`examples`](examples). They preview and simulate through `eth_simulateV1` — nothing is
+[`examples`](https://github.com/IPOR-Labs/ipor-fusion.py/tree/main/examples). They preview and simulate through `eth_simulateV1` — nothing is
 ever signed or broadcast.
 
-- [Simple Aave V3 supply vault](examples/simple_aave_v3_supply_base.py) — start here for vault
+- [Simple Aave V3 supply vault](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/simple_aave_v3_supply_base.py) — start here for vault
   creation, role bootstrap, and configuring a single supported market.
-- [Advanced Euler V2 credit-market vault](examples/advanced_euler_v2_credit_market_base.py) —
+- [Advanced Euler V2 credit-market vault](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/advanced_euler_v2_credit_market_base.py) —
   continue here for composing multiple functional fuses, typed Euler substrates and sub-accounts,
   and an ordered collateral → borrow → repay → unwind lifecycle.
-- [External-state margin leg](examples/external_state_margin_leg_base.py) — a vault whose capital
+- [External-state margin leg](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/external_state_margin_leg_base.py) — a vault whose capital
   sits off-chain: typed market-50 substrates, a dual-custodian propose/confirm marking the NAV,
   the scheduled-withdrawal prep an alpha performs, and a mismatched confirmation being rejected.
-- [Crosschain CCIP lifecycle](examples/crosschain_ccip_usdc_arbitrum_hyperevm.py) (preview feature) — a vault
+- [Crosschain CCIP lifecycle](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/crosschain_ccip_usdc_arbitrum_hyperevm.py) (preview feature) — a vault
   whose capital works on another chain: supply USDC from an Arbitrum hub to a HyperEVM spoke
   over CCIP, attest the remote balance with two keys, deposit and redeem on the spoke, recall
   and claim, driven through `CrosschainLane` and relayed by `CrosschainSimulator`.
-- [Composed HyperCore flow](examples/composed_hypercore_flow_arbitrum_hyperevm.py) (preview feature) — the
+- [Composed HyperCore flow](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/composed_hypercore_flow_arbitrum_hyperevm.py) (preview feature) — the
   same hub funding a HyperCore vault (market 55) that trades on Hyperliquid Core: the Core leg
   (bridge, dex transfer, order, close, exit) built from the vault's substrate grants and estimated
   with `eth_estimateGas` at head (EVM acceptance only, Core executes later), the REDEEM sized by the vault's EVM exit ceiling behind the executor's
@@ -400,6 +400,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | `ExternalStateExecutor` | NAV propose/confirm for off-vault capital (market 50); the executor's thresholds (`staleness_max`, `big_change_bps`, `dust_threshold`, `min_update_interval`), the live aggregate (`get_balance_fuse_snapshot`) and the pre-hook's staleness clock (`get_oldest_update_timestamp`) |
 | `read_external_state`, `ExternalStateVaultState` | The market's vault-scoped state from the vault's ERC-7201 storage at one block: executor, the balance fuse's cached total, the custodian timestamp it last checked and the pause flag the pre-hook enforces (no getter exposes them) |
 | `decode_external_state_event`, `EXTERNAL_STATE_TOPICS` | The ExternalState events the vault emits (big change, cache updates, unpause, rescue, executor creation and deployment, operation enter/exit), decoded by topic with their raw log identity; a malformed listed log raises |
+| `decode_hypercore_event`, `hypercore_events` | **Preview.** The HyperCore fuse, pending-library, settlement and reporter events, decoded by topic with their raw log identity under the same input contract; a malformed listed log raises `HyperCoreEventDecodeError` |
 | `StargateCrosschainExecutor`, `CcipCrosschainExecutor` | **Preview.** Crosschain executor reads and attestation (`propose_balance`, `approve_balance`) |
 | `StargateCrosschainDispatcher`, `CcipCrosschainDispatcher` | Remote dispatcher state (`observation`, tracked idle, command lane) |
 | `StargateCrosschainFactory`, `CcipCrosschainFactory` | Executor creation and route/asset configuration reads |
@@ -427,11 +428,11 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | Universal | `UniversalTokenSwapperFuse` |
 | Off-vault capital | `AsyncActionFuse` (market 40), `ExternalStateOperationFuse` (market 50) |
 | Crosschain (preview) | `StargateCrosschainSupplyFuse`, `StargateCrosschainCommandFuse`, `CcipCrosschainSupplyFuse`, `CcipCrosschainCommandFuse`, `CrosschainClaimFuse` (market 54); transport-agnostic bases `CrosschainSupplyFuse` / `CrosschainCommandFuse` with `StargateSendParams` / `CcipSendParams`, plus `Command`, `CrosschainSubstrateLib`, `OptionsBuilder` |
+| HyperCore (Hyperliquid, market 55, preview) | `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` |
 
 The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Use
 `crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` for that deployment;
 `open_lane` discovers the vault's actual market grants rather than assuming 54.
-| HyperCore (Hyperliquid, market 55, preview) | `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` |
 
 ### Readers (`ipor_fusion.readers`)
 
@@ -495,7 +496,7 @@ cp .env.example .env
 # Edit .env with ARBITRUM_PROVIDER_URL, ETHEREUM_PROVIDER_URL, BASE_PROVIDER_URL
 ```
 
-Contributor and coding-agent instructions (commands, conventions, invariants, domain rules) live in [AGENTS.md](AGENTS.md).
+Contributor and coding-agent instructions (commands, conventions, invariants, domain rules) live in [AGENTS.md](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/AGENTS.md).
 
 ## Examples
 

{ipor_fusion-4.0.0.dev171 → ipor_fusion-4.0.0.dev185}/examples/advanced_euler_v2_credit_market_base.py

@@ -43,6 +43,7 @@ from __future__ import annotations
 import logging
 import os
 import sys
+from typing import TypedDict
 
 from eth_abi import encode
 from eth_typing import ChecksumAddress
@@ -238,7 +239,18 @@ def _evault_debt_of(
 # ── Pure builders (no chain access -- safe to import and unit-test offline) ───
 
 
-def clone_args() -> dict:
+class CloneKwargs(TypedDict):
+    """The keyword arguments of ``FusionFactory.clone``."""
+
+    asset_name: str
+    asset_symbol: str
+    underlying_token: ChecksumAddress
+    redemption_delay_seconds: Period
+    owner: ChecksumAddress
+    dao_fee_package_index: int
+
+
+def clone_args() -> CloneKwargs:
     """Arguments for FusionFactory.clone(...).
 
     The preview and the in-batch create MUST use identical args: same args plus
@@ -250,7 +262,7 @@ def clone_args() -> dict:
         "asset_name": "IPOR WETH Euler Credit Vault (example)",
         "asset_symbol": "ipWETHec",
         "underlying_token": BASE_WETH,
-        "redemption_delay_seconds": 0,
+        "redemption_delay_seconds": Period(0),
         "owner": OWNER,
         "dao_fee_package_index": 0,
     }

{ipor_fusion-4.0.0.dev171 → ipor_fusion-4.0.0.dev185}/examples/advanced_euler_v2_looping_arbitrum.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 import logging
 import os
 import sys
+from typing import TypedDict
 
 from eth_abi import encode
 from eth_abi.packed import encode_packed
@@ -193,12 +194,23 @@ def _debt_of(
 # ── Pure builders (no chain access) ──────────────────────────────────────────
 
 
-def clone_args() -> dict:
+class CloneKwargs(TypedDict):
+    """The keyword arguments of ``FusionFactory.clone``."""
+
+    asset_name: str
+    asset_symbol: str
+    underlying_token: ChecksumAddress
+    redemption_delay_seconds: Period
+    owner: ChecksumAddress
+    dao_fee_package_index: int
+
+
+def clone_args() -> CloneKwargs:
     return {
         "asset_name": "IPOR WBTC Euler Loop Vault (example)",
         "asset_symbol": "ipWBTCel",
         "underlying_token": ARBITRUM_WBTC,
-        "redemption_delay_seconds": 0,
+        "redemption_delay_seconds": Period(0),
         "owner": OWNER,
         "dao_fee_package_index": 0,
     }