build_hypercore_deposit_multicall

Documentation for eth_defi.hyperliquid.core_writer.build_hypercore_deposit_multicall function.

build_hypercore_deposit_multicall(lagoon_vault, evm_usdc_amount, hypercore_usdc_amount, vault_address, check_activation=False, chain_id=None, asset_address=None)

Build a single multicall transaction for the full Hypercore deposit flow.

Warning

The Safe must be activated on HyperCore before using the batched deposit. Pass check_activation=True to automatically verify, or use activate_account() beforehand. Without activation, deposited USDC gets permanently stuck in EVM escrow.

Batches the 4-step deposit into one EVM transaction:

  1. approve(CoreDepositWallet, amount) — approve USDC transfer

  2. CoreDepositWallet.deposit(amount, SPOT_DEX) — bridge USDC to HyperCore spot

  3. CoreWriter.sendRawAction(transferUsdClass) — move USDC from spot to perp

  4. CoreWriter.sendRawAction(vaultTransfer) — deposit into vault

When the EVM block finishes execution, all queued CoreWriter actions are processed sequentially on HyperCore (~47k gas per action).

For extra safety under heavy HyperCore load, use the two-phase approach with build_hypercore_deposit_phase1() and build_hypercore_deposit_phase2() with wait_for_evm_escrow_clear() between them.

Derives all contract instances internally from the LagoonVault:

  • module from LagoonVault.trading_strategy_module

  • usdc_contract from the vault’s underlying asset address

  • core_deposit_wallet from the chain ID (mainnet vs testnet)

  • core_writer at the system address CORE_WRITER_ADDRESS

Example:

from eth_defi.hyperliquid.core_writer import build_hypercore_deposit_multicall

fn = build_hypercore_deposit_multicall(
    lagoon_vault=lagoon_vault,
    evm_usdc_amount=10_000 * 10**6,
    hypercore_usdc_amount=10_000 * 10**6,
    vault_address="0x...",
    check_activation=True,
)
tx_hash = fn.transact({"from": asset_manager})
Parameters

  • lagoon_vault (LagoonVault) – Lagoon vault instance with trading_strategy_module_address configured.

  • evm_usdc_amount (int) – USDC amount in EVM wei (uint256) for approve and CDW deposit.

  • hypercore_usdc_amount (int) – USDC amount in HyperCore wei (uint64) for CoreWriter actions.

  • vault_address (HexAddress | str) – Hypercore native vault address (not the Lagoon vault address).

  • check_activation (bool) – If True, verifies the Safe is activated on HyperCore using the coreUserExists precompile before building the multicall. Set to False (default) in simulate/Anvil mode where the precompile is not available.

  • chain_id (int | None) – Override the chain ID used to look up the CoreDepositWallet address. When None (default), derived from lagoon_vault.spec.chain_id. Pass explicitly when using a LagoonSatelliteVault which has no .spec attribute.

  • asset_address (HexAddress | str | None) – Override the USDC token address used for the approve call. When None (default), derived from the vault’s underlying asset (lagoon_vault.vault_contract.functions.asset()). Pass explicitly when using a satellite vault which has no .vault_contract attribute.

Returns

Bound module.functions.multicall(data) ready to .transact().

Raises

RuntimeError – If check_activation is True and the Safe is not activated on HyperCore.

Return type

ContractFunction