> For the complete documentation index, see [llms.txt](https://docs.upshift.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upshift.finance/vault-architecture/upshift-hypercore-relayer/end-to-end-flow.md).

# 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.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.upshift.finance/vault-architecture/upshift-hypercore-relayer/end-to-end-flow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.