> ## 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. # Private Wallet > 허가 없이 비공개 Ring을 위해 기존 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 키쌍. * **널리파이어 키:** 널리파이어를 파생하는 데 사용되는 키. 지갑은 두 가지 방법으로 보호된 키쌍을 생성할 수 있습니다: 1. 시드 기반 지갑에는 **시드 문구에서 파생**을 선택하세요. 2. 비시드 기반 지갑에는 **EdDSA 서명에서 파생**을 선택하세요. 시드 기반 지갑은 하나의 BIP-39 니모닉과 계정 인덱스(`0`, `1`, …)에서 보호된 키쌍을 파생합니다. 각 계정 인덱스는 하나의 Solana 키쌍을 하나의 보호된 키쌍에 매핑합니다. Solana 키쌍을 복구하는 것과 동일한 방법으로 보호된 키쌍을 복구할 수 있습니다. 예시: * 계정 0: Solana 키쌍 0 및 보호된 키쌍 0 * 계정 1: Solana 키쌍 1 및 보호된 키쌍 1 | Key | 도출 경로 | 스키마 | | ----- | ---------------------------------- | ------------------------- | | 서명 | `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 키쌍의 동일한 메시지 서명은 항상 동일한 보호된 키쌍을 생성합니다. 우리는 서명을 시드로 사용하여 보호된 키쌍을 파생합니다. 고정된 메시지 페이로드는 Solana 오프체인 메시지 v0로 인코딩된 `"TSPP/derive/v1"`입니다. 보호된 서명 키는 지갑의 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를 사용하여 비공개 거래를 생성할 수 있습니다. 귀하의 키 관리는 두 부분으로 프라이버시 인터페이스를 구현합니다. 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에서 메인넷 출시 전에 끝에서 끝으로 암호화된 서버 증명 생성을 계획하고 있습니다. ## 사용자 흐름 통합 ### 비공개 지갑 생성 비공개 지갑은 두 단계로 생성됩니다: 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는 복호화하지 않습니다. 소유자만 뷰잉 키로 비공개 잔액을 복호화할 수 있습니다. 지갑은 비공개 거래 및 모든 백필 실행 시: 지갑 잠금 해제, 비공개 지갑 열기, 앱 재개, 네트워크 재연결, 스트림 간격, 또는 지갑 복원 시 잔액을 복호화하고 업데이트해야 합니다. ### 비공개 잔액으로 입금 사용자는 두 가지 방법으로 비공개 잔액으로 입금할 수 있습니다: 1. 법정 화폐 잔액에서 비공개 암호화폐 잔액으로 온램프 2. 공개 SPL 계정에서 비공개 잔액으로 입금 온램프와 입금은 프라이버시 보장이 다릅니다. 개인 정보 보호를 위해 온램프 사용을 권장합니다. | 필드 | 법정 화폐에서 온램프 | SPL에서 입금 | | ------ | ----------- | -------- | | 자산 | 비공개 | 공개 | | 금액 | 비공개 | 공개 | | 출처 | 온체인 아님 | 공개 | | 목적지 주소 | 공개 | 공개 | 온램프/오프램프로 비공개 잔액에 직접 법정 화폐를 송금합니다. 공개 암호화폐 잔액에서 입금합니다. ### 비공개 전송 사용자는 모든 Solana 지갑 주소로 비공개 전송을 보낼 수 있습니다. 프라이버시 SDK는 비공개 전송마다 온체인 레지스트리에서 지갑 주소를 조회하여 수신자가 비공개 지갑을 가지고 있는지 확인합니다. 수신자가 비공개 지갑을 가지고 있지 않은 경우, 프라이버시 SDK는 비공개 전송을 비공개에서 공개로의 출금으로 해결할 수 있습니다. 사용자가 의도하지 않게 공개 잔액으로 출금하지 않도록 사용자 인터페이스에서 거래를 출금으로 레이블링할 것을 권장합니다. | 필드 | 가시성 | 이유 | | --------- | --- | ---------------------------- | | 자산 | 비공개 | 자산은 온체인에서 암호화됨 | | 금액 | 비공개 | 전송된 금액은 온체인에서 암호화됨 | | 출처 비공개 지갑 | 공개 | 기밀 링에서는 출처 비공개 지갑이 온체인에서 보임. | | 수신자 | 공개 | 기밀 링에서는 수신자가 온체인에서 보임. | 비공개 잔액으로 비공개 전송합니다. ### 공개 잔액으로 출금 출금은 두 가지 방식으로 사용할 수 있습니다: 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)