End-to-End Flow

A single deposit travels through the system as follows:

1. Funds arrive on HyperCore: A user sends supported tokens to the relayer address. Hyperliquid emits a userNonFundingLedgerUpdates event.
2. Reader receives and filters: Matching messages are placed on message_queue.
3. Dispatcher fans out: Spawns a task that calls handle_message then handle_non_funding_ledger_updates_data.
4. 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.
5. 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.
6. 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.
7. 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.