WithdrawExcessLamports в Solana: руководство по SPL Token и Token-2022

WithdrawExcessLamports — это инструкция Token Program 38. Она решает узкую задачу: минт, токен-аккаунт или мультиподпись могут содержать больше лампортов, чем требуется для освобождения от ренты, но эти лампорты нельзя переместить обычным переводом токенов.

Что делает WithdrawExcessLamports?

Инструкция доступна как в классической Token Program SPL, так и в 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 оборачивает инструкцию?

API v2 от 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
• Одобрение токенов в сравнении с полномочиями на минтинг и заморозку