Private Vault
The Private Vault is Orbinum's private storage layer for shielded assets. Your balances and transaction history are never recorded on-chain as plaintext — they exist as encrypted notes stored locally in your browser, decryptable only by your wallet. This page covers how the vault works, how to recover notes if you lose your device, and what risks you must understand before using it.
Private Vault is the encrypted store on your device — the notes, their metadata, and the keys to read them.
Shielded pool is the on-chain component: the pallet, the commitments, and the Merkle forest. That is the name used throughout the runtime, the SDK, and the precompile.
Your vault holds the keys to notes whose commitments live in the shielded pool. Losing the vault does not destroy the notes — see Recovery & Rescan below.
How the Vault Works
Every note is stored individually in your browser's IndexedDB, encrypted with AES-GCM 256. Only your wallet can unlock the vault. There is no plaintext balance anywhere on or off-chain.
When you connect your wallet, the app requests a deterministic signature. The vault encryption key is derived from that signature — the same wallet always produces the same key. There is no separate password or seed phrase.
The vault stores notes — each note encodes an asset, an amount, and an owner key. Your displayed balance is the sum of all unspent notes. When you transfer or withdraw, notes are consumed and new ones are created.
The Orbinum team has no access to your vault. There is no cloud backup, no recovery service, and no admin reset. You are solely responsible for maintaining access to your wallet.
Vault Operations
Every interaction with the vault is one of three operations. Private transfer and unshield are each proven with a zero-knowledge proof; shield needs none, since the deposit is public anyway.
Move public tokens from your wallet into the private pool. Your on-chain balance decreases and a new encrypted note is created in your vault. The amount is hidden from that point forward.
Send shielded tokens to another vault user. The sender's note is nullified; a new note for the recipient is created on-chain, encrypted with their viewing key. Neither the amount nor the recipient address is visible on-chain. A small gasless fee is deducted from the input note at proof-generation time and held as a pending balance inside the shielded pool, credited to whoever submitted the transaction — see who receives the fee.
Withdraw shielded funds to a public address, in full or in part. The note is consumed and the equivalent public balance is restored; if you withdraw only part of it, the remainder returns to the pool as a new private note. A small gasless fee is deducted at proof-generation time and held inside the pool, credited to whoever submitted the transaction. The net amount after the fee is what the recipient receives. This is the only operation that makes an amount visible on-chain again.
What your wallet address reveals
Shielding is the one operation that must be signed: it moves tokens you hold publicly into the pool, and only you can authorise spending them. That deposit is visible, and it links your address to the act of depositing — never to an amount inside the pool, or to anything you do afterwards.
Private transfers and unshields are submitted without a signature. Their authorisation is the ZK proof itself, so no wallet is involved, no gas is charged, and no transaction on chain carries your address. An observer sees a nullifier and new commitments appear; nothing connects them to you.
That means a wallet holding only an EVM account signs once, when it deposits. From then on its activity inside the pool is unlinked from the address that funded it.
If the gasless route cannot be submitted — an unreachable node, for instance — a wallet holding an EVM account will fall back to signing through the precompile so the operation still goes through. That publishes an Ethereum transaction naming the address, in exchange for the transfer completing. See choosing a submit route.
Recovery & Rescan
If you lose your device or clear your browser storage, your local notes are deleted. Reconnecting your wallet alone is not enough — recover them either by importing a note backup (instant) or by running a Rescan.
There are two ways to get your notes back on a new device. Both rebuild a fully spendable vault; they differ in speed and in whether you prepared beforehand.
Option A — Import a note backup (instant)
If you exported a note backup before losing the device, importing it rebuilds the vault without touching the chain:
- Connect the same wallet and unlock the vault (sign the key-derivation message).
- Open Import Notes and paste the JSON or choose the exported file.
- Your notes appear immediately — no scan.
The backup is a plain JSON file that carries only public data (each note's commitment and its encrypted memo) — never a spending key. On import, the app decrypts each memo with your own keys: a note that decrypts is yours and comes back spendable; anything that does not is ignored. Because only the file's own memos are tried, this is not a chain scan. See Export & Import Notes below.
Option B — Rescan the chain (no backup needed)
Rescan reconstructs the vault from the chain itself, so it works even with no backup. Rescan is manual — it never runs on its own. Unlocking your vault on a new device, reconnecting, or switching accounts loads whatever notes are already stored locally and stops there; a full scan walks the entire pool and is expensive, so the app only does it when you ask.
- Connect the same wallet you originally used to set up the vault.
- Sign the vault key derivation message when prompted. This regenerates the same encryption key from your wallet.
- Run Rescan from the vault settings. The app scans the blockchain indexer for all encrypted commitments and attempts to decrypt each one with your key.
- Wait for the scan to complete. Progress is shown in real time (notes scanned, notes found). Duration depends on total chain activity.
- Recovered notes appear in your vault with their current spend status verified on-chain.
Rescan works because every note's contents travel on-chain inside an encrypted memo that only your keys can open. A view tag lets the scan skip ~255 of every 256 foreign notes, so it is far cheaper than it sounds. See Note Discovery for the mechanism.
What can be recovered
- Notes from shielded deposits you made
- Notes received via private transfers
- Both spent and unspent notes
- Notes never submitted to the chain
- Local drafts or test notes
- Notes created with a different wallet
Export & Import Notes
You can move your notes between your own devices as a JSON note backup — without re-scanning the chain.
Export (Private Vault → Export JSON) produces a JSON file — or copies it to
your clipboard — holding every note as { commitment, encrypted memo }. It is a
closed backup: it carries only data that is already public on-chain and no
spending keys, so the file grants nothing on its own.
Import (Private Vault → Import Notes) takes that file or pasted text and decrypts each memo with your wallet's keys. A memo that opens is your note and is restored fully spendable; a memo that does not open belongs to someone else and is skipped. This proves ownership by decryption and needs no chain scan — so importing someone else's backup recovers nothing.
A backup is the fast path you prepare in advance; Rescan is the fallback that always works from the chain. Notes stay spendable after import even without a Merkle proof — the proof is fetched fresh from the chain at spend time.
Payment Slips
When you send a private transfer to someone else, the recipient's note lives
on-chain inside an encrypted memo only they can open — so normally they have to
Rescan the whole pool to find it. A payment slip skips that: the sender
hands the recipient a short orbslip1:… string, and the recipient rebuilds the
note instantly, without scanning.
A slip carries only data that is already public on-chain — the recipient output's commitment and its encrypted memo — sealed toward the recipient, so an interceptor who copies the slip learns nothing, not even that a payment is coming. It grants no spend power: the recipient still derives their own stealth spending key from their identity, and a forged slip rebuilds nothing because the recomputed commitment must match the chain.
Sharing a slip (sender)
Right after a private transfer to another user confirms, the app raises a payment slip dialog so you can capture it immediately and send it to the recipient (chat, email, anywhere).
The slip is also kept with that transaction, so you can re-share it later: find the private transfer in the transaction table and copy its slip from the row.
Importing a slip (recipient)
Open Private Vault → Import Slip, paste the orbslip1:… string, and import.
The app opens the slip with your keys, rebuilds the note, and marks it available —
no chain scan. A slip that is not yours (it does not decrypt) imports nothing.
A payment slip recovers one note the moment it is sent — the recipient never has to scan. A note backup is your own whole-vault export for moving between your devices. Rescan is the always-works fallback from the chain. A slip carries only public data and no spending key, exactly like a backup.
Recovering what you sent
Restoring from your seed phrase brings back both halves of your history: the notes you received, which are on chain for Rescan to find, and the payments you made, which are encrypted toward the people you paid and cannot be reopened with your own keys directly.
Recovering what you sent costs nothing extra on chain. Your wallet derives the one-time keys on its outgoing notes from your seed instead of drawing them at random, so a restored wallet can regenerate the same sequence and recognise its own payments among everyone else's. The recipient's viewing key travels back to you inside your own change note, in a field the commitment never covers. Rescan rebuilds your outgoing history with the exact amount and recipient.
Two consequences worth knowing:
- You can re-issue a payment slip for an old transfer. If a recipient lost theirs, or you never sent one, you can produce a fresh slip for that payment from the recovered history. It opens to the same note; only the envelope differs.
- Nothing signals whether you kept the ability. The derived keys are indistinguishable from random ones without your outgoing viewing key, so a transfer from a wallet that recovers looks exactly like one from a wallet that does not.
A transfer that leaves no change note has nowhere to carry the recipient's key, so it is recovered as a payment you made without the counterparty attached.
The keys are derived from your outgoing viewing key, a sibling of your incoming one rather than something derived from it. Sharing one does not grant the other: an auditor given the outgoing key sees what you sent and nothing you received. See Note Discovery.
Watch-only wallets
Because v3 derives every secret as a separate branch of your seed, read access can
be handed out without spend authority. exportViewingCredential produces a
credential that omits the spending key by type — not by a runtime check, so a
credential cannot carry spend authority by accident.
import { deriveIdentity, exportViewingCredential } from '@orbinum/sdk';
const identity = deriveIdentity(rootSecret, 'v3');
// Sees what arrived. Cannot spend, cannot see what you paid.
const readOnly = exportViewingCredential(identity);
// Adds payment history — hand this over only deliberately.
const auditor = exportViewingCredential(identity, { includeOutgoing: true });
includeOutgoing is opt-in for a reason: the incoming key reveals what you
received, while the outgoing key reveals who you paid. The second is the
payment graph, a strictly larger secret than a list of amounts.
A v3 spending key on its own decrypts nothing and spends nothing. The scalar that spends a received note is derived from the shared secret, which comes from the viewing key — so a wallet has to hold both. Back up the root, not one key.
Best Practices
- Keep your wallet seed phrase safe. It is required to regenerate your vault key. Without it, neither import nor Rescan can recover your notes.
- Do not clear browser storage or uninstall the app without a backup — local notes will be lost.
- Export a note backup regularly and keep the file somewhere safe. Restoring from it is instant; a full Rescan of a busy chain is not.
- Use Import or Rescan whenever you switch devices or after a browser data reset, not just when notes seem missing.
FAQ
Can I export or back up my notes?
Yes. Use Export JSON to save (or copy) a note backup, and Import Notes on another device to restore it — see Export & Import Notes. The backup holds only public data (commitments and encrypted memos), never spending keys, and is restored by decrypting the memos with your own keys. Importing needs no chain scan, and importing a backup that is not yours recovers nothing. Rescan remains available as a no-backup fallback.
Someone sent me a private transfer — do I have to Rescan to get it?
No, if they give you a payment slip. Open Private Vault → Import Slip, paste the orbslip1:… string, and the note is rebuilt instantly — see Payment Slips. The slip holds only public data (the commitment and encrypted memo), never a spending key, and only opens with your keys. Without a slip, Rescan still finds the note the usual way.
What if Rescan finds fewer notes than expected?
The scan can only find notes that were committed on-chain and encrypted with your viewing key. Notes that were created locally but never submitted, or notes created with a different wallet, will not be found. If you believe notes are missing after a complete scan, verify the wallet address matches the one used to originally shield the funds.
Is my vault safe if my device is stolen?
Yes, under normal conditions. The vault key is never stored in plaintext — it is derived from your wallet signature at unlock time and kept only in memory for the session. An attacker with your device cannot read your notes without also controlling your wallet. Ensure your wallet application and device are properly protected.
If I reconnect my wallet on the same device, do I need to Rescan?
No. If your local IndexedDB is intact, reconnecting your wallet and signing the key derivation message is sufficient to unlock and read your existing notes. Rescan is only needed when local storage has been lost or you are setting up on a new device.