Підтримка конфіденційних балансів у 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)

Коротко

• Кожен конфіденційний token account усе одно має публічний залишок, а також зашифрований очікуваний і доступний залишок. Токен може вільно переміщатися між публічним і конфіденційним станами.
• Щоб відобразити конфіденційний залишок, потрібні ключі власника. Рекомендований підхід — деривувати їх із гаманця власника, розшифрувати доступний залишок за допомогою AES-ключа (швидко) і розшифровувати очікувані суми за допомогою ключа ElGamal за потреби.
• Щоб надіслати конфіденційно, ви генеруєте ZK-докази на стороні клієнта (рівності, дійсності шифротексту, діапазону), які зазвичай розміщуються у тимчасових рахунках стану контексту доказів, після чого надсилаєте переказ. Як @solana-program/token-2022 (JS), так і spl-token-client (Rust) надають високорівневі помічники, що формують докази та визначають послідовність транзакцій.
• Конфіденційні перекази історично охоплювали кілька залежних транзакцій, оскільки докази перевищували ліміт розміру транзакції. Формат транзакції v1 підвищує цей ліміт, що дозволяє виконати конфіденційний переказ в одній ончейн-транзакції.
• Гаманець без будь-якої підтримки все одно працює: він показує публічний залишок, і стандартні перекази продовжують функціонувати. Конфіденційні кошти залишаються доступними для будь-якого клієнта з підтримкою конфіденційності, що має ключі власника.

Терміни

• ElGamal keypair: keypair власника на основі відкритого ключа, що використовується для шифрування балансів і побудови ZK-доказів. Відкритий ключ зберігається в кожному налаштованому акаунті.
• Ключ AES: симетричний ключ власника, що використовується для шифрування «розшифровуваного доступного балансу», щоб власник міг прочитати свій доступний баланс за константний час, не розв'язуючи задачу дискретного логарифма.
• Pending balance: зашифрований баланс коштів, отриманих через депозити або вхідні перекази, який ще не було застосовано. Не може бути витрачений безпосередньо.
• Available balance: зашифрований баланс, який можна переказати або вивести.
• Apply: крок, що переміщує очікуваний баланс до доступного.
• Proof context state account: тимчасовий онлайн-акаунт, що містить попередньо перевірений ZK-доказ, на який посилається конфіденційна інструкція, після чого він закривається для повернення rent.
• Auditor: необов'язковий глобальний ключ 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: кількість кредитів, що накопичилися в очікуваному балансі, та ліміт, після досягнення якого необхідно виконати apply.

Усі ці поля повертаються в розпарсованому стані акаунту через стандартний RPC. Будь-хто може читати шифротексти, але лише власники ключів можуть відновити вихідні суми.

Керування ключами

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

• Виведення з підпису гаманця (рекомендований варіант за замовчуванням). Власник підписує канонічне повідомлення з розділенням доменів, а ключі виводяться з цього підпису, тож їх можна відтворити лише за допомогою гаманця, і вам не потрібно їх зберігати. Стандартне виведення прив'язує ключі лише до основного гаманця і взагалі не використовує seed, тому клієнти не можуть випадково вивести різні ключі: один гаманець відповідає одному ElGamal keypair і одному ключу AES для всіх mint і token accounts.
• Похідні від незалежного ключового матеріалу. Для passkeys, захищених анклавів або MPC-налаштувань виводьте ключі з виводу WebAuthn PRF або іншого вхідного ключового матеріалу, щоб конфіденційні ключі не були прив'язані до ключа підпису акаунту. @solana/zk-sdk надає ConfidentialKeys.fromIkm і ConfidentialKeys.fromPrf для цього.
• Генерувати та керувати безпосередньо. Кастодіальні та MPC-провайдери можуть надавати перевагу генерації ключів та управлінню ними як будь-яким іншим чутливим ключовим матеріалом.

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

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

// `owner` signs the constant message "solana-conf-bal/v1" once; both keys are
// derived from that single signature and bound to the wallet alone.
const { aeKey, elgamalKeypair } = await deriveConfidentialKeys({
  signer: owner
});

Допоміжні функції виведення ключів повертають серіалізований ключовий матеріал. Допоміжні функції високорівневих операцій (показані далі) приймають об'єкти 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, що працює за константним часом. Пряме дешифрування ElGamal available_balance вимагає розв'язання дискретного логарифму і його слід уникати для рутинного відображення.

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
});

