How Omniston Works

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

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.