> For the complete documentation index, see [llms.txt](https://docs.glacislabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.glacislabs.com/zero-delta/architecture.md).

# Architecture

### Three components

| Component                   | Who runs it                                         | What it does                                                                                                                                                                                                                                                  |
| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Users / integrators**     | You and your users                                  | Submit orders on-chain and receive the delivered asset. An integrator can submit on a user's behalf.                                                                                                                                                          |
| **Escrow contracts**        | Audited contracts deployed on every supported chain | Hold the user's asset between submission and settlement, and enforce the user's declared terms: destination, minimum output, deadline. The contract is permissionless to call; which assets are eligible is gated at the contract layer (`isSupportedToken`). |
| **Clearing and settlement** | Operated by Glacis today; opens over time           | Matches incoming orderflow, settles the difference, and delivers the destination asset.                                                                                                                                                                       |

Orders clear on a **hub chain**. Because an asset of a given ticker is treated as equivalent across chains through canonical cross-chain transfer (CCTP burn-and-mint for USDC, LayerZero OFT for USDT and USDe), ZeroDelta can match and settle wherever the equivalent asset lives and deliver wherever the user wants it.

**Every order is cross-asset.** An order moves one stablecoin into a *different* stablecoin (for example USDC → USDT); the assets are not interchangeable, so a price has to be set. That price is the firm quote: you request it from the API and submit against it, you do not price the leg yourself. The response carries `askTokenAmount` (the on-chain fill threshold the solver must meet) and `finalAmount` (the expected delivery to the receiver). Same-ticker moves (for example USDC → USDC) are **not** offered through `/quote` today — `fromToken` and `toToken` must differ. How the price is matched is out of scope here; what matters for integration is that the quoted price is the price the order settles at.

***

### How an order clears

```mermaid
flowchart LR
    U[User / Integrator] -->|1. quote| API[ZeroDelta API]
    U -->|2. approve + submitOrder| ESC[Source-chain escrow<br/>holds order until filled or cancelled]
    ESC -->|3. forward order to hub| HUB[Hub-chain escrow<br/>order routing + fulfillment]
    HUB -->|4. orders picked up| SOLV[Glacis-approved solvers]
    SOLV -->|source liquidity| LP[Liquidity providers<br/>various sources, best rate]
    SOLV -->|5. deliver| R[Receiver on destination chain]
    HUB -.->|status events| API
    API -.->|poll status| U
    U -.->|user cancels, then reclaims| HUB
```

*Built on Glacis Core messaging and Glacis Airlift token transfers.*

The dashed cancel path is user-initiated recovery: if an order cannot be settled, the user (or an integrator on their behalf) cancels and reclaims the locked funds on the hub chain. Nothing auto-refunds; the hub never returns funds on its own. Recovery is a hub-chain operation (Ethereum today), so it incurs hub-chain gas regardless of which chain the order originated on. Which function to call depends on whether the order has arrived on the hub yet (`cancel` post-arrival, `claimCancellation` pre-arrival) — see Cancellation for the decision and Trust model.

1. **Quote.** You request a firm quote from the API for a `(fromChain, fromToken) → (toChain, toToken, amount)` pair. The quote carries `lifespanSeconds` — its price-validity window, from the winning provider's signed expiry (`0` when the provider does not sign one, or the quote has lapsed). Treat a quote as short-lived: refetch when `lifespanSeconds` elapses, or periodically (about every 10 seconds) to keep pricing current. The on-chain fill threshold itself does not expire.
2. **Approve and submit.** The user approves the asset to the source-chain escrow (standard ERC-20 `approve`), then calls `submitOrder`. The escrow pulls the asset and locks it. `submitOrder` is the only Zero-Delta-specific call; the preceding approve is a standard ERC-20 transaction.
3. **Settle.** The order is filled on the hub chain at or above the user's declared minimum output (`askTokenAmount`); the escrow verifies the fill meets that floor before releasing funds. Underneath, the source and destination legs move over Circle CCTP V2 (USDC) and LayerZero V2 OFT (USDT, USDe).
4. **Deliver.** The destination asset is delivered to the chosen receiver on the destination chain.

On-chain, the order status moves `Pending → Filled` on the happy path, or `Cancelled` if the user cancels (the `OrderStatus` enum). The **read API uses a different, lowercase status vocabulary** (`pending` / `in_progress` / `outbound_bridging` / `delivered`, plus terminal failure states) — so if you poll the API, compare against its values, not the enum names. You track status either by polling the read API by source transaction hash, or on-chain by `orderId` via `getOrder` / `orderStatuses`; the Reference lists the full status set and the Integration Guide shows a correct poller.

***

### The front end is deliberately standard

There is nothing proprietary to learn on the front end. The deposit pattern is the same **ERC-20 approve + escrow-lock** that many on-chain protocols use:

```jsx
// data is the quote response; see the Integration Guide for the runnable version.
// Exact-amount approve assumes a non-fee-on-transfer token (true for the current stablecoin set).
await erc20.approve(data.escrowAddress, data.orderRequest.bidTokenAmount);
// The quote returns owner/destinationReceiver as null; set both to non-zero addresses
// first, or submitOrder reverts (ZDLite__ZeroAddress).
const request = { ...data.orderRequest, owner, destinationReceiver };
// value covers the bridge messaging fee in the source chain's native token (gasCostSource);
// it is 0 for a USDC/CCTP source. See the Integration Guide for buffer and revert behavior.
await escrow.submitOrder(request, { value: data.gasCostSource });
```

The user signs an approval and one `submitOrder` transaction. Everything after that, matching, settlement, and delivery, is handled by the protocol and ZeroDelta's infrastructure.

***

### What you can rely on

* **Firm quotes.** The price you are quoted is the price the order settles at. No quote-versus-execution drift.
* **A declared floor.** The escrow enforces the user's destination, minimum output, and deadline. An order that cannot meet the declared minimum does not settle.
* **Settlement that holds at size.** Pricing improves with order size rather than decaying against pool depth. An order larger than the depth currently available for a route is declined at quote (`422`) rather than filled at a worse price.
* **A traceable lifecycle.** Every order carries a deterministic ID (`orderId`) and an on-chain record; the canonical record resolves on the hub chain (Ethereum) once the order bridges, and the read API mirrors it keyed by source transaction hash.

***

### Built on the Glacis Labs stack

* [**Glacis Core**](/glacis-core/why-glacis.md) — secure cross-chain messaging / GMP abstraction; the Glacis Labs foundation. See Glacis Core.
* [**Glacis Airlift**](/airlift/why-airlift.md) — interchain token transfers; ZeroDelta uses it for the cross-chain legs. See Airlift.
* **Circle CCTP V2** (USDC; burn-and-mint, native 1:1) and **LayerZero V2 OFT** (USDT, USDe) — the bridge rails underneath, which govern each cross-chain leg and its timing.

***

### Trust model

* **Non-custodial.** User funds move only through audited contracts under conditions the contracts enforce. **ZeroDelta** never holds user balances in an account it controls.
* **Recoverable, but user-initiated.** If an order cannot be settled, the user cancels and reclaims funds on the hub chain. Recovery is not automatic.

> **Operational default worth a risk-committee note:** with `deadline = 0` (the default, no expiry), an unfilled order sits `Pending` indefinitely and **nothing auto-refunds** — funds are recovered only by an explicit user-initiated cancel on the hub chain. For unattended or automated flows, set a real `deadline` so every order has a defined failure point.

* **Upgradeable contracts.** The contracts are currently upgradeable under administrative roles held by Glacis; this is disclosed as an operational risk in the Integration Guide. We intend to move admin roles toward multisig control, with progressive decentralization of governance as a forward direction.
* **Audited.** Smart contracts audited by Halborn; all important findings addressed.