hyperliquid.block
Documentation for eth_defi.hyperliquid.block Python module.
HyperEVM dual-block architecture helpers.
HyperEVM produces two types of blocks:
Small blocks (~2-3M gas, every ~1 second): normal transactions
Large blocks (30M gas, every ~1 minute): contract deployments, heavy computation
Transactions are routed to independent mempools based on the sender’s
account-level usingBigBlocks flag. To deploy contracts that exceed
the small block gas limit (e.g. TradingStrategyModuleV0 at ~5.4M gas),
the deployer must first enable large blocks via the evmUserModify
HyperCore action.
Example:
from eth_defi.hyperliquid.block import big_blocks_for_deployment
# Wrap each contract deployment — no-op on non-HyperEVM chains
with big_blocks_for_deployment(web3, private_key):
deploy_contract(...)
# Configuration transactions run in small blocks (fast confirmation)
setup_guard(...)
See Dual-block architecture for details.
Module Attributes
HyperEVM chain IDs where dual-block architecture applies. |
|
Gas limit for HyperEVM large blocks (30M). |
|
Hyperliquid exchange API URL (mainnet). |
|
Hyperliquid exchange API URL (testnet). |
Functions
|
Context manager that enables large blocks and disables them on exit. |
|
Context manager that enables large blocks for a single contract deployment. |
|
Disable large blocks after contract deployment. |
|
Enable large blocks if needed for contract deployment on HyperEVM. |
|
Check if an address is currently using large blocks. |
|
Check if a chain ID is HyperEVM (mainnet or testnet). |
|
Verify big blocks can be toggled before starting a deployment on HyperEVM. |
|
Enable or disable large blocks for a deployer address. |
Exceptions
Raised when big blocks cannot be enabled/disabled on HyperEVM. |
- exception HyperEVMBigBlocksError
Bases:
ExceptionRaised when big blocks cannot be enabled/disabled on HyperEVM.
Typically happens when the deployer address has never performed an action on Hyperliquid L1 (e.g. a spot transfer), so the exchange API does not recognise the account.
- __init__(*args, **kwargs)
- __new__(**kwargs)
- add_note()
Exception.add_note(note) – add a note to the exception
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- HYPEREVM_CHAIN_IDS: set[int] = {998, 999}
HyperEVM chain IDs where dual-block architecture applies.
- HYPEREVM_BIG_BLOCK_GAS_LIMIT: int = 30000000
Gas limit for HyperEVM large blocks (30M).
Small blocks have ~2-3M gas; large blocks always have 30M. Used to override
eth_getBlock("latest")["gasLimit"]which may return a small block’s limit even when the deployer has big blocks enabled.
- HYPERLIQUID_EXCHANGE_API_MAINNET = 'https://api.hyperliquid.xyz'
Hyperliquid exchange API URL (mainnet).
- HYPERLIQUID_EXCHANGE_API_TESTNET = 'https://api.hyperliquid-testnet.xyz'
Hyperliquid exchange API URL (testnet).
- is_hyperevm(chain_id)
Check if a chain ID is HyperEVM (mainnet or testnet).
- fetch_using_big_blocks(web3, address)
Check if an address is currently using large blocks.
Calls the HyperEVM-specific
eth_usingBigBlocksJSON-RPC method.- Parameters
web3 (web3.main.Web3) – Web3 connected to a HyperEVM node.
address (Union[eth_typing.evm.HexAddress, str]) – Address to check.
- Returns
Trueif the address is flagged for large blocks.- Return type
- set_big_blocks(private_key, enable, is_mainnet=True, timeout=10.0)
Enable or disable large blocks for a deployer address.
Sends an
evmUserModifyaction to the Hyperliquid exchange API. After enabling, all transactions from the address are routed to the large block mempool (~1 minute confirmation) until disabled.- Parameters
- Returns
API response dict.
- Raises
requests.HTTPError – If the API returns an error status code.
- Return type
- big_blocks_enabled(private_key, is_mainnet=True, web3=None)
Context manager that enables large blocks and disables them on exit.
Checks whether the address already has large blocks enabled and only toggles if needed. Always restores the original state on exit (even if an exception occurs).
Example:
with big_blocks_enabled(private_key, is_mainnet=False, web3=web3): deploy_automated_lagoon_vault(...)
- enable_big_blocks(web3, private_key)
Enable large blocks if needed for contract deployment on HyperEVM.
Checks the chain ID and current block gas limit. If the chain is HyperEVM and the block gas limit is below 10M (small block), enables large blocks for the deployer.
Does nothing on non-HyperEVM chains or Anvil forks (which override the gas limit).
- disable_big_blocks(web3, private_key)
Disable large blocks after contract deployment.
Counterpart to
enable_big_blocks(). Only call this if that function returnedTrue.- Parameters
web3 (web3.main.Web3) – Web3 connection.
private_key (str) – Hex-encoded deployer private key.
- big_blocks_for_deployment(web3, private_key)
Context manager that enables large blocks for a single contract deployment.
Use this to wrap individual contract deployment calls so that configuration transactions between deployments run in small blocks (fast ~1 second confirmation) rather than large blocks (~1 minute).
On non-HyperEVM chains or Anvil forks this is a no-op.
Example:
with big_blocks_for_deployment(web3, private_key): deploy_contract(...)- Parameters
web3 (web3.main.Web3) – Web3 connection.
private_key (str) – Hex-encoded deployer private key.
- preflight_check_big_blocks(web3, private_key)
Verify big blocks can be toggled before starting a deployment on HyperEVM.
Performs a quick enable/disable round-trip against the Hyperliquid exchange API. If the deployer address has never performed an L1 action (e.g. a spot transfer), the API will reject the request and this function raises
HyperEVMBigBlocksErrorwith a clear message, rather than letting the deployment fail mid-way with an opaque “exceeds block gas limit” error.No-op on non-HyperEVM chains and Anvil forks.
- Parameters
web3 (web3.main.Web3) – Web3 connection.
private_key (str) – Hex-encoded deployer private key.
- Raises
HyperEVMBigBlocksError – If the Hyperliquid exchange API rejects the big blocks toggle.
- Return type
None