WithdrawExcessLamports w Solana: przewodnik po SPL Token i Token-2022

WithdrawExcessLamports jest instrukcją 38 Token Program. Rozwiązuje konkretny problem: mint, konto tokenów lub multisig może zawierać więcej lamportów, niż potrzebuje do zachowania zwolnienia z czynszu, ale tych lamportów nie można przenieść zwykłym transferem tokenów.

Co robi WithdrawExcessLamports?

Instrukcja jest dostępna zarówno w klasycznym SPL Token Program, jak i w Token-2022. Była przydatna do odzyskiwania lamportów przypadkowo wysłanych na konta należące do programu tokenów przed propozycją czynszu 2026. Niższe minimum czynszowe poszerza jej zastosowanie: starsze konta mogą zachować pierwotne saldo, wymagając jednocześnie mniejszej rezerwy.

Miarodajny opis działania i aktualny przykład klienta znajdują się w Dokumentacja Withdraw Excess Lamports w Solana. Implementacja procesora jest również publicznie dostępna w repozytorium Token Program.

Jakich kont wymaga ta instrukcja?

Procesor odczytuje długość danych źródła i bieżące ustawienia czynszu, oblicza minimalne saldo i przenosi różnicę. Nie przyjmuje rezerwy podanej przez wywołującego, która mogłaby być nieaktualna lub zmanipulowana.

Kto musi podpisać transakcję dla każdego typu źródła?

Przypadek mintu z cofniętym uprawnieniem wymaga szczególnej uwagi. Jeśli mint źródłowy utworzono z pary kluczy on-curve, podpis musi złożyć ta pierwotna para kluczy. Jeśli mint jest off-curve, kontrolujący go program musi wywołać Token Program z prawidłowymi seedami podpisującymi PDA. Posiadacz tokena ani były podmiot uprawniony do emisji nie mogą zastąpić podpisu źródła.

Jak utworzyć instrukcję za pomocą klienta Solana?

Bieżący oficjalny przykład korzysta z @solana-program/token ze skonfigurowanym @solana/kit klienta:

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

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

await client.sendTransaction([instruction]);

Tutaj authority jest TransactionSigner odpowiedni dla źródła. W przypadku podmiotu multisig uwzględnij współpodpisujących za pomocą multiSigners. W środowisku produkcyjnym przypinaj wersje pakietów i kompiluj z użyciem dokładnie tej wersji klienta, której używasz; typy klienta mogą ulec zmianie, nawet jeśli kontrakt konta on-chain pozostaje bez zmian.

Czym różnią się tutaj SPL Token i Token-2022?

Podstawowy efekt instrukcji jest taki sam, ale Token-2022 sprawia, że założenia dotyczące długości danych są szczególnie ryzykowne. Rozszerzenia mintów i kont zwiększają rozmiar danych po serializacji, a tym samym wymaganą rezerwę. Integracja używająca dla każdego źródła standardowych rozmiarów 82 lub 165 bajtów może zawyżać nadwyżkę.

CPI Guard w Token-2022 to kolejna praktyczna różnica dla wrapperów. Gdy mechanizm Guard jest zablokowany, wywołanie międzyprogramowe może zostać odrzucone, nawet jeśli portfel byłby w innej sytuacji prawidłowym podmiotem uprawnionym. Sol Incinerator pomija te źródła, zamiast umieszczać jedną gwarantowaną porażkę w większej transakcji porządkującej.

Konta tokenów natywnego opakowanego SOL są odrzucane z komunikatem NativeNotSupported. Rozpakowanie natywnego SOL odbywa się inną ścieżką zamknięcia konta; nie jest wypłatą nadwyżkowych lamportów.

Jak Sol Incinerator API opakowuje tę instrukcję?

v2 API od Sol Incinerator tworzy wywołanie Token Program przez Assetcinerator, dzięki czemu opłaty protokołu i opcjonalne opłaty partnerskie są egzekwowane on-chain. Ta warstwa opakowująca jest warstwą produktu; sama surowa instrukcja Token Program nie nakłada opłaty Sol Incinerator.

Przed poproszeniem użytkownika o podpis skorzystaj z uwierzytelnionego podglądu:

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"
  }'

Powiązane ścieżki transakcji i instrukcji to:

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

userPublicKey jest portfelem docelowym i domyślnym podmiotem uprawnionym. Podaj authorityPublicKey gdy podpis musi złożyć inny podmiot uprawniony do mintu, źródła lub multisig. Podaj maksymalnie 11 multisigSignerPublicKeys podczas tworzenia przepływu multisig tokena. Każdy klucz prywatny pozostaje lokalnie; API zwraca materiały przeznaczone do zatwierdzenia przez wymaganych podpisujących.

Podstawowa opłata protokołu wynosi 200 bps. Integrator bezpośredni może dodać partnerFeeAccount oraz partnerFeeBps, natomiast standardowa opłata za transakcję Solana jest naliczana oddzielnie. Użyj zwróconych feeLamports oraz pól odzyskiwania, zamiast ponownie wykorzystywać zbuforowane obliczenia procentowe.

Jakie błędy powinna obsługiwać integracja?

• Brak nadwyżki: saldo źródła jest już równe bieżącej rezerwie.
• Nieprawidłowy właściciel lub układ konta: źródło nie jest obsługiwanym kontem Token Program.
• Nieprawidłowy podmiot uprawniony: podany podpisujący nie odpowiada zdekodowanemu stanowi źródła.
• Niekompletny multisig: podano zbyt mało prawidłowych, skonfigurowanych podpisujących.
• Konto natywne: opakowany SOL korzysta z innej operacji.
• Zablokowany CPI Guard: Token-2022 odrzuca wrappera CPI.
• Stan uległ zmianie: saldo, uprawnienie lub ustawienie czynszu zmieniło się po wyświetleniu podglądu.
• Koszt transakcji przekracza wartość: niewielka wypłata może być nieopłacalna po uwzględnieniu opłat sieciowych.

Ponownie wyświetl podgląd, jeśli stan mógł się zmienić, zadbaj o idempotentność wyboru źródła i nigdy nie łącz źródła, o którym wiadomo, że się nie kwalifikuje, z innymi prawidłowymi operacjami.

Powiązane materiały

• Solana — obniżka czynszu 2026
• Jak odzyskać nadwyżkę SOL bez zamykania kont tokenów
• Jak odzyskać nadwyżkę SOL z mintu tokena Solana
• Zatwierdzenie tokena a uprawnienia do emisji i zamrażania