> 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/architecture/wallet.md).

# Wallet, Recovery and Discovery

The wallet turns a note protocol into an account-like product.

## Key hierarchy

The planned hierarchy separates:

* a master recovery secret;
* spending authority;
* incoming note discovery;
* optional scoped viewing access;
* diversified receiving addresses.

One backup should be able to recover the wallet's shielded state without requiring the original browser database. Spending and viewing capabilities should be exportable separately.

## State discovery

The wallet scans commitments and encrypted outputs from the indexer, attempts decryption locally, and checks nullifiers to determine which notes remain spendable. A local database caches this derived state for performance; it is not the source of ownership.

## Note selection

For a payment, the wallet chooses enough notes to cover the amount and fee, then creates recipient and change outputs. Selection should minimize unnecessary merging while avoiding obviously unique public-boundary patterns.

## Recovery

The current Vault exports individual encrypted note backups bound to the connected wallet. The production direction replaces per-note manual recovery with deterministic key recovery plus chain rescan, while retaining optional portable transaction exports for resilience.

## User safety

The wallet should make irreversible boundaries explicit:

* whether a destination is shielded or public;
* which facts become visible during unshielding;
* whether a receiving Stellar account must already exist;
* whether a note backup or recovery key has been verified;
* whether the selected relayer and policy provider are available.


---

# 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/architecture/wallet.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.