> For the complete documentation index, see [llms.txt](https://docs.okkult.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.okkult.io/shield/how-it-works.md).

# How it works

## How it works

Shielded balances are represented as private UTXOs.

Each shield action creates a commitment. Each later spend proves ownership and validity without revealing the private balance.

### 1. The UTXO model

Each shielded balance is a UTXO, or unspent transaction output.

A new UTXO is created when a user shields assets into the pool.

Its commitment is:

```
commitment = Poseidon(amount, token, secret, owner)
```

Only the commitment is stored on-chain.

The user stores the secret locally, encrypted in the browser.

Without the secret, the UTXO cannot be spent.

### 2. The Merkle tree

All commitments are inserted into an incremental Merkle tree.

### Tree properties

| Property     | Value                   |
| ------------ | ----------------------- |
| Tree type    | Incremental Merkle tree |
| Depth        | `20`                    |
| Capacity     | `2^20 UTXOs`            |
| Root storage | On-chain                |

The tree root is stored on-chain.

A Merkle path proves that a UTXO exists in the tree without revealing which balance belongs to the user.

### 3. Spending a UTXO

To spend a UTXO, the user generates a zero-knowledge proof for either a transfer or an unshield action.

The proof verifies ownership through the Merkle path and the private secret.

During the spend, the protocol publishes a nullifier:

```
nullifier = Poseidon(commitment, secret)
```

The nullifier prevents the same UTXO from being spent twice.

After a valid spend:

1. The old UTXO is marked as spent.
2. One or more new UTXOs are created, or
3. Value is withdrawn to a public address.

### 4. Three ZK verifier contracts

Okkult Shield uses three verifier contracts for different actions.

| Contract           | Role                                                        |
| ------------------ | ----------------------------------------------------------- |
| `ShieldVerifier`   | Validates shield commitment creation                        |
| `UnshieldVerifier` | Validates unshield actions and reveals the recipient        |
| `TransferVerifier` | Validates private transfers and enforces value conservation |

### Conservation law

Private transfers must preserve value.

```
inAmount === outAmount1 + outAmount2
```

This rule ensures that a spend cannot create value from nothing.

### Next Steps

* [Shield assets](/shield/shield-assets.md)
* [Private transfer](/shield/private-transfer.md)
* [UTXO model](/shield/utxo-model.md)


---

# 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:

```
GET https://docs.okkult.io/shield/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.