Key Management
Privacy Boost derives a set of privacy keys from a single seed. These keys give the user a private identity — separate from their public wallet address — that can send, receive, and hold shielded tokens.
What Gets Derived
From the seed, the SDK derives three keys that together form the user’s private identity:
| Key | Purpose | Scope |
|---|
| Viewing key | Encrypts and decrypts transaction metadata. Included in your privacy address so others can send you private transfers. | Controls visibility — who can see your balance and transaction history. |
| Nullifying key | Links your identity to your notes. Used to compute nullifiers when spending. | Controls identity — ties specific notes in the shielded pool to your account. |
| Auth key | Authorizes transfers and withdrawals inside ZK proofs. Registered on-chain in the AuthRegistry. | Controls spending — required to move funds. Can be rotated or revoked via your wallet. |
Key Sources
The keySource parameter controls where the seed comes from.
| Key Source | Best for | What the user needs to back up |
|---|
walletDerived | Most apps | Nothing — same wallet always produces same keys |
mnemonic | Cross-wallet portability | The 12-word phrase |
rawSeed | Testing and development | The hex seed |
walletDerived (recommended)
The SDK asks the wallet to sign a deterministic message and uses the signature as the seed. The same wallet always produces the same signature, so the same privacy keys are derived every time. This is the simplest option because the wallet itself is the backup — there’s nothing extra for the user to write down.
mnemonic
The SDK derives keys from a BIP-39 mnemonic phrase. This is useful when you want keys to be portable across different wallets, but the user must securely store the phrase.
rawSeed
A raw 32-byte hex seed. Intended for testing.
// Wallet-derived (recommended)
await sdk.auth.authenticate(adapter, { type: 'walletDerived' });
// From mnemonic
await sdk.auth.authenticate(adapter, { type: 'mnemonic', phrase: 'your twelve word phrase ...' });
Persistence & Protection
Without persistence, the SDK re-derives keys every time the user opens your app (requiring wallet signature popups). With persistence enabled, keys are encrypted and stored locally so returning users can log in silently.
Persistence has two parts: where keys are stored and how they’re protected.
Storage
| Storage | Platform | Notes |
|---|
localStorage | Web | Simple, cleared when users clear site data |
indexedDb | Web | More robust, survives some clear-data actions |
osKeychain | iOS, Android | Platform-native secure storage (Keychain / Keystore) |
Protection (Unlock Method)
You can require the user to unlock stored keys before they’re used:
| Unlock Method | How it works |
|---|
none | Keys are encrypted but accessible without user input |
pin | User enters a numeric PIN each time |
password | User enters a password each time |
biometric | Face ID, Touch ID, or fingerprint prompt (iOS, Android) |
passkey | WebAuthn passkey (experimental) |
pin or password is used, authenticate() returns a credentialRequired result so your app can show the appropriate input. See Authentication — PIN / Password Unlock.
When biometric is used, the platform prompt appears automatically.
Configuration
const sdk = await PrivacyBoost.create({
// ... required fields
persistence: {
storage: 'localStorage', // 'localStorage' | 'indexedDb'
unlock: 'pin', // 'none' | 'pin' | 'password'
},
});
How Persistence Interacts with Key Source
| Returning user? | What happens |
|---|
| First visit (no stored keys) | SDK uses keySource to derive keys, then saves them |
| Returning (keys stored) | SDK loads keys from storage; keySource is ignored |
Session Export & Import
If you don’t want to use persistence, you can manually save and restore sessions on native platforms:
if let session = sdk.exportSession() {
saveToKeychain(session) // You handle secure storage
}
if let session = loadFromKeychain() {
try sdk.importSession(session)
}
Exported sessions contain private keys. Always store them in the platform’s secure storage (Keychain, Keystore, or encrypted storage).
Recovery
Keys are derived deterministically, so recovery is straightforward as long as the original key source is available.
| Key Source | How to recover |
|---|
walletDerived | Log in with the same wallet — same keys are derived automatically |
mnemonic | Provide the same 12-word phrase |
rawSeed | Provide the same hex seed |
Common Recovery Scenarios
Cleared app data or reinstalled the app?
Re-authenticate with the same key source. A new vault is created automatically.
Forgot vault PIN/password?
Clear app storage, then re-authenticate with the original key source. The old vault is discarded and a new one is created. No funds are lost.
Lost device?
Your funds are safe — session data is encrypted on-device. Set up a new device and authenticate with the same wallet or mnemonic.
Switching to a new device?
Either re-authenticate with the same key source, or on native platforms use exportSession() / importSession() to transfer the session directly.
If you used mnemonic and lose the phrase without having an exported session, your keys cannot be recovered. Back up the phrase securely.
Next Steps
- Error Handling — Handle SDK errors with structured error codes
- Keys & Encryption — Deep dive into the key hierarchy, privacy addresses, and 3-way ECDH encryption
Platform-specific session and storage guides:
iOS: Session Storage
Secure Keychain storage and biometric unlock
Android: Session Storage
Android Keystore storage and biometric unlock
React Native: Session Storage
AsyncStorage and Keychain persistence
