Private Wallet

description: Add a Private Wallet to an existing Solana wallet
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, AskUserQuestion, Task, TaskCreate, TaskGet, TaskList, TaskUpdate, TaskOutput, mcp__deepwiki, mcp__helius-docs
---

## Add a Private Wallet to an existing Solana wallet

Voice:
- Point. Then a short, self-contained explanation in a real sentence.
- No fill words.

Current Page: https://www.helius.dev/docs/privacy/integration/wallet.md

Implement in this sequence. Do not skip or rearrange:
1. Shielded keypair derivation
2. Privacy Interface in key management
3. User flows.

Context:
- Docs index: https://www.helius.dev/docs/privacy.md
- Spec: https://github.com/helius-labs/zolana/blob/main/docs/spec.md
- MCP: https://www.helius.dev/docs/privacy/ai-tools.md
- Packages: @heliuslabs/zolana, @solana/kit · zolana-client, zolana-interface, zolana-keypair, zolana-transaction
- Examples: https://github.com/helius-labs/zolana-examples/tree/main/typescript-client · https://github.com/helius-labs/zolana-examples/tree/main/rust-client

Key APIs: ShieldedKeypairLike, ViewingKeyLike, ShieldedKeypairTrait, ViewingKeyTrait, createZolanaClient. Flow APIs: the pages linked from the docs index.

### 1. Index project
- Grep \`ShieldedKeypairLike|ViewingKeyLike|createZolanaClient|@heliuslabs/zolana|zolana-keypair|TSPP/derive\` across src/
- Glob \`**/*.{ts,tsx,js,rs}\` · read package.json / Cargo.toml
- Identify: existing Solana key management, seed vs hardware/MPC, account index, send path, balance/history UI
- Task subagent if multiple packages

### 2. Read references
- WebFetch the current page — both interface languages, both derivation tabs
- WebFetch the docs index — follow the pages for the sequence above. Add on-/off-ramp only if selected in step 3
- WebFetch the spec when protocol behavior is ambiguous (registry, spends, encryption)
- TaskCreate one todo per phase below

### 3. Clarify intention
- AskUserQuestion: Are you using TypeScript or Rust?
- AskUserQuestion: Are you a seed-based wallet, creating tests, or a non-seed-based wallet?
  - Seed-based wallet → derive from the seed phrase
  - Tests → derive from a fixed message
  - Non-seed-based wallet → derive from a fixed message
- AskUserQuestion: Do you want on-/off-ramp?
- AskUserQuestion: Localnet or devnet?
- Summarize. Wait for confirmation before planning

### 4. Create plan
- Do not edit unrelated files. Do not add dead code.
- Take existing code byte for byte. Do not invent APIs, files, or helpers that are not on the fetched pages or in the repo.
- Every claimed path, symbol, and line number comes from step 1 or 2. If it was not read, do not write it.
- ASCII tree of files to add or change. One line per file: path, then what that file does.
- Follow the sequence. If unclear, AskUserQuestion. Present the plan. Wait for approval.

### 5. Implement
- TS: Bash \`pnpm add @heliuslabs/zolana @solana/kit\` if missing
- Rust: add the crates from the SDK page linked from the docs index
- Follow the approved plan. Write/Edit. Do not replace the Solana keypair
- TaskUpdate each step

### 6. Verify
- Every interface method for the chosen language is implemented
- No secrets in logs or network payloads
- TS: Bash \`tsc --noEmit\` + existing tests
- Rust: Bash \`cargo check\` + \`cargo test\` if tests exist
- TaskUpdate complete

### Tools
- mcp__helius-docs for docs pages
- mcp__deepwiki__ask_question("helius-labs/zolana", "<q>")
- WebFetch \`https://www.helius.dev/docs/<path>.md\`
- Task subagent for parallel Grep/Read/WebFetch
- TaskList for remaining work

Invariants:
- Wallet holds the shielded keypair. Never send key material to the Privacy API.
- Implement every method on the chosen language's interface. Do not copy Rust-only methods (\`sign_hash\`, \`nullifier_key\`) onto TypeScript.
- Viewing-key operations are local and synchronous. A sign-only custodian is invalid.
- Use only APIs from the current page, the docs index, and the flow pages in the sequence. If an API is not there, stop and AskUserQuestion.
- Do not log mnemonic, nullifier, viewing key, or the \`TSPP/derive/v1\` signature.
- Language is TypeScript or Rust, not both.
- Assets are SOL, SPL, and Token-2022.
- Every Solana public key of the user can add a Private Wallet. One Solana address maps to one Shielded Address.
- When the recipient of a private transfer does not have a Private Wallet, the Privacy API can resolve the transfer to a private-to-public withdrawal.
We recommend requesting a separate user signature in the UI to ensure the user does not withdraw to a public balance by accident.