# How Omniston Works

Omniston provides a single RFQ-based integration for swaps on TON and cross-chain swaps.

For swaps on TON, Omniston aggregates liquidity from connected TON sources, including AMM DEXs and RFQ resolvers, and returns the best available terms.

For cross-chain swaps, the trader sends an RFQ, resolvers return quotes, and the selected resolver settles the trade so the output asset is delivered on the destination blockchain. HTLC-based settlement uses hashlocks and timelocks to make the cross-chain flow verifiable and atomic.

For role and object definitions, see the [glossary](/developer-section/omniston/glossary.md). Glossary terms match the names used in protocol messages and SDKs.

## Conceptual model

Actors:

* **Trader** - sends an **RFQ**, accepts a quote, and funds a position or signs an order.
* **Resolver** - returns a **Quote** and performs the required settlement actions.
* **Integrator** - an optional partner that may receive an integrator fee in the **Output asset** on the destination blockchain.

Core objects and how they chain together:

1. The **Trader** sends an **RFQ** (request for quote).
2. Resolvers return **Quote** for that RFQ. Several quotes may be available for the same request.
3. In **order settlement**, an **Order** is created from the selected **Quote** and has its own lifecycle.
4. An **Order** may contain multiple **Executions**. Each **Execution** represents one fill attempt or fill fragment, such as a partial fill.
5. **Input position** and **Output position** represent the protocol state of the **Input asset** and **Output asset** for a given **Execution**. **Output position** is used in HTLC-based cross-chain settlement and is not used for intrachain swaps.

**Swap settlement** does not create a persistent **Order** object in the API flow. It uses immediate swap routes instead. **Order settlement** introduces **Order**, **Execution**, reservations, and cancellation semantics.

## Settlement modes

|                             | **Swap settlement**                                                        | **Order settlement**                                                                                               |
| --------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **When settlement happens** | Immediately through one or more **swap routes** made of chunks and steps.  | An **Order** is created first, and resolvers fill it over time.                                                    |
| **Trader action**           | Accepts a quote with a swap payload and follows the swap transaction flow. | Creates or registers an **Order**, either escrow-backed or signed-order / gasless.                                 |
| **Resolver role**           | Provides liquidity according to the selected route.                        | May reserve, complete, or roll back **Executions**; exclusivity and HTLC windows apply.                            |
| **Why data shapes differ**  | A quote carries **routes**, slippage hints, and gas estimates.             | A quote carries **OrderSettlementData**: protocol contracts, HTLC parameters, deadlines, and optional exclusivity. |

Use **swap settlement** for immediate execution through a selected route. Use **order settlement** when the protocol must represent an ongoing position, such as escrow, HTLC, partial fills, or timed phases.

## Intrachain swaps vs cross-chain swaps

In an intrachain swap, the trader sends and receives assets on the same blockchain. In a cross-chain swap, the trader sends the input asset on the source blockchain and receives the output asset on the destination blockchain.

HTLC-specific fields are used only for cross-chain swaps, where the source blockchain and destination blockchain differ.

In intrachain swaps, there is no cross-chain HTLC leg, so HTLC-only fields such as output positions, secret hashes, and security deposits are not included.

**HTLC-based** cross-chain settlement uses:

* **Secret hashes** based on protocol-generated secrets or trader-provided hashes.
* A distinct **Output position** on the destination blockchain, with its own **ExecutionPhase** lifecycle alongside the **Input position**.
* **Completion** and **rollback** windows, plus security deposits on source and/or destination where applicable.

If a field's comment in the schema says **(HTLC-only)** or **omitted for intrachain**, the field is expected to be missing in that flow.

## Supported chains

Each supported blockchain has a fixed `chain_id` that identifies the chain where the input asset is provided or the output asset is delivered.

Supported chains and `chain_id` values:

{% hint style="info" %}

