> ## Documentation Index > Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Billetera privada > Agrega compatibilidad con la privacidad a una billetera de Solana existente para el Ring confidencial sin permisos. Crea billeteras privadas y recibe y envía transacciones privadas. 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 hagan lo siguiente: 1. Crear una billetera privada de autocustodia 2. Recibir transferencias privadas con una dirección de Solana 3. Depositar tokens en un saldo privado 4. Enviar fondos de forma privada a una dirección de Solana 5. Retirar fondos a cualquier dirección de Solana 6. Descifrar localmente los saldos privados y el historial de transacciones La integración incluye: 1. [**Par de claves protegido**](#integra-el-par-de-claves-protegido) – en tu sistema de gestión de claves para el cifrado 2. [**Interfaz de privacidad y SDK**](#integra-la-interfaz-de-privacidad-y-el-sdk) – para crear transacciones privadas 3. [**Flujos de usuario**](#integra-los-flujos-de-usuario) – para integrarlos en tu billetera ## Contexto para tu IA {`--- 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", "") - WebFetch \`https://www.helius.dev/docs/.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.`} ```text theme={"system"} 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", "") - WebFetch \`https://www.helius.dev/docs/.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 La integración de una 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, anulador y 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 P-256 usado para cifrar y descifrar transacciones. * **Clave de anulador:** Una clave usada para derivar anuladores. Una billetera puede crear el par de claves protegido de dos maneras: 1. Para billeteras basadas en semillas, elige **Derivar de la frase semilla**. 2. Para billeteras que no se basan en semillas, elige **Derivar de la firma EdDSA**. Una billetera basada en semillas deriva el par de claves protegido de una frase mnemónica BIP-39 y un índice de cuenta (`0`, `1`, …). Cada índice de cuenta asigna un par de claves de Solana a un par de claves protegido. Puedes recuperar el par de claves protegido de la misma manera que recuperas el par de claves de Solana. Por ejemplo: * Cuenta 0: par de claves de Solana 0 y par de claves protegido 0 * Cuenta 1: par de claves de Solana 1 y par de claves protegido 1 | Clave | Ruta de derivación | Esquema | | ------------- | ---------------------------------- | ------------------------- | | Firma | `m/44'/501'/account'/0'` | SLIP-0010 Ed25519 | | Anulador | `m/44'/1392955331'/account'/1'/0'` | SLIP-0010 Ed25519\[1..32] | | Visualización | `m/44'/1392955331'/account'/2'/0'` | SLIP-0010 NIST P-256 | La clave de firma protegida es la clave Ed25519 de Solana de esa cuenta. Las claves de anulador y visualización son claves adicionales derivadas de la misma semilla. Implementación de ejemplo: [Ejemplo en TypeScript](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/ts/test/seed-based-keypair.test.ts#L60) · [Ejemplo en Rust](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/keypair/tests/seed_based_keypair.rs#L111) Deriva el par de claves protegido de una firma EdDSA sobre un mensaje fijo. Las firmas EdDSA son deterministas, por lo que la firma del mismo par de claves de Solana para el mismo mensaje 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 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 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 de una firma de Solana: ```jsx theme={"system"} 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) } ``` Implementación de ejemplo: [TypeScript](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/ts/src/keypair/shielded.ts#L201) · [Rust](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/keypair/src/shielded.rs#L126) ## 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 de claves. Tu sistema de gestión de claves implementa la Interfaz de privacidad en dos partes. 1. Interfaz de firma para crear transacciones con el SDK de privacidad. Ver código fuente: [TypeScript](https://github.com/helius-labs/zolana/blob/236e6cd6cee4d07e567b316210e018f31dfa4d90/sdk-libs/ts/src/keypair/shielded.ts#L132)/ [Rust](https://github.com/helius-labs/zolana/blob/236e6cd6cee4d07e567b316210e018f31dfa4d90/sdk-libs/keypair/src/traits/shielded_keypair.rs) 2. Interfaz de cifrado y descifrado. Ver código fuente: [TypeScript](https://github.com/helius-labs/zolana/blob/236e6cd6cee4d07e567b316210e018f31dfa4d90/sdk-libs/ts/src/keypair/shielded.ts#L154)/ [Rust](https://github.com/helius-labs/zolana/blob/236e6cd6cee4d07e567b316210e018f31dfa4d90/sdk-libs/keypair/src/traits/view_key.rs) La Interfaz de privacidad no mantiene estado y, por lo tanto, no almacena saldos ni historiales de transacciones. Para mejorar el rendimiento, recomendamos almacenar localmente en caché los saldos y los historiales 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 las transacciones 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. Está previsto ofrecer generación de pruebas en el servidor con cifrado de extremo a extremo en AWS Nitro antes del lanzamiento de la red principal. ## Integra los flujos de usuario ### Crea una billetera privada Una billetera privada se crea en dos pasos: 1. Deriva el par de claves protegido 2. Registra la dirección de Solana en un registro en cadena. Crear una billetera privada no requiere depositar fondos en el saldo privado. El registro vincula la clave pública de firma con las claves públicas de anulador y visualización. En conjunto, estas claves públicas forman la dirección protegida. ```mermaid theme={"system"} %%{init: { 'theme': 'base', 'themeVariables': { 'lineColor': '#FF6B35', 'primaryTextColor': '#737373', 'primaryBorderColor': '#9CA3AF', 'actorBkg': '#FFFFFF', 'actorBorder': '#9CA3AF', 'actorTextColor': '#737373', 'signalColor': '#FF6B35', 'signalTextColor': '#737373', 'labelBoxBkgColor': '#FF6B351F', 'labelBoxBorderColor': '#FF6B35', 'noteBkgColor': '#F5F5F5', 'noteTextColor': '#737373', 'noteBorderColor': '#9CA3AF' } }}%% sequenceDiagram participant User participant Privacy SDK participant Solana User->>Privacy SDK: Create Private Wallet Privacy SDK->>Solana: Register Solana address ``` Cada registro es una PDA propiedad del [programa de registro](https://orbmarkets.io/address/regyS5rkAcw2YzDJCmTwCTHs2s246FXxbmuRZ42u2PD), que cualquiera puede consultar para comprobar si una dirección de Solana puede recibir transferencias privadas. ```typescript theme={"system"} import { buildRegistrationTransaction } from "@heliuslabs/zolana"; import { isWalletRegistered } from "@heliuslabs/zolana/wallet"; const registration = await buildRegistrationTransaction({ client, owner: signer.address, address, }); if (registration !== undefined) { await sendTransaction(registration); } const registered = await isWalletRegistered({ rpc: client, owner: signer.address, }); ``` * `owner` es la dirección de Solana del usuario, usada para derivar la PDA del registro. * `address` es la dirección protegida del usuario. * `buildRegistrationTransaction` devuelve una transacción compilada de registro o actualización de claves. Devuelve `undefined` si la billetera ya está registrada. * `sendTransaction` firma y envía la transacción. * `isWalletRegistered` lee la PDA del registro para comprobar el registro. ```rust theme={"system"} use solana_signer::Signer; use zolana_client::{sign_transaction, Rpc}; use zolana_wallet::{ build_registration_transaction_sync, is_wallet_registered_sync, }; if let Some(registration) = build_registration_transaction_sync( &client, owner.pubkey(), &owner.shielded_address()?, None, )? { let registration = sign_transaction(registration, &[&owner])?; client.process_transaction(registration)?; } 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. * `build_registration_transaction_sync` devuelve un mensaje sin firmar de registro o actualización de claves. Devuelve `None` si la billetera ya está registrada. * `None` se usa para billeteras Ed25519. * `sign_transaction` firma el mensaje. `process_transaction` 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](https://github.com/helius-labs/zolana-examples/blob/7775438e0a290a4c28dccf919719bd640c3ec5e3/typescript-client/examples/register_private_wallet.ts) · [Rust](https://github.com/helius-labs/zolana-examples/blob/7775438e0a290a4c28dccf919719bd640c3ec5e3/rust-client/examples/register_private_wallet.rs) ### Sincroniza el saldo privado y el historial de transacciones La sincronización del saldo obtiene el estado cifrado del 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 de datos históricos: al desbloquear la billetera, abrir la billetera privada, reanudar la aplicación, restablecer la conexión de red, detectar una interrupción en el flujo o restaurar la billetera. ### Deposita fondos en un saldo privado Los usuarios pueden depositar fondos en un saldo privado de dos maneras: 1. Incorporar fondos desde un saldo fiduciario a un saldo privado de criptomonedas 2. Depositar desde una cuenta SPL pública a un saldo privado La incorporación y el depósito ofrecen distintas garantías de privacidad. Para obtener mayor privacidad, recomendamos usar la incorporación de fondos en lugar del depósito. | Campo | Incorporación desde moneda fiduciaria | Depósito desde SPL | | -------------------- | ------------------------------------- | ------------------ | | Activo | Privado | Público | | Importe | Privado | Público | | Origen | Fuera de la cadena | Público | | Dirección de destino | Pública | Pública | Incorpora o retira moneda fiduciaria directamente hacia o desde un saldo privado. 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. | 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. | Transfiere fondos de forma privada a un saldo privado. ### Retira fondos a un saldo público Los retiros se pueden usar de dos maneras: 1. Como alternativa para las transferencias privadas a destinatarios que no tienen una billetera privada, o 2. Como retiro directo a una cuenta pública de tokens SPL. Para los retiros, recomendamos indicar claramente que el usuario está abandonando el saldo privado, como se hace al exportar 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 | Retira fondos a un saldo público de criptomonedas. ## Didn't find what you were looking for? Reach out! [Telegram](https://t.me/tilo_light) | [E-Mail](mailto:sales@helius.xyz) | [Contact](https://www.helius.dev/contact)