> For the complete documentation index, see [llms.txt](https://vayyl.gitbook.io/vayyl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vayyl.gitbook.io/vayyl-docs/build-with-vayyl/integration-model.md).

# Integration Model

Vayyl's long-term integration surface is a wallet SDK plus proof-bound Soroban adapters.

## Wallet integration

A wallet integration is expected to provide:

1. shielded key creation and recovery;
2. commitment and ciphertext synchronization;
3. private balance and transaction history reconstruction;
4. receiving-address generation;
5. note selection and local proof generation;
6. relayer discovery, fee quotes, and submission;
7. explicit disclosure of public-boundary metadata.

The SDK should not upload spending keys, note plaintext, or proof witnesses to Vayyl services.

## Application integration

A Soroban application integrates through an adapter that treats Vayyl notes as inputs and outputs. The adapter defines its public statement; the circuit proves the private witness satisfies it.

```
wallet notes
  -> application proof
  -> verifier + adapter state transition
  -> Vayyl output notes or explicit public settlement
```

The adapter must bind contract ID, network, asset, action type, nonce, expiry, and every public settlement parameter. Domain separation prevents a proof prepared for one application from being replayed in another.

## Integration levels

| Level             | Integration                                                          |
| ----------------- | -------------------------------------------------------------------- |
| Private payout    | Application creates an authorized Vayyl output commitment            |
| Private funding   | User consumes notes to fund a public application action              |
| Private state     | Application stores commitments and accepts state-transition proofs   |
| Full private loop | Funding, state updates, and settlement all remain inside Vayyl notes |

The full private loop provides the strongest product value, but also requires the most circuit and contract review.


---

# 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://vayyl.gitbook.io/vayyl-docs/build-with-vayyl/integration-model.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.