Поддержка конфиденциальных переводов в Solana

Общие сведения

Расширение конфиденциальных переводов позволяет минтам Token-2022 хранить суммы переводов и балансы аккаунтов в зашифрованном виде в блокчейне. Балансы зашифрованы, поэтому для их отображения требуются ключи дешифрования владельца, а для отправки необходимо генерировать доказательства с нулевым разглашением на стороне клиента.

Это руководство предназначено для команд, интегрирующих токены с конфиденциальными переводами (кошельки, обозреватели, биржи, кастодианы, индексеры), а не для эмитентов, настраивающих минт. Если вы строите базовый процесс с нуля, начните с пошаговых страниц, ссылки на которые приведены ниже; данное руководство сосредоточено на том, что должен делать ваш продукт для корректной поддержки этих токенов.

Адреса аккаунтов, минт и владелец каждого аккаунта остаются публичными. Зашифрованы только суммы и балансы, поэтому всё остальное, включая информацию о том, кто с кем проводит транзакции, остаётся видимым. Это обеспечивает конфиденциальность от публичных наблюдателей, но не анонимность.

Ресурсы

• Обзор конфиденциальных переводов и пошаговые руководства
• Код расширения на Rust
• @solana-program/token-2022 JS-клиент (инструкции, парсинг состояния аккаунта, деривация ключей и высокоуровневые вспомогательные функции для конфиденциальных переводов)
• @solana/zk-sdk WASM SDK (примитивы шифрования и генерация данных доказательств)
• @solana-program/zk-elgamal-proof JS-клиент (инструкции верификации доказательств)
• spl-token-client Rust-крейт (высокоуровневые сквозные вспомогательные функции на Rust)

Коротко о главном

• Каждый аккаунт конфиденциального токена по-прежнему имеет публичный баланс, а также зашифрованный ожидающий и доступный баланс. Токен может свободно перемещаться между публичным и конфиденциальным состояниями.
• Для отображения конфиденциального баланса необходимы ключи владельца. Рекомендуемый подход — деривация ключей из кошелька владельца, расшифровка доступного баланса с помощью AES-ключа (быстро) и расшифровка ожидающих сумм с помощью ключа ElGamal по мере необходимости.
• Для конфиденциальной отправки на стороне клиента генерируются ZK-доказательства (равенство, валидность шифротекста, диапазон), которые обычно размещаются во временных аккаунтах состояния контекста доказательств, после чего выполняется перевод. Как @solana-program/token-2022 (JS), так и spl-token-client (Rust) предоставляют высокоуровневые вспомогательные функции, которые формируют доказательства и выстраивают последовательность транзакций.
• Конфиденциальные переводы в настоящее время охватывают несколько зависимых транзакций, поскольку доказательства превышают текущий лимит размера транзакции. Предстоящее обновление (формат транзакций v1, выходящий вместе с Agave v4.2) повысит этот лимит и, как ожидается, позволит выполнять конфиденциальный перевод в рамках одной транзакции в блокчейне.
• Кошелёк без какой-либо поддержки всё равно работает: он отображает публичный баланс, а стандартные переводы продолжают функционировать. Конфиденциальные средства остаются доступными для любого клиента с поддержкой конфиденциальности, имеющего ключи владельца.

Термины

• ElGamal keypair: keypair с открытым ключом для каждого аккаунта, используемый для шифрования балансов и построения ZK-доказательств. Открытый ключ хранится в аккаунте.
• AES-ключ: симметричный ключ для каждого аккаунта, используемый для шифрования «расшифровываемого доступного баланса», чтобы владелец мог читать свой доступный баланс за постоянное время, без решения задачи дискретного логарифма.
• Ожидающий баланс: зашифрованный баланс средств, полученных через депозиты или входящие переводы, которые ещё не были применены. Не может быть потрачен напрямую.
• Доступный баланс: зашифрованный баланс, который можно перевести или вывести.
• Применение: шаг, который переводит ожидающий баланс в доступный.
• Аккаунт состояния контекста доказательства: временный аккаунт в сети, хранящий предварительно проверенное ZK-доказательство, на которое ссылается конфиденциальная инструкция, после чего он закрывается для возврата rent.
• Аудитор: необязательный глобальный ElGamal-ключ на минте; если задан, каждый перевод дополнительно шифрует свою сумму под этим ключом, чтобы назначенная сторона могла её расшифровать.

Модель аккаунта и балансы

