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

# Đọc số dư riêng tư

> Hướng dẫn đọc số dư riêng tư của ví từ bộ lập chỉ mục, kèm theo ví dụ mã đầy đủ.

1. Thao tác đọc truy xuất các Tài khoản Token Solana Riêng tư đã mã hóa từ bộ lập chỉ mục bằng các phương thức RPC chuyên dụng.
2. Chỉ người dùng hoặc bất kỳ ai được người dùng ủy quyền mới có thể giải mã số dư bằng khóa xem của họ.
3. Sử dụng thao tác này sau khi số dư riêng tư thay đổi và trước khi chuyển khoản.

```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="Compare to getBalance / getAccount">
  1. `getBalance` trả về SOL công khai. `getAccount` trả về một tài khoản token công khai.
  2. RPC trả về số dư công khai.

  ```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>

## Bắt đầu

<Tabs>
  <Tab title="TypeScript Client">
    <Steps>
      <Step>
        ### Điều kiện tiên quyết

        <Info>
          Các ví dụ TypeScript yêu cầu Node.js 24 trở lên, pnpm 11.18.0 và Solana CLI.
        </Info>

        ```bash theme={"system"}
        pnpm add 'git+ssh://git@github.com/helius-labs/zolana.git#v0.3.0-alpha&path:/sdk-libs/ts' @solana/kit@^8.3.0
        ```

        Nguồn: [sdk-libs/ts](https://github.com/helius-labs/zolana/tree/v0.3.0-alpha/sdk-libs/ts)

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

              Thêm [khóa API Helius](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: "https://d2xah7tnhdhcom.cloudfront.net",
                proverUrl: "https://d21ni15goiip6l.cloudfront.net",
              });
              ```

              Theo mặc định, các ví dụ sử dụng ví Solana CLI làm bên thanh toán. Bên thanh toán phải có SOL trên devnet. Xem [Cách nhận SOL trên devnet](/docs/vi/rpc/devnet-sol).
            </Tab>

            <Tab title="Localnet">
              Trên localnet, SDK khởi động trình xác thực kiểm thử cục bộ (`:8899`), trình lập chỉ mục Photon (`:8784`) và trình chứng minh (`:3001`), đồng thời
              máy khách tự động kết nối với chúng mà không cần cấu hình điểm cuối.

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

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

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

      <Step>
        ### Tạo thẻ xem

        ```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` là `senderAddress.confidentialViewTag()`, khóa công khai Solana của người gửi trong các Ring bảo mật. Bộ lập chỉ mục sử dụng khóa này để trả về các đầu ra được mã hóa tương ứng.
      </Step>

      <Step>
        ### Truy xuất đầu ra giao dịch từ bộ lập chỉ mục

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

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

        * `getShieldedTransactionsByTags` truy xuất các đầu ra được mã hóa liên kết với `senderViewTag`.
        * `atSlot(depositTx.slot)` chờ cho đến khi bộ lập chỉ mục có khoản nạp tại slot đó.
        * Bộ lập chỉ mục trả về dữ liệu đầu ra được mã hóa. Bộ lập chỉ mục không giải mã số dư riêng tư.
      </Step>

      <Step>
        ### Giải mã thành số dư riêng tư

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

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

        * `sender` cung cấp khóa xem của người gửi để giải mã cục bộ.
        * `decryptToBalances` giải mã các đầu ra tương ứng và trả về số dư riêng tư của người gửi.
        * `balancesAfterDeposit.balance(SOL_MINT)` đọc số dư SOL riêng tư.

        <Note>
          Xem [Khái niệm](/docs/vi/privacy/concepts) để tìm hiểu cách hoạt động của tính năng gắn thẻ chủ sở hữu và Tài khoản Token Solana Riêng tư.
        </Note>
      </Step>
    </Steps>

    ### Ví dụ mã đầy đủ

    Sao chép kho lưu trữ và chạy ví dụ:

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

    <Info>
      Các ví dụ sử dụng một Ring bảo mật trên local/devnet [tại đây](https://github.com/helius-labs/zolana-examples/blob/7775438e0a290a4c28dccf919719bd640c3ec5e3/typescript-client/examples/sync_balance.ts).
    </Info>
  </Tab>

  <Tab title="Rust Client">
    <Steps>
      <Step>
        ### Điều kiện tiên quyết

        <Info>
          Các ví dụ Rust yêu cầu Rust 1.98.1 và Solana CLI v4.0.2. Xem [hướng dẫn cài đặt Solana](https://solana.com/docs/intro/installation).
        </Info>

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

        Nguồn: [sdk-libs/client](https://github.com/helius-labs/zolana/tree/v0.3.0-alpha/sdk-libs/client)

        <Accordion title="Connect to Endpoints">
          <Tabs>
            <Tab title="Devnet">
              Thêm [khóa API Helius](https://dashboard.helius.dev/):

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

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

              let tree = pda::tree(0);
              let client = ZolanaClient::from_urls(
                  SolanaRpc::new("https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY"),
                  "https://d2xah7tnhdhcom.cloudfront.net",
                  "https://d21ni15goiip6l.cloudfront.net",
              )?;
              ```

              Theo mặc định, các ví dụ sử dụng ví Solana CLI làm tài khoản thanh toán. Tài khoản thanh toán phải có SOL trên devnet. Xem [Cách nhận SOL trên devnet](/docs/vi/rpc/devnet-sol).
            </Tab>

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

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

              let tree = pda::tree(0);
              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",
              )?;
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Tạo thẻ xem

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

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

        * `sender_tag` là `sender_shielded_address.confidential_view_tag()`, khóa công khai Solana của người gửi trong các Ring bảo mật. Bộ lập chỉ mục sử dụng khóa này để trả về các đầu ra được mã hóa tương ứng.
      </Step>

      <Step>
        ### Truy xuất đầu ra giao dịch từ bộ lập chỉ mục

        ```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` truy xuất các đầu ra được mã hóa liên kết với `sender_tag`.
        * `IndexerRpcConfig::at_slot(slot)` chờ cho đến khi bộ lập chỉ mục có khoản nạp tại slot đó.
        * Bộ lập chỉ mục trả về dữ liệu đầu ra được mã hóa. Bộ lập chỉ mục không giải mã số dư riêng tư.
      </Step>

      <Step>
        ### Giải mã thành số dư riêng tư

        ```rust theme={"system"}
        use anyhow::anyhow;
        use zolana_transaction::{decrypt_spendable, SOL_MINT};

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

        * `sender` cung cấp khóa xem của người gửi để giải mã cục bộ.
        * `decrypt_spendable` giải mã và xác minh các đầu ra tương ứng. Trường `.balances` của đối tượng này chứa số dư của người gửi cho các đầu ra đó.
        * `get_balance(SOL_MINT)` đọc số dư SOL riêng tư.
      </Step>
    </Steps>

    ### Ví dụ mã đầy đủ

    Sao chép kho lưu trữ và chạy ví dụ:

    ```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 sync_balance
    ```

    <Info>
      Các ví dụ sử dụng một Ring bảo mật trên local/devnet [tại đây](https://github.com/helius-labs/zolana-examples/blob/7775438e0a290a4c28dccf919719bd640c3ec5e3/rust-client/examples/sync_balance.rs).
    </Info>
  </Tab>
</Tabs>

## Hướng dẫn liên quan

<CardGroup cols={2}>
  <Card title="Create a Private Wallet" icon="wallet" href="/docs/vi/privacy/integration/wallet#tạo-ví-riêng-tư" horizontal />

  <Card title="Deposit" icon="arrow-down-to-bracket" href="/docs/vi/privacy/guides/deposit" horizontal />

  <Card title="Transfer" icon="arrow-right-arrow-left" href="/docs/vi/privacy/guides/transfer" horizontal />

  <Card title="Withdraw" icon="arrow-up-from-bracket" href="/docs/vi/privacy/guides/withdraw" horizontal />

  <Card title="Read Private History" icon="clock-rotate-left" href="/docs/vi/privacy/guides/read-history" horizontal />
</CardGroup>

## Không tìm thấy nội dung bạn đang tìm kiếm?

<Callout type="info">
  Hãy liên hệ với chúng tôi! [Telegram](https://t.me/tilo_light) | [Email](mailto:sales@helius.xyz) | [Liên hệ](https://www.helius.dev/contact)
</Callout>