> 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/architecture-and-runtime/operational-correctness-and-finance-kernel.md). # Operational correctness & finance kernel SONIC v2.2 hardens the AI-native music network around **single ownership of authoritative state, formal state machines, immutable commercial snapshots, versioned policies, replay-safe events, separate ledgers, finance-kernel settlement and continuous reconciliation**. > **Core authority rule:** Client state and provider callbacks are never authoritative for money, rewards, permissions, balances, entitlements or settlement. ## Bounded contexts `SonicProject` remains the creative aggregate without becoming a god object. | Context | Authoritative state | | ------------- | ------------------------------------------------------ | | Identity | creator, profile, verified wallet ownership | | Creation | tracks, stems, generations, versions | | Projects | projects, members, contributions | | Media | artwork, video, files, provenance | | Publishing | releases, distribution, metadata | | Community | posts, challenges, activity | | Marketplace | listings, orders, license offers, entitlements | | Commerce | quotes, payment intents, settlement | | Finance | economic operations, fees, idempotency, reconciliation | | Token | supply, allocations, burns, verified registry | | Network | Blinks, Actions, campaigns | | Participation | seasons, scores, programs, rewards | | Analytics | derived metrics, attribution, reporting | Domains connect through durable IDs and versioned events rather than sharing mutable ownership. ## Finance kernel All value-moving domains use the same operation envelope. ``` VALIDATE → OPERATION → QUOTE / POLICY SNAPSHOT → INTENT → SIMULATE → AUTHORIZE → SUBMIT → CONFIRM → VERIFY → SETTLE → RECONCILE ``` Typical operation types include `SWAP`, `CHECKOUT`, `SOLANA_PAY`, `CREDIT_PURCHASE`, `MARKETPLACE_PURCHASE`, `REWARD_CLAIM`, `VESTING_CLAIM`, `CROSS_CHAIN_TRANSFER`, `TREASURY_TRANSFER`, `LIQUIDITY_DEPLOYMENT` and `TOKEN_BURN`. ## Source-of-truth matrix | Data | Authority | | --------------------------- | ------------------------------------------------------ | | Project state | Project service/database | | AI generation state | Generation service | | AI credits | Credit ledger | | Marketplace/order economics | Immutable listing + quote + order snapshots | | Payment settlement | Finance kernel + verified chain/provider evidence | | Wallet ownership | Verified wallet-link record | | SOL/SPL balance | Verified Solana state | | SONIC allocation | Token allocation ledger | | Token supply | Solana mint state + supply service | | Market price | Market-data observation only | | Reward allocation | Reward ledger | | Claim state | Claim service + reconciliation | | Streamflow state | Verified on-chain schedule mapped to allocation ledger | | CCTP state | Cross-chain operation + destination verification | | Analytics | Derived event data | ## Formal economic state machine ``` CREATED → VALIDATED → QUOTED → INTENT_CREATED → AWAITING_SIGNATURE → SIGNED → SUBMITTED → CONFIRMING → CONFIRMED → VERIFYING → VERIFIED → SETTLING → SETTLED → RECONCILED ``` Terminal/exception states include `EXPIRED`, `REJECTED`, `CANCELLED`, `INVALID`, `FAILED` and `REQUIRES_REVIEW`. Business state, Solana confirmation state and provider state remain separate models. ## Atomic accounting All authoritative financial amounts use integer atomic units with explicit decimals. `Number()` and `parseFloat()` must not be used to perform settlement, fee, reward, liquidity, treasury or burn accounting. Historical quotes and operations retain their decimals, currency, policy version and relevant price snapshot. ## Ledgers SONIC separates **Activity**, **Credit**, **Financial**, **Reward**, **Token Allocation** and **Entitlement** ledgers. A mutable balance, analytics row, provider cache or client cache is never the only record of an economic movement. ## Idempotency and concurrency A logical operation may be observed or retried many times, but produces at most one authoritative settlement. Financial writers enforce operation-scoped idempotency and a single authoritative `SETTLING → SETTLED` transition using database uniqueness/locking or equivalent concurrency controls. Duplicate callbacks, signatures and verification attempts return the existing economic result rather than creating another one. ## Transaction intent integrity Before signature, the server persists the approved purpose, network, payer, recipient, mints/assets, atomic amounts, minimum output where applicable, fees, quote/policy ID and expiry. A canonical intent hash can be used to detect mutation between review and settlement. After confirmation, actual chain effects are compared to the stored intent before settlement. ## Outbox + Inbox Financial/credit business state and its outbox event are written transactionally. Async publishers emit versioned domain events. Consumers persist `(consumer,eventId)` inbox receipts before applying side effects so retries/replays remain safe. Provider webhooks first enter their own durable inbox and never mutate financial ledgers directly. ## Reconciliation Reconciliation is a first-class production layer. Workers cover payments, swaps, credits, rewards, Streamflow, treasury, supply, liquidity, CCTP and burns. A reconciliation result is one of `MATCH`, `DRIFT_DETECTED`, `REQUIRES_REVIEW` or `FAILED`. Only explicitly safe derived state may be automatically repaired. ## Protocol boundaries * Solana is the execution network and authoritative on-chain source after verification. * Helius accelerates RPC/indexing/events. * Jupiter routes swaps; Raydium, Meteora and Orca are venue adapters. * Streamflow provides lock/vesting schedules that must reconcile to allocation state. * Birdeye is analytics only. * Solana Pay transports payment requests. * CCTP transports native USDC cross-chain and requires destination verification. * x402 expresses machine-payment requirements; payments create versioned entitlements. * ZK verifies defined predicates; proof success does not imply financial settlement. ## Provider health and circuit breakers Provider health tracks availability, latency, freshness and error rate. Sensitive writes fail closed when required dependencies or authoritative data are unavailable. Independent feature flags allow swaps, checkout, SOL/SONIC/USDC payments, cross-chain payments, claims, vesting, venue adapters, x402 and ZK verification to be paused without taking unrelated read surfaces offline. ## Policies and commercial snapshots Policies carry `policyId`, integer version and immutable content hash. Historical operations retain the policy version governing fees, price rules, circulating-supply methodology, reward eligibility, burn rules, swap risk and ZK verification. Seller edits, catalog changes or later policy updates cannot rewrite historical economics or rights. ## Chain settlement Chain evidence progresses through `submitted → processed → confirmed → finalized`, with `failed` terminal state. Business workflows select their required threshold according to risk. A wallet submission initiates an action; trusted verification and reconciliation complete settlement. ## Product experience Public product language remains simple: **CREATE → BUILD → RELEASE → GROW → EARN → PARTICIPATE → CREATE AGAIN**. Blockchain complexity stays behind explicit finance surfaces while SONIC utility remains optional and feature-gated. --- # 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/architecture-and-runtime/operational-correctness-and-finance-kernel.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.