Когда аккаунт настроен для конфиденциальных переводов, расширение ConfidentialTransferAccount хранит (среди прочих полей):

• elgamal_pubkey: ElGamal-открытый ключ аккаунта.
• pending_balance_lo / pending_balance_hi: ElGamal-шифротексты ожидающего баланса, разбитые на младшие и старшие биты (расшифровка старших битов обходится дороже, поэтому они хранятся отдельно).
• available_balance: ElGamal-шифротекст расходуемого баланса.
• decryptable_available_balance: AES-шифротекст того же доступного баланса, который владелец может расшифровать мгновенно. Это поле следует использовать для отображения.
• allow_confidential_credits / allow_non_confidential_credits: принимает ли аккаунт в настоящее время входящие конфиденциальные или публичные зачисления.
• pending_balance_credit_counter и maximum_pending_balance_credit_counter: количество зачислений, накопившихся в ожидающем балансе, и лимит, после которого требуется применение.

Все эти поля возвращаются в разобранном состоянии аккаунта через стандартный RPC. Любой может прочитать зашифрованные тексты, но только владельцы ключей могут восстановить исходные суммы.

Управление ключами

Каждый конфиденциальный аккаунт использует два ключа: keypair ElGamal для шифрования и доказательств, и ключ AES для быстрой расшифровки баланса. Способ создания и хранения этих ключей — это выбор при интеграции. Несколько распространённых вариантов:

• Получение из подписи кошелька (рекомендуется по умолчанию). Владелец подписывает канонически разделённое по доменам сообщение, и ключи выводятся из этой подписи, поэтому они воспроизводимы только из кошелька и их не нужно хранить. seed детерминирован для каждого аккаунта: JS-хелперы ниже привязывают его к паре (owner, mint), тогда как пример на Rust использует в качестве seed адрес token account (для associated token account они эквивалентны, поскольку этот адрес сам выводится из владельца и mint).
• Получение из независимого ключевого материала. Для passkeys, защищённых анклавов или MPC-решений выводите ключи из вывода WebAuthn PRF или другого входного ключевого материала, чтобы конфиденциальные ключи не были привязаны к ключу подписи аккаунта. @solana/zk-sdk предоставляет ConfidentialKeys.fromIkm и ConfidentialKeys.fromPrf для этой цели.
• Генерация и управление напрямую. Кастодиальные провайдеры и провайдеры MPC могут предпочесть генерировать ключи и управлять ими как любым другим конфиденциальным ключевым материалом.

Клиент @solana-program/token-2022 поставляется с хелперами для рекомендуемого пути:

import {
  deriveElGamalKeypairForOwnerMint,
  deriveAeKeyForOwnerMint
} from "@solana-program/token-2022";

// `owner` signs a domain-separated message; the keys are bound to (owner, mint).
const { elgamalPubkey, secretKey } = await deriveElGamalKeypairForOwnerMint({
  signer: owner,
  owner: owner.address,
  mint
});
const aesKey = await deriveAeKeyForOwnerMint({
  signer: owner,
  owner: owner.address,
  mint
});

Вспомогательные функции деривации возвращают сериализованный ключевой материал. Высокоуровневые вспомогательные функции операций (показанные далее) принимают объекты WASM ElGamalKeypair и AeKey, поэтому при необходимости восстанавливайте их из байтов:

Создание и настройка аккаунтов

Прежде чем аккаунт сможет хранить конфиденциальный баланс, ему необходимо расширение ConfidentialTransferAccount, которое добавляет примерно 295 байт к token account (порядка 0,0015 SOL дополнительного rent). Настройка выполняется в два этапа: создание token account и последующая настройка расширения.

Настройка обычно требует подписи владельца аккаунта и предоставления доказательства того, что он владеет открытым ключом ElGamal, устанавливаемым для аккаунта. Кошелёк или биржа могут создать и пополнить базовый token account для пользователя, однако без этой подписи настроить конфиденциальное расширение от имени пользователя невозможно.

Поэтому не следует автоматически создавать конфиденциальные аккаунты для каждого пользователя без его ведома: это требует дополнительного rent и всё равно предполагает участие владельца. Выполняйте настройку при первом использовании или когда пользователь явно включает конфиденциальные переводы.

