> ## 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. # Carteira Privada > Adicione suporte de privacidade a uma carteira Solana existente para o Ring confidencial sem permissão. Crie carteiras privadas, receba e envie transações privadas. Uma carteira privada consiste em um par de chaves Solana para assinatura, uma chave nula e uma chave de visualização para criptografia – juntas estas chaves formam o par de chaves blindado. A gestão de suas chaves mantém o par de chaves blindado. O código da carteira usa a Interface de Privacidade e o SDK para construir transações privadas. A gestão de chaves e o SDK de Privacidade se conectam através da Interface de Privacidade. O SDK de Privacidade chama a API de Privacidade. A API de Privacidade submete a transação para Solana. A integração permite que seus usuários: 1. Criem uma carteira privada autocustódia 2. Recebam transferências privadas com um endereço Solana 3. Depositem tokens para um saldo privado 4. Enviem de forma privada para um endereço Solana 5. Retirem para qualquer endereço Solana 6. Desencriptem saldos privados e histórico de transações localmente A integração inclui: 1. [**Par de Chaves Blindado**](#integrar-o-par-de-chaves-blindado) – na sua gestão de chaves para criptografia 2. [**Interface de Privacidade e SDK**](#integrar-a-interface-de-privacidade-e-sdk) – para construir transações privadas 3. [**Fluxos de Usuário**](#integrar-fluxos-de-usuário) – para integrar na sua carteira ## Contexto para sua 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. ``` ## Integrar o Par de Chaves Blindado Uma integração de carteira privada adiciona um par de chaves blindado à sua gestão de chaves. Um par de chaves blindado assina, encripta e desencripta transações. O par de chaves blindado é um conjunto das chaves de assinatura, nullifier e visualização. * **Chave de assinatura:** O par de chaves Ed25519 Solana da carteira para assinar transações. * **Chave de visualização:** Um par de chaves P-256, usado para encriptar e desencriptar transações. * **Chave nullifier:** Uma chave usada para derivar nullifiers. Uma carteira pode criar o par de chaves blindado de duas maneiras: 1. Para carteiras baseadas em seed escolha **Derivar da frase seed**. 2. Para carteiras não baseadas em seed escolha **Derivar da assinatura EdDSA**. Uma carteira baseada em seed deriva o par de chaves blindado de uma única frase mnemônica BIP-39 e um índice de conta (`0`, `1`, …). Cada índice de conta mapeia um par de chaves Solana para um par de chaves blindado. Você pode recuperar o par de chaves blindado da mesma forma que recupera o par de chaves Solana. Por exemplo: * Conta 0: Par de chaves Solana 0 e par de chaves blindado 0 * Conta 1: Par de chaves Solana 1 e par de chaves blindado 1 | Chave | Caminho de Derivação | Esquema | | ------------ | ---------------------------------- | ------------------------- | | Assinatura | `m/44'/501'/account'/0'` | SLIP-0010 Ed25519 | | Nullifier | `m/44'/1392955331'/account'/1'/0'` | SLIP-0010 Ed25519\[1..32] | | Visualização | `m/44'/1392955331'/account'/2'/0'` | SLIP-0010 NIST P-256 | A chave de assinatura blindada é a chave Ed25519 Solana dessa conta. As chaves nullifier e de visualização são chaves adicionais derivadas do mesmo seed. Implementação de Exemplo: [Exemplo em TypeScript](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/ts/test/seed-based-keypair.test.ts#L60) · [Exemplo em Rust](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/keypair/tests/seed_based_keypair.rs#L111) Derivar o par de chaves blindado de uma assinatura EdDSA sobre uma mensagem fixa. Assinaturas EdDSA são determinísticas, então a assinatura do mesmo par de chaves Solana para a mesma mensagem sempre produz o mesmo par de chaves blindado. Usamos a assinatura como seed para derivar um par de chaves blindado. O payload da mensagem fixa é `"TSPP/derive/v1"`, codificado como uma mensagem Solana off-chain v0. A chave de assinatura blindada é a chave EdDSA Solana da carteira. As chaves nullifier e de visualização são chaves adicionais derivadas da assinatura. A assinatura é o seed de derivação. Quem a possui pode derivar as chaves nullifier e de visualização e pode desencriptar transações do usuário. Rejeite qualquer solicitação de assinatura para a mensagem `"TSPP/derive/v1"` de terceiros. Pseudocódigo para derivar um par de chaves blindado de uma assinatura 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) } ``` Implementação de Exemplo: [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) ## Integrar a Interface de Privacidade e SDK A Interface de Privacidade permite que seu código use o SDK de Privacidade para construir transações privadas sem acessar diretamente o material das chaves. Sua gestão de chaves implementa a Interface de Privacidade em duas partes. 1. Interface de Assinatura para Construção de Transações com o SDK de Privacidade. Visualizar Fonte: [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. Interface de Criptografia e Descriptografia. Visualizar Fonte: [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) A Interface de Privacidade é sem estado e, portanto, não armazena saldos ou histórico de transações. Para desempenho, recomendamos o cache local dos saldos e histórico de transações do usuário. ### Sobre a Geração de Prova A geração de prova de conhecimento zero requer entradas de texto simples de todos os dados de transação do usuário e chaves nullifier. Atualmente, a geração de provas no servidor está disponível através do URL padrão do Helius RPC. A geração de provas local estará disponível em breve. A geração de provas no servidor encriptada de ponta a ponta no AWS Nitro está planejada antes do lançamento na mainnet. ## Integrar Fluxos de Usuário ### Criar Carteira Privada Uma carteira privada é criada em dois passos: 1. Derivar o par de chaves blindado 2. Registrar o endereço Solana no registro on-chain. O registro vincula a chave pública de assinatura às chaves públicas nullifier e de visualização – juntas estas chaves públicas formam o endereço blindado. ```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 é um PDA de propriedade do [programa de registro](https://orbmarkets.io/address/regyS5rkAcw2YzDJCmTwCTHs2s246FXxbmuRZ42u2PD), que qualquer pessoa pode consultar para ver se um endereço Solana pode receber transferências privadas. ### Sincronizar Saldo Privado & Histórico de Transações A sincronização de saldo busca o estado encriptado do RPC e o desencripta na carteira. O RPC não desencripta. Apenas o proprietário pode desencriptar um saldo privado com uma chave de visualização. Uma carteira deve desencriptar e atualizar saldos antes de transações privadas e sempre que realizar backfills: ao desbloquear a carteira, abrir carteira privada, retomar aplicativo, reconectar à rede, gap de streaming, ou restaurar a carteira. ### Depositar em um Saldo Privado Os usuários podem depositar em um saldo privado de duas maneiras: 1. On-ramp de um saldo fiat para um saldo cripto privado 2. Depositar de uma conta SPL pública para um saldo privado On-ramp e depósito diferem em suas garantias de privacidade. Recomendamos o uso de on-ramp sobre depósito para melhor privacidade. | Campo | On-ramp de Fiat | Depósito de SPL | | ------------------- | --------------- | --------------- | | Ativo | Privado | Público | | Quantidade | Privada | Pública | | Origem | Não onchain | Pública | | Endereço de destino | Público | Público | On-/Off-ramp fiat diretamente para e de um saldo privado. Depositar a partir de um saldo cripto público. ### Transferências Privadas Os usuários podem enviar transferências privadas para qualquer endereço de carteira Solana. Para cada transferência privada, o SDK de Privacidade procura o endereço da carteira no registro onchain para verificar se o destinatário possui uma carteira privada. O SDK de Privacidade pode resolver uma transferência privada para uma retirada privada para pública, quando o destinatário não possui uma Carteira Privada. Recomendamos rotular a transação na interface do usuário como uma retirada para garantir que o usuário não retire para um saldo público por acidente. | Campo | Visibilidade | Por quê | | -------------------------- | ------------ | ----------------------------------------------------------------------- | | Ativo | Privado | O ativo é encriptado onchain | | Quantidade | Privada | A quantidade transferida é encriptada onchain | | Carteira privada de origem | Pública | Em um Ring confidencial a carteira privada de origem é visível onchain. | | Destinatário | Público | Em um Ring confidencial o destinatário é visível onchain. | Transferir de forma privada para um saldo privado. ### Retirar para um Saldo Público As retiradas podem ser usadas de duas maneiras: 1. Como fallback para transferências privadas para destinatários que não possuem uma carteira privada, ou 2. Retirada direta para uma conta de token SPL pública. Para retiradas, recomendamos rotular claramente que o usuário está saindo do saldo privado, semelhante a uma exportação de frase seed ou chave privada. | Campo | Visibilidade | Por quê | | --------------------------- | ------------ | ----------------------------------------------------------------------- | | Ativo | Público | O ativo é visível onchain | | Quantidade | Pública | A quantidade retirada é visível onchain | | Carteira privada de origem | Pública | Em um Ring confidencial a carteira privada de origem é visível onchain. | | Carteira pública de destino | Público | O endereço da carteira de destino é visível onchain | | Saldo público de destino | Público | O saldo público resultante é visível onchain | | Saldo privado restante | Privado | O saldo restante é encriptado onchain | Retirar para um saldo cripto público. ## 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)