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

# Finance & Protocols

Canonical finance and protocol execution model for quotes, credits, payments, effect verification, settlement, reconciliation and provider resilience.

SONIC finance workflows are **server-authoritative, idempotent, evidence-driven and ledger-backed**. A successful provider response, wallet signature or chain confirmation is not itself settlement.

> **Core invariant:** verify the real economic effect first; apply the terminal financial effect second; reconcile third.

## Canonical lifecycle

```
request
→ validate authority + policy
→ resolve immutable quote / pricing context
→ create durable operation
→ reserve / authorize
→ dispatch / submit
→ observe provider or chain result
→ verify expected effect
→ settle OR release/refund
→ reconcile
→ terminal
```

For AI Credits the compact lifecycle is:

```
REQUESTED → RESERVED → DISPATCHED → COMPLETED/FAILED → SETTLED/REFUNDED
```

A reservation prevents double-spend before external work begins. Completion alone does not debit credits until the terminal outcome is verified. A qualifying failure releases the reservation instead of creating a false settled charge.

## Three finance boundaries

| Boundary      | Responsibility                                                  | Must not imply                |
| ------------- | --------------------------------------------------------------- | ----------------------------- |
| Authorization | User/session/wallet/policy permits the proposed operation       | Economic effect occurred      |
| Verification  | Observed provider/ledger/chain result matches the frozen intent | Ledger settlement is complete |
| Settlement    | Apply exactly one terminal accounting effect                    | Reconciliation has finished   |

## Verification criteria

Before settlement, the verifier checks the criteria that apply to the operation class.

### On-chain / wallet operations

* expected network and cluster;
* expected signer / authorized account;
* transaction success at the required commitment/finality policy;
* expected input/output mint or asset;
* exact or policy-accepted atomic amount and decimals;
* expected recipient, treasury, program or reference;
* fee amount and fee recipient where applicable;
* minimum-output / slippage condition where applicable;
* transaction uniqueness and replay protection;
* compatibility with the immutable `TransactionIntent` or quote;
* no terminal-state regression or contradictory evidence.

### Provider payments and external processors

* provider event belongs to the durable SONIC operation;
* trusted provider status is terminal for the expected operation type;
* amount, currency, decimals and merchant/account context match the snapshot;
* provider event/callback has not already produced the terminal accounting effect;
* refund/capture semantics match the provider state;
* provider correlation IDs and evidence are retained for audit.

### AI Credits

* durable generation/DSP operation exists;
* reservation belongs to the same tenant/workspace and operation;
* provider result is a verified terminal success or qualifying terminal failure;
* callback/polling convergence cannot regress terminal state;
* one reservation has at most one terminal accounting outcome.

## Terminal accounting rule

```
one logical operation
+ one reservation / payment intent
→ exactly one terminal financial outcome
```

Allowed terminal outcomes are operation-specific, typically:

* `SETTLED`
* `RELEASED`
* `REFUNDED`
* an explicit authorized reversal workflow when policy supports it

Retries re-enter the same durable operation. They must not create a second debit, refund, provider dispatch or settlement effect.

## Reconciliation

Reconciliation compares the full chain of evidence:

```
quote / catalog snapshot
+ durable operation
+ reservation / payment intent
+ provider or chain evidence
+ verified economic effect
+ accounting effect
= reconciled result
```

A settlement may be operationally complete before reconciliation finishes. If reconciliation detects a mismatch, the system records the mismatch and raises the appropriate operational alert; it does not silently rewrite historical financial state.

## Failure handling

| Failure                                       | Safe behavior                                                                  |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| Client timeout                                | Recover by durable operation / idempotency identity; do not redispatch blindly |
| Provider timeout                              | Keep operation non-terminal until authoritative status is known                |
| Duplicate callback                            | Deduplicate and reuse the existing state transition                            |
| Out-of-order callback                         | Merge monotonically; never regress completed/failed state                      |
| Chain confirmation without expected effect    | Do not settle; classify for retry/manual reconciliation                        |
| Settlement write fails after verified success | Retry the accounting effect only; do not repeat provider/chain execution       |
| Terminal provider failure                     | Release/refund exactly once according to policy                                |

## Evidence and observability

Finance logs and durable records should correlate at minimum:

* `requestId`
* `operationId`
* tenant/workspace/account scope
* idempotency identity
* quote/catalog/policy version
* reservation or payment-intent ID
* provider correlation ID or chain signature
* verification result
* accounting effect
* reconciliation status

Secrets, private keys, raw payment credentials and privileged provider credentials remain server-only.

## Documentation map

* **Credits, subscriptions & decimals** — price snapshots, atomic units, AI Credit reserve/settle/release rules.
* **Verification, settlement & reconciliation** — detailed verification contract and failure matrix.
* **Full-stack finance & protocol wiring** — end-to-end service topology.
* **Web3 Payment Adapters** — Solana Pay, CCTP, x402 and ZK adapter boundaries.
* **Solana payments, QR & protocol integrations** — transaction intent, submission and post-chain 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/finance-and-protocols.md?ask=<question>&goal=<endgoal>
```

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