ipor-fusion 4.0.0.dev311__tar.gz → 4.0.0.dev319__tar.gz

{ipor_fusion-4.0.0.dev311 → ipor_fusion-4.0.0.dev319}/AGENTS.md

@@ -3,9 +3,7 @@
 `ipor-fusion` is the Python SDK for IPOR Fusion Plasma Vaults: typed fuse
 encoders, on-chain readers, and a `fusion` CLI plus `fusion-mcp` MCP server
 built on the same SDK. Published to PyPI. It is a library and inspection
-tooling, not an automation service. `scripts/crosschain_readiness.py` is a
-read-only diagnostic run on demand, not a keeper or production monitor; any
-scheduled run of it belongs to the monitoring repository.
+tooling, not an automation service.
 
 Related repositories (siblings, referenced by name; clone paths vary):
 - [ipor-fusion](https://github.com/IPOR-Labs/ipor-fusion) — Solidity contracts, the source of truth for market ids, roles and substrates.
@@ -29,8 +27,6 @@ uv run ruff check ./                                          # lint: bandit S,
 uv run pyright                                                # types, basic mode, src + tests + examples + scripts
 uv run pytest                                                 # all tests + coverage gate (fail_under = 98, mcp/ included)
 uv run pytest -m "cli or mcp" --no-cov                        # CLI/MCP subset (the full suite is mostly offline too)
-uv run pytest --run-readiness -m readiness --no-cov -rA       # opt-in live Ethereum-hub POC checks
-uv run python scripts/crosschain_readiness.py --output /tmp/crosschain-readiness.json # live Arbitrum/HyperEVM report
 uv run pytest tests/test_fuse_encoding.py -k aave --no-cov    # single file / test
 UPDATE_GOLDEN=1 uv run pytest -k golden --no-cov              # rewrite pinned CLI/MCP output (tests/fixtures/*_golden/)
 uv lock --check                                               # uv.lock in sync with pyproject.toml
@@ -74,33 +70,19 @@ public Solidity sources from GitHub). Skip only for an unavailable source; an
 exception from the
 SDK is a test failure, never a skip. Never print `.env` or a provider URL: they
 embed API keys, so skip and fail messages carry the exception type only.
-`HYPEREVM_PROVIDER_URL` is used by the HyperEVM lifecycle/deployment tests and
-the readiness script; general PR CI does not supply it.
-`test_simulate_crosschain_hyperevm.py` rehearses Arbitrum → HyperEVM on pinned blocks,
-parametrized by `generation`: `v2` and `v3` run the live factory pairs (`FactoryPair`:
-address, pins, creation-code hashes, route and dispatcher deployment gas limits) with
-executors from the creation code they store; `source` builds a factory pair from
-`FUSE_SOURCE_REVISION` inside the simulation. All need `IPOR_FUSION_CONTRACTS_DIR` at
-that revision (the fuses are compiled from it); a checkout without `node_modules` also
+`HYPEREVM_PROVIDER_URL` is used by the Arbitrum → HyperEVM rehearsal and the
+HyperCore tests; general PR CI does not supply it.
+`test_simulate_crosschain_hyperevm.py` rehearses Arbitrum → HyperEVM on pinned blocks
+with a CCIP factory pair compiled from `FUSE_SOURCE_REVISION` (the contracts release
+the official deployment was built from) and built inside the simulation; the SDK
+supports only that release, so there is no live-pair generation. It needs
+`IPOR_FUSION_CONTRACTS_DIR` at that revision; a checkout without `node_modules` also
 needs `IPOR_FUSION_FOUNDRY_REMAPPINGS` for OpenZeppelin. `test_crosschain_ccip_events.py`
 mirrors the CCIP event registry from a checkout at its own `CONTRACTS_REVISION`.
 `test_solidity_compiler.py` unit-tests that compiler helper (`tests/_foundry.py`)
 offline, with `forge` and `git` mocked. The checkout-based tests above skip when their
 external prerequisites are unavailable. `test_hypercore_live.py`,
