> ## 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 lịch sử riêng tư

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

1. Thao tác đọc tìm nạp các giao dịch đã 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ã lịch sử bằng khóa xem của họ.
3. Sử dụng thao tác này ở bất cứ nơi nào ví chạy quá trình truy xuất dữ liệu quá khứ: khi mở khóa ví, mở ví riêng tư, tiếp tục ứng dụng, kết nối lại mạng, có khoảng trống trong luồng hoặc khôi phục ví.

```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="Compare to getSignaturesForAddress">
  1. `getSignaturesForAddress` trả về các chữ ký công khai.
  2. RPC trả về lịch sử 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: getSignaturesForAddress
      RPC-->>Wallet: Public signatures
  ```
</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 vòng bảo mật. Bộ lập chỉ mục sử dụng khóa này để trả về các đầu ra đã mã hóa khớp với khóa.
      </Step>

      <Step>
        ### Tìm nạp đầ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` tìm nạp các đầu ra đã 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 đã mã hóa. Nó không giải mã lịch sử riêng tư.
      </Step>

      <Step>
        ### Giải mã thành lịch sử riêng tư

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

        const wallet = new Wallet({
          identity: senderAddress,
          registry: assets,
        });
        await decryptTransactions({
          wallet,
          keys: LocalShieldedKeys.fromKeypair(sender),
          transactions: depositResponse.transactions,
        });
        const history = wallet.privateTransactions();
        ```

        * `LocalShieldedKeys.fromKeypair(sender)` cung cấp các khóa của người gửi để giải mã cục bộ.
        * `decryptTransactions` giải mã các đầu ra khớp và ghi lịch sử vào `Wallet`.
        * `wallet.privateTransactions()` đọc lịch sử đã giải mã.
        * `decryptToBalances` chỉ trả về số dư.

        **Phản hồi mẫu:**

        ```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>
          Xem [Khái niệm](/docs/vi/privacy/concepts) để tìm hiểu cách hoạt động của việc 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/read_history.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/read_history.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 vòng bảo mật. Bộ lập chỉ mục sử dụng khóa này để trả về các đầu ra đã mã hóa khớp với khóa.
      </Step>

      <Step>
        ### Tìm nạp đầ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` tìm nạp các đầu ra đã 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 đã mã hóa. Nó không giải mã lịch sử riêng tư.
      </Step>

      <Step>
        ### Giải mã thành lịch sử riêng tư

        ```rust theme={"system"}
        use anyhow::anyhow;
        use zolana_wallet::{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` cung cấp khóa xem của người gửi để giải mã cục bộ.
        * `Wallet::sync` giải mã các đầu ra khớp và ghi lịch sử vào `Wallet`.
        * `wallet.private_transactions()` đọc lịch sử đã giải mã.
        * `decrypt_spendable` trả về số dư đã xác minh và các UTXO kèm dữ liệu, không phải lịch sử giao dịch.

        **Phản hồi mẫu:**

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

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

    <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/read_history.rs).
    </Info>
  </Tab>
</Tabs>

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

<CardGroup cols={2}>
  <Card title="Read a Private Balance" icon="wallet" href="/docs/vi/privacy/guides/read-balance" 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 />
</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>