# Migration v1beta7 → v1beta8 This guide explains the main changes when migrating from Omniston API `v1beta7` to `v1beta8`. It covers terminology, protocol concepts, and flow changes. It does not cover field-by-field changes or SDK-specific migration steps. `v1beta8` also updates the protocol terminology used across quotes, swaps, orders, resolver operations, and partner fees. Aligning this terminology early makes API usage, monitoring, support, and later SDK migration easier. For terminology definitions, see the [Omniston glossary](/developer-section/omniston/glossary.md). For protocol-level concepts, see [How Omniston Works](/developer-section/omniston/how-omniston-works.md). For application integration, see the [Omniston SDK](/developer-section/omniston/sdk.md). > You can also use an AI coding agent with a **copy-paste prompt** tailored for `@ston-fi/omniston-sdk-react` 0.7 → 0.8: see [AI-assisted migration prompt](/developer-section/omniston/sdk/migration-v0.7-to-v0.8.md#ai-assisted-migration-prompt) (canonical location; includes checklist below it). ## Scope Use this guide if you: * work directly with Omniston protobuf schemas; * operate resolver infrastructure; * maintain backend integrations that reason about the protocol lifecycle; * need to understand why `v1beta8` has a different API model while the product flow is still "quote, create, and settle a trade". If you use Omniston only through an SDK, use this document as protocol context. The practical migration steps for SDK consumers should live in a separate SDK-specific guide. For React apps using `@ston-fi/omniston-sdk-react@0.7`, see the [React SDK v0.7 to v0.8 migration guide](/developer-section/omniston/sdk/migration-v0.7-to-v0.8.md). ## Headline Changes The main change in `v1beta8` is not a simple rename of methods or fields. The API now models Omniston more explicitly as a protocol with distinct objects and lifecycles. In `v1beta7`, many integrations could think primarily in terms of: * a quote; * a trade; * a stream of trade statuses; * separate service surfaces for escrow and gasless flows. In `v1beta8`, the protocol model is: * an `RFQ` produces `Quote` updates; * a quote can lead either to the immediate swap settlement or to order settlement; * an `Order` is a persistent object with its own lifecycle; * an order may have one or more `Execution` records; * HTLC and intrachain flows are represented more explicitly. This means clients should update terminology and flow assumptions instead of expecting a one-to-one mapping from `v1beta7`. ## Terminology Changes The most visible migration work is terminology. `v1beta8` consistently uses language that reflects protocol roles and asset direction more clearly. ### Asset Direction `v1beta7` commonly used `bid` and `ask`. `v1beta8` uses: * `input` * `output` This is a semantic change, not only a rename. The new terms describe the trade from the trader's point of view: * `input` is what the trader provides; * `output` is what the trader receives. For resolvers, `v1beta8` also makes a clearer distinction between: * what the trader receives after fees; * what the resolver must send including fees. ### Addresses and Asset IDs Are Now Different Types `v1beta7` used a single generic `Address` type both for chain addresses and for asset references such as `bid_asset_address` and `ask_asset_address`. `v1beta8` splits these concerns explicitly: * `ChainAddress` for wallet, trader, resolver, contract, and position addresses; * `AssetId` for asset identifiers such as native assets, jettons, ERC-20, or ERC-1155 assets. This is an important migration change, not just a schema cleanup. In `v1beta7`, integrations could treat "asset address" and "account or contract address" as the same kind of value. In `v1beta8`, that assumption is no longer correct: * not every asset is represented by a plain chain address; * native assets are represented as asset kinds, not contract addresses; * asset validation and address validation should now be handled separately. If your integration has shared helpers, database columns, API DTOs, or validation logic for generic "addresses", check whether each field should now use `ChainAddress` or `AssetId`. ### 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. If your old integration used custom network labels or enums, they should be mapped to these values during migration. Supported chains and `chain_id` values: {% hint style="info" %} **`chain_id` values** * `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 %} Migration checklist: * Replace custom network enums, aliases, or ad hoc chain labels with the fixed map above. * Ensure the source-side asset and source-side address use the same chain. * Ensure the destination-side asset and destination-side address use the same chain. * In SDK code, normalize on the chain names `arbitrum`, `avalanche`, `base`, `bnb`, `ethereum`, `polygon`, and `ton`. ### Referral and Integrator Terminology `v1beta7` used `referrer` and `referrer_fee_bps`. `v1beta8` uses: * `integrator` * `integrator fees` * `pips` instead of `bps` This matches the terminology used for partner integrations in the protocol and documentation. If your internal systems still say "referral" or "referrer", update that terminology during migration. This is not only a rename. The fee unit also changed: * `v1beta7` commonly expressed fee configuration in `bps`; * `v1beta8` uses `pips`. If you have internal config, metrics, validation logic, or operator tooling that assumes basis points, treat this as a semantic migration item rather than as a cosmetic terminology update. ### Settlement Terminology `v1beta7` exposed settlement primarily through `SettlementMethod` values such as: * `SWAP` * `ESCROW` * `HTLC` `v1beta8` still distinguishes immediate swap settlement from order-based settlement, but the API is now organized around settlement lifecycles: * `Swap settlement` * `Order settlement` For migration purposes, the important shift is: * `swap settlement` remains the immediate execution path; * `order settlement` becomes the umbrella for flows that create an order or position first and settle it over time; * HTLC semantics are now part of the order lifecycle, not only a separate settlement method. ### Trade Status to Protocol Objects `v1beta7` encouraged clients to reason through `TradeStatus` variants such as: * `AwaitingTransfer` * `Swapping` * `AwaitingFill` * `ClaimAvailable` * `RefundAvailable` * `TradeSettled` `v1beta8` still exposes status, but the primary conceptual building blocks are now explicit protocol objects: * `Quote` * `Order` * `Execution` * `Input position` * `Output position` This means downstream systems should shift from "current trade status enum" to "which protocol object exists, and what phase is it in?". ## Package and API Surface Changes The package namespace changed from `omni.v1beta7` to `stonfi.omni.v1beta8`. This is not only a version bump. It reflects the new public API namespace and schema layout. On the trader side, `v1beta7` exposed several separate services, including: * `QuoteGrpc` * `TradeGrpc` * `GaslessGrpc` * `EscrowGrpc` * `TransactionBuilderGrpc` In `v1beta8`, the trader-facing surface is reorganized around clearer concerns: * `QuoteRpc` for RFQ quote streams; * `SwapRpc` for tracking swap settlement; * `OrderRpc` for order creation, tracking, registration, and cancellation; * chain-specific builder APIs under `trader/chains/`. The resolver API also changed: * `ResolverGrpc` became `ResolverRpc`; * quote handling is expressed through higher-level resolver quote objects; * protocol-specific operations are represented through explicit request types. As a result, clients should map old service usage to the new `QuoteRpc`, `SwapRpc`, `OrderRpc`, resolver APIs, and chain-specific builder APIs. ## Flow Changes The biggest behavioral migration is how clients should think about lifecycle. ### 1. RFQ Is Now a More Explicit Entry Point In both versions, integrations start with a request-for-quote flow. In `v1beta8`, the RFQ model is more explicit and becomes the natural root for the rest of the lifecycle: * an RFQ produces quote updates; * a quote may lead to the swap settlement or order settlement; * the chosen settlement mode determines which API surface and lifecycle follows. In `v1beta7`, clients often moved from quote creation directly to trade tracking. In `v1beta8`, clients should first choose between swap settlement and order settlement. ### 2. Swap Flow and Order Flow Are Separated In `v1beta7`, a single trade-tracking model had to represent several very different flows, including direct swap, escrow, and HTLC cases. In `v1beta8`, these flows are separated: * `SwapRpc` handles immediate swap settlement progress; * `OrderRpc` handles order-based settlement flows. This is one of the most important migration points. Clients should no longer assume that one generic "track trade" stream is the right abstraction for all settlement modes. ### 3. Orders Are First-Class Protocol Objects In `v1beta7`, order-related data existed, but the mental model was still dominated by quote creation and trade status updates. In `v1beta8`, an `Order` is a separate protocol object with: * its own status; * a persistent protocol address or contract context; * cancellation semantics; * one or more executions. This is especially important for integrators that persist protocol state or build operator tooling. Integrations should store and track orders separately from quotes. ### 4. Execution Is a Unit of Settlement Progress `v1beta7` had partial-fill concepts, but they were not as central or explicit. `v1beta8` introduces `Execution` as a clear unit of settlement progress. One order may have several executions, especially when partial filling is involved. For monitoring and analytics, track progress at the execution level: * old mental model: "a trade is moving through statuses"; * new mental model: "an order may accumulate executions over time". ### 5. HTLC Flows Are More Explicit `v1beta7` exposed HTLC-related milestones, but much of the protocol semantics were implied by status names such as `ClaimAvailable` or `RefundAvailable`. `v1beta8` makes HTLC concepts more explicit through dedicated types and order execution data, including: * hashing function; * secret hashes; * input and output positions; * completion and rollback phases; * secret disclosure. For migration, do not treat HTLC only as a trade status branch. Treat it as a protocol flow with positions, timing windows, secret hashes, and completion rules. ### 6. Intrachain and HTLC Flows Diverge More Clearly In `v1beta7`, a lot of complexity was compressed into generic trade tracking. In `v1beta8`, intrachain and HTLC flows use different data shapes and client logic. Clients that use the API below the SDK level should branch earlier by flow type: * intrachain flow; * HTLC flow. That branching now affects how to interpret positions, timings, secrets, and settlement progress. ## Gasless and Escrow Migration `v1beta8` changes how gasless and escrow flows are organized. In `v1beta7`, there were dedicated trader-facing services for: * gasless order operations; * escrow order listing; * transaction building. In `v1beta8`, these concerns are reorganized around the order lifecycle. The execution modes still exist. Instead, `v1beta8` represents them in a more unified way: * gasless orders are part of the order flow; * escrow-backed positions are also part of the order flow; * chain-specific payload building is handled by chain-specific APIs. For migration, the practical takeaway is: * do not look for a one-to-one replacement of every `GaslessGrpc` or `EscrowGrpc` method; * instead, remap your integration around `OrderRpc` plus chain-specific order payload building where needed. ## Resolver Integration Changes In `v1beta8`, resolver integrations work with explicit protocol objects, deadlines, reservations, and settlement constraints. Important conceptual shifts: * resolver quote data is more structured around source and destination roles; * source-side and destination-side responsibilities are clearer; * trade start deadlines, reservations, and order lifecycle matter more; * HTLC-specific responsibilities are more explicit. For resolver operators, this usually means revisiting: * internal naming; * quote construction logic; * monitoring dashboards; * fill, reservation, and cancellation workflows. ## What Usually Needs Renaming Internally Even if your SDK shields you from most wire-level changes, old terminology may still appear in dashboards, logs, metrics, and support runbooks. These are the most common concept-level renames worth making: * `bid` -> `input` * `ask` -> `output` * `referrer` -> `integrator` * `referrer fee` -> `integrator fee` * generic `trade tracking` -> `swap tracking` or `order tracking`, depending on the flow * `gasless API` / `escrow API` as separate top-level concepts -> order flow variants within a single order lifecycle Updating these names early makes `v1beta8` comments, docs, and support material easier to use. ## Suggested Migration Strategy For most teams, start with terminology and flow changes before updating implementation details. 1. Update terminology in internal documentation and code comments. 2. Separate your mental model into RFQ, swap flow, and order flow. 3. Treat orders as durable entities rather than temporary trade artifacts. 4. Treat executions as first-class progress units for order settlement. 5. Review any HTLC handling with the assumption that positions, phases, and secret disclosure are now explicit protocol concepts. 6. Only after that, map the concrete SDK or field-level changes. This reduces mistakes compared with translating protobuf symbols one by one. ## What This Guide Intentionally Does Not Cover This document does not cover: * field-by-field protobuf renames; * exact message compatibility mappings; * SDK method migrations; * generated client code changes; * chain-specific signing details. Those topics should be documented separately where the target audience can act on them directly. ## AI-assisted React SDK migration The copy-paste prompt for Cursor, Codex, and similar agents is maintained in one place: [**AI-assisted migration prompt**](/developer-section/omniston/sdk/migration-v0.7-to-v0.8.md#ai-assisted-migration-prompt) on the React SDK **v0.7 → v0.8** page (same upstream links, prompt block, and manual checklist). For protocol context while the agent works, use the sections above together with the [glossary](/developer-section/omniston/glossary.md). ## Summary Migrating from `v1beta7` to `v1beta8` is mainly a terminology and flow-model migration. The key mindset shift is: * stop thinking only in terms of quote plus trade status; * start thinking in terms of RFQ, quote, swap or order settlement, order lifecycle, execution lifecycle, and explicit HTLC semantics. Teams that align on this model first usually make fewer mistakes during SDK and implementation migration. --- # 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/v1beta7-to-v1beta8-migration-guide.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.