-`test_hypercore_deployment.py` and `test_hypercore_simulation.py` need
-`HYPEREVM_PROVIDER_URL` as well.
-`test_simulate_crosschain_lifecycle.py` drives the mainnet POC deployment from
-Ethereum to every spoke on every transport through `CrosschainLane` and
-`CrosschainSimulator`; the fixtures (`Chain`, `Deployment`, `Spoke`, pinned
-blocks) live in `tests/_crosschain.py`. A planned spoke (HyperEVM) is a
-`pending` chain there and an `xfail(strict=True)` param until it is wired.
-`test_simulate_crosschain_canary.py` runs the same lifecycle on `CANARY` and
-`CANARY_V3`, the live Arbitrum → HyperEVM USDC canaries on the pilot-v2 and v3 CCIP
-factory pairs, each pinned right after its last transaction, then checks the final gates and every delivery's receiver
-gas against its route limit; a `Chain.simulated_gas_limit` lifts HyperEVM's 3 M
-small-block pin to 30 M and `Deployment.ccip_debits_sent_amount` /
-`attestation_zero_dust_sd` carry the executor generation's accounting into `Run`.
-It needs `ARBITRUM_PROVIDER_URL` and `HYPEREVM_PROVIDER_URL`.
+and `test_hypercore_deployment.py` need `HYPEREVM_PROVIDER_URL` as well.
 HyperCore (market 55) cannot be simulated directly: the HyperEVM RPC ignores code
 overrides at the precompile addresses `0x800`–`0x813`, and the public Hyperliquid RPC
 has no `eth_simulateV1`. `tests/_hypercore_shadow.py` therefore compiles the HyperCore
@@ -110,33 +92,12 @@ CoreWriter constants redirected to ordinary addresses, proves the rest is identi
 the deployed runtimes, and `tests/_hypercore_model.py` answers those addresses through
 `VaultSimulator.with_state_override_provider`. Core never applies anything there: the
 tests prove EVM validation under supplied Core state. `test_hypercore_simulation.py`
