p-token: Add unwrap_lamports instruction

p-interface/src/instruction.rs

@@ -498,6 +498,23 @@ pub enum TokenInstruction {
     ///   3. `..+M` `[signer]` M signer accounts.
     WithdrawExcessLamports = 38,
 
+    /// Transfer lamports from a native SOL account to a destination account.
+    ///
+    /// This is useful to unwrap lamports from a wrapped SOL account.
+    ///
+    /// Accounts expected by this instruction:
+    ///
+    ///   0. `[writable]` The source account.
+    ///   1. `[writable]` The destination account.
+    ///   2. `[signer]` The source account's owner/delegate.
+    ///
+    /// Data expected by this instruction:
+    ///
+    ///   - `Option<u64>` The amount of lamports to transfer. When an amount is
+    ///     not specified, the entire balance of the source account will be
+    ///     transferred.
+    UnwrapLamports = 45,
+
     /// Executes a batch of instructions. The instructions to be executed are
     /// specified in sequence on the instruction data. Each instruction
     /// provides:

p-token/src/entrypoint.rs

@@ -486,6 +486,13 @@ fn inner_process_remaining_instruction(
 
             process_withdraw_excess_lamports(accounts)
         }
+        // 45 - UnwrapLamports
+        45 => {
+            #[cfg(feature = "logging")]
+            pinocchio::msg!("Instruction: UnwrapLamports");
+
+            process_unwrap_lamports(accounts, instruction_data)
+        }
         _ => Err(TokenError::InvalidInstruction.into()),
     }
 }

p-token/src/processor/batch.rs

@@ -84,7 +84,8 @@ pub fn process_batch(mut accounts: &[AccountInfo], mut instruction_data: &[u8])
                 // 13 - ApproveChecked
                 // 22 - InitializeImmutableOwner
                 // 38 - WithdrawExcessLamports
-                4..=13 | 22 | 38 => {
+                // 45 - UnwrapLamports
+                4..=13 | 22 | 38 | 45 => {
                     let [a0, ..] = ix_accounts else {
                         return Err(ProgramError::NotEnoughAccountKeys);
                     };

p-token/src/processor/mod.rs

@@ -41,6 +41,7 @@ pub mod thaw_account;
 pub mod transfer;
 pub mod transfer_checked;
 pub mod ui_amount_to_amount;
+pub mod unwrap_lamports;
 pub mod withdraw_excess_lamports;
 // Shared processors.
 pub mod shared;
@@ -61,6 +62,7 @@ pub use {
     set_authority::process_set_authority, sync_native::process_sync_native,
     thaw_account::process_thaw_account, transfer::process_transfer,
     transfer_checked::process_transfer_checked, ui_amount_to_amount::process_ui_amount_to_amount,
+    unwrap_lamports::process_unwrap_lamports,
     withdraw_excess_lamports::process_withdraw_excess_lamports,
 };
 

p-token/src/processor/unwrap_lamports.rs

@@ -0,0 +1,87 @@
+use {
+    super::validate_owner,
+    crate::processor::{check_account_owner, unpack_amount},
+    pinocchio::{
+        account_info::AccountInfo, hint::likely, program_error::ProgramError, ProgramResult,
+    },
+    pinocchio_token_interface::{
+        error::TokenError,
+        state::{account::Account, load_mut},
+    },
+};
+
+#[allow(clippy::arithmetic_side_effects)]
+pub fn process_unwrap_lamports(accounts: &[AccountInfo], instruction_data: &[u8]) -> ProgramResult {
+    // instruction data: expected u8 (1) + optional u64 (8)
+    let [has_amount, maybe_amount @ ..] = instruction_data else {
+        return Err(TokenError::InvalidInstruction.into());
+    };
+
+    let maybe_amount = if likely(*has_amount == 0) {
+        None
+    } else if *has_amount == 1 {
+        Some(unpack_amount(maybe_amount)?)
+    } else {
+        return Err(TokenError::InvalidInstruction.into());
+    };
+
+    let [source_account_info, destination_account_info, authority_info, remaining @ ..] = accounts
+    else {
+        return Err(ProgramError::NotEnoughAccountKeys);
+    };
+
+    // SAFETY: single immutable borrow to `source_account_info` account data
+    let source_account =
+        unsafe { load_mut::<Account>(source_account_info.borrow_mut_data_unchecked())? };
+
+    if !source_account.is_native() {
+        return Err(TokenError::NonNativeNotSupported.into());
+    }
+
+    // SAFETY: `authority_info` is not currently borrowed; in the case
+    // `authority_info` is the same as `source_account_info`, then it cannot be
+    // a multisig.
+    unsafe { validate_owner(&source_account.owner, authority_info, remaining)? };
+
+    // If we have an amount, we need to validate whether there are enough lamports
+    // to unwrap or not; otherwise we just use the full amount.
+    let (amount, remaining_amount) = if let Some(amount) = maybe_amount {
+        (
+            amount,
+            source_account
+                .amount()
+                .checked_sub(amount)
+                .ok_or(TokenError::InsufficientFunds)?,
+        )
+    } else {
+        (source_account.amount(), 0)
+    };
+
+    // Comparing whether the AccountInfo's "point" to the same account or
+    // not - this is a faster comparison since it just checks the internal
+    // raw pointer.
+    let self_transfer = source_account_info == destination_account_info;
+
+    if self_transfer || amount == 0 {
+        // Validates the token account owner since we are not writing
+        // to the account.
+        check_account_owner(source_account_info)
+    } else {
+        source_account.set_amount(remaining_amount);
+
+        // SAFETY: single mutable borrow to `source_account_info` lamports.
+        let source_lamports = unsafe { source_account_info.borrow_mut_lamports_unchecked() };
+        // Note: The amount of a source token account is already validated and the
+        // `lamports` on the account is always greater than `amount`.
+        *source_lamports -= amount;
+
+        // SAFETY: single mutable borrow to `destination_account_info` lamports; the
+        // account is already validated to be different from `source_account_info`.
+        let destination_lamports =
+            unsafe { destination_account_info.borrow_mut_lamports_unchecked() };
+        // Note: The total lamports supply is bound to `u64::MAX`.
+        *destination_lamports += amount;
+
+        Ok(())
+    }
+}