Реестр ElGamal устраняет необходимость выполнять шаг с участием владельца для каждого аккаунта. Пользователь один раз регистрирует свой открытый ключ ElGamal (подписывая доказательство при регистрации), и запись в реестре может повторно использоваться для любого минта. После этого третья сторона может настраивать конфиденциальные аккаунты для пользователя с помощью ConfigureAccountWithRegistry — без подписи владельца или доказательства в момент настройки, требуется лишь плательщик за rent. Это механизм, который следует использовать, если вы хотите беспрепятственно создавать конфиденциальные аккаунты для пользователей.

Отображение балансов

Надёжная интеграция отображает публичный баланс с использованием стандартного баланса токена, определяет конфиденциальное расширение и, когда пользователь разблокировал свои ключи, расшифровывает и показывает доступный баланс.

Доступный баланс лучше всего считывать из decryptable_available_balance с помощью ключа AES, что выполняется за постоянное время. Прямая расшифровка available_balance ElGamal требует решения задачи дискретного логарифма и должна избегаться при обычном отображении.

import { AeCiphertext } from "@solana/zk-sdk/bundler";
import { fetchToken } from "@solana-program/token-2022";
import { unwrapOption } from "@solana/kit";

const account = await fetchToken(rpc, tokenAccountAddress);

// `extensions` is an Option<Array<Extension>>; each extension is a tagged union.
const extensions = unwrapOption(account.data.extensions) ?? [];
const ct = extensions.find((e) => e.__kind === "ConfidentialTransferAccount");

if (ct) {
  // Fast path: decrypt the AES "decryptable available balance" for display.
  const ciphertext = AeCiphertext.fromBytes(
    new Uint8Array(ct.decryptableAvailableBalance)
  );
  // `aesKey` is the rebuilt AeKey object (see the rebuild snippet above), not raw bytes.
  const availableBalance = ciphertext?.decrypt(aesKey); // bigint | undefined
  console.log("Available (confidential):", availableBalance);
}

Если пользователь не разблокировал свои ключи, отображайте публичный баланс и указывайте, что конфиденциальный баланс существует, но заблокирован, — вместо того чтобы показывать ноль.

Получение переводов

Входящие депозиты и переводы поступают в ожидающий баланс и не могут быть потрачены до применения. Каждое зачисление увеличивает pending_balance_credit_counter; как только это значение достигает maximum_pending_balance_credit_counter, аккаунт не может получать новые конфиденциальные зачисления до тех пор, пока владелец не применит ожидающий баланс.

Интеграции, хранящие средства от имени пользователей, должны:

• Отображать ожидающий и доступный балансы раздельно, чтобы пользователи понимали, почему только что полученная сумма ещё не доступна для трат.
• Применять ожидающий баланс от имени пользователя в подходящие моменты (например, перед отправкой), чтобы балансы не зависали.

import { getApplyConfidentialPendingBalanceInstructionFromToken } from "@solana-program/token-2022";

// Builds a single instruction; no proofs are needed to apply.
const instruction = getApplyConfidentialPendingBalanceInstructionFromToken({
  token: tokenAccountAddress,
  tokenAccount, // decoded Token account
  authority: owner,
  elgamalSecretKey: elgamalKeypair.secret(),
  aesKey
});

См. страницу Применение ожидающего баланса для ознакомления с полным процессом.

Отправка переводов

Конфиденциальный перевод требует трёх доказательств с нулевым разглашением, генерируемых на стороне клиента:

• Доказательство равенства того, что новый зашифрованный текст баланса отправителя шифрует то же значение, что и свежее обязательство, которое отправитель может раскрыть.
• Доказательство корректности зашифрованного текста того, что зашифрованные тексты суммы перевода корректно сформированы под ключами источника, получателя и (если задан) аудитора.
• Доказательство диапазона того, что сумма и остаток баланса отправителя являются допустимыми неотрицательными целыми числами — именно это предотвращает создание стоимости из воздуха.

Эти доказательства превышают допустимый размер транзакции для встроенной передачи, поэтому стандартный подход — создавать аккаунты состояния контекста доказательств, верифицировать в них каждое доказательство, ссылаться на них из инструкции перевода, а затем закрывать их для возврата rent. Это охватывает несколько зависимых транзакций. Формат транзакций v1 (появляющийся в Agave v4.2) увеличивает ограничение размера и, как ожидается, позволит выполнять конфиденциальный перевод в рамках одной транзакции в блокчейне, что упростит этот процесс.

