> 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/finance-and-protocols/verification-settlement-and-reconciliation.md). # Verification, Settlement & Reconciliation Detailed SONIC contract for expected-effect verification, exactly-once settlement/refund and post-settlement reconciliation. This page defines the boundary between **authorization**, **observed execution**, **verified effect**, **accounting settlement** and **reconciliation**. > A signature, provider `success`, HTTP `2xx`, blockchain confirmation or generated artifact is evidence. It becomes financially authoritative only after the expected effect is verified against the original durable intent. ## State model ``` AUTHORIZED → SUBMITTED / DISPATCHED → OBSERVED → VERIFIED | VERIFICATION_FAILED → SETTLED | RELEASED | REFUNDED → RECONCILED | RECONCILIATION_MISMATCH ``` Not every domain uses every label, but the authority boundaries remain the same. ## Expected-effect contract Each money-moving operation freezes the values that later verification must prove. Depending on operation type this includes: | Field | Purpose | | -------------------------- | -------------------------------------------- | | `operationId` | Durable business identity | | `tenantId` / workspace | Ownership boundary | | `network` | Expected chain/network | | `actor` / signer | Authorized initiating identity | | `asset` / `mint` | Expected token/currency | | `amountAtomic` | Exact precision-safe amount | | `decimals` | Interpretation of atomic amount | | `recipient` / program | Expected destination | | `feePolicyVersion` | Immutable fee calculation context | | `quoteId` / price snapshot | Commercial context | | `reference` | Correlation/replay protection where required | | `expiresAt` | Intent validity boundary | Verification compares observed effects against this immutable contract. ## On-chain verification checklist Before settlement, verify all applicable conditions: 1. cluster/network is the intended environment; 2. transaction signature is valid and uniquely associated with the operation; 3. expected signer/account participated as required; 4. transaction succeeded under the required commitment/finality policy; 5. expected mint/asset matches actual balance movements; 6. actual atomic amount and decimals are policy-compatible; 7. expected recipient/program/reference match; 8. fee transfer and fee recipient match the frozen fee policy; 9. minimum output / slippage protection is satisfied for swaps; 10. no unauthorized side effect invalidates the business intent; 11. the operation has not already reached an incompatible terminal state. A confirmed transaction that fails one of these checks is **not settled**. ## Provider verification checklist For external payment or AI providers, verify: 1. callback/poll result belongs to the known provider task/payment ID; 2. provider account/merchant context matches the configured server-side credential domain; 3. status is authoritative for that provider operation class; 4. amount/currency/model/usage data match the frozen SONIC operation context; 5. callback is authentic and replay-safe; 6. monotonic state merge cannot regress terminal state; 7. terminal financial effect has not already been applied. ## Exactly-once accounting effects Settlement/release/refund writes are **retryable**, but the economic effect is unique. Recommended invariant: ``` UNIQUE(operationId, effect) ``` Examples: ``` (operation-123, SETTLE) (operation-456, RELEASE) (operation-789, REFUND) ``` A transient database error may retry the same effect record. It may not create a second logical effect. ## Settlement transaction boundary Where possible, settlement performs these changes atomically: * assert operation is in a compatible verified state; * assert reservation/payment intent has no terminal effect; * write terminal accounting effect; * update reservation/payment state; * update operation financial state; * emit durable outbox/event record for downstream reconciliation. External provider or blockchain execution is **not repeated** inside this database retry. ## Reconciliation Reconciliation proves that independently observable evidence agrees: ``` intent / quote ↕ provider or chain evidence ↕ SONIC accounting ledger ``` ### Reconciled All expected economic effects and ledger entries match. ### Reconciliation mismatch Examples: * chain amount differs from the settled ledger amount; * expected fee recipient did not receive the fee; * provider capture succeeded but SONIC settlement is missing; * SONIC settled but provider reports terminal failure/refund; * duplicate provider event maps to different operations; * token decimals/mint/network differ from the frozen intent. A mismatch should create a durable investigation state and alert. Do not hide it by editing historical evidence. ## Recovery matrix | Situation | Recovery | | ------------------------------------- | --------------------------------------------------------------- | | Verification source unavailable | Retry verification; keep non-terminal accounting state | | Verification deterministically fails | Do not settle; route to failure/recovery policy | | Settlement write failed | Retry the same unique accounting effect only | | Callback arrives after terminal state | Record/deduplicate; do not regress terminal state | | Reconciliation mismatch | Alert + investigate/repair through explicit corrective workflow | | Client retries after timeout | Resolve existing operation by operation/idempotency identity | ## Monitoring and alerts Critical signals include: * verified success with no settlement beyond SLA; * settled operation with missing provider/chain evidence; * reservation stuck after terminal provider failure; * duplicate terminal accounting-effect conflict; * reconciliation mismatch; * repeated RPC/provider unavailability; * terminal-state regression attempt. Logs should include `requestId`, `operationId`, tenant/workspace, provider correlation ID or transaction signature, previous/new state, verification result and accounting effect—without exposing secrets. --- # 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/finance-and-protocols/verification-settlement-and-reconciliation.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.