> For the complete documentation index, see [llms.txt](https://docs.zama.org/protocol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zama.org/protocol/sdk/vaults/building-a-ui.md).

# Building a vault UI

What a vault UI should show and offer on the form, during the send, and in each batch state.

A vault deposit lives on after its transaction: it sits in a batch until a keeper settles and claims it (see the [Vaults overview](https://docs.zama.org/protocol/sdk/vaults/vaults.md)). A UI that only covers the form leaves users with funds they cannot see or move. This guide lists what to show and offer at each step, so that no state is missing. The layout is yours.

Redemptions go through the same steps: read "shares" for "assets" and the other way around. The examples use the `STABLE` group from [Vault deposits and redemptions](https://docs.zama.org/protocol/sdk/vaults/deposits.md#1-define-a-group).

## The form

| Situation                                      | What to do                                                                                                                                                                                                                                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The balance is encrypted                       | Show it as hidden, with a button to decrypt it. The first decryption asks for a signature, so start it from a click. See [`useConfidentialBalance`](https://docs.zama.org/protocol/sdk/api-references/react/useconfidentialbalance.md).                                   |
| The amount is above the balance                | Disable the button and say why. The SDK checks too, but the user should not learn it from an error.                                                                                                                                                                       |
| A batcher of the group is paused               | [`useOpenBatches`](https://docs.zama.org/protocol/sdk/api-references/react/useopenbatches.md) returns `paused` for each vault. Disable the button and say joins are paused. See [Paused batchers](https://docs.zama.org/protocol/sdk/vaults/advanced.md#paused-batchers). |
| The user wants to know when the batch closes   | `useOpenBatches` returns each vault's `dispatchableAt`: the earliest time the open batch can be dispatched.                                                                                                                                                               |
| A redemption                                   | Label the amount as shares, not assets.                                                                                                                                                                                                                                   |
| A first redemption from a group of N vaults    | Before the user starts, say the wallet may ask for up to N approvals, then the redemption. See [Wallet prompts](https://docs.zama.org/protocol/sdk/vaults/advanced.md#wallet-prompts).                                                                                    |
| The user holds public tokens, not confidential | Shield first with [`useShield`](https://docs.zama.org/protocol/sdk/api-references/react/useshield.md).                                                                                                                                                                    |

## The send

Lock the form while the mutation is pending, so the user cannot send twice. Show "Confirm in your wallet" until `onJoinSubmitted` fires, then "Waiting for the transaction":

```tsx
deposit.mutate({
  group: STABLE,
  vaultId: "beta",
  amount: 1_000_000n,
  onJoinSubmitted: () => setLabel("Waiting for the transaction"),
});
```

When the mutation succeeds, [store the batches](https://docs.zama.org/protocol/sdk/vaults/deposits.md#4-store-the-batches) and say the amount is **queued**, not deposited: the user holds no shares yet.

Two errors need their own handling:

* `ChainMismatchError`: the wallet is on another chain. Prompt a network switch.
* [`VaultJoinUnconfirmedError`](https://docs.zama.org/protocol/sdk/api-references/sdk/errors.md#vaultjoinunconfirmederror): do not offer a plain retry. Handle it as its reference says.

## The batch

Show one entry per join, for the vault the user chose, and read that leg's batch with [`useBatch`](https://docs.zama.org/protocol/sdk/api-references/react/usebatch.md). Pass the account, so the batch lists `claim` and `quit`. Keep every leg's batch anyway: a cancel must quit them all.

| `state`      | What the user sees                     | What the user can do                         | Hook                                                                                          |
| ------------ | -------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `pending`    | Queued, with when it can be dispatched | Cancel, to get the amount back               | [`useQuit`](https://docs.zama.org/protocol/sdk/api-references/react/usequit.md), on every leg |
| `dispatched` | Processing                             | Wait. If it stays too long, settle it        | [`useFinalize`](https://docs.zama.org/protocol/sdk/api-references/react/usefinalize.md)       |
| `finalized`  | Ready                                  | Wait for the keeper's claim, or claim now    | [`useClaim`](https://docs.zama.org/protocol/sdk/api-references/react/useclaim.md)             |
| `canceled`   | Did not go through                     | Wait for the keeper's refund, or get it back | [`useQuit`](https://docs.zama.org/protocol/sdk/api-references/react/usequit.md), on every leg |

Offer an action only when `batch.actions` includes it. Switch on `batch.state` exhaustively, so TypeScript flags a state your UI forgets. In the component below, `legs` are the stored `batches` of the join, and `chosen` is the one the user picked:

```tsx
import { useBatch, useClaim, useQuit } from "@zama-fhe/react-sdk/vaults";
import type { BatchRef } from "@zama-fhe/sdk/vaults";
import type { Address } from "viem";

// `Row` and `formatCountdown` stand in for your own components and helpers.

interface DepositRowProps {
  chosen: BatchRef;
  legs: readonly BatchRef[];
  account: Address;
}

function DepositRow({ chosen, legs, account }: DepositRowProps) {
  const { data: batch } = useBatch(chosen, { account });
  const claim = useClaim();
  const quit = useQuit();

  if (!batch) return <Row label="Loading…" />;

  const quitAll = async () => {
    for (const leg of legs) await quit.mutateAsync(leg);
  };

  switch (batch.state) {
    case "pending":
      return (
        <Row
          label={
            batch.nextChangeAt === null
              ? "Queued"
              : `Queued, sent ${formatCountdown(batch.nextChangeAt)} at the earliest`
          }
          action={
            batch.actions.includes("quit") ? { label: "Cancel", onClick: quitAll } : undefined
          }
        />
      );
    case "dispatched":
      return <Row label="Processing" />;
    case "finalized":
      return (
        <Row
          label="Ready"
          action={
            batch.actions.includes("claim")
              ? { label: "Claim now", onClick: () => claim.mutate({ ...chosen, account }) }
              : undefined
          }
        />
      );
    case "canceled":
      return (
        <Row
          label="Did not go through"
          action={
            batch.actions.includes("quit") ? { label: "Get it back", onClick: quitAll } : undefined
          }
        />
      );
    default:
      return batch satisfies never;
  }
}
```

### Pending

`dispatchableAt` is the earliest time anyone may dispatch the batch, not a promise: word it as "at the earliest". After it, a keeper normally dispatches. You can offer [`useDispatch`](https://docs.zama.org/protocol/sdk/api-references/react/usedispatch.md) as a fallback once `actions` includes `dispatch`.

### Dispatched

A keeper normally settles the batch. If it stays dispatched longer than your app expects, offer `useFinalize`. The delay is yours to pick: the SDK does not decide when a keeper is late.

Past `cancelsAt`, the same `finalize` call **cancels** the batch instead of settling it, so label the button "Cancel and get it back" rather than "Settle". The exception is a redeem batcher whose vault settles redemptions asynchronously: once it has placed its request, `finalize` keeps settling.

### Finalized and canceled

A keeper normally pays the user, so the user often does nothing. `claim` or `quit` stays in `actions` after the payout (see [`Batch`](https://docs.zama.org/protocol/sdk/api-references/sdk/vaultclient.md#batch)), so decide from the deposit whether to keep the entry:

1. Refetch the batch, for example when the list opens. `useBatch` stops polling once the batch is finalized or canceled, so it does not see a keeper's payout.
2. Decrypt the deposit, together with every other leg's deposit, as the [privacy rules](https://docs.zama.org/protocol/sdk/vaults/vaults.md#a-group-hides-which-vault-you-chose) say.
3. A zero on the chosen leg means paid out: remove the entry.

## Checklist

* [ ] The encrypted balance is decrypted only after a click.
* [ ] The send button says why it is disabled: no amount, above balance, paused.
* [ ] A first multi-vault redemption says how many wallet prompts to expect.
* [ ] Every leg's batch is stored and survives a reload.
* [ ] After sending, the UI says "queued", not "deposited".
* [ ] Every `state` has a view, enforced by an exhaustive `switch`.
* [ ] Actions are offered only when `actions` includes them.
* [ ] A cancel quits every leg of the join.
* [ ] A dispatched batch offers `finalize` after a delay you choose, and says when that cancels.
* [ ] A finalized or canceled entry is refetched, and leaves the list once its deposit decrypts to zero.

## Next steps

* [Vault deposits and redemptions](https://docs.zama.org/protocol/sdk/vaults/deposits.md): the SDK calls behind each step
* [`useBatch`](https://docs.zama.org/protocol/sdk/api-references/react/usebatch.md) and [`Batch`](https://docs.zama.org/protocol/sdk/api-references/sdk/vaultclient.md#batch): every field of a batch


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zama.org/protocol/sdk/vaults/building-a-ui.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
