Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypernode-docs.polynode.dev/llms.txt

Use this file to discover all available pages before exploring further.

The HyperLiquid bridge handles all asset movement between the L1 and Arbitrum. It is a validator-voted system: both deposits and withdrawals require quorum agreement from the active bridge validator set before execution. Key numbers:
  • Withdrawal time: ~5 minutes to finalize
  • Withdrawal fee: $1 USDC
  • Quorum: 2/3+ of bridge validator stake weight must agree
  • Bridge validator set: distinct from the consensus validator set, updated when the consensus set changes

​
Bridge state

The bridge maintains several state structures to track in-flight operations:
FieldPurpose
eth_id_to_deposit_votesMaps Ethereum event IDs to deposit vote tallies
finished_deposits_dataCompleted deposit records
withdrawal_signaturesValidator signatures on pending withdrawals
withdrawal_finalized_votesFinalized withdrawal vote tallies
finished_withdrawal_to_timeCompleted withdrawal timestamps
validator_set_signaturesValidator signatures for set updates
validator_set_finalized_votesFinalized validator set update votes

​
Bridge validator set

The bridge validator set is distinct from the consensus validator set. It tracks which validators are authorized to sign bridge operations. 
BridgeEpoch          -- epoch counter for the bridge validator set
BridgePower          -- voting power of a bridge validator
BridgeValidator      -- individual validator in the bridge set
BridgeValidatorSet   -- the full set of bridge validators
ValidatorSetSnapshot -- point-in-time snapshot including:
  stakes             -- validator stake amounts
  jailed_validators  -- currently jailed validators
  consensus          -- consensus participation status
The bridge epoch increments whenever the validator set changes, ensuring that operations signed under an old validator set cannot be replayed.

​
Event identification

Every bridge event on Arbitrum is identified by an EthEventId (the “Eth” prefix is HyperLiquid’s internal naming convention): 
EthEventId:
  block_number  -- Arbitrum block number
  event_type    -- Deposit, WithdrawalFinalized, ValidatorSetUpdate, etc.
  event_index   -- index within the block
  tx_hash       -- Arbitrum transaction hash
This uniquely identifies any event on Arbitrum that the bridge needs to process.

​
Deposit flow

Deposits move assets from Arbitrum to HyperLiquid L1. The flow requires validator quorum before crediting the user.
1

Arbitrum deposit detected

Validators independently observe a deposit event on Arbitrum, identified by its EthEventId.
2

Validators vote

Each validator submits a VoteEthDepositAction referencing the ethId of the L1 event. Votes accumulate in eth_id_to_deposit_votes.
3

Quorum reached

Once sufficient validators have confirmed the deposit, it becomes a FinishedDeposit and is stored in finished_deposits_data.
4

User credited

The deposited USDC is credited to the user’s HyperLiquid L1 account.
If a deposit is determined to be invalid (e.g., the Ethereum transaction reverted or was fraudulent), validators can reject it, resulting in a DepositInvalidated event.
Deposits are the only way to move USDC onto HyperLiquid L1. All deposit events must pass validator quorum — there is no unilateral crediting mechanism.

​
Withdrawal flow

Withdrawals move assets from HyperLiquid L1 to Arbitrum. The process includes a time-lock period and requires validator signatures. Users initiate withdrawals by submitting a withdraw3 action (see Account Actions).
1

User requests withdrawal

The user submits a bridgeWithdrawal action, which emits a WithdrawalRequested event and enters withdrawal_signatures tracking.
2

Time-lock period

The withdrawal enters a pending state with a lockedUntilTimestamp. It cannot be executed until this time passes.
3

Validators sign

Each validator submits a ValidatorSignWithdrawalAction containing the destination address, usd amount, and nonce.
4

Finalization votes

Validators vote on the finalized Arbitrum transaction via VoteEthFinalizedWithdrawalAction, which includes the ethTxHash of the settlement transaction.
5

Withdrawal complete

Once quorum is reached, the withdrawal is marked as WithdrawalFinalized and recorded in finished_withdrawal_to_time. Funds arrive on Arbitrum.

​
Pending withdrawal state

Each pending withdrawal tracks: 
PendingWithdrawals:
  amount               -- USDC amount
  validator            -- assigned validator
  lockedUntilTimestamp -- time-lock before execution
  token / tokenId      -- token being withdrawn

​
Validator set updates

When the HyperLiquid validator set changes, the bridge must update its Arbitrum-side validator set to keep bridge operations secure. This is a multi-step process with its own quorum requirement.
1

Update proposed

A ValidatorSetUpdateAction is created with the new validator set. It includes an associated EthEventId and signature in (r, s, v) Legacy format.
2

Validators sign

Each validator submits a SignValidatorSetUpdateAction containing their signature over the new set. Signatures accumulate in validator_set_signatures.
3

Finalization

Once quorum is reached via validator_set_finalized_votes, a VoteEthFinalizedValidatorSetUpdateAction confirms the update is committed on Arbitrum.
Related event types:
EventDescription
ValidatorSetUpdateThe update event itself
ValidatorSetUpdateEventEvent wrapper for indexing
WithdrawalFinalizedValidatorSetUpdateCombined finalization variant

​
USDC EVM contract

The bridge manages a USDC contract on the HyperLiquid EVM side: 
UsdcEvmContract                 -- the USDC contract on HyperLiquid EVM
usdc_evm_system_balance         -- system balance of USDC in the EVM bridge
initial_usdc_evm_system_balance -- starting balance at genesis

​
L1 transfers

Internal L1 transfers between HyperLiquid accounts can be toggled via a feature flag: 
l1_transfers_enabled -- feature flag controlling L1 transfers
This flag can be modified through governance, appearing alongside disabled_core_writer_actions in the protocol state.