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.

These keys are designed with separation of concerns: the viewing key handles privacy, the nullifying key handles identity, and the auth key handles fund custody. This means a single key being exposed doesn’t give full access — for example, leaking the viewing key reveals your balance but doesn’t allow anyone to spend your funds. For the full security model and threat analysis, see Keys & Encryption. Your Master Public Key (MPK) and privacy address are derived from these keys. The MPK is your public identity in Privacy Boost — safe to share. The privacy address is what you give to others so they can send you private transfers.

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, { keySource: { type: 'walletDerived' } });

// From mnemonic
await sdk.auth.authenticate(adapter, { keySource: { type: 'mnemonic', phrase: 'your twelve word phrase ...' } });

// Wallet-derived
try await sdk.authenticate(wallet: wallet, keySource: .walletDerived())

// From mnemonic
try await sdk.authenticate(wallet: wallet, keySource: .mnemonic(phrase: "your twelve word phrase ..."))

// Wallet-derived
sdk.authenticate(wallet, keySource = KeySource.WalletDerived())

// From mnemonic
sdk.authenticate(wallet, keySource = KeySource.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)

When 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'
  },
});

let config = PrivacyBoostConfig(
    // ... required fields
    persistenceStorage: .osKeychain,
    persistenceUnlock: .biometric
)

val config = PrivacyBoostConfig(
    // ... required fields
    persistenceStorage = StorageBackend.OsKeychain,
    persistenceUnlock = UnlockMethod.Biometric
)

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

This means a user only needs to provide their mnemonic once. After that, keys are loaded from storage.

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)
}

sdk.exportSession()?.let { saveToSecureStorage(it) }

loadFromSecureStorage()?.let { sdk.importSession(it) }

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

Funds are never lost. Deposits live on-chain in the shielded pool. Once keys are re-derived, the SDK automatically finds and restores your balance.

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

Quickstart

Setup

SDKs

Key Management

Key Management

What Gets Derived

Key Sources

walletDerived (recommended)

mnemonic

rawSeed

Persistence & Protection

Storage

Protection (Unlock Method)

Configuration

How Persistence Interacts with Key Source

Session Export & Import

Recovery

Common Recovery Scenarios

Next Steps

iOS: Session Storage

Android: Session Storage

React Native: Session Storage

​Key Management

​What Gets Derived

​Key Sources

​walletDerived (recommended)

​mnemonic

​rawSeed

​Persistence & Protection

​Storage

​Protection (Unlock Method)

​Configuration

​How Persistence Interacts with Key Source

​Session Export & Import

​Recovery

​Common Recovery Scenarios

​Next Steps

iOS: Session Storage

Android: Session Storage

React Native: Session Storage

Key Management

What Gets Derived

Key Sources

walletDerived (recommended)

mnemonic

rawSeed

Persistence & Protection

Storage

Protection (Unlock Method)

Configuration

How Persistence Interacts with Key Source

Session Export & Import

Recovery

Common Recovery Scenarios

Next Steps