Підтримка конфіденційних переказів у Solana

Передумови

Розширення Confidential Transfer дозволяє мінтам Token-2022 зберігати суми переказів та залишки на рахунках у зашифрованому вигляді в блокчейні. Оскільки залишки зашифровані, їх відображення потребує ключів дешифрування власника, а надсилання — генерації доказів нульового знання на стороні клієнта.

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

Адреси рахунків, мінт і власник кожного рахунку залишаються публічними. Шифруються лише суми та залишки, тому все інше, включно з інформацією про те, хто з ким проводить транзакції, залишається видимим. Це забезпечує конфіденційність від публічних спостерігачів, але не анонімність.

Ресурси

• Огляд Confidential Transfer та покрокові посібники
• Код розширення на 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, що з'явиться разом із Agave v4.2) підвищить це обмеження і, як очікується, дозволить виконувати конфіденційний переказ в одній транзакції в блокчейні.
• Гаманець без будь-якої підтримки все одно працює: він показує публічний залишок, і стандартні перекази продовжують функціонувати. Конфіденційні кошти залишаються доступними для будь-якого клієнта з підтримкою конфіденційності, що має ключі власника.

Терміни

• ElGamal keypair: keypair з відкритим ключем для кожного акаунту, що використовується для шифрування балансів та побудови ZK-доказів. Відкритий ключ зберігається в акаунті.
• AES key: симетричний ключ для кожного акаунту, що використовується для шифрування «розшифровуваного доступного балансу», щоб власник міг зчитувати свій доступний баланс за константний час, без розв'язання задачі дискретного логарифму.
• 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 є детермінованим для кожного акаунту: 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, що працює за константним часом. Пряме дешифрування 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
});

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

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

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

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

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