WithdrawExcessLamports у Solana: посібник для SPL Token і Token-2022

WithdrawExcessLamports — це інструкція Token Program 38. Вона розв’язує вузьку задачу: мінт, акаунт токена або мультипідпис може містити більше лампортів, ніж потрібно для звільнення від ренти, але ці лампорти неможливо перемістити звичайним переказом токенів.

Що робить WithdrawExcessLamports?

Інструкція доступна як у класичній SPL Token Program, так і в Token-2022. Вона була корисною для повернення лампортів, випадково надісланих на акаунти, що належать токен-програмі, до пропозиції щодо ренти 2026. Нижчий мінімум ренти розширює її застосування: старі акаунти можуть зберігати свій початковий баланс, потребуючи меншого резерву.

Офіційний опис поведінки й актуальний приклад клієнта наведено в документація Solana щодо Withdraw Excess Lamports. Реалізація обробника також у відкритому доступі в репозиторії Token Program.

Які акаунти потрібні для інструкції?

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

Хто має підписувати для кожного типу джерела?

Сценарій із відкликаними повноваженнями мінта потребує особливої уваги. Якщо мінт-джерело було створено з ключової пари на кривій, підписати має ця початкова ключова пара. Якщо він перебуває поза кривою, його керівна програма має викликати Token Program із правильними початковими значеннями підписувача PDA. Власник токена або колишня уповноважена сторона мінта не може замінити підпис джерела.

Як створити інструкцію за допомогою клієнта Solana?

Поточний офіційний приклад використовує @solana-program/token із налаштованим @solana/kit клієнтом:

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

const instruction = getWithdrawExcessLamportsInstruction({
    source,
    destination,
    authority,
});

await client.sendTransaction([instruction]);

Тут authority є TransactionSigner відповідну джерелу. Для уповноваженої сторони з мультипідписом додайте співпідписувачів через multiSigners. У робочому середовищі фіксуйте версії пакетів і компілюйте з точною версією клієнта, яку використовуєте; типи клієнта можуть змінюватися, навіть якщо ончейн-контракт акаунта не змінюється.

Чим тут відрізняються SPL Token і Token-2022?

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

CPI Guard від Token-2022 — ще одна практична відмінність для обгорток. Коли захист заблоковано, міжпрограмний виклик може бути відхилено, навіть якщо гаманець інакше був би дійсною уповноваженою стороною. Sol Incinerator пропускає такі джерела, замість того щоб додавати одну гарантовано невдалу операцію до більшої транзакції очищення.

Акаунти токенів нативного обгорнутого SOL відхиляються з помилкою NativeNotSupported. Розгортання нативного SOL виконується іншим шляхом закриття акаунта; це не виведення надлишкових лампортів.

Як Sol Incinerator API обгортає інструкцію?

v2 API від Sol Incinerator створює виклик Token Program через Assetcinerator, щоб комісії протоколу й необов’язкові партнерські комісії стягувалися ончейн. Ця обгортка є продуктовим рівнем; сама необгорнута інструкція Token Program не стягує комісію Sol Incinerator.

Скористайтеся автентифікованим попереднім переглядом, перш ніж просити користувача підписати:

curl -X POST https://v2.api.sol-incinerator.com/withdraw-excess-lamports/preview \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "userPublicKey": "DESTINATION_WALLET",
    "sourceAccount": "TOKEN_ACCOUNT_MINT_OR_MULTISIG"
  }'

Пов’язані маршрути транзакцій та інструкцій:

• POST /withdraw-excess-lamports
• POST /withdraw-excess-lamports-instructions

userPublicKey є гаманцем призначення та уповноваженою стороною за замовчуванням. Передайте authorityPublicKey коли підписати має інший мінт, джерело або уповноважена сторона мультипідпису. Передайте до 11 multisigSignerPublicKeys під час створення процесу з токен-мультипідписом. Усі приватні ключі залишаються локальними; API повертає дані, які мають схвалити необхідні підписувачі.

Базова комісія протоколу становить 200 bps. Прямий інтегратор може додати partnerFeeAccount і partnerFeeBps, тоді як звичайна комісія за транзакцію Solana сплачується окремо. Використовуйте повернуті feeLamports і поля повернення замість повторного використання кешованого розрахунку відсотка.

Які помилки має обробляти інтеграція?

• Немає надлишку: баланс джерела вже дорівнює поточному резерву.
• Неправильний власник або формат акаунта: джерело не є підтримуваним акаунтом Token Program.
• Недійсні повноваження: наданий підписувач не відповідає декодованому стану джерела.
• Неповний мультипідпис: надано недостатньо дійсних налаштованих підписувачів.
• Нативний акаунт: для обгорнутого SOL використовується інша операція.
• Заблокований CPI Guard: Token-2022 відхиляє обгортку CPI.
• Стан змінився: баланс, повноваження або налаштування ренти змінилися після попереднього перегляду.
• Вартість транзакції перевищує суму: дуже мале виведення може бути економічно недоцільним після сплати мережевих комісій.

Виконайте попередній перегляд знову, якщо стан міг змінитися; забезпечте ідемпотентність вибору джерел і ніколи не об’єднуйте завідомо неприйнятне джерело з іншими коректними операціями.

Матеріали за темою

• Solana Зменшення ренти 2026
• Як повернути надлишок SOL, не закриваючи акаунти токенів
• Як повернути надлишок SOL із мінта токена Solana
• Схвалення токенів порівняно з повноваженнями мінтингу та заморожування