> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/omniston/how-omniston-works.md).

# Settlement lifecycle

Protocol-level Omniston concepts for RFQs, settlement modes, orders, executions, HTLC-based cross-chain settlement, timings, and fees.

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

For swaps on TON, Omniston returns quotes from connected liquidity sources, including AMM DEXs and RFQ resolvers.

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.

In cross-chain flows, the selected resolver provides the destination-side liquidity. The protocol links the source-side and destination-side legs with HTLC rules, so integrators do not need to pre-fund destination-side inventory on every chain they support.

See the [glossary](/developer-section/omniston/glossary.md) for role and object definitions.

## 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. In cross-chain flows, the resolver also provides the destination-side liquidity for the selected route.
* **Integrator** - a partner that receives the configured 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** updates for that RFQ.
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.                        | Follows the selected protocol's reservation, completion, and rollback rules for **Executions**.                    |
| **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. |

Enable the supported settlement modes in the RFQ, then follow the settlement branch returned in the selected quote. Order settlement covers escrow-backed and signed orders, including HTLC cross-chain settlement.

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

## Cross-chain Execution Model

The trader and resolver fund different sides of a cross-chain execution:

* the trader funds the source-side leg
* the selected resolver funds the destination-side leg
* the HTLC rules link both legs so the flow can move toward completion or timed rollback

Clients use one RFQ and settlement model. Resolvers supply destination-side liquidity for the selected route.

## Atomic Outcomes in HTLC Settlement

For app logic, treat an HTLC-based cross-chain execution as converging to one of these outcomes:

| Scenario                                                                             | Result                                                                                                      |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| The destination-side leg completes and the secret is disclosed at the required phase | The trader receives the destination-side assets and the resolver can complete the linked source-side claim. |
| The destination-side leg is not completed in time                                    | The source-side position follows its refund or rollback path under the HTLC deadlines.                      |
| A cross-chain execution rolls back after liquidity was locked                        | The locked positions are unwound according to the same HTLC windows for that execution.                     |

## Chains and asset identities

See [Supported chains and assets](/developer-section/omniston/chains.md) for network identifiers, token addresses, and wallet guides.

## 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 funds to reach the protocol contract or for order signing. Settlement after this deadline is at the resolver's discretion.
3. **`exclusivity_timeout`** - maximum duration from trader position creation to resolver reservation, including the required security deposit.
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.

## Authoritative Streams After Submit

Use different streams for different stages:

* **RFQ stream** (`requestForQuote()` / `useRfq`) is for pricing and reservation updates before you commit to a route.
* **`swapTrack()`** tracks swap settlement.
* **`orderTrack()`** tracks order settlement.

RFQ keep-alives and quote refreshes cover pricing before submission. After submitting the transaction or signed order, track settlement with the corresponding stream.

## 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; the resolver holding its reservation follows the protocol's settlement rules.
* **Ready for private completion** (HTLC) - on-chain finality reached; completion is available to the reserved resolver.
* **Ready for public completion** (HTLC) - private window ended; completion is available to other authorized resolvers.
* **Ready for private rollback** - rollback is available to the reserved resolver.
* **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.

Secret fields are present on HTLC cross-chain executions and omitted for intrachain swaps.

### When to Call `orderDiscloseHtlcSecret()`

In cross-chain HTLC flows, the source-side **Input position** and destination-side **Output position** do not necessarily advance in lockstep.

Disclose the secret after the destination-side **Output position** enters the completion-ready phase required by the flow. Use `outputPositionPhase` to drive disclosure; source-side readiness alone is insufficient.

After `orderDiscloseHtlcSecret()` returns, continue tracking the trade with `orderTrack()`. The RPC response acknowledges disclosure; Order status and Execution phases report settlement progress.

## Reading Completion in Order Settlement

For order settlement, the primary completion signal is **`Order.status`**.

Treat these values as the main user-facing outcomes:

* `TRADE_STATUS_FULLY_FILLED`
* `TRADE_STATUS_PARTIALLY_FILLED`
* `TRADE_STATUS_CANCELLED`
* `TRADE_STATUS_FAILED`

For cross-chain HTLC flows, correlate `Order.status` with per-execution phases:

* use `Order.status` as the headline trade result
* use **Input position** and **Output position** phases to drive operational steps such as secret disclosure, support diagnostics, and advanced UI

Keep the last `order` snapshot when the stream emits `unsubscribed`. This event closes the subscription; settlement outcome is recorded in `Order.status`.

## Settlement field reference

For contract addresses, HTLC parameters, and deadlines, see [API model v1beta8](/developer-section/omniston/swap/v1beta8.md#how-to-read-raw-settlement-data). To implement the flow, use the [JS/TS](/developer-section/omniston/sdk/nodejs.md) or [React](/developer-section/omniston/sdk/react.md) guide.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.