> 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/concepts/how-vayyl-works.md).

# How Vayyl Works

Vayyl converts public Stellar assets into private notes held by the user's wallet. Contracts know that valid value exists, but the wallet keeps the information needed to identify and spend it.

## The lifecycle

```mermaid
sequenceDiagram
    participant U as User wallet
    participant P as Vayyl pool
    participant I as Indexer
    participant R as Relayer
    participant S as Stellar

    U->>P: Shield asset and publish commitment
    P->>S: Lock public asset
    I-->>U: Sync commitment tree
    U->>U: Create outputs and generate proof locally
    U->>R: Submit proof and public instructions
    R->>P: Relay transaction
    P->>P: Verify proof and reject used nullifiers
    P->>S: Publish new commitments or public settlement
```

### 1. Shield

The wallet creates a note and publishes only its commitment. The corresponding Stellar asset moves into the pool. The deposit is public; the note opening remains local.

### 2. Hold

The wallet scans public commitments and uses encrypted note metadata to recover its private balance. The pool does not maintain a public account balance per user.

### 3. Transact

The wallet selects input notes and creates output notes for the recipient and change. A proof enforces ownership and conservation. Only nullifiers and new commitments need to become public.

### 4. Use applications

Instead of unshielding, a user can authorize a proof-bound action: fund a position, commit a hidden order, or receive an application payout. Each application adapter must preserve the same conservation and authorization rules.

### 5. Settle publicly

When value leaves Vayyl, the destination asset and amount required by the public Stellar transfer become visible. A relayer can separate transaction submission from the user's connected Stellar account, but cannot make the public recipient invisible by itself.

## What the current release establishes

The available Vault implements the core commitment → proof → nullifier → settlement path with a fixed note. It is the smallest deployed slice of this architecture, not the intended ceiling of the product.


---

# 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/concepts/how-vayyl-works.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.