Private Wallet

A private wallet consists of a Solana keypair for signing, a nullifier key, and a viewing key for encryption – together these keys form the shielded keypair. Your key management holds the shielded keypair. The wallet code uses the Privacy Interface and SDK to build private transactions.

Key management and the Privacy SDK connect through the Privacy Interface. The Privacy SDK calls the Privacy API. The Privacy API submits the transaction to Solana.

The integration enables your users to:

Create a self-custodial private wallet
Receive private transfers with a Solana address
Deposit tokens to a private balance
Send privately to a Solana address
Withdraw to any Solana address
Decrypt private balances and transaction history locally

The integration includes:

Shielded Keypair – in your key management for encryption
Privacy Interface and SDK – to build private transactions
User Flows – to integrate into your wallet

Context for your AI

Add a Private Wallet to an existing Solana wallet

Open in Cursor

View prompt

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.

Integrate the Shielded Keypair

A private wallet integration adds a shielded keypair to your key management. A shielded keypair signs, encrypts and decrypts transactions.The shielded keypair is a bundle of the signing, nullifier, and viewing keys.

Signing key: The wallet’s Ed25519 Solana keypair to sign transactions.
Viewing key: A P-256 keypair, used to encrypt and decrypt transactions.
Nullifier key:

A wallet can create the shielded keypair in two ways:

For seed-based wallets choose Derive from seed phrase.
For non-seed-based wallets choose Derive from EdDSA signature.

Derive from seed phrase
Derive from EdDSA signature

A seed-based wallet derives the shielded keypair from one BIP-39 mnemonic and an account index (0, 1, …).Each account index maps one Solana keypair to one shielded keypair. You can recover the shielded keypair the same way you recover the Solana keypair.For example:

Account 0: Solana keypair 0 and shielded keypair 0
Account 1: Solana keypair 1 and shielded keypair 1

Key	Derivation Path	Scheme
Signing	`m/44'/501'/account'/0'`	SLIP-0010 Ed25519
Nullifier	`m/44'/1392955331'/account'/1'/0'`	SLIP-0010 Ed25519[1..32]
Viewing	`m/44'/1392955331'/account'/2'/0'`	SLIP-0010 NIST P-256

The shielded signing key is that account’s Solana Ed25519 key. The nullifier and viewing keys are additional keys derived from the same seed.

Example Implementation: TypeScript example · Rust example

Derive the shielded keypair from an EdDSA signature over a fixed message. EdDSA signatures are deterministic, so the signature of the same Solana keypair for the same message always produces the same shielded keypair. We use the signature as a seed to derive a shielded keypair.The fixed message payload is "TSPP/derive/v1", encoded as a Solana off-chain message v0.The shielded signing key is the wallet’s Solana EdDSA key. The nullifier and viewing keys are additional keys derived from the signature.

The signature is the derivation seed. Whoever holds it can derive the nullifier and viewing keys and can decrypt user transactions. Reject any sign request for the "TSPP/derive/v1" message from a third party.

Pseudocode to derive a shielded keypair from a Solana signature:

function deriveShieldedKeypair(solanaKeypair):
      solanaPubkey = solanaKeypair.publicKeyBytes() // 32 bytes
	
      payload = UTF8("TSPP/derive/v1")

      // Solana off-chain message v0 envelope
      derivationMessage =
          bytes("\xffsolana offchain")            // 16 bytes
          || u8(0)                                // version
          || SHA256(payload)                      // application domain
          || u8(0)                                // restricted ASCII format
          || u8(1)                                // one signer
          || solanaPubkey
          || u16LE(length(payload))
          || payload

      // Ed25519 signatures are deterministic, so the same wallet produces
      // the same 64-byte seed every time.
      derivationSeed = ED25519_SIGN(
          solanaKeypair.secretKey,
          derivationMessage
      )

      // HKDF-Extract with no salt
      prk = HKDF_SHA256_EXTRACT(
          salt = empty,
          ikm  = derivationSeed
      )

      nullifierSecret = HKDF_SHA256_EXPAND(
          prk,
          info   = UTF8("TSPP/nf_key/ed25519/v1"),
          length = 31
      )

      viewingKeyMaterial = HKDF_SHA256_EXPAND(
          prk,
          info   = UTF8("TSPP/view_key/ed25519/v1"),
          length = 48
      )

      // RFC hash-to-field reduction into a non-zero P-256 scalar
      viewingSecret = P256_SCALAR_FROM_OKM(viewingKeyMaterial)

      return ShieldedKeypair {
          signingKey:    solanaKeypair,
          nullifierKey:  NullifierKey(nullifierSecret),
          viewingKey:    P256Keypair(viewingSecret)
}

Example Implementation: TypeScript · Rust

Integrate the Privacy Interface and SDK

The Privacy Interface enables your code to use the Privacy SDK to build private transactions without accessing the key material directly. Your key management implements the Privacy Interface in two parts.

