Add withdraw_excess_lamports instruction

Author: febo

Diff for: interface/src/instruction.rs

@@ -478,6 +478,18 @@ pub enum TokenInstruction {
     ///   - `&str` The `ui_amount` of tokens to reformat.
     UiAmountToAmount,
 
+    /// This instruction is to be used to rescue SOL sent to any `TokenProgram`
+    /// owned account by sending them to any other account, leaving behind only
+    /// lamports for rent exemption.
+    ///
+    /// Accounts expected by this instruction:
+    ///
+    ///   0. `[writable]` Source Account owned by the token program
+    ///   1. `[writable]` Destination account
+    ///   2. `[signer]` Authority
+    ///   3. `..+M` `[signer]` M signer accounts.
+    WithdrawExcessLamports = 38,
+
     /// Executes a batch of instructions. The instructions to be executed are specified
     /// in sequence on the instruction data. Each instruction provides:
     ///   - `u8`: number of accounts
@@ -503,7 +515,7 @@ impl TryFrom<u8> for TokenInstruction {
     fn try_from(value: u8) -> Result<Self, Self::Error> {
         match value {
             // SAFETY: `value` is guaranteed to be in the range of the enum variants.
-            0..=24 | 255 => Ok(unsafe { core::mem::transmute::<u8, TokenInstruction>(value) }),
+            0..=24 | 38 | 255 => Ok(unsafe { core::mem::transmute::<u8, TokenInstruction>(value) }),
             _ => Err(ProgramError::InvalidInstructionData),
         }
     }

Diff for: p-token/src/entrypoint.rs

@@ -257,6 +257,13 @@ fn inner_process_remaining_instruction(
 
             process_ui_amount_to_amount(accounts, instruction_data)
         }
+        // 38 - WithdrawExcessLamports
+        38 => {
+            #[cfg(feature = "logging")]
+            pinocchio::msg!("Instruction: WithdrawExcessLamports");
+
+            process_withdraw_excess_lamports(accounts)
+        }
         _ => Err(ProgramError::InvalidInstructionData),
     }
 }

Diff for: p-token/src/processor/mod.rs

@@ -39,6 +39,7 @@ pub mod thaw_account;
 pub mod transfer;
 pub mod transfer_checked;
 pub mod ui_amount_to_amount;
+pub mod withdraw_excess_lamports;
 // Shared processors.
 pub mod shared;
 
@@ -68,6 +69,7 @@ pub use thaw_account::process_thaw_account;
 pub use transfer::process_transfer;
 pub use transfer_checked::process_transfer_checked;
 pub use ui_amount_to_amount::process_ui_amount_to_amount;
+pub use withdraw_excess_lamports::process_withdraw_excess_lamports;
 
 /// Maximum number of digits in a formatted `u64`.
 ///

Diff for: p-token/src/processor/withdraw_excess_lamports.rs

@@ -0,0 +1,74 @@
+use pinocchio::{
+    account_info::AccountInfo,
+    program_error::ProgramError,
+    sysvars::{rent::Rent, Sysvar},
+    ProgramResult,
+};
+use spl_token_interface::{
+    error::TokenError,
+    state::{account::Account, load, mint::Mint, multisig::Multisig, Transmutable},
+};
+
+use super::validate_owner;
+
+#[inline(always)]
+pub fn process_withdraw_excess_lamports(accounts: &[AccountInfo]) -> ProgramResult {
+    let [source_account_info, destination_info, authority_info, remaining @ ..] = accounts else {
+        return Err(ProgramError::NotEnoughAccountKeys);
+    };
+
+    // SAFETY: single mutable borrow to `source_account_info` account data
+    let source_data = unsafe { source_account_info.borrow_data_unchecked() };
+
+    match source_data.len() {
+        Account::LEN => {
+            let account = unsafe { load::<Account>(source_data)? };
+
+            if account.is_native() {
+                return Err(TokenError::NativeNotSupported.into());
+            }
+
+            validate_owner(&account.owner, authority_info, remaining)?;
+        }
+        Mint::LEN => {
+            let mint = unsafe { load::<Mint>(source_data)? };
+
+            if let Some(mint_authority) = mint.mint_authority() {
+                validate_owner(mint_authority, authority_info, remaining)?;
+            } else {
+                return Err(TokenError::AuthorityTypeNotSupported.into());
+            }
+        }
+        Multisig::LEN => {
+            validate_owner(source_account_info.key(), authority_info, remaining)?;
+        }
+        _ => return Err(TokenError::InvalidState.into()),
+    }
+
+    let source_rent_exempt_reserve = Rent::get()?.minimum_balance(source_data.len());
+
+    let transfer_amount = source_account_info
+        .lamports()
+        .checked_sub(source_rent_exempt_reserve)
+        .ok_or(TokenError::NotRentExempt)?;
+
+    let source_starting_lamports = source_account_info.lamports();
+    // SAFETY: single mutable borrow to `source_account_info` lamports.
+    unsafe {
+        // Moves the lamports out of the source account.
+        *source_account_info.borrow_mut_lamports_unchecked() = source_starting_lamports
+            .checked_sub(transfer_amount)
+            .ok_or(TokenError::Overflow)?;
+    }
+
+    let destination_starting_lamports = destination_info.lamports();
+    // SAFETY: single mutable borrow to `destination_info` lamports.
+    unsafe {
+        // Moves the lamports to the destination account.
+        *destination_info.borrow_mut_lamports_unchecked() = destination_starting_lamports
+            .checked_add(transfer_amount)
+            .ok_or(TokenError::Overflow)?;
+    }
+
+    Ok(())
+}