End-to-End Flow
A single deposit travels through the system as follows:
Funds arrive on HyperCore: A user sends supported tokens to the relayer address. Hyperliquid emits a userNonFundingLedgerUpdates event.
Reader receives and filters: Matching messages are placed on message_queue.
Dispatcher fans out: Spawns a task that calls handle_message then handle_non_funding_ledger_updates_data.
Address guard + per-update parsing: The handler confirms the update is for the configured relayer address, then concurrently runs handle_non_funding_ledger_update for every update. That helper parses each deposit, persists a HyperliquidRelayerDeposit record keyed by transfer hash, and enqueues the (transfer_hash, amount, recipient) tuple onto bridge_queue.
Bridge batching: It then checks gas balances, checks the HyperCore balance covers the total, bridges the aggregate amount to HyperEVM via Fordefi, marks all transfers as is_bridged, and forwards each onto deposit_queue.
Deposit batching: Process batched transfers, checks the HyperEVM token balance covers the total, submits one batch_deposit transaction through BatchDepositor and stamps the returned fordefi_id onto every matching deposit row.
Settlement: The vault credits each recipient with shares. Because the deposit call does not wait for confirmation, final on-chain settlement is tracked out of band via the fordefi_id.
Balance prerequisites
The relayer wallet must hold:
enough gas on HyperEVM
enough of the token on HyperCore to cover pending bridges
enough of the token on HyperEVM to cover pending deposits
A failure in any of these checks will surface as a bridge or deposit batch failure.
Recovering failed transfers
Deposits marked is_failed = True in the HyperliquidRelayerDeposit table are the authoritative list of items needing attention. After fixing the root cause, re-enqueue or replay those transfer hashes through the appropriate stage.
Last updated