Add `unwrap_lamports` instruction #857

abelmarnk · 2025-11-21T19:35:52Z

Background

This PR adds the unwrap_lamports instruction originally proposed here to the Token-2022 program. It also addresses and closes issue #773.

Problem

In order to transfer out lamports from native SOL accounts, currently it is necessary to create and close ATAs or token accounts all the time.

Solution

This PR adds a new unwrap_lamports instruction that allows transferring out lamports directly to any destination account. This eliminates the need for creating temporary native token accounts for the recipient.

The new instruction uses the discriminator 45, which is currently unused in Token-2022.

The amount to unwrap is specified as an Option<u64>:

None: the entire token balance is unwrap
Some(amount): the specified amount is unwrap

Scope

Add instruction builder and associated tests
Add the POD type and helpers with tests
Add instruction processor associated tests
Update the Rust legacy test helpers
Update the Rust legacy tests
Update JS & JS legacy implementations
Update auto-generated code
Update CLI functionality and CLI tests

abelmarnk · 2025-11-26T10:37:01Z

clients/cli/tests/command.rs

 }

 async fn wrapped_sol(test_validator: &TestValidator, payer: &Keypair) {
+    // both tests use the same ata so they can't run together


Both the original wrapped sol tests and the unwrap lamport tests create and use the payer native mint ata, so one may end up failing depending on the order the tests are run, so i put them here so they run in order.

Fine by me!

abelmarnk · 2025-11-26T10:37:47Z

clients/js/src/generated/accounts/mint.ts

  extensions: OptionOrNullable<Array<ExtensionArgs>>;
 };

+/** Gets the encoder for {@link MintArgs} account data. */


These comments were generated when i ran the generate clients script

abelmarnk · 2025-11-26T10:38:58Z

clients/rust-legacy/tests/cpi_guard.rs

    test_context
 }