* `1` — Arbitrum (`arbitrum`)
* `2` — Avalanche C-Chain (`avalanche`)
* `3` — Base (`base`)
* `4` — BNB Chain (`bnb`)
* `5` — Ethereum (`ethereum`)
* `6` — Polygon (`polygon`)
* `50` — TON (`ton`)
  {% endhint %}

Chain matching rules:

* `chain_id` must stay consistent across the asset and address used on the same side of the trade.
* The source-side input asset and source-side address must use the same chain.
* The destination-side output asset and destination-side address must use the same chain.
* `intrachain` means source and destination use the same chain.
* `cross-chain` means source and destination use different chains.
* EVM chains use EIP-55 addresses and support `native`, `erc20`, and `erc1155` assets.
* TON uses a valid TON address string and supports `native` and `jetton` assets.

## Lifecycle and timing

The main timers have different meanings:

1. **`quote_validity_timeout`** - protocol parameter visible in resolver events: the maximum duration after quote generation during which the trader must make a valid deposit.
2. **`trade_start_deadline`** - latest timestamp, in UTC seconds, for trade start. Depending on the flow, trade start means that funds are received by the protocol contract or that an order is signed. Resolver behavior after this deadline depends on the specific flow.
3. **`exclusivity_timeout`** - after the trader creates a position, the window in which a resolver must reserve it, including a security deposit where required. When it ends, exclusivity ends: the position may become withdrawable or subject to auction rules per escrow configuration.
4. **`cancellation_available_timestamp`** - on order updates: time after which the trader may cancel the unfilled remainder. Any exclusivity period also ends at this timestamp.

Simplified order-settlement timeline:

RFQ -> quote accepted -> trader opens a position or signs an order -> exclusivity window -> optional public fill phase -> per-**Execution** completion or rollback timestamps -> terminal **Execution** state.

## Execution phases

`ExecutionPhase` represents the lifecycle state of a position. Phases exist separately for the **Input position** and, in HTLC-based cross-chain settlement, for the **Output position**.

Non-final phase groups:

* **Created** - position exists; resolver that holds reservation may proceed where rules allow.
* **Ready for private completion** (HTLC) - on-chain finality reached; reserved resolver may drive successful completion.
* **Ready for public completion** (HTLC) - private window ended; other authorized resolvers may complete under protocol rules.
* **Ready for private rollback** - reserved resolver may initiate rollback.
* **Ready for public rollback** - public rollback; only the **Input position** enters this phase per schema comments.

Final states are **Completed** (successful settlement) and **Rolled back** (assets returned per rules).

HTLC-only phases and **Output position** fields are absent for intrachain swaps by design.

## Amounts and fees

At quote level:

* **`input_units`** - total **Input asset** the trader sends, including fees charged in that leg where applicable.
* **`output_units`** - net **Output asset** the trader receives after integrator and protocol fees.
* **`resolver_sends_units`** (order settlement) - total **Output asset** the resolver must move, including protocol and integrator fees. It is greater than the trader's net output when fees are non-zero, and equal when fees are zero.
* **`integrator_fee_units`** / **`protocol_fee_units`** - fee portions taken in **Output asset** as quoted.

On each **Execution**, the same distinction appears: **`output_units`** vs **`resolver_sends_units`** for that slice of the trade.

## Secrets and disclosure in HTLC

HTLC-based cross-chain settlement depends on hashlocks:

* **`secret_hash`** on an **Execution** is HTLC-only and is not included in intrachain swaps.
* **Order details** (`VersionedHtlcOrderDetails`) carry **`secret_hashes`**, destination receive address, and optional **`trader_dst_disclose_address`** when disclosure must happen at an address distinct from the destination payout address.

Secrets may be generated by the protocol or provided by the trader as ordered secret hashes, aligned with execution/chunk indexing and the quote's hashing function. The secret preimage is disclosed later to complete the cryptographic leg that unlocks funds according to protocol rules.

For integrators: never assume every **Execution** carries secret fields. Check the settlement mode and whether the swap is intrachain or cross-chain first.


---

# Agent Instructions: 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:

```
GET https://docs.ston.fi/developer-section/omniston/how-omniston-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.