Signing Interface for Transaction Building with the Privacy SDK. View Source: TypeScript/ Rust
Encryption & Decryption Interface. View Source: TypeScript/ Rust

The Privacy Interface is stateless and therefore does not store balances or transaction history. For performance, we recommend caching user balances and transaction history locally.

On Proof Generation

Zero-knowledge proof generation requires plaintext inputs of the complete user transaction data and nullifier keys.Currently, server proof generation is available through the standard Helius RPC URL.Local proof generation is coming soon. End-to-end encrypted server proof generation on AWS Nitro is planned before mainnet launch.

Integrate User Flows

Create Private Wallet

A private wallet is created in two steps:

Derive the shielded keypair
Register the Solana address in the on-chain registry.

The registry links the signing public key to the nullifier and viewing public keys – together these public keys form the shielded address.

Each registry record is a PDA owned by the , which anyone can look up to see whether a Solana address can receive private transfers.

Sync Private Balance & Transaction History

Balance sync fetches encrypted state from the RPC and decrypts it in the wallet.The RPC does not decrypt. Only the owner can decrypt a private balance with a viewing key.

A wallet should decrypt and update balances before private transactions and wherever it runs backfills: on wallet unlock, private wallet open, app resume, network reconnect, stream gap, or wallet restore.

Read a Private Balance

Read Private Transaction History

Deposit to a Private Balance

Users can deposit to a private balance in two ways:

On-ramp from a fiat balance to a private crypto balance
Deposit from a public SPL account to a private balance

On-ramp and deposit differ in their privacy guarantees. We recommend using on-ramp over deposit for better privacy.

Field	On-ramp from Fiat	Deposit from SPL
Asset	Private	Public
Amount	Private	Public
Source	Not onchain	Public
Destination address	Public	Public

On-/Off-Ramp

On-/Off-ramp fiat directly to and from a private balance.

Deposit

Deposit from a public crypto balance.

Private Transfers

Users can send private transfers to any Solana wallet address.For every private transfer, the Privacy SDK looks up the wallet address in the onchain registry to check if the recipient has a private wallet.The Privacy SDK can resolve a private transfer to a private-to-public withdrawal, when the recipient does not have a Private Wallet.

We recommend labeling the transaction in the UI as a withdrawal to ensure the user does not withdraw to a public balance by accident.

Field	Visibility	Why
Asset	Private	The asset is encrypted onchain
Amount	Private	The transferred amount is encrypted onchain
Source private wallet	Public	In a confidential Ring the source private wallet is visible onchain.
Recipient	Public	In a confidential Ring the recipient is visible onchain.

Private Transfer

Transfer privately to a private balance.

Withdraw to a Public Balance

Withdrawals can be used in two ways:

As fallback for private transfers to recipients that don’t have a private wallet, or
Direct withdrawal to a public SPL token account.

For withdrawals, we recommend clearly labeling that the user is leaving the private balance, similar to a seed phrase or private key export.

Field	Visibility	Why
Asset	Public	The asset is visible onchain
Amount	Public	The withdrawn amount is visible onchain
Source private wallet	Public	In a confidential Ring the source private wallet is visible onchain.
Destination public wallet	Public	The destination wallet address is visible onchain
Destination public balance	Public	The resulting public balance is visible onchain
Remaining private balance	Private	The remaining balance is encrypted onchain

Withdraw

Withdraw to a public crypto balance.

Didn’t find what you were looking for?

Reach out! Telegram | E-Mail | Contact

Get Started

Data Streaming & Event Listening

Data APIs & RPCs

Trading

Sending Transactions

Wallet-as-a-Service

Privacy

Guides

Resources

Context for your AI

Integrate the Shielded Keypair

Integrate the Privacy Interface and SDK

On Proof Generation

Integrate User Flows

Create Private Wallet

Sync Private Balance & Transaction History

Read a Private Balance

Read Private Transaction History

Deposit to a Private Balance

On-/Off-Ramp

Deposit

Private Transfers

Private Transfer

Withdraw to a Public Balance

Withdraw

Didn’t find what you were looking for?

​Context for your AI

​Integrate the Shielded Keypair

​Integrate the Privacy Interface and SDK

​On Proof Generation

​Integrate User Flows

​Create Private Wallet

​Sync Private Balance & Transaction History

Read a Private Balance

Read Private Transaction History

​Deposit to a Private Balance

On-/Off-Ramp

Deposit

​Private Transfers

Private Transfer

​Withdraw to a Public Balance

Withdraw

​Didn’t find what you were looking for?

Context for your AI

Integrate the Shielded Keypair

Integrate the Privacy Interface and SDK

On Proof Generation

Integrate User Flows

Create Private Wallet

Sync Private Balance & Transaction History

Deposit to a Private Balance

Private Transfers

Withdraw to a Public Balance

Didn’t find what you were looking for?