Billetera privada

Una billetera privada consta de un par de claves de Solana para firmar, una clave de anulador y una clave de visualización para el cifrado. En conjunto, estas claves forman el par de claves protegido. Tu sistema de gestión de claves almacena el par de claves protegido. El código de la billetera usa la interfaz de privacidad y el SDK para crear transacciones privadas.

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.

La integración permite que tus usuarios:

Creen una billetera privada de autocustodia
Reciban transferencias privadas con una dirección de Solana
Depositen tokens en un saldo privado
Envíen fondos de forma privada a una dirección de Solana
Retiren fondos a cualquier dirección de Solana
Descifren localmente los saldos privados y el historial de transacciones

La integración incluye:

Par de claves protegido – en tu sistema de gestión de claves para el cifrado
Interfaz de privacidad y SDK – para crear transacciones privadas
Flujos de usuario – para integrarlos en tu billetera

Contexto para tu IA

Add a Private Wallet to an existing Solana wallet

Abrir en 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.

Integra el par de claves protegido

Una integración de billetera privada agrega un par de claves protegido a tu sistema de gestión de claves. Un par de claves protegido firma, cifra y descifra transacciones.El par de claves protegido agrupa las claves de firma, de anulador y de visualización.

Clave de firma: El par de claves Ed25519 de Solana de la billetera para firmar transacciones.
Clave de visualización: Un par de claves X25519 que se usa para cifrar y descifrar transacciones.
Clave de anulador:

Una billetera puede derivar el par de claves protegido a partir de una firma EdDSA de un mensaje fijo.Las firmas EdDSA son deterministas, por lo que firmar el mismo mensaje con el mismo par de claves de Solana siempre produce el mismo par de claves protegido. Usamos la firma como semilla para derivar un par de claves protegido.La carga útil del mensaje fijo es "TSPP/derive/v1", codificada como un mensaje fuera de cadena v0 de Solana.La clave de firma protegida es la clave EdDSA de Solana de la billetera. Las claves de anulador y de visualización son claves adicionales derivadas de la firma.

La firma es la semilla de derivación. Quien la tenga puede derivar las claves de anulador y de visualización, y descifrar las transacciones del usuario. Rechaza cualquier solicitud de firma de un tercero para el mensaje "TSPP/derive/v1".

Pseudocódigo para derivar un par de claves protegido a partir de una firma de 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))
}

Implementación de ejemplo: TypeScript · Rust

Integra la interfaz de privacidad y el SDK

La interfaz de privacidad permite que tu código use el SDK de privacidad para crear transacciones privadas sin acceder directamente al material criptográfico de las claves. Tu sistema de gestión de claves implementa la interfaz de privacidad en dos partes.

Interfaz de firma para crear transacciones con el SDK de privacidad. Consulta el código fuente: TypeScript/ Rust
Interfaz de cifrado y descifrado. Consulta el código fuente: TypeScript/ Rust

La interfaz de privacidad no tiene estado y, por lo tanto, no almacena saldos ni el historial de transacciones. Para mejorar el rendimiento, recomendamos almacenar localmente en caché los saldos y el historial de transacciones de los usuarios.

Acerca de la generación de pruebas

La generación de pruebas de conocimiento cero requiere como entradas en texto sin formato todos los datos de la transacción del usuario y las claves de anulador.Actualmente, la generación de pruebas en el servidor está disponible mediante la URL RPC estándar de Helius.La generación local de pruebas estará disponible próximamente. El demostrador predeterminado de los SDK es un enclave AWS Nitro con certificación.

Integra los flujos de usuario

Crea una billetera privada

Una billetera privada se crea en dos pasos:

Deriva el par de claves protegido
Registra la dirección de Solana en un registro en cadena.

Crear una billetera privada no requiere depositar fondos en el saldo privado.

En tu aplicación de billetera, puedes permitir que tus usuarios creen billeteras privadas solo para una clave pública dedicada de «Billetera privada» o para cualquier clave pública.

El registro vincula la clave pública de firma con las claves públicas de anulador y de visualización. En conjunto, estas claves públicas forman la dirección protegida.

Cada registro es una PDA propiedad del , que cualquiera puede consultar para comprobar si una dirección de Solana puede recibir transferencias privadas.

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 es el firmante de Solana del usuario y se usa para derivar la PDA del registro.
address es la dirección protegida del usuario.
getRegisterInstructionAsync registra las claves de la dirección protegida.
getSetMergeEncryptionInstructionAsync activa la fusión de las UTXO del usuario. Una transferencia puede gastar como máximo 40 UTXO, por lo que la fusión garantiza que los usuarios siempre puedan gastar todo su saldo en una sola transferencia. Obtén más información sobre la fusión de UTXO.
sendTransaction firma y envía la transacción.
isWalletRegistered lee la PDA del registro para comprobar el registro.

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 es el ShieldedKeypair del usuario. Su clave pública de Solana identifica el registro y su firma autoriza el registro.
owner.shielded_address() devuelve la dirección protegida del usuario.
register registra las claves de la dirección protegida.
set_merge_encryption activa la fusión de las UTXO del usuario. Una transferencia puede gastar como máximo 40 UTXO, por lo que la fusión garantiza que los usuarios siempre puedan gastar todo su saldo en una sola transferencia. Obtén más información sobre la fusión de UTXO.
create_and_send_transaction firma, envía y confirma la transacción.
is_wallet_registered_sync lee la PDA del registro para comprobar el registro.

