Portefeuille privé

Un portefeuille privé comprend une paire de clés Solana pour la signature, une clé d’annulateur et une clé de visualisation pour le chiffrement. Ensemble, ces clés forment la paire de clés protégée. Votre système de gestion des clés conserve la paire de clés protégée. Le code du portefeuille utilise l’interface de confidentialité et le SDK pour créer des transactions privées.

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.

L’intégration permet à vos utilisateurs de :

Créer un portefeuille privé non dépositaire
Recevoir des transferts privés avec une adresse Solana
Déposer des jetons sur un solde privé
Envoyer des fonds de manière privée à une adresse Solana
Retirer des fonds vers n’importe quelle adresse Solana
Déchiffrer localement les soldes privés et l’historique des transactions

L’intégration comprend :

Paire de clés protégée – dans votre système de gestion des clés pour le chiffrement
Interface de confidentialité et SDK – pour créer des transactions privées
Parcours utilisateur – à intégrer dans votre portefeuille

Contexte pour votre IA

Ajouter un portefeuille privé à un portefeuille Solana existant

Ouvrir dans Cursor

Voir l'invite

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-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, 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", "<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.

Intégrer la paire de clés protégée

L’intégration d’un portefeuille privé ajoute une paire de clés protégée à votre système de gestion des clés. Une paire de clés protégée signe, chiffre et déchiffre les transactions.La paire de clés protégée regroupe les clés de signature, d’annulateur et de visualisation.

Clé de signature : la paire de clés Ed25519 Solana du portefeuille, utilisée pour signer les transactions.
Clé de visualisation : une paire de clés X25519, utilisée pour chiffrer et déchiffrer les transactions.
Clé d’annulateur :

Un portefeuille peut dériver la paire de clés protégée d’une signature EdDSA portant sur un message fixe.Les signatures EdDSA sont déterministes. La signature d’une même paire de clés Solana pour un même message produit donc toujours la même paire de clés protégée. Nous utilisons la signature comme graine pour dériver une paire de clés protégée.La charge utile du message fixe est "TSPP/derive/v1", encodée sous forme de message hors chaîne Solana v0.La clé de signature protégée est la clé EdDSA Solana du portefeuille. Les clés d’annulateur et de visualisation sont des clés supplémentaires dérivées de la signature.

La signature est la graine de dérivation. Toute personne qui la détient peut dériver les clés d’annulateur et de visualisation, puis déchiffrer les transactions de l’utilisateur. Rejetez toute demande de signature du message "TSPP/derive/v1" provenant d’un tiers.

Pseudo-code permettant de dériver une paire de clés protégée à partir d’une signature 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))
}

Exemple d’implémentation : TypeScript · Rust

Intégrer l’interface de confidentialité et le SDK

L’interface de confidentialité permet à votre code d’utiliser le SDK de confidentialité pour créer des transactions privées sans accéder directement aux éléments de clé. Votre système de gestion des clés implémente l’interface de confidentialité en deux parties.

Interface de signature pour la création de transactions avec le SDK de confidentialité. Voir la source : TypeScript/ Rust
Interface de chiffrement et de déchiffrement. Voir la source : TypeScript/ Rust

L’interface de confidentialité est sans état et ne stocke donc ni les soldes ni l’historique des transactions. Pour de meilleures performances, nous recommandons de mettre en cache localement les soldes des utilisateurs et l’historique des transactions.

À propos de la génération de preuves

La génération de preuves à divulgation nulle de connaissance nécessite des entrées en texte clair contenant l’intégralité des données de transaction de l’utilisateur ainsi que les clés d’annulateur.La génération de preuves côté serveur est actuellement disponible via l’URL RPC Helius standard.La génération locale de preuves sera bientôt disponible. Le générateur de preuves par défaut des SDK est une enclave AWS Nitro attestée.

Intégrer les parcours utilisateur

Créer un portefeuille privé

Un portefeuille privé se crée en deux étapes :

Dériver la paire de clés protégée
Enregistrer l’adresse Solana dans un registre sur la blockchain.

