> ## 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. # Portefeuille Privé > Ajoutez le support de confidentialité à un portefeuille Solana existant pour le Ring confidentiel sans permission. Créez des portefeuilles privés, recevez et envoyez des transactions privées. Un portefeuille privé se compose d'une paire de clés Solana pour la signature, d'une clé de nullification et d'une clé de visualisation pour le chiffrement – ensemble, ces clés forment la paire de clés protégée. Votre gestion des clés détient la paire de clés protégée. Le code du portefeuille utilise l'Interface de Confidentialité et le SDK pour construire des transactions privées. Gestion des clés et le SDK Privacy se connectent via l'Interface de Confidentialité. Le SDK Privacy appelle l'API Privacy. L'API Privacy soumet la transaction à Solana. L'intégration permet à vos utilisateurs de : 1. Créer un portefeuille privé auto-custodial 2. Recevoir des transferts privés avec une adresse Solana 3. Déposer des jetons sur un solde privé 4. Envoyer en privé à une adresse Solana 5. Retirer vers n'importe quelle adresse Solana 6. Décrypter les soldes privés et l'historique des transactions localement L'intégration inclut : 1. [**Paire de clés protégée**](#intégrer-la-paire-de-clés-protégée) – dans votre gestion des clés pour le chiffrement 2. [**Interface de Confidentialité et SDK**](#intégrer-linterface-de-confidentialité-et-le-sdk) – pour construire des transactions privées 3. [**Flux Utilisateurs**](#intégrer-les-flux-utilisateurs) – pour intégrer dans votre portefeuille ## Contexte pour votre 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. ``` ## Intégrer la Paire de Clés Protégée Une intégration de portefeuille privé ajoute une paire de clés protégée à votre gestion des clés. Une paire de clés protégée signe, chiffre et déchiffre des transactions. La paire de clés protégée est un ensemble des clés de signature, de nullification et de visualisation. * **Clé de signature :** La paire de clés Ed25519 Solana du portefeuille pour signer des transactions. * **Clé de visualisation :** Une paire de clés P-256, utilisée pour chiffrer et déchiffrer des transactions. * **Clé de nullification :** Une clé utilisée pour dériver les nullificateurs. Un portefeuille peut créer la paire de clés protégée de deux manières : 1. Pour les portefeuilles basés sur une graine, choisissez **Dériver à partir de la phrase de récupération**. 2. Pour les portefeuilles non basés sur une graine, choisissez **Dériver à partir de la signature EdDSA**. Un portefeuille basé sur une graine dérive la paire de clés protégée à partir d'un mnémonique BIP-39 et d'un index de compte (`0`, `1`, …). Chaque index de compte associe une paire de clés Solana à une paire de clés protégée. Vous pouvez récupérer la paire de clés protégée de la même manière que vous récupérez la paire de clés Solana. Par exemple : * Compte 0 : paire de clés Solana 0 et paire de clés protégée 0 * Compte 1 : paire de clés Solana 1 et paire de clés protégée 1 | Clé | Chemin de Dérivation | Schéma | | ------------- | ---------------------------------- | ------------------------- | | Signature | `m/44'/501'/account'/0'` | SLIP-0010 Ed25519 | | Nullificateur | `m/44'/1392955331'/account'/1'/0'` | SLIP-0010 Ed25519\[1..32] | | Visualisation | `m/44'/1392955331'/account'/2'/0'` | SLIP-0010 NIST P-256 | La clé de signature protégée est la clé Ed25519 Solana de ce compte. Les clés de nullification et de visualisation sont des clés supplémentaires dérivées de la même graine. Implémentation Exemple: [Exemple TypeScript](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/ts/test/seed-based-keypair.test.ts#L60) · [Exemple Rust](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/keypair/tests/seed_based_keypair.rs#L111) Dérive la paire de clés protégée à partir d'une signature EdDSA sur un message fixe. Les signatures EdDSA sont déterministes, donc la signature de la même paire de clés Solana pour le même message produit toujours la même paire de clés protégée. Nous utilisons la signature comme une graine pour dériver une paire de clés protégée. La charge utile du message fixe est `"TSPP/derive/v1"`, encodée comme un message Solana hors chaîne v0. La clé de signature protégée est la clé EdDSA Solana du portefeuille. Les clés de nullification et de visualisation sont des clés supplémentaires dérivées de la signature. La signature est la graine de dérivation. Celui qui la possède peut dériver les clés de nullification et de visualisation et peut déchiffrer les transactions utilisateur. Rejetez toute demande de signature pour le message `"TSPP/derive/v1"` d'un tiers. Pseudocode pour dériver une paire de clés protégée à partir d'une signature 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) } ``` Implémentation Exemple: [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) ## Intégrer l'Interface de Confidentialité et le SDK L'Interface de Confidentialité permet à votre code d'utiliser le SDK Privacy pour construire des transactions privées sans accéder directement au matériel des clés. Votre gestion des clés implémente l'Interface de Confidentialité en deux parties. 1. Interface de Signature pour la Construction de Transactions avec le SDK Privacy. Voir Source: [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 Chiffrement & Déchiffrement. Voir Source: [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) L'Interface de Confidentialité est sans état et ne stocke donc pas les soldes ou l'historique des transactions. Pour la performance, nous recommandons de mettre en cache les soldes et l'historique des transactions des utilisateurs localement. ### Sur la Génération de Preuves La génération de preuves à connaissance nulle nécessite des entrées en texte clair des données complètes de la transaction de l'utilisateur et des clés de nullification. Actuellement, la génération de preuves par le serveur est disponible via l'URL standard de Helius RPC. La génération de preuves locales sera bientôt disponible. La génération de preuves sur serveur entièrement cryptée de bout en bout sur AWS Nitro est prévue avant le lancement sur le réseau principal. ## Intégrer les Flux Utilisateurs ### Créer un Portefeuille Privé Un portefeuille privé est créé en deux étapes : 1. Dériver la paire de clés protégée 2. Enregistrer l'adresse Solana dans le registre sur chaîne. Le registre lie la clé publique de signature aux clés publiques de nullification et de visualisation – ensemble, ces clés publiques forment l'adresse protégée. ```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 ``` Chaque enregistrement de registre est un PDA détenu par le [programme de registre](https://orbmarkets.io/address/regyS5rkAcw2YzDJCmTwCTHs2s246FXxbmuRZ42u2PD), que tout le monde peut consulter pour voir si une adresse Solana peut recevoir des transferts privés. ### Synchroniser le Solde Privé & l'Historique des Transactions La synchronisation des soldes récupère l'état chiffré du RPC et le déchiffre dans le portefeuille. Le RPC ne déchiffre pas. Seul le propriétaire peut déchiffrer un solde privé avec une clé de visualisation. Un portefeuille devrait déchiffrer et mettre à jour les soldes avant les transactions privées et partout où il exécute des remplissages : lors du déverrouillage du portefeuille, de l'ouverture du portefeuille privé, de la reprise de l'application, de la reconnexion au réseau, de l'écart de flux, ou de la restauration du portefeuille. ### Dépôt sur un Solde Privé Les utilisateurs peuvent déposer sur un solde privé de deux façons : 1. Passerelle d'entrée depuis un solde fiat vers un solde crypto privé 2. Dépôt depuis un compte SPL public vers un solde privé La passerelle et le dépôt diffèrent dans leurs garanties de confidentialité. Nous recommandons d'utiliser la passerelle plutôt que le dépôt pour une meilleure confidentialité. | Champ | Passerelle d'entrée depuis Fiat | Dépôt depuis SPL | | ---------------------- | ------------------------------- | ---------------- | | Actif | Privé | Public | | Montant | Privé | Public | | Source | Pas sur la chaîne | Public | | Adresse de destination | Public | Public | Rampe d'accès/de sortie en fiat directement vers et depuis un solde privé. Dépôt depuis un solde crypto public. ### Transferts Privés Les utilisateurs peuvent envoyer des transferts privés à n'importe quelle adresse de portefeuille Solana. Pour chaque transfert privé, le SDK Privacy recherche l'adresse du portefeuille dans le registre sur chaîne pour vérifier si le destinataire possède un portefeuille privé. Le SDK Privacy peut résoudre un transfert privé en un retrait privé-vers-public, lorsque le destinataire ne possède pas de portefeuille privé. Nous recommandons de marquer la transaction dans l'interface utilisateur comme un retrait pour assurer que l'utilisateur ne retire pas par accident vers un solde public. | Champ | Visibilité | Pourquoi | | ------------------------- | ---------- | ---------------------------------------------------------------------------------- | | Actif | Privé | L'actif est chiffré sur la chaîne | | Montant | Privé | Le montant transféré est chiffré sur la chaîne | | Portefeuille privé source | Public | Dans un Ring confidentiel, le portefeuille privé source est visible sur la chaîne. | | Destinataire | Public | Dans un Ring confidentiel, le destinataire est visible sur la chaîne. | Transfert privé vers un solde privé. ### Retirer vers un Solde Public Les retraits peuvent être utilisés de deux façons : 1. En tant que solution de repli pour des transferts privés vers des destinataires qui n'ont pas de portefeuille privé, ou 2. Retrait direct vers un compte de jeton SPL public. Pour les retraits, nous recommandons de bien indiquer que l'utilisateur quitte le solde privé, similaire à une phrase de récupération ou une exportation de clé privée. | Champ | Visibilité | Pourquoi | | ---------------------------------- | ---------- | ---------------------------------------------------------------------------------- | | Actif | Public | L'actif est visible sur la chaîne | | Montant | Public | Le montant retiré est visible sur la chaîne | | Portefeuille privé source | Public | Dans un Ring confidentiel, le portefeuille privé source est visible sur la chaîne. | | Portefeuille public de destination | Public | L'adresse du portefeuille de destination est visible sur la chaîne | | Solde public de destination | Public | Le solde public résultant est visible sur la chaîne | | Solde privé restant | Privé | Le solde restant est chiffré sur la chaîne | Retirer vers un solde crypto public. ## 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)