> 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 an **execution 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, USDe and the other OFT stables), ZeroDelta can match and settle wherever the equivalent asset lives and deliver wherever the user wants it. The execution chain is chosen **per order** — every order carries an `executionChainId` that the escrow validates against its allowlist, and the API elects it for you (Ethereum is the default; Base, Arbitrum and Plume are also allowed in the current deployment).

**Most orders are 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 across chains** (for example USDC → USDC) are quoted too, as a **direct bridge**: `isDirect: true`, no swap and no solver fill, the funds leave in the submit transaction itself, and the transfer is **not cancellable**. Only a same token on the *same* chain is rejected, with **`400 BAD_REQUEST`** — a malformed pair rather than a pricing failure, so it does not join the `422` family the other quote refusals belong to. There is nothing to bridge or swap. How a swap 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 execution chain| HUB[Execution-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
```

*Cross-chain legs move over ZeroDelta's own CCTP V2 and LayerZero V2 OFT bridge adapters; Glacis Core provides the GMP status layer.*

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 execution chain. Nothing auto-refunds; the escrow never returns funds on its own. Recovery runs on the order's execution chain — the one named in the quote's `executionChainId` — so it incurs that chain's gas regardless of which chain the order originated on. Which function to call depends on whether the order has arrived yet (`cancel` post-arrival, `claimCancellation` pre-arrival), and a relayer can submit the owner's signed cancel with `cancelFor` — 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 execution 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 and the other OFT stables).
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 `continuing` and the 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.

> **A chained order has two statuses, and only one of them answers "is the user done?"** A chained (two-leg) order — which is what every RWA purchase is — exposes a per-order `status` and a journey-scoped `journeyStatus`. When leg 1 lands, `status` reads `delivered`: that leg genuinely finished. But the value is parked on the destination escrow awaiting leg 2, not in the receiver's wallet, and `journeyStatus` reads `continuing` for that entire window. Completion checks belong on `journeyStatus`, with `status` as the fallback for non-chained orders.

***

### 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.orderRequests[0].bidTokenAmount);
// The quote returns owner/destinationReceiver as null on every element; set both to
// non-zero addresses first, or submitOrder reverts (ZDLite__ZeroAddress).
const requests = data.orderRequests.map((request) => ({ ...request, owner, destinationReceiver }));
// submitOrder takes the ARRAY plus a partnerId (attribution only — pass the zero value).
// 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(requests, PARTNER_ID, { 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 order's execution chain once it bridges, and the read API mirrors it keyed by source transaction hash.

***

### Built on the Glacis Labs stack

* **Glacis Core** — secure cross-chain messaging / GMP abstraction; the Glacis Labs foundation. ZeroDelta uses it for **cross-chain message status**, which is what drives the tracked-transaction lifecycle. See Glacis Core.
* **ZeroDelta's own bridge adapters** — the cross-chain token legs themselves move through adapters that ship with the ZeroDelta contracts (`CctpV2BridgeAdapter` for USDC, `LayerZeroOFTAdapter` for the OFT stables), not through a separate transfer product.
* **Circle CCTP V2** (USDC; burn-and-mint, native 1:1) and **LayerZero V2 OFT** (USDT, USDe and the other OFT stables) — the bridge rails underneath, which govern each cross-chain leg and its timing.
* **Glacis Airlift** is a sibling Glacis Labs product for interchain token transfers. ZeroDelta does **not** route its cross-chain legs through it. See Airlift.

***

### 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 execution chain. Recovery is not automatic. Direct-bridge transfers are the exception: they complete in the submit transaction and have nothing to recover.

> **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 execution 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 and Sherlock; all important findings addressed.