La création d’un portefeuille privé ne nécessite aucun dépôt sur le solde privé.

Dans votre application de portefeuille, vous pouvez permettre à vos utilisateurs de créer des portefeuilles privés uniquement pour une clé publique « Portefeuille privé » dédiée ou pour n’importe quelle clé publique.

Le registre associe la clé publique de signature aux clés publiques d’annulateur et de visualisation. Ensemble, ces clés publiques forment l’adresse protégée.

Chaque enregistrement du registre est un PDA détenu par le , que tout le monde peut consulter pour déterminer si une adresse Solana peut recevoir des transferts privés.

TypeScript Client
Rust Client

import { MergeEncryptionScheme } from "@heliuslabs/zolana";
import {
  getRegisterInstructionAsync,
  getSetMergeEncryptionInstructionAsync,
} from "@heliuslabs/zolana/instructions";
import { isWalletRegistered } from "@heliuslabs/zolana/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 est le signataire Solana de l’utilisateur, utilisé pour dériver le PDA du registre.
address est l’adresse protégée de l’utilisateur.
getRegisterInstructionAsync enregistre les clés de l’adresse protégée.
getSetMergeEncryptionInstructionAsync active la fusion des UTXO de l’utilisateur. Un transfert peut dépenser au maximum 40 UTXO. La fusion garantit donc que les utilisateurs peuvent toujours dépenser la totalité de leur solde en un seul transfert. En savoir plus sur la fusion des UTXO.
sendTransaction signe et envoie la transaction.
isWalletRegistered lit le PDA du registre pour vérifier l’enregistrement.

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 est le ShieldedKeypair de l’utilisateur. Sa clé publique Solana identifie l’enregistrement du registre et sa signature autorise l’enregistrement.
owner.shielded_address() renvoie l’adresse protégée de l’utilisateur.
register enregistre les clés de l’adresse protégée.
set_merge_encryption active la fusion des UTXO de l’utilisateur. Un transfert peut dépenser au maximum 40 UTXO. La fusion garantit donc que les utilisateurs peuvent toujours dépenser la totalité de leur solde en un seul transfert. En savoir plus sur la fusion des UTXO.
create_and_send_transaction signe, envoie et confirme la transaction.
is_wallet_registered_sync lit le PDA du registre pour vérifier l’enregistrement.

Exemples complets d’enregistrement : TypeScript · Rust

Synchroniser le solde privé et l’historique des transactions

La synchronisation du solde récupère l’état chiffré depuis le RPC et le déchiffre dans le portefeuille.Le RPC n’effectue aucun déchiffrement. Seul le propriétaire peut déchiffrer un solde privé avec une clé de visualisation.

Un portefeuille doit déchiffrer et mettre à jour les soldes avant les transactions privées et chaque fois qu’il effectue un rattrapage historique : au déverrouillage du portefeuille, à l’ouverture du portefeuille privé, à la reprise de l’application, à la reconnexion au réseau, après une interruption du flux ou lors de la restauration du portefeuille.

Read a Private Balance

Read Private Transaction History

Déposer des fonds sur un solde privé

Les utilisateurs peuvent déposer des fonds sur un solde privé de deux manières :

Convertir un solde fiduciaire en solde crypto privé
Effectuer un dépôt depuis un compte SPL public vers un solde privé

La conversion entrante et le dépôt offrent des garanties de confidentialité différentes. Pour une meilleure confidentialité, nous recommandons la conversion entrante plutôt que le dépôt.

Champ	Conversion depuis une monnaie fiduciaire	Dépôt depuis SPL
Actif	Privé	Public
Montant	Privé	Public
Source	Hors chaîne	Publique
Adresse de destination	Publique	Publique

On-/Off-Ramp

Convertissez directement une monnaie fiduciaire vers ou depuis un solde privé.

Deposit

Effectuez un dépôt depuis un solde crypto public.

Transferts privés

