Ví riêng tư

Ví riêng tư bao gồm một cặp khóa Solana để ký, một khóa nullifier và một khóa xem để mã hóa – các khóa này cùng nhau tạo thành cặp khóa được che chắn. Hệ thống quản lý khóa của bạn lưu giữ cặp khóa được che chắn. Mã ví sử dụng Privacy Interface và SDK để tạo các giao dịch riêng tư.

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.

Việc tích hợp cho phép người dùng:

Tạo ví riêng tư tự lưu ký
Nhận các giao dịch chuyển riêng tư bằng địa chỉ Solana
Nạp token vào số dư riêng tư
Gửi riêng tư đến một địa chỉ Solana
Rút về bất kỳ địa chỉ Solana nào
Giải mã cục bộ số dư riêng tư và lịch sử giao dịch

Việc tích hợp bao gồm:

Cặp khóa được che chắn – trong hệ thống quản lý khóa của bạn để mã hóa
Privacy Interface và SDK – để tạo các giao dịch riêng tư
Luồng người dùng – để tích hợp vào ví của bạn

Ngữ cảnh cho AI của bạn

Add a Private Wallet to an existing Solana wallet

Mở trong 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/spr, @solana/kit · zolana-client, zolana-interface, zolana-program, 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, createSprClient. Flow APIs: the pages linked from the docs index.

