> 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/utxo-model.md).

# UTXO model

## UTXO model

Okkult Shield tracks shielded balances as UTXOs.

A UTXO is a private balance unit that you can spend later with a zero-knowledge proof.

### Think of a UTXO like a sealed envelope

Imagine you place value into a sealed envelope.

Inside the envelope are the amount, the token, and your secret.

On-chain, nobody sees what is inside.

They only see the envelope's fingerprint, called a commitment.

When you want to spend it, you prove that you own the envelope without opening it in public.

### What a commitment is

A commitment is the fingerprint of a shielded balance.

It represents the UTXO without revealing its contents.

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

This commitment is what gets stored on-chain.

The amount, token, and secret stay private.

### What a nullifier is

A nullifier is a second fingerprint created when you spend a UTXO.

It tells the protocol that this UTXO has already been used.

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

### Why nullifiers matter

Nullifiers prevent double-spending.

Without a nullifier, the same shielded balance could be reused more than once.

With a nullifier, the protocol can reject any attempt to spend the same UTXO again.

### Why secrets matter

The secret is what gives you spending control over the UTXO.

Without the secret, the UTXO cannot be spent.

That is why secret storage matters as much as wallet security.

### Where secrets are stored

UTXO secrets are stored locally in your browser.

In Okkult, they are stored in encrypted browser `localStorage`.

{% hint style="warning" %}
Your UTXO secrets are stored locally in your browser.

Clearing your browser data may cause you to lose access to your shielded funds.

Always back up your secrets when prompted.
{% endhint %}

### What happens if you lose your secret

If you lose the secret for a UTXO, you cannot prove ownership of it anymore.

That means the UTXO becomes permanently locked.

The funds are still on-chain, but no one can spend them without the correct secret.

### Simple lifecycle

1. You shield assets into Okkult Shield.
2. The app creates a commitment for the new UTXO.
3. The commitment is added to the Merkle tree.
4. Later, you generate a proof to spend it.
5. The protocol records a nullifier to mark it as used.
6. New UTXOs are created, or funds are unshielded publicly.

### Quick reference

| Item       | Meaning                                         |
| ---------- | ----------------------------------------------- |
| Commitment | The private balance fingerprint stored on-chain |
| Nullifier  | The spend marker that prevents reuse            |
| Secret     | The private value required to spend the UTXO    |
| Storage    | Encrypted browser `localStorage`                |

### Next Steps

* [How it works](/shield/how-it-works.md)
* [Shield assets](/shield/shield-assets.md)
* [Unshield assets](/shield/unshield-assets.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/utxo-model.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.