> ## 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.

# 비공개 기록 읽기

> 인덱서에서 지갑의 비공개 거래 기록을 읽는 가이드와 전체 코드 예제입니다.

1. 전용 RPC 메서드를 사용하여 인덱서에서 암호화된 거래를 읽어옵니다.
2. 사용자 또는 사용자가 권한을 부여한 사람만이 자신의 보기 키로 기록을 해독할 수 있습니다.
3. 지갑이 백필을 수행하는 곳 어디에서든 사용: 지갑 잠금 해제 시, 비공개 지갑 열기 시, 앱 재개 시, 네트워크 재연결 시, 스트림 간격, 또는 지갑 복원 시.

```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 Wallet
    participant RPC as RPC Provider

    Wallet->>RPC: getShieldedTransactionsByTags
    RPC-->>Wallet: Encrypted transactions
    Note over Wallet: Decrypt
    Note over Wallet: Decrypt to private history
```

<Accordion title="getSignaturesForAddress와 비교">
  1. `getSignaturesForAddress`는 공개 서명을 반환합니다.
  2. RPC는 공개 기록을 반환합니다.

  ```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 Wallet
      participant RPC

      Wallet->>RPC: getSignaturesForAddress
      RPC-->>Wallet: Public signatures
  ```
</Accordion>

# 시작하기