Les utilisateurs peuvent envoyer des transferts privés vers n’importe quelle adresse de portefeuille Solana.Pour chaque transfert privé, le SDK de confidentialité recherche l’adresse du portefeuille dans le registre sur la blockchain afin de vérifier si le destinataire possède un portefeuille privé.Le SDK de confidentialité peut convertir un transfert privé en retrait d’un solde privé vers un solde public lorsque le destinataire ne possède pas de portefeuille privé.

Nous recommandons d’indiquer clairement dans l’interface utilisateur que la transaction est un retrait afin d’éviter que l’utilisateur ne retire accidentellement des fonds vers un solde public.Nous recommandons de demander une signature distincte à l’utilisateur dans l’interface afin d’éviter qu’il ne retire accidentellement des fonds vers un solde public.

Champ	Visibilité	Raison
Actif	Privé	L’actif est chiffré sur la blockchain
Montant	Privé	Le montant transféré est chiffré sur la blockchain
Portefeuille privé source	Public	Dans un anneau confidentiel, le portefeuille privé source est visible sur la blockchain.
Destinataire	Public	Dans un anneau confidentiel, le destinataire est visible sur la blockchain.

Private Transfer

Effectuez un transfert privé vers un solde privé.

Retirer des fonds vers un solde public

Les retraits peuvent être utilisés de deux manières :

Comme solution de secours pour les transferts privés vers des destinataires qui ne possèdent pas de portefeuille privé, ou
Comme retrait direct vers un compte de jetons SPL public.

Pour les retraits, nous recommandons d’indiquer clairement que l’utilisateur quitte le solde privé, comme lors de l’exportation d’une phrase de récupération ou d’une clé privée.

Champ	Visibilité	Raison
Actif	Public	L’actif est visible sur la blockchain
Montant	Public	Le montant retiré est visible sur la blockchain
Portefeuille privé source	Public	Dans un anneau confidentiel, le portefeuille privé source est visible sur la blockchain.
Portefeuille public de destination	Public	L’adresse du portefeuille de destination est visible sur la blockchain
Solde public de destination	Public	Le solde public obtenu est visible sur la blockchain
Solde privé restant	Privé	Le solde restant est chiffré sur la blockchain

Withdraw

Retirez des fonds vers un solde crypto public.

Vous n’avez pas trouvé ce que vous cherchiez ?

Contactez-nous ! Telegram | E-Mail | Contact

Bien démarrer

Diffusion de données et écoute d’événements

API de données et RPC

Trading

Envoi de transactions

Portefeuille en tant que service

Confidentialité

Ressources

Contexte pour votre IA

Intégrer la paire de clés protégée

Intégrer l’interface de confidentialité et le SDK

À propos de la génération de preuves

Intégrer les parcours utilisateur

Créer un portefeuille privé

Synchroniser le solde privé et l’historique des transactions

Read a Private Balance

Read Private Transaction History

Déposer des fonds sur un solde privé

On-/Off-Ramp

Deposit

Transferts privés

Private Transfer

Retirer des fonds vers un solde public

Withdraw

Vous n’avez pas trouvé ce que vous cherchiez ?

​Contexte pour votre IA

​Intégrer la paire de clés protégée

​Intégrer l’interface de confidentialité et le SDK

​À propos de la génération de preuves

​Intégrer les parcours utilisateur

​Créer un portefeuille privé

​Synchroniser le solde privé et l’historique des transactions

Read a Private Balance

Read Private Transaction History

​Déposer des fonds sur un solde privé

On-/Off-Ramp

Deposit

​Transferts privés

Private Transfer

​Retirer des fonds vers un solde public

Withdraw

​Vous n’avez pas trouvé ce que vous cherchiez ?

Contexte pour votre IA

Intégrer la paire de clés protégée

Intégrer l’interface de confidentialité et le SDK

À propos de la génération de preuves

Intégrer les parcours utilisateur

Créer un portefeuille privé

Synchroniser le solde privé et l’historique des transactions

Déposer des fonds sur un solde privé

Transferts privés

Retirer des fonds vers un solde public

Vous n’avez pas trouvé ce que vous cherchiez ?