-runs one vault cycle; `test_simulate_crosschain_hypercore.py` runs the composed flow
-(v3 canary hub → CCIP → the market-55 vault → a trade → recall → claim) and holds every
-CCIP delivery to its route gas limit. Both skip without the source directory;
-`test_hypercore_simulation.py` also needs `HYPEREVM_PROVIDER_URL`, the composed flow
-`ARBITRUM_PROVIDER_URL` as well.
-`test_crosschain_readiness.py` checks the Ethereum-hub POC's live bridge and IPOR
-preconditions. Its `readiness` marker requires `--run-readiness`: ordinary runs
-exclude it even with `-m sdk`. Known HyperEVM gaps are non-strict xfails restricted
-to assertion failures, so availability improving is an XPASS, not broken CI.
-Readiness RPC clients fail on missing/unreachable providers or wrong chain IDs;
-they pin a snapshot per chain and do not require `eth_simulateV1`.
-`scripts/crosschain_readiness.py` separately reports both Arbitrum/HyperEVM USDC
-directions and the v3 factory pair's configuration (creation codes, routes, the
-dispatcher deployment gas limit, the canary creator's allowance, balance and HyperEVM
-big-block flag) with snapshot block numbers/hashes/timestamps. `hyperevm_delivery`
-flags manual execution into HyperEVM per message kind: `manual_execution_required` for
-commands and recalls (the hub route's `messageGasLimit`) and `dispatcher_deployment_manual`
-for the one-time deployment ticket. A delivery above the 3 M small block is manual
-unless every Chainlink executor seen delivering on HyperEVM's CCIP 2.0 OffRamp over
-the last ~2 weeks (`chainlink_executors`: `ExecutionStateChanged` senders from every
-source, the canary EOA excluded, at least 20 executions) sends into big blocks; a
-ticket below a dispatcher creation's gas is manual regardless. The executor set is
-derived on every run; `eth_usingBigBlocks` is read at the latest block.
-Blocked availability is a successful observation, not acceptance; incomplete probes
-fail. There is no GitHub workflow for it in this repository: run it locally with
-the Arbitrum and HyperEVM provider URLs from `.env`. A `Spoke` declares which transports reach it;
-the lifecycle matrix follows that.
+pins the shadow guard offline. `test_simulate_examples_hyperevm.py` runs the HyperCore
+example on the official deployment (`fixtures/hypercore_official.json`) at its pinned
+block: the wiring needs only `HYPEREVM_PROVIDER_URL`; the Core leg also needs the source
+directory at the fixture's `build.source_revision` and compiles with its
+`build.optimizer_runs` (the deployed set reproduces only with that setting, not the
+checkout's default profile), the pending reader included.
 
 ## Conventions
 

{ipor_fusion-4.0.0.dev311 → ipor_fusion-4.0.0.dev319}/MIGRATION_4.md

@@ -503,6 +503,55 @@ fails at run time:
   `dataclasses.asdict` form) with every field parsed; use it instead of
   `FusionInstance(**data)`, which passes raw strings into the role-typed fields.
 
+#### Crosschain follows the released contracts
+
+4.0 encodes and decodes the crosschain contracts of the 2026-10-21 contracts
+release (`ipor-abi`: the CCIP and Stargate factories, fuses and NAV pre-hook at
+one CREATE3 address on Arbitrum and HyperEVM). Earlier crosschain deployments
+are not supported: their fuses reject the new calldata, their envelopes fail
+the version check, and their dispatcher `observation()` raises
+`UnsupportedContractVersionError`, so an earlier-generation lane is unreadable
+on the spoke side.
+
+- **Envelopes.** `CODEC_VERSION` is 4 (Stargate), `CCIP_VERSION` 3.
+- **`Command`.** New `min_execution_gas` before `action_data` (0 = the lane's
+  default, at most `MAX_COMMAND_EXECUTION_GAS`); `as_tuple()` / `from_tuple()`
+  have six members and `COMMAND_TUPLE_TYPE` is
+  `(bytes32,uint64,uint64,uint8,uint64,bytes)`.
+- **REQUEST_SHARES.** `Command.request_shares(withdraw_manager, vault, shares,
+  max_fee_shares)`: the fee ceiling in shares is required (`NO_FEE_CEILING` for
+  none).
+- **CCIP supply.** `CcipSendParams.min_delivered` is the delivered-amount floor
+  the supply `enter` carries (0 = none, at most the amount).
+  `CcipCommandType.CANCEL_DEPLOYMENT` cancels an expired dispatcher deployment.
+- **Observations.** `CcipObservation` gains `unpriced_count` and
+  `unpriced_codes` (`unpriced_reason(index)` returns a `TrackedVaultPricing`); the
+  Stargate `Observation` gains `vault_valued` and `unpriced_count`;
+  `LaneObservation` gains `unpriced_count`.
+- **Attestation.** `CrosschainLane.attestation(...)` takes `receipt_at`, the hub's
+  `LaneHubState.last_value_moving_receipt_at` (0 on Stargate). The executor
+  refuses an observation that is not strictly later than its last value-moving
+  receipt; the method raises `ValueError` for it and while a tracked vault is
+  unpriced. New: `LaneHubState.last_value_moving_receipt_at`,
+  `CrosschainLane.last_value_moving_receipt_at()` (`None` on Stargate) and
+  `CcipCrosschainExecutor.last_value_moving_receipt_at`.
+- **Core.** `Call` gains an optional `decode_error` field: a wrapper maps an
+  undecodable answer to a named SDK exception (the earlier-generation
+  `observation()` raises `UnsupportedContractVersionError` this way), and it
+  survives `Call.map()`.
+- **Removed.** `CrosschainDispatcher.pending_request_shares` (neither released
+  dispatcher has it). From the repository: `scripts/crosschain_readiness.py`, the
+  pytest `--run-readiness` option and `readiness` marker, and the examples
+  `crosschain_ccip_usdc_arbitrum_hyperevm.py` and
+  `composed_hypercore_flow_arbitrum_hyperevm.py`, which drove an earlier
+  deployment.
+- **Events and errors.** `CCIP_EVENTS` mirrors the released contracts:
+  `ReturnFinalized` / `LateReturnFinalized` gain `debitedSD`, `SharesRequested`
+  gains `feeShares`, and new events are registered. The crosschain error registry
+  decodes every error the released contracts declare.
+- **Routes.** The released CCIP README requires a route `messageGasLimit` of at
+  least 2.7 M for commands.
+
 ## Errors
 
 Every exception class the SDK defines now derives from `IporFusionError` and is

{ipor_fusion-4.0.0.dev311 → ipor_fusion-4.0.0.dev319}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev311
+Version: 4.0.0.dev319
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -392,30 +392,29 @@ ever signed or broadcast.
 - [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](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](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
-  fee gate, then recall, residual attestation and claim replayed in `CrosschainSimulator` at
-  blocks pinned inside the second live cycle.
-
+- [HyperCore vault on the official deployment](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/hypercore_vault_official_deployment_hyperevm.py) —
+  a HyperEVM vault that trades on Hyperliquid Core (market 55, preview): wiring the published
+  HyperCore fuses, pre-hooks and grants on a factory clone, and building the Core leg (bridge,
+  dex transfers, an order and its reduce-only close, Core → EVM) as unsigned `execute` calldata.
+  Core execution is never simulated; see the example for what is.
 ```bash
 export BASE_PROVIDER_URL="https://base-mainnet.g.alchemy.com/v2/YOUR_KEY"
 uv run python examples/simple_aave_v3_supply_base.py
 uv run python examples/advanced_euler_v2_credit_market_base.py
 uv run python examples/external_state_margin_leg_base.py
-uv run python examples/crosschain_ccip_usdc_arbitrum_hyperevm.py  # needs ARBITRUM_PROVIDER_URL and HYPEREVM_PROVIDER_URL
-uv run python examples/composed_hypercore_flow_arbitrum_hyperevm.py  # same two providers
 ```
 
 No RPC key? `BASE_PROVIDER_URL=https://mainnet.base.org` (Base's public RPC) runs the examples out of
 the box — it supports `eth_simulateV1` and serves their pinned blocks. It is rate-limited, so use a
 dedicated archive node for repeated or CI runs.
 
+The HyperCore example runs on HyperEVM:
+
+```bash
+export HYPEREVM_PROVIDER_URL="https://YOUR_HYPEREVM_ARCHIVE_NODE"
+uv run python examples/hypercore_vault_official_deployment_hyperevm.py
+```
+
 ## Public API and stability
 
 The supported API is `ipor_fusion.__all__`: import from `ipor_fusion`. Removing or
@@ -530,12 +529,12 @@ the pilot executors and factories). Pin an exact version if you depend on them.
 | Crosschain fuses (market 54): `StargateCrosschainSupplyFuse`, `StargateCrosschainCommandFuse`, `CcipCrosschainSupplyFuse`, `CcipCrosschainCommandFuse`, `CrosschainClaimFuse`; transport-agnostic bases `CrosschainSupplyFuse` / `CrosschainCommandFuse` with `StargateSendParams` / `CcipSendParams`, plus `Command`, `CrosschainSubstrateLib`, `OptionsBuilder` | `ipor_fusion.crosschain` |
 | HyperCore fuses (market 55): `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` | `ipor_fusion.hypercore`, with `HyperCoreReader`, `read_hypercore_vault_state` and the event decoders |
 
-The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Pass
-`market_id=crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` to `open_lane`
-/ `discover_deployment` for that deployment. Both require it explicitly:
-`discover_deployment` reads the market's executor grants; `open_lane` takes an executor
-address and uses the market ID to find the vault's matching fuses unless they are
-passed.
+The crosschain API supports only the contracts of the 2026-10-21 release; earlier
+deployments are unreadable (`MIGRATION_4.md`). `open_lane` and `discover_deployment`
+take the market ID explicitly (54, or a keccak-derived one from
+`crosschain_market_id(name)` for a vault built with its own): `discover_deployment`
+reads the market's executor grants; `open_lane` takes an executor address and uses the
+market ID to find the vault's matching fuses unless they are passed.
 
 ### Readers (`ipor_fusion.readers`)
 

{ipor_fusion-4.0.0.dev311 → ipor_fusion-4.0.0.dev319}/README.md

@@ -343,30 +343,29 @@ ever signed or broadcast.
 - [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](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](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
-  fee gate, then recall, residual attestation and claim replayed in `CrosschainSimulator` at
-  blocks pinned inside the second live cycle.
-
+- [HyperCore vault on the official deployment](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/examples/hypercore_vault_official_deployment_hyperevm.py) —
+  a HyperEVM vault that trades on Hyperliquid Core (market 55, preview): wiring the published
+  HyperCore fuses, pre-hooks and grants on a factory clone, and building the Core leg (bridge,
+  dex transfers, an order and its reduce-only close, Core → EVM) as unsigned `execute` calldata.
+  Core execution is never simulated; see the example for what is.
 ```bash
 export BASE_PROVIDER_URL="https://base-mainnet.g.alchemy.com/v2/YOUR_KEY"
 uv run python examples/simple_aave_v3_supply_base.py
 uv run python examples/advanced_euler_v2_credit_market_base.py
 uv run python examples/external_state_margin_leg_base.py
-uv run python examples/crosschain_ccip_usdc_arbitrum_hyperevm.py  # needs ARBITRUM_PROVIDER_URL and HYPEREVM_PROVIDER_URL
-uv run python examples/composed_hypercore_flow_arbitrum_hyperevm.py  # same two providers
 ```
 
 No RPC key? `BASE_PROVIDER_URL=https://mainnet.base.org` (Base's public RPC) runs the examples out of
 the box — it supports `eth_simulateV1` and serves their pinned blocks. It is rate-limited, so use a
 dedicated archive node for repeated or CI runs.
 
+The HyperCore example runs on HyperEVM:
+
+```bash
+export HYPEREVM_PROVIDER_URL="https://YOUR_HYPEREVM_ARCHIVE_NODE"
+uv run python examples/hypercore_vault_official_deployment_hyperevm.py
+```
+
 ## Public API and stability
 
 The supported API is `ipor_fusion.__all__`: import from `ipor_fusion`. Removing or
@@ -481,12 +480,12 @@ the pilot executors and factories). Pin an exact version if you depend on them.
 | Crosschain fuses (market 54): `StargateCrosschainSupplyFuse`, `StargateCrosschainCommandFuse`, `CcipCrosschainSupplyFuse`, `CcipCrosschainCommandFuse`, `CrosschainClaimFuse`; transport-agnostic bases `CrosschainSupplyFuse` / `CrosschainCommandFuse` with `StargateSendParams` / `CcipSendParams`, plus `Command`, `CrosschainSubstrateLib`, `OptionsBuilder` | `ipor_fusion.crosschain` |
 | HyperCore fuses (market 55): `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` | `ipor_fusion.hypercore`, with `HyperCoreReader`, `read_hypercore_vault_state` and the event decoders |
 
-The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Pass
-`market_id=crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` to `open_lane`
-/ `discover_deployment` for that deployment. Both require it explicitly:
-`discover_deployment` reads the market's executor grants; `open_lane` takes an executor
-address and uses the market ID to find the vault's matching fuses unless they are
-passed.
+The crosschain API supports only the contracts of the 2026-10-21 release; earlier
+deployments are unreadable (`MIGRATION_4.md`). `open_lane` and `discover_deployment`
+take the market ID explicitly (54, or a keccak-derived one from
+`crosschain_market_id(name)` for a vault built with its own): `discover_deployment`
+reads the market's executor grants; `open_lane` takes an executor address and uses the
+market ID to find the vault's matching fuses unless they are passed.
 
 ### Readers (`ipor_fusion.readers`)
 

{ipor_fusion-4.0.0.dev311 → ipor_fusion-4.0.0.dev319}/examples/README.md

@@ -38,29 +38,21 @@ transaction.
   brings the margin home and releases it for a user's scheduled withdrawal, then
   demonstrates the executor rejecting a confirmation that does not match its
   proposal.
-- [`crosschain_ccip_usdc_arbitrum_hyperevm.py`](crosschain_ccip_usdc_arbitrum_hyperevm.py) --
-  a vault whose capital works on another chain. Opens a `CrosschainLane` on a
-  live Arbitrum hub vault whose executor has a dispatcher on HyperEVM, then
-  drives the whole lifecycle over CCIP: supply USDC to the spoke, have a
-  proposer and an approver attest the dispatcher's balance into the hub NAV,
-  DEPOSIT into and REDEEM from the spoke vault by command, re-attest, recall
-  the idle to the hub and claim it back into the vault. Both chains run under
-  `eth_simulateV1` and `CrosschainSimulator` relays each CCIP message between
-  them, so it needs an Arbitrum and a HyperEVM archive RPC.
-- [`composed_hypercore_flow_arbitrum_hyperevm.py`](composed_hypercore_flow_arbitrum_hyperevm.py) --
-  the composed flow: the same Arbitrum hub funding a HyperCore vault on
-  HyperEVM (a Plasma Vault that is itself a Hyperliquid Core account) and the
-  trade inside it. Part A builds the Core leg from the vault's market-55
-  substrate grants (bridge EVM -> Core, spot -> perp dex, a limit order and its
-  reduce-only close, dex -> spot, Core -> EVM) and estimates each action with
-  `eth_estimateGas` at head -- six independent previews, EVM acceptance only --
-  with a balance override where the vault holds no USDC and sized to the live
-  Core inventory where the fuse checks a Core balance or dex equity, because
-  `eth_simulateV1` cannot run the HyperCore precompiles.
-  Part B replays the hub legs of the second live cycle in `CrosschainSimulator`
-  at pinned blocks: the REDEEM sized by `read_hypercore_evm_exit_ceiling` behind
-  the executor's maxFee gate, then recall, token return, the residual
-  attestation and the claim. Nothing is signed; it needs the same two RPCs.
+- [`hypercore_vault_official_deployment_hyperevm.py`](hypercore_vault_official_deployment_hyperevm.py) --
+  a vault that is itself a Hyperliquid Core account (HyperCore, market 55; a
+  preview feature). No live vault uses the official HyperCore contracts yet, so
+  it clones a USDC vault from the official HyperEVM factory, wires the published
+  HyperCore fuses, balance fuse and pre-hooks with narrow market-55 grants, reads
+  the post-deployment checklist back, checks its constants against live Core
+  metadata at head, and builds the Core leg (EVM -> Core bridge, spot -> xyz dex,
+  an IOC order and its reduce-only close, dex -> spot, Core -> EVM) as unsigned
+  `execute` calldata. Core execution is never simulated, and the HyperCore read
+  precompiles do not run in `eth_simulateV1`: the default run stops before the
+  Core leg. Its RPC-gated test runs the Core leg too, with the fuses recompiled
+  from source against stand-in precompile answers (EVM acceptance only); it needs
+  `HYPEREVM_PROVIDER_URL`, `IPOR_FUSION_HYPERCORE_SOURCE_DIR` (an ipor-fusion
+  checkout at the release the deployment was built from) and `forge`, and skips
+  without them, which is how pull-request CI runs it.
 
 ## Prerequisites