> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/solana-and-swap/sonic-swap-documentation-standard.md). # SONIC Swap Documentation Standard Canonical terminology, writing, ownership and cross-reference standard for SONIC Swap documentation. > **Development status** — SONIC Swap remains under active development. Documentation describes the intended server-authoritative contract; it is not evidence of mainnet activation, verified liquidity, completed security review or public availability. This page governs how Swap behavior is documented. It intentionally does **not** duplicate the implementation test matrix. ## Documentation ownership ``` Tokenomics → economic policy API Reference → endpoint, authentication, authorization, idempotency and error contracts Swap Execution, Settlement & Launch Verification → execution behavior → atomic accounting → routing → quote → TransactionIntent → signature / submission → verification → settlement → reconciliation → all production-readiness and test gates Deployment Registry → network → mint / token program / decimals → fee recipient → verified markets → provider configuration Solana → authoritative on-chain execution state ``` A secondary page must link to the owning source instead of copying its checklist. ## Status vocabulary | Status | Meaning | | ------------------ | ------------------------------------------------------------------------- | | `TBA` | Required value intentionally unresolved. | | `Planned` | Approved future capability, unavailable. | | `Prototype` | Experimental or demonstrable. | | `In Progress` | Actively being implemented/integrated. | | `Configured` | Concrete configuration exists; verification incomplete. | | `Devnet Verified` | Expected state independently confirmed on devnet. | | `Mainnet Verified` | Expected state independently confirmed on mainnet. | | `Live` / `Active` | Verified and deliberately enabled for the documented production use case. | | `Paused` | Deployment exists but execution is disabled. | | `Deprecated` | Identifiable but no longer intended for use. | ``` Configured ≠ Verified ≠ Active ``` ## Canonical product description SONIC Swap is a **server-authoritative swap application**. The client requests and explains an operation; routing infrastructure discovers an executable route; the wallet explicitly authorizes the transaction; Solana executes it; and SONIC independently verifies, settles and reconciles the economic result. ## Required execution order ``` trusted token selection → signed session / auth context → access + entitlement checks → wallet + network validation → balance validation → atomic conversion → service fee → slippage policy → route discovery → normalized immutable quote → price-impact validation → TransactionIntent → review → signature → submission → confirmation → effect verification → settlement → reconciliation → receipt ``` For executable swaps, **quote → intent** is mandatory. ## Security-state separation Keep these concepts distinct: authentication, authorization, route access, SaaS entitlement, wallet connection, wallet verification, quote, TransactionIntent, signature, confirmation, effect verification, settlement and reconciliation. ``` wallet connected ≠ wallet verified ≠ transaction authorized SIGNED ≠ SUBMITTED ≠ CONFIRMED ≠ VERIFIED ≠ SETTLED ≠ RECONCILED ``` ## Trusted identity ``` network + mint + token program + verified decimals + registry version = trusted token identity ``` SONIC resolves from the active deployment registry. Symbol, name, logo, explorer result, token list, wallet metadata, social post or permissionless pool is insufficient identity evidence. Production token program and decimals are deployment-controlled; documentation must not hard-code unresolved SONIC production values. ## Atomic amount language Use `AtomicAmount = bigint` for authoritative financial values. Never describe floating-point or display-rounded arithmetic as authoritative settlement behavior. Balance states distinguish `ZERO`, `INSUFFICIENT`, `SUFFICIENT`, `UNAVAILABLE` and `STALE`. ## Fee terminology Current SONIC Swap service fee: ``` 200 bps = 2% ``` Keep SONIC Service Fee, Solana Network Fee, Priority Fee, DEX/Venue Fee, Routing/Provider Fee and any verified token-level transfer fee separate. Do not imply a SONIC token-level transfer fee exists unless the production token configuration verifies one. ## Routing terminology Jupiter is an **aggregator/router**, not a liquidity pool. Raydium, Meteora and Orca are venues only when verified and enabled. Provider output is input to SONIC domain logic, not settlement authority. ## Transaction language A quote is time-bounded and immutable. A `TransactionIntent` is the durable server-created authorization boundary. A signature is user authorization evidence. Confirmation is chain status. Effect verification validates the intended economics. Settlement records SONIC's authoritative economic result. Reconciliation independently compares intended and observed truth. ## Normalized failures Prefer boundary-specific failures: ``` UNAUTHENTICATED SESSION_EXPIRED ACCESS_DENIED ENTITLEMENT_REQUIRED WALLET_REQUIRED WALLET_MISMATCH NETWORK_MISMATCH TOKEN_NOT_TRUSTED BALANCE_UNAVAILABLE INSUFFICIENT_BALANCE INSUFFICIENT_SOL_RESERVE INVALID_AMOUNT QUOTE_UNAVAILABLE QUOTE_EXPIRED QUOTE_MISMATCH SLIPPAGE_OUT_OF_POLICY PRICE_IMPACT_EXCEEDED ROUTE_UNAVAILABLE SIMULATION_FAILED SIGNATURE_REJECTED SUBMISSION_UNCERTAIN TRANSACTION_FAILED VERIFICATION_FAILED SETTLEMENT_FAILED RECONCILIATION_DRIFT PROVIDER_UNAVAILABLE REQUIRES_REVIEW ``` ## Requirement keywords * **MUST / MUST NOT** — mandatory invariant / prohibition. * **SHOULD / SHOULD NOT** — expected default unless an exception is documented. * **MAY** — optional capability. * **TBA** — intentionally unresolved. * **Verified** — checked against authoritative evidence. * **Active / Live** — verified and deliberately enabled. ## Testing and launch ownership There is exactly one canonical readiness source: **Swap Launch Readiness & Verification** in **SONIC Swap — Execution, Settlement & Launch Verification**. Do not reproduce separate: * launch gates; * acceptance-test matrices; * wallet/session test lists; * decimal test lists; * fee test lists; * slippage/price-impact test lists; * provider failure lists; * confirmation/verification tests; * settlement/reconciliation tests. Implementation pages, API docs, runbooks and admin docs should link to the relevant readiness category. ## Release vocabulary ``` NOT_READY → READY_FOR_STAGING → STAGING_VERIFIED → MAINNET_READY → ACTIVE ACTIVE → PAUSED ``` `MAINNET_READY` means the canonical verification suite passed. `ACTIVE` additionally requires verified production configuration and explicit product enablement. ## Documentation invariant Every Swap statement should make clear: ``` what is authoritative + who authorizes it + what state it is in + what may fail + what verifies success + what settles the economic result + what reconciles final state ``` This standard owns terminology. The canonical Swap execution page owns implementation behavior and all production verification. --- # 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, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/solana-and-swap/sonic-swap-documentation-standard.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.