# How Khalani works

> Hub and spokes, mTokens, and what happens to the user's funds from deposit to payout.

Khalani separates accounting and matching from custody and delivery.

- The **hub** is one chain that keeps the books. Orders are published, matched and settled there.
- **Spokes** are the chains your users hold tokens on: Ethereum, Arbitrum, Base and the others. On most spokes a deposit contract holds the real tokens and pays them out. On TRON, deposits go to a per-order deposit address, and an operated bridge service credits them and executes payouts. Spokes run no matching logic.

## mTokens: the hub's ledger

When a user deposits a token on a spoke, the token stays in that spoke's custody, and the hub mints an **mToken**: a one-to-one ledger entry for that token on that spoke. USDC on Arbitrum and USDC on Base are different mTokens.

Everything after the deposit (publishing the order, filling it, settling it) happens in mTokens on the hub. When value leaves, the hub burns the mTokens first and the destination spoke releases the real tokens. Minting on each credited deposit and burning on each withdrawal keeps every mToken backed by the token held in its spoke's custody.

```text
  user wallet ──deposit──► spoke deposit contract ══ relayed ══► hub: mint mToken
                                    ▲                                   │
                                    └──── release ◄═══ relayed ═════ burn mToken
```

## A transfer is a trade

Moving value from chain A to chain B takes three steps, and the middle one is an ordinary trade on the hub:

1. **Deposit on A.** The hub mints mToken-A.
2. **Trade on the hub.** An order exchanges mToken-A for mToken-B, filled by solvers.
3. **Withdraw on B.** The hub burns mToken-B and B's deposit contract releases the real token.

A cross-chain swap changes only the pair in the middle, and a same-chain conversion puts both ends on one spoke. Because every case is a trade in one book, the same liquidity serves all of them.

## The journey of one order

```mermaid
sequenceDiagram
    participant W as User's wallet
    participant A as Spoke A (source)
    participant H as Hub
    participant S as Solvers
    participant B as Spoke B (destination)
    W->>A: deposit (from the order's build)
    A->>H: deposit relayed: mint mToken-A
    H->>H: order published as an intent
    S->>H: fill: mToken-A for mToken-B, at the order's rate
    H->>H: settlement: payout, refund, fees
    H->>B: withdrawal relayed: burn mToken-B
    B->>W: payout released to payoutAddr
```

1. **Build.** The API signs the order's terms: the pair, the amount, the rate, the flat fee, the recipients and the deadline.
2. **Deposit.** The user's wallet sends the deposit to the source spoke's deposit contract, or on TRON transfers it to the order's deposit address.
3. **Relay and publish.** The deposit is relayed to the hub, which mints mTokens and publishes the order as an [intent](/concepts/intents-and-orders/) with those terms.
4. **Fill.** [Solvers](/concepts/solvers-and-solver-markets/) fill the intent, whole or in parts, each part at the order's rate.
5. **Settle.** When the order fills completely, reaches its deadline, or is cancelled, one hub transaction pays the filled part, refunds the unfilled share, and takes the fees.
6. **Pay out.** The hub burns the mTokens and the destination spoke releases the payout to the recipient. Any refund is released on the source spoke the same way.

## Who does what

| Party | Does | Cannot |
|---|---|---|
| **Your backend** | Quotes, builds orders, relays cancels | Move user funds: deposits and cancels need the user's signature |
| **The user's wallet** | Signs the deposit, and any cancel | Change the terms of a built order |
| **Solvers** | Fill orders, competing to do so | Fill below an order's rate: every fill is re-validated on the hub |
| **Khalani's services** | Quote, sign build terms, track orders, sequence fills and settlement, relay messages between chains | Change an order's rate or recipients after it is built |

The [trust model](/concepts/trust-model/) states what the contracts enforce and what depends on operated services.