<Tabs>
  <Tab title="TypeScript 클라이언트">
    <Steps>
      <Step>
        ### 전제 조건

        <Info>
          The TypeScript examples require Node.js 24 or later, pnpm 11.18.0, and the Solana CLI.
        </Info>

        ```bash theme={"system"}
        pnpm add @heliuslabs/zolana @solana/kit
        ```

        Source: [sdk-libs/ts](https://github.com/helius-labs/zolana/tree/main/sdk-libs/ts)

        <Accordion title="Connect to Endpoints">
          <Tabs>
            <Tab title="Devnet">
              ```bash theme={"system"}
              pnpm install
              cp .env.example .env
              ```

              Add a [Helius API key](https://dashboard.helius.dev/):

              ```bash .env theme={"system"}
              API_KEY=YOUR_API_KEY
              ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json
              ```

              ```ts theme={"system"}
              import { createZolanaClient } from "@heliuslabs/zolana";

              const client = await createZolanaClient({
                solanaRpcUrl: "https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY",
                indexerUrl: "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com",
                proverUrl: "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com:3001",
                allowInsecureHttp: true,
              });
              ```

              The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See [How to Get Devnet SOL](/docs/rpc/devnet-sol).
            </Tab>

            <Tab title="Localnet">
              On localnet the SDK starts the local test validator (`:8899`), Photon indexer (`:8784`), and prover (`:3001`), and the
              client connects to them automatically without needing endpoint configuration.

              ```bash theme={"system"}
              cargo install --git https://github.com/helius-labs/zolana --tag v0.1.0-alpha zolana-cli
              zolana dev start
              ```

              ```ts theme={"system"}
              import { createZolanaClient } from "@heliuslabs/zolana";

              const client = await createZolanaClient({});
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### 보기 태그 파생

        ```typescript theme={"system"}
        import { createZolanaClient } from "@heliuslabs/zolana";

        // The view tag is the sender's Solana public key in confidential rings.
        // Used by the indexer to fetch the sender's UTXOs.
        const senderViewTag =
          senderAddress.confidentialViewTag();
        ```

        * `senderViewTag`는 비공개 링에 있는 발신자의 Solana 공개 키인 `senderAddress.confidentialViewTag()`입니다. 인덱서는 이를 사용하여 일치하는 암호화된 출력을 반환합니다.
      </Step>

      <Step>
        ### 인덱서에서 거래 출력 가져오기

        ```typescript theme={"system"}
        import { atSlot } from "@heliuslabs/zolana/client";

        const depositResponse =
          await client.getShieldedTransactionsByTags(
            { tags: [senderViewTag] },
            atSlot(depositTx.slot),
          );
        ```

        * `getShieldedTransactionsByTags`는 `senderViewTag`와 관련된 암호화된 출력을 가져옵니다.
        * `atSlot(depositTx.slot)`는 인덱서가 해당 슬롯에 입금을 할 때까지 기다립니다.
        * 인덱서는 암호화된 출력 데이터를 반환합니다. 비공개 기록은 해독하지 않습니다.
      </Step>

      <Step>
        ### 비공개 기록으로 해독

        ```typescript theme={"system"}
        import { Wallet } from "@heliuslabs/zolana";
        import { decryptTransactions } from "@heliuslabs/zolana/transaction";

        const wallet = new Wallet({
          identity: senderAddress,
          registry: assets,
        });
        await decryptTransactions({
          wallet,
          authority: {
            syncMaterial: () =>
              Promise.resolve({
                identity: senderAddress,
                viewingKeys: [senderKeypair.viewingKey()],
                nullifierKey: senderKeypair.nullifierKey(),
              }),
          },
          transactions: depositResponse.transactions,
        });
        const history = wallet.privateTransactions();
        ```

        * `senderKeypair`는 로컬 해독을 위해 발신자의 보기 키를 제공합니다.
        * `decryptTransactions`는 일치하는 출력을 해독하고 `Wallet`에 기록합니다.
        * `wallet.privateTransactions()`는 해독된 기록을 읽습니다.
        * `decryptToBalances`는 잔액만 반환합니다.

        **예시 응답:**

        ```ts theme={"system"}
        [
          {
            id: { signature: "5x…", slot: 291044100n, index: 0n },
            kind: "deposit",
            direction: "inbound",
            status: "confirmed",
            asset: SOL_MINT,
            amount: 100_000_000n,
            counterpartyViewingPublicKey: undefined,
          },
        ]
        ```

        <Note>
          소유자 태그 지정 및 비공개 Solana 토큰 계정이 작동하는 방법에 대한 정보는 [개념](/docs/ko/privacy/concepts)을 참조하세요.
        </Note>
      </Step>
    </Steps>

    ### 전체 코드 예제

    예제를 복제하고 실행하세요:

    ```bash theme={"system"}
    git clone https://github.com/helius-labs/zolana-examples.git
    cd zolana-examples/typescript-client
    pnpm install
    pnpm example examples/deposit_transfer_withdraw.ts
    ```

    <Info>
      예제는 [여기](https://github.com/helius-labs/zolana-examples/blob/main/typescript-client/examples/deposit_transfer_withdraw.ts)에 있는 로컬/개발 네트워크의 비공개 링을 사용합니다.
    </Info>
  </Tab>

  <Tab title="Rust 클라이언트">
    <Steps>
      <Step>
        ### 전제 조건

        <Info>
          The Rust examples require the latest stable Rust toolchain and the Solana CLI v4.0.2. See the [Solana installation guide](https://solana.com/docs/intro/installation).
        </Info>

        ```toml Cargo.toml theme={"system"}
        [dependencies]
        zolana-client = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha", features = ["indexer-api", "solana-rpc"] }
        zolana-interface = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha", features = ["solana"] }
        zolana-keypair = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha" }
        zolana-transaction = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha" }
        ```

        Source: [sdk-libs/client](https://github.com/helius-labs/zolana/tree/v0.1.0-alpha/sdk-libs/client)

        <Accordion title="Connect to Endpoints">
          <Tabs>
            <Tab title="Devnet">
              Add a [Helius API key](https://dashboard.helius.dev/):

              ```bash .env theme={"system"}
              API_KEY=YOUR_API_KEY
              ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json
              ```

              ```rust theme={"system"}
              use solana_address::Address;
              use zolana_client::{SolanaRpc, ZolanaClient};
              use zolana_interface::DEFAULT_TREE_ADDRESS;

              let tree: Address = DEFAULT_TREE_ADDRESS.parse()?;
              let client = ZolanaClient::from_urls_allowing_insecure_http(
                  SolanaRpc::new("https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY"),
                  "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com",
                  "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com:3001",
                  tree,
              );
              ```

              The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See [How to Get Devnet SOL](/docs/rpc/devnet-sol).
            </Tab>

            <Tab title="Localnet">
              ```bash theme={"system"}
              cargo install --git https://github.com/helius-labs/zolana --tag v0.1.0-alpha zolana-cli
              zolana dev start
              ```

              ```rust theme={"system"}
              use solana_address::Address;
              use zolana_client::{SolanaRpc, ZolanaClient};
              use zolana_interface::DEFAULT_TREE_ADDRESS;

              let tree: Address = DEFAULT_TREE_ADDRESS.parse()?;
              let client = ZolanaClient::from_urls(
                  SolanaRpc::new("http://127.0.0.1:8899"),
                  "http://127.0.0.1:8784",
                  "http://127.0.0.1:3001",
                  tree,
              )?;
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### 보기 태그 파생

        ```rust theme={"system"}
        use zolana_client::Rpc;

        let sender_tag = sender_shielded_address.confidential_view_tag()?;
        ```

        * `sender_tag`는 비공개 링에 있는 발신자의 Solana 공개 키인 `sender_shielded_address.confidential_view_tag()`입니다. 인덱서는 이를 사용하여 일치하는 암호화된 출력을 반환합니다.
      </Step>

      <Step>
        ### 인덱서에서 거래 출력 가져오기

        ```rust theme={"system"}
        use zolana_client::{IndexerRpcConfig, Rpc};

        let response = client.get_shielded_transactions_by_tags(
            vec![sender_tag],
            None,
            Some(50),
            Some(IndexerRpcConfig::at_slot(slot)),
        )?;
        ```

        * `get_shielded_transactions_by_tags`는 `sender_tag`와 관련된 암호화된 출력을 가져옵니다.
        * `IndexerRpcConfig::at_slot(slot)`는 인덱서가 해당 슬롯에 입금을 할 때까지 기다립니다.
        * 인덱서는 암호화된 출력 데이터를 반환합니다. 비공개 기록은 해독하지 않습니다.
      </Step>

      <Step>
        ### 비공개 기록으로 해독

        ```rust theme={"system"}
        use anyhow::anyhow;
        use zolana_transaction::{Wallet, DEFAULT_TAG_WINDOW};

        let mut wallet = Wallet::new(sender.shielded_address()?, assets.clone())
            .map_err(|e| anyhow!("create wallet: {e:?}"))?;
        wallet
            .sync(&sender, &response.transactions, 0, DEFAULT_TAG_WINDOW)
            .map_err(|e| anyhow!("decrypt sender transactions: {e:?}"))?;
        let history = wallet.private_transactions();
        ```

        * `sender`는 로컬 해독을 위해 발신자의 보기 키를 제공합니다.
        * `Wallet::sync`는 일치하는 출력을 해독하고 `Wallet`에 기록합니다.
        * `wallet.private_transactions()`는 해독된 기록을 읽습니다.
        * `decrypt_transactions`는 잔액만 반환합니다.

        **예시 응답:**

        ```rust theme={"system"}
        [
            PrivateTransaction {
                id: PrivateTransactionId {
                    signature: "5x…".into(),
                    slot: 291044100,
                    index: 0,
                },
                kind: PrivateTransactionKind::Deposit,
                direction: PrivateTransactionDirection::Inbound,
                status: PrivateTransactionStatus::Confirmed,
                asset: SOL_MINT,
                amount: 100_000_000,
                counterparty_viewing_pubkey: None,
            },
        ]
        ```
      </Step>
    </Steps>

    ## 전체 코드 예제

    예제를 복제하고 실행하세요:

    ```bash theme={"system"}
    git clone https://github.com/helius-labs/zolana-examples.git
    cd zolana-examples/rust-client
    cargo run -p rust-client-example --example deposit_transfer_withdraw
    ```

    <Info>
      예제는 [여기](https://github.com/helius-labs/zolana-examples/blob/main/rust-client/examples/deposit_transfer_withdraw.rs)에 있는 로컬/개발 네트워크의 비공개 링을 사용합니다.
    </Info>
  </Tab>
</Tabs>

## 관련 가이드

<CardGroup cols={2}>
  <Card title="비공개 잔액 읽기" icon="wallet" href="/docs/ko/privacy/guides/read-balance" horizontal />

  <Card title="입금" icon="arrow-down-to-bracket" href="/docs/ko/privacy/guides/deposit" horizontal />

  <Card title="전송" icon="arrow-right-arrow-left" href="/docs/ko/privacy/guides/transfer" horizontal />

  <Card title="출금" icon="arrow-up-from-bracket" href="/docs/ko/privacy/guides/withdraw" horizontal />
</CardGroup>

## Didn't find what you were looking for?

<Callout type="info">
  Reach out! [Telegram](https://t.me/tilo_light) | [E-Mail](mailto:sales@helius.xyz) | [Contact](https://www.helius.dev/contact)
</Callout>