+async fn make_context_with_native_mint(amount: u64) -> TestContext {


The old tests generate new mints each time so i added this helper for the native mint

abelmarnk · 2025-11-26T10:41:07Z

interface/idl.json

I actually wrote this by hand, is this how it's usually done?
The origin of the file says shank, but i couldn't find any shank macros

Yeah it's been written by hand, thanks for handling this!

abelmarnk · 2025-11-26T10:42:52Z

program/src/processor.rs

+        }
+
+        let self_transfer = source_account_info.key == destination_account_info.key;
+        if let Ok(cpi_guard) = source_account.get_extension::<CpiGuard>() {


I added the cpi guard since an unwrap is a transfer

Thanks for thinking about other extensions 🙏

abelmarnk · 2025-11-26T11:01:55Z

@joncinque 🙏 Could I get a high level review of this before I mark it ready for review?

joncinque

This was in such good shape that I gave it a full review. Thanks for your contribution, and for making it so complete!

Most of the comments are pretty minor, so we should be able to land this pretty quickly.

cc @febo to also give it a look since he wrote the p-token implementation

joncinque · 2025-11-26T19:58:06Z

interface/src/instruction.rs

+    signer_pubkeys: &[&Pubkey],
+    amount: Option<u64>,
+) -> Result<Instruction, ProgramError> {
+    check_program_account(token_program_id)?;


Since p-token will support this too, may as well relax the check to either token program:

Suggested change

check_program_account(token_program_id)?;

check_spl_token_program_account(token_program_id)?;

joncinque · 2025-11-26T20:03:21Z

interface/src/instruction.rs

+        /// The amount of lamports to transfer. When an amount is
+        /// not specified, the entire balance of the source account will be
+        /// transferred.
+        #[cfg_attr(feature = "serde", serde(with = "coption_fromstr"))]


Maybe this is ok, since generally we should do this more for u64 values, but we don't normally serialize amounts as strings.

joncinque · 2025-11-26T20:03:45Z

interface/idl.json

Yeah it's been written by hand, thanks for handling this!

joncinque · 2025-11-26T20:57:44Z

clients/rust-legacy/tests/unwrap_lamports.rs

+    // unwrap Some(1) lamports is ok
+    token
+        .unwrap_lamports(
+            &alice_account,
+            &bob_account,
+            &alice.pubkey(),
+            Some(1),
+            &[&alice],
+        )
+        .await
+        .unwrap();


Can we check that the lamport was moved?

joncinque · 2025-11-26T20:58:01Z

clients/rust-legacy/tests/unwrap_lamports.rs

+    // unwrap None lamports is ok
+    token
+        .unwrap_lamports(
+            &alice_account,
+            &bob_account,
+            &alice.pubkey(),
+            None,
+            &[&alice],
+        )
+        .await
+        .unwrap();


Can we check that all of the lamports were moved and the account was deleted?

joncinque · 2025-11-26T21:30:10Z

clients/js-legacy/test/e2e-2022/unwrapLamports.test.ts

+import { PublicKey } from '@solana/web3.js';
+import { Keypair } from '@solana/web3.js';


nit: may as well combine these imports

joncinque · 2025-11-26T21:32:20Z

program/src/processor.rs

+        }
+
+        let self_transfer = source_account_info.key == destination_account_info.key;
+        if let Ok(cpi_guard) = source_account.get_extension::<CpiGuard>() {


Thanks for thinking about other extensions 🙏

program/src/processor.rs

joncinque · 2025-11-26T21:36:19Z

program/src/processor.rs

+        // Revisit this later to see if it's worth adding a check to reduce
+        // compute costs, ie:
+        // if self_transfer || amount == 0
+        check_program_account(source_account_info.owner)?;


No need to check this in every case -- only if self_transfer || amount == 0 works

joncinque · 2025-11-26T21:49:22Z

program/src/processor.rs

+            .checked_add(amount)
+            .ok_or(TokenError::Overflow)?;
+
+            source_account.base.amount = remaining_amount.into();


This is also present in the p-token implementation, and now I'm questioning it. We don't decrement the source_account.amount during a self-transfer, but it would definitely be clearer if we did. Meaning, if I unwrap from my wrapped SOL account into itself, I would imagine those lamports go from being part of amount to no longer being part of amount.

What do you think @febo ?

Co-authored-by: Jon C <[email protected]>

abelmarnk · 2025-11-27T19:00:58Z

I've made the changes, i'll resolve the conversation with the commit references after the last comment(the one about the p-token implementation) has been resolved since it would affect most of the code.

abelmarnk mentioned this pull request Nov 21, 2025

Feature proposal: unwrap_lamports instruction #773

Open

abelmarnk added 16 commits November 26, 2025 11:26

Add COption pack/unpack helpers

48cf9eb

Add instruction builder

f9e2ca7

Add serde tests for new instruction using coption_u64

58d0323

Corrected instruction docs

d374c8e

Add PodTokenInstruction helpers

993d722

Add unwrap lamports processor

98ec326

Add unwrap lamports cli clap_app parser

011157d

Add unwrap lamports cli handler

eb71194

Add auto-generated js code

6b4de83

Add js COption serialization helper

b8119a8

Add unwrap lamports js action & instruction

b401e17

Add unwrap lamports js e2e tests

20d2610

Add unwrap lamports rust-legacy processor

9eacd3f

Updated rust-legacy cpi guard helpers & tests

721a16a

Added unwrap lamport rust-legacy tests

6488ab5

Remove spl-token-2022-interface patch

0d937fe

abelmarnk force-pushed the unwrap-lamports branch from a49dba9 to 0d937fe Compare November 26, 2025 10:30

abelmarnk commented Nov 26, 2025

View reviewed changes

abelmarnk added 3 commits November 26, 2025 11:44

Remove memo code from unwrap lamports processor

9a773e6

Fix self transfer in unwrap lamports processor

ed37839

Refactor self transfer in unwrap lamports processor

f7bf0da

joncinque reviewed Nov 26, 2025

View reviewed changes

joncinque requested a review from febo November 26, 2025 21:51

Fix help description for UnwrapLamports amount argument

bfcf620

Co-authored-by: Jon C <[email protected]>

Fix None lamport amount for UnwrapLamports

93c42fe

Co-authored-by: Jon C <[email protected]>

	check_program_account(token_program_id)?;
	check_spl_token_program_account(token_program_id)?;

		import { PublicKey } from '@solana/web3.js';
		import { Keypair } from '@solana/web3.js';

Add unwrap_lamports instruction #857

Are you sure you want to change the base?

Add unwrap_lamports instruction #857

Uh oh!

Conversation

abelmarnk commented Nov 21, 2025

Background

Problem

Solution

Scope

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abelmarnk commented Nov 26, 2025

Uh oh!

joncinque left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abelmarnk commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add `unwrap_lamports` instruction #857

Add `unwrap_lamports` instruction #857

abelmarnk commented Nov 27, 2025 •

edited

Loading