> ## 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 메서드를 통해 인덱서에서 암호화된 개인 Solana 토큰 계정을 가져옵니다.
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: Sum to private balances
```

<Accordion title="getBalance / getAccount과 비교">
  1. `getBalance`는 공개 SOL을 반환합니다. `getAccount`는 공개 토큰 계정을 반환합니다.
  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: getBalance / getAccount
      RPC-->>Wallet: Public SOL or token account
  ```
</Accordion>

# 시작하기

<Tabs>
  <Tab title="TypeScript Client">
    <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 공개 키로, 인덱서는 이를 사용하여 일치하는 암호화된 출력을 반환합니다.
      </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 { SOL_MINT } from "@heliuslabs/zolana";
        import { decryptToBalances } from "@heliuslabs/zolana/transaction";

        const balancesAfterDeposit =
          await decryptToBalances({
            keypair: senderKeypair,
            registry: assets,
            transactions: depositResponse.transactions,
          });
        const depositBalance =
          balancesAfterDeposit.balance(SOL_MINT);
        ```

        * `senderKeypair`는 지역 복호화를 위한 발신자의 조회 키를 제공합니다.
        * `decryptToBalances`는 일치하는 출력을 복호화하고 발신자의 개인 잔액을 반환합니다.
        * `balancesAfterDeposit.balance(SOL_MINT)`는 개인 SOL 잔액을 읽습니다.

        <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>
      예제는 로컬/devnet의 비공개 링을 사용합니다 [여기](https://github.com/helius-labs/zolana-examples/blob/main/typescript-client/examples/deposit_transfer_withdraw.ts).
    </Info>
  </Tab>

  <Tab title="Rust Client">
    <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 공개 키로, 인덱서는 이를 사용하여 일치하는 암호화된 출력을 반환합니다.
      </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::{decrypt_transactions, SOL_MINT};

        let balances = decrypt_transactions(&sender, &response.transactions, &assets)
            .map_err(|e| anyhow!("decrypt sender transactions: {e:?}"))?;
        let sender_balance = balances.get_balance(SOL_MINT);
        ```

        * `sender`는 지역 복호화를 위한 발신자의 조회 키를 제공합니다.
        * `decrypt_transactions`는 일치하는 출력을 복호화하고 발신자의 개인 잔액을 반환합니다.
        * `get_balance(SOL_MINT)`는 개인 SOL 잔액을 읽습니다.
      </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>
      예제는 로컬/devnet의 비공개 링을 사용합니다 [여기](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="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 />

  <Card title="개인 이력 읽기" icon="clock-rotate-left" href="/docs/ko/privacy/guides/read-history" 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>