> For the complete documentation index, see [llms.txt](https://docs.useshadowpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.useshadowpay.com/protocol-and-architecture/protocol-overview.md).

# Protocol Overview

ShadowPay's on-chain layer is built on Solana Token-2022 (Token Extensions), using the Confidential Balances extension as its privacy primitive. Unlike a typical fintech product, ShadowPay doesn't run its own settlement ledger. Settlement is Solana itself.

***

## What the protocol layer does

1. **Custody and signing:** every account is a standard Solana keypair, generated client-side. ShadowPay never holds keys.
2. **Confidential transfers:** transfer amounts are encrypted using the Confidential Balances extension, with proof generation happening on the client.
3. **Gas abstraction:** a small SOL reserve is maintained per account automatically and topped up via an internal swap when it drops below threshold, so users only ever think in USDC.
4. **Agent policy enforcement:** spend policies are checked client-side, in the agent's signing flow, before a transaction is ever constructed.
5. **Indexing:** on-chain events are indexed off-chain via Helius webhooks, powering the real-time feed and webhook system without requiring any party to poll the chain directly.

Everything that requires trust, meaning custody of funds and the validity of a transfer, is enforced by Solana's runtime and the Token-2022 program. Everything else, UI rendering, notifications, indexing, is a convenience layer on top.

***

## Stack

```
+-----------------------------------------------+
|              ShadowPay App Layer               |
|      Web app . Mobile (iOS/Android) . SDK      |
+---------------------+---------------------------+
                       |
+---------------------v---------------------------+
|              ShadowPay API Layer                |
|   REST + WebSocket . Agent API . Webhooks       |
+---------------------+---------------------------+
                       |
+---------------------v---------------------------+
|            ShadowPay Core Services              |
|                                                 |
|  Wallet Engine   Privacy Engine   Agent Engine  |
|  (key mgmt,      (ZK proof gen,   (spend        |
|   tx building)    client-side)    policies,     |
|                                    x402 handler) |
|                                                 |
|  Indexer (Helius webhooks + PostgreSQL)         |
+---------------------+---------------------------+
                       |
+---------------------v---------------------------+
|                Solana Mainnet                   |
|  Token-2022 . Confidential Balances . x402      |
+-----------------------------------------------+
```

***

## Trust model

* **Users** don't need to trust ShadowPay with their funds. Keys are generated and held on-device; ShadowPay's servers see signed transactions, never private keys.
* **Users** don't need to trust ShadowPay with their transaction amounts. Proof generation and decryption happen client-side. ShadowPay's backend only ever handles ciphertext.
* **Agents** operate under spend policies enforced at the signing layer, not by ShadowPay's discretion after the fact. A transaction that violates policy is never produced.

***

## Further reading

* [On-Chain Architecture](/protocol-and-architecture/on-chain-architecture.md): the Token-2022 account layout underneath ShadowPay
* [Trust & Security Model](/protocol-and-architecture/trust-and-security.md): the full security layer breakdown


---

# 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://docs.useshadowpay.com/protocol-and-architecture/protocol-overview.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.