> 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). # 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. 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. 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. In cross-chain flows, the resolver also provides the destination-side liquidity for the selected route. * **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. ## Cross-chain Execution Model For integrators, the most important operational distinction is this: * 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 This is why Omniston cross-chain execution is different from a separate wrapped-asset bridge transfer. Clients integrate one RFQ and settlement model, while resolvers supply the destination-side liquidity per 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. | The intended safety property is that the flow resolves through successful settlement or timed rollback, rather than an unresolved mid-transfer state. ## 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. {% hint style="info" %} Arbitrum, Avalanche C-Chain, and TRON are listed for upcoming support and are not available yet. {% endhint %} Supported chains and `chain_id` values: {% hint style="info" %} * `1` — Arbitrum (`arbitrum`) — *Planned, not available yet* * `2` — Avalanche C-Chain (`avalanche`) — *Planned, not available yet* * `3` — Base (`base`) * `4` — BNB Chain (`bnb`) * `5` — Ethereum (`ethereum`) * `6` — Polygon (`polygon`) * `50` — TON (`ton`) * `60` — TRON (`tron`) — *Planned, not available yet* {% 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 currently support ERC-20 assets only. Native assets should be wrapped. ERC-1155 assets are not supported yet. * 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. ## 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()`** is the authoritative settlement stream for swap settlement. * **`orderTrack()`** is the authoritative settlement stream for order settlement. RFQ keep-alives and quote refreshes cover the pre-submit pricing stage. After a signed order or escrow transfer is submitted, the settlement tracking stream becomes the lifecycle source of truth. ## 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. ### 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. Important implementation rule: * do not disclose purely because the source leg looks completion-ready * prefer disclosing only after the destination-side **Output position** is present and has entered the completion-ready phase required by your flow In practice, this means your app should usually key disclosure off `outputPositionPhase`, not only `inputPositionPhase`. Also note: * a successful `orderDiscloseHtlcSecret()` RPC response does **not** by itself prove that the destination assets are already received by the trader * `orderTrack()` remains the source of truth for the trade lifecycle after disclosure ## 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 If your client stores stream state, keep the last `order` snapshot even if the stream later emits `unsubscribed`. The end of the subscription does not mean the order rolled back. ## How to Read Raw Settlement Data This section is an advanced/reference guide for integrator UIs that expose a panel called `Settlement Data` or a similar debug block. It is easiest to read after the lifecycle, phase, fee, and HTLC sections above, because those sections explain the timing and state concepts that many settlement fields point to. Two practical rules help avoid confusion: * docs and protobuf schemas use `snake_case`, while app UIs often render the same keys in `camelCase` * not every field shown under one UI heading necessarily comes from the same protobuf message For current cross-chain order quotes, most of the contract, HTLC, and timing fields below come from `OrderSettlementData`. Related fee/config values may come from quote-level fields or resolver-side protocol parameters and are often shown nearby in advanced tooling. Field availability depends on the quote type, settlement path, source and destination chains, and API version. Do not build UI logic that assumes every field below is always present. ### Common `OrderSettlementData` Fields | Raw field | Meaning | | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `src_protocol_contract_address` / `srcProtocolContractAddress` | Protocol contract on the **Source blockchain** that enforces settlement. This is the source-side contract your app is ultimately settling against. | | `src_wrapped_native_token_address` / `srcWrappedNativeTokenAddress` | Wrapper contract for the **Input asset** when that asset is native on the source chain, such as `pTON` or `wETH`. Omitted when the input asset is not native. | | `src_initial_resolver_address` / `srcInitialResolverAddress` | Resolver wallet on the **Source blockchain** for which the position is initially reserved during the exclusivity window. If omitted, the position is not exclusively reserved at creation time. | | `src_htlc_security_deposit_asset` / `srcHtlcSecurityDepositAsset` | HTLC-only asset used for the source-side security deposit. This is not part of simple intrachain settlement. | | `src_htlc_security_deposit_units` / `srcHtlcSecurityDepositUnits` | HTLC-only amount of the source-side security deposit, denominated in `src_htlc_security_deposit_asset`. | | `htlc_hashing_function` / `htlcHashingFunction` | HTLC-only hashing function the trader must use when generating secret hashes. If your app provides hashes rather than protocol-generated secrets, they must match this function. | | `dst_protocol_contract_address` / `dstProtocolContractAddress` | HTLC-only protocol contract on the **Destination blockchain** that enforces the output-side leg. | | `resolver_sends_units` / `resolverSendsUnits` | Total **Output asset** moved by the resolver for this order-settlement quote, including protocol and integrator fees. This is not the same as the trader's net `output_units`. | | `dst_wrapped_native_token_address` / `dstWrappedNativeTokenAddress` | Wrapper contract for the **Output asset** when that asset is native on the destination chain. Omitted when the output asset is not native. | | `dst_security_deposit_asset` / `dstSecurityDepositAsset` | HTLC-only asset used for the destination-side security deposit. | | `dst_security_deposit_units` / `dstSecurityDepositUnits` | HTLC-only amount of the destination-side security deposit, denominated in `dst_security_deposit_asset`. | | `trade_start_deadline` / `tradeStartDeadline` | Latest UTC timestamp when the trade must start. In practice, trade start means either funds reach the source-side protocol contract or the order is signed, depending on the flow. | | `exclusivity_timeout` / `exclusivityTimeout` | Duration after position creation during which the initially selected resolver can reserve or fill under exclusivity rules. When this period ends, the flow may move toward public fill, withdrawal, or Dutch-auction logic depending on the escrow conditions. | ### Related Fee and Config Fields Often Shown Nearby * `integrator_fee_pips` / `integratorFeePips` is the requested partner fee rate on the RFQ. In `v1beta8`, one pip is `1/1,000,000` or `0.0001%`. * `protocol_fee_pips` / `protocolFeePips` is the protocol fee rate in pips. In resolver-side protocol parameters, protocol fees are collected in the **Output asset**. * `protocol_fee_recipient_address` / `protocolFeeRecipientAddress` should be treated as advanced/debug metadata. If your UI exposes it, document which API object or protocol message your implementation reads it from. ### UI Guidance for Settlement-Data Panels * Prefer product-language labels over raw protocol keys in the main user-facing flow. * If you expose raw keys, keep them in an advanced/debug view and link them back to the quote or order object they came from. * Do not assume every HTLC-related field will be present. Intrachain flows intentionally omit HTLC-only fields. * Do not assume fields shown in one panel all come from `Quote.order`. Some tools combine quote settlement data, quote-level fee fields, and resolver-side parameters into one visual block. --- # 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 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= ``` 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.