### 1. Index project
- Grep \`ShieldedKeypairLike|ViewingKeyLike|createSprClient|@heliuslabs/spr|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/spr @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.

Tích hợp cặp khóa được che chắn

Việc tích hợp ví riêng tư sẽ thêm một cặp khóa được che chắn vào hệ thống quản lý khóa của bạn. Cặp khóa được che chắn dùng để ký, mã hóa và giải mã giao dịch.Cặp khóa được che chắn là một gói gồm khóa ký, khóa nullifier và khóa xem.

Khóa ký: Cặp khóa Ed25519 Solana của ví dùng để ký giao dịch.
Khóa xem: Một cặp khóa X25519 dùng để mã hóa và giải mã giao dịch.
Khóa nullifier:

Ví có thể suy ra cặp khóa được che chắn từ chữ ký EdDSA trên một thông điệp cố định.Chữ ký EdDSA có tính xác định, vì vậy chữ ký của cùng một cặp khóa Solana cho cùng một thông điệp luôn tạo ra cùng một cặp khóa được che chắn. Chúng tôi sử dụng chữ ký làm seed để suy ra một cặp khóa được che chắn.Payload của thông điệp cố định là "TSPP/derive/v1", được mã hóa dưới dạng thông điệp ngoài chuỗi Solana v0.Khóa ký được che chắn là khóa EdDSA Solana của ví. Khóa nullifier và khóa xem là các khóa bổ sung được suy ra từ chữ ký.

Chữ ký là seed dùng để suy ra khóa. Bất kỳ ai nắm giữ chữ ký đều có thể suy ra khóa nullifier và khóa xem, đồng thời giải mã giao dịch của người dùng. Từ chối mọi yêu cầu ký thông điệp "TSPP/derive/v1" từ bên thứ ba.

Mã giả để suy ra một cặp khóa được che chắn từ chữ ký Solana:

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
      )

      viewingSecret = HKDF_SHA256_EXPAND(
          prk,
          info   = UTF8("TSPP/view_key/ed25519/x25519/v1"),
          length = 32
      )

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

Ví dụ triển khai: TypeScript · Rust

Tích hợp Privacy Interface và SDK

Privacy Interface cho phép mã của bạn sử dụng Privacy SDK để tạo các giao dịch riêng tư mà không cần truy cập trực tiếp vào dữ liệu khóa. Hệ thống quản lý khóa của bạn triển khai Privacy Interface theo hai phần.

Giao diện ký để tạo giao dịch bằng Privacy SDK. Xem mã nguồn: TypeScript/ Rust
Giao diện mã hóa và giải mã. Xem mã nguồn: TypeScript/ Rust

Privacy Interface không có trạng thái nên không lưu trữ số dư hoặc lịch sử giao dịch. Để cải thiện hiệu năng, bạn nên lưu cục bộ số dư và lịch sử giao dịch của người dùng vào bộ nhớ đệm.

Về việc tạo bằng chứng

Việc tạo bằng chứng không kiến thức yêu cầu đầu vào dạng văn bản thuần của toàn bộ dữ liệu giao dịch người dùng và các khóa nullifier.Hiện tại, tính năng tạo bằng chứng trên máy chủ được cung cấp thông qua URL RPC Helius tiêu chuẩn.Tính năng tạo bằng chứng cục bộ sẽ sớm ra mắt. Trình tạo bằng chứng mặc định của các SDK là một enclave AWS Nitro đã được chứng thực.

Tích hợp luồng người dùng

Tạo ví riêng tư

Ví riêng tư được tạo theo hai bước:

Suy ra cặp khóa được che chắn
Đăng ký địa chỉ Solana trong một registry trên chuỗi.

Việc tạo ví riêng tư không yêu cầu nạp tiền vào số dư riêng tư.

Trong ứng dụng ví, bạn có thể cho phép người dùng tạo ví riêng tư chỉ cho một khóa công khai “Private Wallet” chuyên dụng hoặc cho bất kỳ khóa công khai nào.

Registry liên kết khóa công khai dùng để ký với các khóa công khai nullifier và khóa xem. Các khóa công khai này cùng nhau tạo thành địa chỉ được che chắn.

Mỗi bản ghi registry là một PDA thuộc sở hữu của . Bất kỳ ai cũng có thể tra cứu để xem một địa chỉ Solana có thể nhận giao dịch chuyển riêng tư hay không.

TypeScript Client
Rust Client

import { MergeEncryptionScheme } from "@heliuslabs/spr";
import {
  getRegisterInstructionAsync,
  getSetMergeEncryptionInstructionAsync,
} from "@heliuslabs/spr/instructions";
import { isWalletRegistered } from "@heliuslabs/spr/wallet";

await sendTransaction([
  await getRegisterInstructionAsync({
    owner: signer,
    nullifierPublicKey: address.nullifierPublicKey,
    viewingPublicKey: address.viewingPublicKey.toBytes(),
  }),
  await getSetMergeEncryptionInstructionAsync({
    owner: signer,
    scheme: MergeEncryptionScheme.PoseidonCtrV1,
  }),
]);

const registered = await isWalletRegistered({
  rpc: client,
  owner: signer.address,
});

owner là người ký Solana của người dùng, được dùng để suy ra PDA registry.
address là địa chỉ được che chắn của người dùng.
getRegisterInstructionAsync đăng ký các khóa của địa chỉ được che chắn.
getSetMergeEncryptionInstructionAsync bật tính năng hợp nhất cho các UTXO của người dùng. Một giao dịch chuyển có thể chi tiêu tối đa 40 UTXO, vì vậy việc hợp nhất đảm bảo người dùng luôn có thể chi tiêu toàn bộ số dư trong một giao dịch chuyển. Tìm hiểu thêm về việc hợp nhất UTXO.
sendTransaction ký và gửi giao dịch.
isWalletRegistered đọc PDA registry để kiểm tra trạng thái đăng ký.

use solana_signer::Signer;
use zolana_client::user_registry::is_wallet_registered_sync;
use zolana_client::Rpc;
use zolana_user_registry_interface::{
    instruction::{register, set_merge_encryption, RegisterData},
    user_record_pda, MergeEncryptionScheme,
};

let address = owner.shielded_address()?;
let user_record = user_record_pda(&owner.pubkey()).0;
client.create_and_send_transaction(
    &[
        register(
            user_record,
            owner.pubkey(),
            owner.pubkey(),
            RegisterData {
                nullifier_pubkey: address.nullifier_pubkey,
                viewing_pubkey: *address.viewing_pubkey.as_bytes(),
            },
        ),
        set_merge_encryption(
            user_record,
            owner.pubkey(),
            MergeEncryptionScheme::PoseidonCtrV1,
        ),
    ],
    owner.pubkey(),
    &[&owner],
    client.compute_budget(),
)?;

assert!(is_wallet_registered_sync(&client, owner.pubkey())?);

owner là ShieldedKeypair của người dùng. Khóa công khai Solana của nó xác định bản ghi registry và chữ ký của nó cho phép đăng ký.
owner.shielded_address() trả về địa chỉ được che chắn của người dùng.
register đăng ký các khóa của địa chỉ được che chắn.
set_merge_encryption bật tính năng hợp nhất cho các UTXO của người dùng. Một giao dịch chuyển có thể chi tiêu tối đa 40 UTXO, vì vậy việc hợp nhất đảm bảo người dùng luôn có thể chi tiêu toàn bộ số dư trong một giao dịch chuyển. Tìm hiểu thêm về việc hợp nhất UTXO.
create_and_send_transaction ký, gửi và xác nhận giao dịch.
is_wallet_registered_sync đọc PDA registry để kiểm tra trạng thái đăng ký.

Ví dụ đăng ký đầy đủ: TypeScript · Rust

Đồng bộ số dư riêng tư và lịch sử giao dịch

Quá trình đồng bộ số dư lấy trạng thái đã mã hóa từ RPC và giải mã trạng thái đó trong ví.RPC không thực hiện giải mã. Chỉ chủ sở hữu mới có thể giải mã số dư riêng tư bằng khóa xem.

Ví nên giải mã và cập nhật số dư trước các giao dịch riêng tư và ở bất cứ đâu ví chạy quá trình truy xuất dữ liệu bù: khi mở khóa ví, mở ví riêng tư, tiếp tục ứng dụng, kết nối lại mạng, có khoảng trống luồng hoặc khôi phục ví.

Read a Private Balance

Read Private Transaction History

Nạp vào số dư riêng tư

Người dùng có thể nạp vào số dư riêng tư theo hai cách:

Chuyển từ số dư tiền pháp định sang số dư tiền mã hóa riêng tư
Nạp từ tài khoản SPL công khai vào số dư riêng tư

Chuyển đổi trực tiếp và nạp tiền có các mức bảo đảm quyền riêng tư khác nhau. Để có quyền riêng tư tốt hơn, bạn nên sử dụng hình thức chuyển đổi trực tiếp thay vì nạp tiền.

Trường	Chuyển đổi trực tiếp từ tiền pháp định	Nạp từ SPL
Tài sản	Riêng tư	Công khai
Số tiền	Riêng tư	Công khai
Nguồn	Không ở trên chuỗi	Công khai
Địa chỉ đích	Công khai	Công khai

On-/Off-Ramp

Chuyển đổi trực tiếp tiền pháp định vào và ra khỏi số dư riêng tư.

Deposit

Nạp từ số dư tiền mã hóa công khai.

Giao dịch chuyển riêng tư

Người dùng có thể gửi giao dịch chuyển riêng tư đến bất kỳ địa chỉ ví Solana nào.Đối với mỗi giao dịch chuyển riêng tư, Privacy SDK tra cứu địa chỉ ví trong registry trên chuỗi để kiểm tra xem người nhận có ví riêng tư hay không.Privacy SDK có thể chuyển một giao dịch chuyển riêng tư thành giao dịch rút từ riêng tư sang công khai khi người nhận không có ví riêng tư.

Bạn nên gắn nhãn giao dịch trong giao diện người dùng là giao dịch rút tiền để đảm bảo người dùng không vô tình rút sang số dư công khai.Bạn nên yêu cầu một chữ ký người dùng riêng biệt trong giao diện người dùng để đảm bảo người dùng không vô tình rút sang số dư công khai.

Trường	Khả năng hiển thị	Lý do
Tài sản	Riêng tư	Tài sản được mã hóa trên chuỗi
Số tiền	Riêng tư	Số tiền được chuyển được mã hóa trên chuỗi
Ví riêng tư nguồn	Công khai	Trong Ring bảo mật, ví riêng tư nguồn hiển thị trên chuỗi.
Người nhận	Công khai	Trong Ring bảo mật, người nhận hiển thị trên chuỗi.

Private Transfer

Chuyển riêng tư vào số dư riêng tư.

Rút về số dư công khai

Có thể sử dụng tính năng rút tiền theo hai cách:

Làm phương án dự phòng cho các giao dịch chuyển riêng tư đến người nhận không có ví riêng tư, hoặc
Rút trực tiếp về tài khoản token SPL công khai.

Đối với giao dịch rút tiền, bạn nên ghi rõ rằng người dùng đang rời khỏi số dư riêng tư, tương tự như khi xuất cụm từ khôi phục hoặc khóa riêng tư.

Trường	Khả năng hiển thị	Lý do
Tài sản	Công khai	Tài sản hiển thị trên chuỗi
Số tiền	Công khai	Số tiền đã rút hiển thị trên chuỗi
Ví riêng tư nguồn	Công khai	Trong Ring bảo mật, ví riêng tư nguồn hiển thị trên chuỗi.
Ví công khai đích	Công khai	Địa chỉ ví đích hiển thị trên chuỗi
Số dư công khai đích	Công khai	Số dư công khai tạo ra hiển thị trên chuỗi
Số dư riêng tư còn lại	Riêng tư	Số dư còn lại được mã hóa trên chuỗi

Withdraw

Rút về số dư tiền mã hóa công khai.

Không tìm thấy nội dung bạn đang tìm kiếm?

Hãy liên hệ với chúng tôi! Telegram | Email | Liên hệ

Bắt đầu

Truyền dữ liệu & lắng nghe sự kiện

API dữ liệu & RPC

Giao dịch mua bán

Gửi giao dịch

Ví dưới dạng dịch vụ

Quyền riêng tư

Tài nguyên

Ngữ cảnh cho AI của bạn

Tích hợp cặp khóa được che chắn

Tích hợp Privacy Interface và SDK

Về việc tạo bằng chứng

Tích hợp luồng người dùng

Tạo ví riêng tư

Đồng bộ số dư riêng tư và lịch sử giao dịch

Read a Private Balance

Read Private Transaction History

Nạp vào số dư riêng tư

On-/Off-Ramp

Deposit

Giao dịch chuyển riêng tư

Private Transfer

Rút về số dư công khai

Withdraw

Không tìm thấy nội dung bạn đang tìm kiếm?

​Ngữ cảnh cho AI của bạn

​Tích hợp cặp khóa được che chắn

​Tích hợp Privacy Interface và SDK

​Về việc tạo bằng chứng

​Tích hợp luồng người dùng

​Tạo ví riêng tư

​Đồng bộ số dư riêng tư và lịch sử giao dịch

Read a Private Balance

Read Private Transaction History

​Nạp vào số dư riêng tư

On-/Off-Ramp

Deposit

​Giao dịch chuyển riêng tư

Private Transfer

​Rút về số dư công khai

Withdraw

​Không tìm thấy nội dung bạn đang tìm kiếm?

Ngữ cảnh cho AI của bạn

Tích hợp cặp khóa được che chắn

Tích hợp Privacy Interface và SDK

Về việc tạo bằng chứng

Tích hợp luồng người dùng

Tạo ví riêng tư

Đồng bộ số dư riêng tư và lịch sử giao dịch

Nạp vào số dư riêng tư

Giao dịch chuyển riêng tư

Rút về số dư công khai

Không tìm thấy nội dung bạn đang tìm kiếm?