Дивіться сторінку Застосування очікуваного балансу для ознайомлення з повним процесом.

Надсилання переказів

Конфіденційний переказ потребує трьох доказів з нульовим розголошенням, що генеруються на клієнті:

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

Ці докази більші, ніж дозволяє ліміт розміру legacy- та v0-транзакцій для вбудованого розміщення, тому звичайний підхід — створити акаунти стану контексту доказу (proof context state accounts), верифікувати в них кожен доказ, послатися на них в інструкції переказу, а потім закрити їх, щоб повернути rent. Це охоплює кілька залежних транзакцій. Формат транзакції v1 підвищує цей ліміт, що дозволяє виконати конфіденційний переказ в одній ончейн-транзакції та спрощує цей процес.

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

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-клієнті), а утримана комісія шифрується так само, як і сума. Збір утриманих комісій (harvesting та виведення) — це завдання органу з комісій, а не інтегратора.
• Конфіденційний випуск та спалення. Монетний двір з цим розширенням випускає та спалює пропозицію конфіденційно, що вимикає публічний шлях депозиту та виведення. Токени не можуть переміщатися між публічним і конфіденційним балансами на такому монетному дворі, тому не відображайте депозит або виведення для нього.

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

Розбір транзакцій конфіденційного переказу

Оглядачі та індексатори повинні розпізнавати й позначати активність конфіденційних переказів, не маючи змоги зчитувати суми. Клієнт @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 pubkey. Якщо встановлено, кожен конфіденційний переказ повинен містити суму, зашифровану за допомогою ключа аудитора, щоб власник секретного ключа аудитора міг розшифрувати всі суми переказів для цього монетного двору. Доказ дійсності охоплює зашифрований текст аудитора, тому як інтегратор ви не робите нічого особливого на шляху відправлення, окрім передачі ключа аудитора з конфігурації монетного двору (високорівневі допоміжні інструменти зчитують його автоматично).

Якщо ваш продукт є аудитором (наприклад, регульований емітент або провайдер комплаєнсу), ви розшифровуєте суми переказів секретним ключем аудитора так само, як власник розшифровує свій баланс. Власники також можуть вибірково ділитися своїми ключами з конкретною стороною, не розкриваючи їх публічно, — однак за стандартного виведення, прив'язаного до гаманця, ті самі ключі охоплюють усі конфіденційні баланси власника, тому надання доступу до них розкриває кожен конфіденційний акаунт, а не лише один.

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

Для провайдерів KYT та AML конфіденційні перекази змінюють те, що можна спостерігати, але не загальну модель:

• Аналіз адрес і графів не зачіпається. Відправники, одержувачі, монетні двори та власники рахунків залишаються публічними, тому перевірка адрес, відповідність санкційним спискам і аналіз графів контрагентів працюють так само, як і для будь-якого токена.
• Евристика на основі сум потребує ключа аудитора. Структурування, порогова звітність і ризик-скоринг на основі обсягів не можуть самостійно зчитувати суми конфіденційних переказів. Суми депозитів і виведень залишаються у відкритому вигляді, тому розмір потоків, що входять і виходять із конфіденційного пулу, залишається видимим.
• Покриття забезпечується моделлю аудитора. На монетних дворах, де налаштовано глобального аудитора, провайдер, що діє з ключем аудитора (або отримує вибіркове розкриття від користувача чи емітента), може відновити суми переказів. Емітентам у регульованих контекстах слід планувати налаштування аудитора або підтримку вибіркового розкриття, щоб моніторинг був можливим.

Зворотна сумісність

• Конфіденційний token account завжди має публічний баланс. Гаманці та застосунки, які не підтримують розширення, продовжують працювати та відображають публічний баланс.
• Стандартні перекази досі працюють для публічного балансу, якщо одержувач дозволяє некофіденційні зарахування.
• Конфіденційні баланси не видимі в інструментах без відповідної підтримки, але кошти не втрачаються: будь-який клієнт із підтримкою конфіденційності може отримати до них доступ за допомогою ключів власника.
• Оскільки суми зашифровані, аналітика на рівні постачання та обсягу, що спирається на зчитування сум переказів, не відображатиме конфіденційну активність. Плануйте дашборди та облік з урахуванням цього.

Рекомендовані пріоритети інтеграції за платформами

Загальні вимоги

Гаманці

Оглядачі та індексатори

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

Постачальники відповідності та KYT