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.
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. |
|
Wait until the EVM RPC reports the expected large-block flag state. |
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(note, /)
Add a note to the exception
- with_traceback(tb, /)
Set self.__traceback__ to tb and return self.
- 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(...)
- 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.
- 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.
- 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).
- fetch_using_big_blocks(web3, address)
Check if an address is currently using large blocks.
Calls the HyperEVM-specific
eth_usingBigBlocksJSON-RPC method.This readback is not supported by dRPC and some other third-party HyperEVM RPC providers. For explicit big-block activation checks, use Hyperliquid’s own RPC endpoint.
- 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
- is_hyperevm(chain_id)
Check if a chain ID is HyperEVM (mainnet or testnet).
- 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
- 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
- wait_for_using_big_blocks(web3, address, enabled, timeout=15.0, poll_interval=1.0)
Wait until the EVM RPC reports the expected large-block flag state.
This is useful on HyperEVM testnet where the exchange API toggle may take a moment to become visible through the
eth_usingBigBlocksRPC method.- Parameters
- Raises
HyperEVMBigBlocksError – If the expected state is not observed before the timeout.
- Return type
None