Вам не нужно собирать доказательства вручную. Оба клиента предоставляют высокоуровневый вспомогательный инструмент, который формирует доказательства и генерирует инструкции для отправки:

import { getConfidentialTransferInstructionPlan } from "@solana-program/token-2022";

// Returns an instruction plan covering proof setup, the transfer, and cleanup.
const plan = await getConfidentialTransferInstructionPlan({
  rpc,
  payer, // funds rent for the temporary proof context state accounts
  sourceToken,
  mint,
  destinationToken,
  sourceTokenAccount, // decoded Token account for the source
  destinationTokenAccount, // decoded Token account for the destination,
  // or pass `destinationElgamalPubkey` directly instead
  authority: owner,
  amount,
  sourceElgamalKeypair, // ElGamal keypair for the source account
  aesKey, // AES key for the source account
  auditorElgamalPubkey // optional, read from the mint config
});

// Execute the plan with your instruction-plan executor of choice.

Если вам нужен более тонкий контроль, доступны и низкоуровневые строительные блоки: @solana/zk-sdk генерирует данные каждого доказательства (CiphertextCommitmentEqualityProofData, BatchedGroupedCiphertext3HandlesValidityProofData, BatchedRangeProofU128Data), @solana-program/zk-elgamal-proof предоставляет инструкции верификации доказательств, а @solana-program/token-2022 — инструкции для confidentialTransfer и аккаунтов состояния контекста.

Подробную последовательность инструкций см. на странице Перевод токенов.

Вывод средств

Вывод средств перемещает активы с конфиденциального доступного баланса обратно на публичный баланс, после чего они ведут себя как обычный баланс токенов. Вывод также требует доказательств (доказательство равенства и доказательство диапазона), доступных как getConfidentialWithdrawInstructionPlan в JS-клиенте и confidential_transfer_withdraw в Rust-клиенте. Сначала примените все ожидающие балансы, чтобы полная сумма стала доступна. См. Вывод токенов.

Связанные конфиденциальные расширения

На основе конфиденциальных переводов строятся два опциональных расширения. Оба в основном входят в зону ответственности эмитента, однако каждое из них меняет то, что должен учитывать интегратор:

• Конфиденциальные комиссии за перевод. Когда минт сочетает конфиденциальные переводы с комиссией за перевод, отправки используют путь перевода с комиссией (confidential_transfer_transfer_with_fee в Rust-клиенте), а удержанная комиссия шифруется так же, как и сумма. Сбор удержанных комиссий (сбор и вывод) — задача уполномоченного по комиссиям, а не интегратора.
• Конфиденциальный минт и сжигание. Минт с этим расширением выпускает и сжигает предложение конфиденциально, что отключает публичный путь пополнения и вывода. Токены не могут перемещаться между публичным и конфиденциальным балансами для такого минта, поэтому не предоставляйте для него функции пополнения или вывода.

Для получения сведений о деталях на уровне протокола для обоих случаев см. документацию по конфиденциальным балансам.

Разбор транзакций конфиденциальных переводов

Обозреватели и индексаторы должны распознавать и маркировать операции конфиденциального перевода, не имея возможности прочитать суммы. Клиент @solana-program/token-2022 предоставляет identifyToken2022Instruction для классификации каждой инструкции Token-2022, а также парсеры для отдельных инструкций (например, parseConfidentialTransferInstruction) для декодирования аккаунтов и незащищённых полей. Зашифрованные суммы остаются в виде шифртекстов: отображайте их как конфиденциальные, а не пытайтесь интерпретировать байты как число.

import {
  identifyToken2022Instruction,
  Token2022Instruction,
  TOKEN_2022_PROGRAM_ADDRESS
} from "@solana-program/token-2022";

for (const ix of instructions) {
  if (ix.programAddress !== TOKEN_2022_PROGRAM_ADDRESS) continue;

  const kind = identifyToken2022Instruction(ix);
  switch (kind) {
    case Token2022Instruction.ConfidentialTransfer:
    case Token2022Instruction.ConfidentialTransferWithFee:
      console.log("Confidential transfer (amount encrypted)");
      break;
    case Token2022Instruction.ConfidentialDeposit:
      console.log("Deposit to confidential balance");
      break;
    case Token2022Instruction.ConfidentialWithdraw:
      console.log("Withdraw from confidential balance");
      break;
    case Token2022Instruction.ApplyConfidentialPendingBalance:
      console.log("Apply pending balance");
      break;
    default:
      break;
  }
}

