> ## 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="Compare to 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 Client">
    <Steps>
      <Step>
        ### Предварительные требования

        <Info>
          Для примеров на TypeScript требуются Node.js 24 или более поздней версии, pnpm 11.18.0 и Solana CLI.
        </Info>

        ```bash theme={"system"}
        pnpm add @heliuslabs/zolana@^0.4.0-alpha @solana/kit@^8.3.0
        ```

        Источник: [sdk-libs/ts](https://github.com/helius-labs/zolana/tree/ts-sdk-v0.4.0-alpha/sdk-libs/ts)

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

              Добавьте [ключ 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",
              });
              ```

              По умолчанию в примерах в качестве плательщика используется кошелёк Solana CLI. На балансе плательщика должны быть SOL в devnet. См. [Как получить SOL в devnet](/docs/ru/rpc/devnet-sol).
            </Tab>

            <Tab title="Localnet">
              В localnet SDK запускает локальный тестовый валидатор (`:8899`), индексатор Photon (`:8784`) и средство доказательства (`:3001`), после чего
              клиент автоматически подключается к ним без необходимости настраивать конечные точки.

              ```bash theme={"system"}
              cargo install --git https://github.com/helius-labs/zolana --tag v0.4.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` — это `senderAddress.confidentialViewTag()`, публичный ключ 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 { 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)` предоставляет ключи отправителя для локальной расшифровки.
        * `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 см. в разделе [Приватное состояние и UTXO](/docs/ru/privacy/concepts/utxo).
        </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/read_history.ts
    ```

    <Info>
      В примерах используется конфиденциальное кольцо в локальной сети/devnet, доступное [здесь](https://github.com/helius-labs/zolana-examples/blob/7775438e0a290a4c28dccf919719bd640c3ec5e3/typescript-client/examples/read_history.ts).
    </Info>
  </Tab>

  <Tab title="Rust Client">
    <Steps>
      <Step>
        ### Предварительные требования

        <Info>
          Для примеров на Rust требуются Rust 1.98.1 и Solana CLI v4.0.2. См. [руководство по установке 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.4.0-alpha", features = ["indexer-api", "solana-rpc"] }
        zolana-interface = { git = "https://github.com/helius-labs/zolana", tag = "v0.4.0-alpha" }
        zolana-program = { git = "https://github.com/helius-labs/zolana", tag = "v0.4.0-alpha" }
        zolana-keypair = { git = "https://github.com/helius-labs/zolana", tag = "v0.4.0-alpha" }
        zolana-transaction = { git = "https://github.com/helius-labs/zolana", tag = "v0.4.0-alpha" }
        zolana-wallet = { git = "https://github.com/helius-labs/zolana", tag = "v0.4.0-alpha" }
        ```

        Источник: [sdk-libs/client](https://github.com/helius-labs/zolana/tree/v0.4.0-alpha/sdk-libs/client)

        <Accordion title="Connect to Endpoints">
          <Tabs>
            <Tab title="Devnet">
              Добавьте [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 url = "https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY";
              let client = ZolanaClient::from_urls(SolanaRpc::new(url), url, url)?;
              ```

              По умолчанию в примерах в качестве плательщика используется кошелёк Solana CLI. На балансе плательщика должны быть SOL в сети devnet. См. [Как получить SOL в сети devnet](/docs/ru/rpc/devnet-sol).
            </Tab>

            <Tab title="Localnet">
              ```bash theme={"system"}
              cargo install --git https://github.com/helius-labs/zolana --tag v0.4.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>
        ### Получение тега просмотра

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

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

        * `sender_tag` — это `sender_shielded_address.confidential_view_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_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` предоставляет ключ просмотра отправителя для локальной расшифровки.
        * `Wallet::sync` расшифровывает соответствующие выходы и записывает историю в `Wallet`.
        * `wallet.private_transactions()` считывает расшифрованную историю.
        * `decrypt_spendable` возвращает проверенные балансы и UTXO вместе с данными, а не историю транзакций.

        **Пример ответа:**

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

    <Info>
      В примерах используется конфиденциальное кольцо в локальной сети/devnet, доступное [здесь](https://github.com/helius-labs/zolana-examples/blob/7775438e0a290a4c28dccf919719bd640c3ec5e3/rust-client/examples/read_history.rs).
    </Info>
  </Tab>
</Tabs>

## Связанные руководства

<CardGroup cols={2}>
  <Card title="Read a Private Balance" icon="wallet" href="/docs/ru/privacy/guides/read-balance" horizontal />

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

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

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

## Не нашли то, что искали?

<Callout type="info">
  Свяжитесь с нами! [Telegram](https://t.me/tilo_light) | [Электронная почта](mailto:sales@helius.xyz) | [Контакты](https://www.helius.dev/contact)
</Callout>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.