Ejemplos completos de registro: TypeScript · Rust

Sincroniza el saldo privado y el historial de transacciones

La sincronización del saldo obtiene el estado cifrado desde el RPC y lo descifra en la billetera.El RPC no descifra los datos. Solo el propietario puede descifrar un saldo privado con una clave de visualización.

Una billetera debe descifrar y actualizar los saldos antes de las transacciones privadas y siempre que ejecute recuperaciones históricas: al desbloquear la billetera, abrir la billetera privada, reanudar la aplicación, volver a conectarse a la red, detectar una interrupción del flujo o restaurar la billetera.

Read a Private Balance

Read Private Transaction History

Deposita fondos en un saldo privado

Los usuarios pueden depositar fondos en un saldo privado de dos maneras:

Convertir un saldo en moneda fiduciaria en un saldo privado de criptomonedas
Depositar desde una cuenta SPL pública en un saldo privado

La conversión y el depósito ofrecen distintas garantías de privacidad. Para obtener mayor privacidad, recomendamos usar la conversión en lugar del depósito.

Campo	Conversión desde moneda fiduciaria	Depósito desde SPL
Activo	Privado	Público
Importe	Privado	Público
Origen	Fuera de cadena	Público
Dirección de destino	Pública	Pública

On-/Off-Ramp

Convierte moneda fiduciaria directamente hacia y desde un saldo privado.

Deposit

Deposita desde un saldo público de criptomonedas.

Transferencias privadas

Los usuarios pueden enviar transferencias privadas a cualquier dirección de billetera de Solana.Para cada transferencia privada, el SDK de privacidad busca la dirección de la billetera en el registro en cadena para comprobar si el destinatario tiene una billetera privada.El SDK de privacidad puede convertir una transferencia privada en un retiro de un saldo privado a uno público cuando el destinatario no tiene una billetera privada.

Recomendamos etiquetar la transacción en la interfaz de usuario como un retiro para evitar que el usuario retire fondos accidentalmente a un saldo público.Recomendamos solicitar una firma adicional del usuario en la interfaz de usuario para evitar que retire fondos accidentalmente a un saldo público.

Campo	Visibilidad	Motivo
Activo	Privado	El activo está cifrado en cadena
Importe	Privado	El importe transferido está cifrado en cadena
Billetera privada de origen	Pública	En un Ring confidencial, la billetera privada de origen es visible en cadena.
Destinatario	Público	En un Ring confidencial, el destinatario es visible en cadena.

Private Transfer

Transfiere fondos de forma privada a un saldo privado.

Retira fondos a un saldo público

Los retiros se pueden usar de dos maneras:

Como alternativa para las transferencias privadas a destinatarios que no tienen una billetera privada, o
Como retiro directo a una cuenta pública de tokens SPL.

Para los retiros, recomendamos indicar claramente que el usuario está saliendo del saldo privado, de forma similar a una exportación de una frase semilla o una clave privada.

Campo	Visibilidad	Motivo
Activo	Público	El activo es visible en cadena
Importe	Público	El importe retirado es visible en cadena
Billetera privada de origen	Pública	En un Ring confidencial, la billetera privada de origen es visible en cadena.
Billetera pública de destino	Pública	La dirección de la billetera de destino es visible en cadena
Saldo público de destino	Público	El saldo público resultante es visible en cadena
Saldo privado restante	Privado	El saldo restante está cifrado en cadena

Withdraw

Retira fondos a un saldo público de criptomonedas.

¿No encontraste lo que buscabas?

¡Contáctanos! Telegram | Correo electrónico | Contacto

Primeros pasos

Transmisión de datos y escucha de eventos

API de datos y RPC

Trading

Envío de transacciones

Billetera como servicio

Privacidad

Recursos

Contexto para tu IA

Integra el par de claves protegido

Integra la interfaz de privacidad y el SDK

Acerca de la generación de pruebas

Integra los flujos de usuario

Crea una billetera privada

Sincroniza el saldo privado y el historial de transacciones

Read a Private Balance

Read Private Transaction History

Deposita fondos en un saldo privado

On-/Off-Ramp

Deposit

Transferencias privadas

Private Transfer

Retira fondos a un saldo público

Withdraw

¿No encontraste lo que buscabas?

​Contexto para tu IA

​Integra el par de claves protegido

​Integra la interfaz de privacidad y el SDK

​Acerca de la generación de pruebas

​Integra los flujos de usuario

​Crea una billetera privada

​Sincroniza el saldo privado y el historial de transacciones

Read a Private Balance

Read Private Transaction History

​Deposita fondos en un saldo privado

On-/Off-Ramp

Deposit

​Transferencias privadas

Private Transfer

​Retira fondos a un saldo público

Withdraw

​¿No encontraste lo que buscabas?

Contexto para tu IA

Integra el par de claves protegido

Integra la interfaz de privacidad y el SDK

Acerca de la generación de pruebas

Integra los flujos de usuario

Crea una billetera privada

Sincroniza el saldo privado y el historial de transacciones

Deposita fondos en un saldo privado

Transferencias privadas

Retira fondos a un saldo público

¿No encontraste lo que buscabas?