> ## 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. # プライベートウォレット > 許可不要の機密リング用にプライバシーサポートを既存のSolanaウォレットに追加します。プライベートウォレットを作成し、プライベートトランザクションを受信および送信します。 プライベートウォレットは署名用のSolanaキー ペア、ヌリファイアキー、および暗号化用のビューイングキーで構成されています。これらのキーがシールドキー ペアを形成します。 キー管理はシールドキー ペアを保持します。 ウォレットコードはプライバシーインターフェースとSDKを使用してプライベートトランザクションを作成します。 キー管理とプライバシーSDKはプライバシーインターフェースを通じて接続します。プライバシーSDKはプライバシーAPIを呼び出します。プライバシーAPIはトランザクションをSolanaに送信します。 この統合により、ユーザーは次のことができます: 1. 自己管理のプライベートウォレットを作成 2. Solanaアドレスでプライベート転送を受信 3. トークンをプライベート残高に入金 4. Solanaアドレスにプライベートに送信 5. 任意のSolanaアドレスに出金 6. プライベート残高とトランザクション履歴をローカルで復号化 統合には次のものが含まれます: 1. [**シールドキー ペア**](#シールドキー-ペアの統合) – 暗号化のためのキー管理 2. [**プライバシーインターフェースとSDK**](#プライバシーインターフェースとsdkの統合) – プライベートトランザクションを構築するため 3. [**ユーザーフロー**](#ユーザーフローの統合) – ウォレットに統合するため ## AIのためのコンテキスト {`--- 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. ``` ## シールドキー ペアの統合 プライベートウォレットの統合は、キー管理にシールドキー ペアを追加します。 シールドキー ペアはトランザクションの署名、暗号化、復号化を行います。 シールドキー ペアは署名、ヌリファイア、およびビューイングキーのバンドルです。 * **署名キー:** トランザクションに署名するためのウォレットのEd25519 Solanaキー ペア。 * **ビューイングキー:** トランザクションを暗号化および復号化するためのP-256キー ペア。 * **ヌリファイアキー:** ヌリファイアを導き出すためのキーです。 ウォレットはシールドキー ペアを2つの方法で作成できます: 1. シードベースのウォレットの場合、**シードフレーズから導き出す**を選択。 2. シードベースでないウォレットの場合、**EdDSA署名から導き出す**を選択。 シードベースのウォレットは、1つのBIP-39ニーモニックとアカウントインデックス (`0`, `1`, …) からシールドキー ペアを導き出します。 各アカウントインデックスは1つのSolanaキー ペアと1つのシールドキー ペアにマップされます。 Solanaキー ペアと同じ方法でシールドキー ペアを復元できます。 例: * アカウント0: Solanaキー ペア0とシールドキー ペア0 * アカウント1: Solanaキー ペア1とシールドキー ペア1 | キー | 導出パス | スキーム | | ------ | ---------------------------------- | ------------------------- | | 署名 | `m/44'/501'/account'/0'` | SLIP-0010 Ed25519 | | ヌリファイア | `m/44'/1392955331'/account'/1'/0'` | SLIP-0010 Ed25519\[1..32] | | ビューイング | `m/44'/1392955331'/account'/2'/0'` | SLIP-0010 NIST P-256 | シールド署名キーはそのアカウントのSolana Ed25519キーです。 ヌリファイアとビューイングキーは同じシードから導出された追加キーです。 実装例: [TypeScript例](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/ts/test/seed-based-keypair.test.ts#L60) · [Rust例](https://github.com/helius-labs/zolana/blob/cad0664e374f6a0e5c532169c5895203e366eb56/sdk-libs/keypair/tests/seed_based_keypair.rs#L111) EdDSA署名でシールドキー ペアを導き出します。 EdDSA署名は決定的なので、同じメッセージの同じSolanaキー ペアの署名は常に同じシールドキー ペアを生成します。 署名をシードとして使用し、シールドキー ペアを導き出します。 固定されたメッセージペイロードは`"TSPP/derive/v1"`、Solanaオフチェーンメッセージv0としてエンコードされます。 シールド署名キーはウォレットのSolana EdDSAキーです。 ヌリファイアとビューイングキーは署名から導出された追加キーです。 署名が導出シードです。 これを持っている者はヌリファイアとビューイングキーを導出し、ユーザートランザクションを復号化できます。 第三者からの`"TSPP/derive/v1"`メッセージに対する署名要求を拒否してください。 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) } ``` 実装例: [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) ## プライバシーインターフェースとSDKの統合 プライバシーインターフェースにより、コードはプライバシーSDKを使用してキー素材に直接アクセスせずにプライベートトランザクションを構築できます。 キー管理はプライバシーインターフェースを2つの部分で実装します。 1. プライバシーSDKによるトランザクション構築用の署名インターフェース。ソースを表示: [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. 暗号化および復号化インターフェース。ソースを表示: [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) プライバシーインターフェースはステートレスであり、残高やトランザクション履歴を保存しません。 パフォーマンス向上のため、ユーザーの残高やトランザクション履歴をローカルでキャッシュすることをお勧めします。 ### 証明生成について ゼロ知識証明生成には、完全なユーザートランザクションデータとヌリファイアキーの平文入力が必要です。 現在、サーバーでの証明生成は標準的なHelius RPC URLを通じて利用可能です。 ローカルでの証明生成は近日公開予定です。 メインネットローンチ前にAWS Nitroでのエンドツーエンド暗号化サーバー証明生成を計画しています。 ## ユーザーフローの統合 ### プライベートウォレットを作成 プライベートウォレットは2つのステップで作成されます: 1. シールドキー ペアを導き出す 2. Solanaアドレスをオンチェーンレジストリに登録 レジストリは署名公開鍵をヌリファイアおよびビューイング公開鍵にリンクします。これらの公開鍵がシールドアドレスを形成します。 ```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 ``` 各レジストリレコードは[レジストリプログラム](https://orbmarkets.io/address/regyS5rkAcw2YzDJCmTwCTHs2s246FXxbmuRZ42u2PD)が所有するPDAであり、誰でもSolanaアドレスがプライベート転送を受け取れるかどうかを確認できます。 ### プライベート残高とトランザクション履歴の同期 残高同期は暗号化された状態をRPCから取得し、ウォレットで復号化します。 RPCは復号化を行いません。所有者のみがビューイングキーを使ってプライベート残高を復号化できます。 ウォレットはプライベートトランザクションの前やバックフィルの際、ウォレットのロック解除、プライベートウォレットのオープン、アプリの再開、ネットワークの再接続、ストリームギャップ、ウォレットの復元時に残高を復号化し更新すべきです。 ### プライベート残高への入金 ユーザーは次の2つの方法でプライベート残高に入金できます: 1. フィアット残高からプライベート暗号残高へのオンランプ 2. 公共のSPLアカウントからプライベート残高への入金 オンランプと入金はプライバシーの保証が異なります。 より良いプライバシーのためにオンランプの使用をお勧めします。 | フィールド | フィアットからオンランプ | SPLから入金 | | ------- | ------------ | ------- | | アセット | プライベート | パブリック | | 金額 | プライベート | パブリック | | ソース | オンチェーンではない | パブリック | | 送信先アドレス | パブリック | パブリック | プライベート残高へ直接フィアットのオン/オフランプを実行します。 公共の暗号残高から入金。 ### プライベート転送 ユーザーは任意のSolanaウォレットアドレスにプライベート転送を送信できます。 各プライベート転送に対して、プライバシーSDKはオンチェーンレジストリでウォレットアドレスを確認し、受取人がプライベートウォレットを持っているか確認します。 受取人がプライベートウォレットを持っていない場合、プライバシーSDKはプライベートからパブリックの出金にプライベート転送を解決できます。 誤ってパブリック残高に出金しないよう、UIでトランザクションを出金とラベル付けすることをお勧めします。 | フィールド | 可視性 | 理由 | | ------------- | ------ | ---------------------------------- | | アセット | プライベート | アセットはオンチェーンで暗号化されている | | 金額 | プライベート | 転送された金額はオンチェーンで暗号化されている | | 出所プライベートウォレット | パブリック | 機密リングでは出所プライベートウォレットはオンチェーンで表示される。 | | 受取人 | パブリック | 機密リングでは受取人はオンチェーンで表示される。 | プライベート残高へプライベートに転送します。 ### パブリック残高への出金 出金は次の2つの方法で使用できます: 1. プライベートウォレットを持たない受取人へのプライベート転送のフォールバックとして、または 2. 公共のSPLトークンアカウントへの直接出金として。 出金には、シードフレーズやプライベートキーのエクスポートのように、ユーザーがプライベート残高を離れることを明確にラベル付けすることをお勧めします。 | フィールド | 可視性 | 理由 | | ------------- | ------ | ---------------------------------- | | アセット | パブリック | アセットはオンチェーンで表示されている | | 金額 | パブリック | 出金された金額はオンチェーンで表示されている | | 出所プライベートウォレット | パブリック | 機密リングでは出所プライベートウォレットはオンチェーンで表示される。 | | 送信先パブリックウォレット | パブリック | 送信先ウォレットアドレスはオンチェーンで表示される | | 送信先パブリック残高 | パブリック | 結果のパブリック残高はオンチェーンで表示される | | 残りのプライベート残高 | プライベート | 残りの残高はオンチェーンで暗号化されている | パブリック暗号残高に出金します。 ## 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)