Ограничения индексирования, которые необходимо учитывать:

• Суммы конфиденциальных переводов недоступны. ConfidentialTransfer содержит зашифрованные суммы, поэтому аналитика по объёму, потокам и размерам переводов не может быть вычислена на его основе. Отмечайте такие переводы как конфиденциальные, а не записывайте нулевое значение или необработанный шифртекст.
• Дельты баланса недоступны. Конфиденциальные переводы не изменяют публичный баланс токенов, поэтому стандартное отслеживание изменений баланса до/после, на котором основана большинство механизмов индексирования переводов, их не фиксирует. Ожидающие и доступные балансы представлены в виде шифртекстов.
• Депозиты и выводы средств прозрачны. ConfidentialDeposit и ConfidentialWithdraw содержат суммы в открытом виде, поэтому вы по-прежнему можете индексировать потоки средств в конфиденциальный пул и из него — но не переводы внутри него.
• Один перевод сегодня охватывает несколько транзакций. Аккаунты состояния контекста доказательства создаются, используются и закрываются в рамках перевода, поэтому соотносите связанные транзакции, а не обрабатывайте каждую по отдельности. Это ограничение исчезнет после внедрения конфиденциальных переводов в рамках одной транзакции (см. выше).
• Аудиторские минты поддаются расшифровке. Если минт имеет глобального аудитора и вы располагаете ключом аудитора, вы можете расшифровать суммы переводов для данного минта (см. ниже).

Аудиторы и соответствие требованиям

Минт может настроить глобальный аудиторский публичный ключ ElGamal. Если он задан, каждый конфиденциальный перевод должен включать сумму, зашифрованную под ключом аудитора, чтобы владелец секретного ключа аудитора мог расшифровать все суммы переводов для этого минта. Доказательство корректности охватывает зашифрованный текст аудитора, поэтому в качестве интегратора вам не нужно делать ничего особенного на стороне отправки, кроме как передать ключ аудитора из конфигурации минта (высокоуровневые вспомогательные функции считывают его за вас).

Если ваш продукт является аудитором (например, регулируемый эмитент или провайдер соответствия), вы расшифровываете суммы переводов с помощью секретного ключа аудитора так же, как владелец расшифровывает собственный баланс. Владельцы также могут избирательно делиться своими ключами для каждого аккаунта с конкретной стороной, не раскрывая их публично.

Мониторинг транзакций (KYT)

Для провайдеров KYT и AML конфиденциальные переводы меняют то, что доступно для наблюдения, но не общую модель:

• Анализ адресов и графов не затрагивается. Отправители, получатели, минты и владельцы аккаунтов остаются публичными, поэтому проверка адресов, сопоставление санкционных списков и анализ графа контрагентов работают так же, как и для любого токена.
• Эвристика на основе сумм требует ключа аудитора. Структурирование, пороговая отчётность и оценка рисков на основе объёма не могут самостоятельно считывать суммы конфиденциальных переводов. Суммы депозитов и вывода средств остаются в открытом виде, поэтому размер потоков, входящих и выходящих из конфиденциального пула, по-прежнему виден.
• Охват обеспечивается моделью аудитора. На минтах, настраивающих глобального аудитора, провайдер, работающий с ключом аудитора (или получающий избирательное раскрытие от пользователя или эмитента), может восстановить суммы переводов. Эмитентам в регулируемых контекстах следует планировать настройку аудитора или поддержку избирательного раскрытия, чтобы мониторинг был возможен.

Обратная совместимость

• У конфиденциального token account всегда есть публичный баланс. Кошельки и приложения, не поддерживающие расширение, продолжают работать и отображают публичный баланс.
• Стандартные переводы по-прежнему функционируют для публичного баланса, при условии что адрес получателя допускает неконфиденциальные зачисления.
• Конфиденциальные балансы не видны инструментам без соответствующей поддержки, однако средства не теряются: любой клиент с поддержкой конфиденциальности может получить к ним доступ с помощью ключей владельца.
• Поскольку суммы зашифрованы, аналитика объёмов и оборота, основанная на чтении сумм переводов, не будет учитывать конфиденциальную активность. Учитывайте это при разработке дашбордов и ведении отчётности.

Рекомендуемые приоритеты интеграции по платформам

Общие требования

Кошельки

Обозреватели и индексаторы

Биржи и кастодианы

Провайдеры соответствия требованиям и KYT