Intermediate

Token Upgrade Program

The Token Upgrade Program is a protocol for converting tokens from one mint to another. The program defines an escrow authority and a program-derived escrow account that holds both the original and new tokens. The token holder provides their original token account and new token account, and the protocol burns the original tokens and transfers the same amount of new tokens to the new account. The program is written in Rust and has a command-line utility (spl-token-upgrade-cli) for managing the token upgrades. The mint owner must add tokens to the escrow account either by minting new tokens or transferring existing ones. This guide describes the process for upgrading tokens from Token to Token-2022 using the spl-token command-line tool.

The Token Upgrade Program provides a stateless protocol for permanently converting tokens from one mint to another.

The program provides a simple mechanism for burning the original tokens and receiving an equal number of new tokens from an escrow account controlled by the program.

Background​

Token-2022 contains many new features for mint owners to customize the behavior of their tokens. You can find full information about Token-2022 and its extensions in the documentation.

Mint owners may want to take advantage of new functionality for their users, but there is no way to automatically convert tokens from Token to Token-2022.

The Token Upgrade Program defines an escrow authority, a program-derived address from two addresses, the original and new mints. Any new token account owned by or delegated to this escrow authority may be used as the escrow account.

A holder of original tokens provides their original token account, a new token account, and the escrow account. If the escrow account has enough tokens, the protocol will burn the original tokens and transfer the same amount of new tokens to the user’s new account.

The program ensures that the decimals of both mints are the same, so if the mints have different decimals, the upgrade fails.

The program is completely stateless and has a simple implementation, so mint owners may customize it with additional functionality. For example, if they want to upgrade between mints with different decimals, they can define how to scale the transferred number up or down as desired.

Note: The Token Upgrade Program can also exchange tokens that belong to the same program, but different mints. For example, a mint owner can provide an upgrade between two Token-2022 mints. This is useful if the mint owner wants to add new functionality to their mint.

Source​

The Token Upgrade Program’s source is available on GitHub

Interface​

The Token Upgrade Program is written in Rust and available on crates.io and docs.rs.

Command-line Utility​

The spl-token-upgrade command-line utility can be used to manage token upgrades. Once you have Rust installed, run:

$ cargo install spl-token-upgrade-cli

Run spl-token-upgrade --help for a full description of available commands.

Configuration​

The spl-token-upgrade configuration is shared with the solana command-line tool.

Token Upgrade Process​

This section describes how to upgrade tokens from Token to Token-2022, for the mint owner and token holders.

This guide also uses the spl-token command-line tool. Please see the full Token documentation for more info.

Setup​

A mint owner has a mint associated with the Token program at address o1d5Jt8z8vszx4FJ2gNJ3FZH34cer9sbparg7GVt7qm, and they want o1d token holders to upgrade to NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ tokens, associated with Token-2022.

Create token escrow​

The command-line tool allows anyone to create a new token account owned by the escrow authority, given the original and new mint addresses:

$ spl-token-upgrade create-escrow o1d5Jt8z8vszx4FJ2gNJ3FZH34cer9sbparg7GVt7qm NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ
Creating escrow account 2mW9oGUbaJiCHtkhN5TNTaucY2ziJmAdcJtp5Ud6m4Jy owned by escrow authority A38VXB1Qgssz2qkKgzEkyZNQ27oTuy18T6tA9HRP5mpE
Signature: 4tuJffE4DTrsXb7AM3UWNjd286vyAQcvhQaSKPVThaZMzaBiptKCKudaMWjbbygTUEaho87Ar288Mih5Hx6PpKke

Note: The command-line tool creates the associated token account for the escrow authority, but any token account for NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ is usable for upgrades, as long as the account is owned by or delegated to the escrow authority.

Add tokens to the escrow account​

With the escrow account created, the mint owner must now add tokens to that account. They can do this by minting new tokens or transferring existing tokens.

$ spl-token mint NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ 1000 2mW9oGUbaJiCHtkhN5TNTaucY2ziJmAdcJtp5Ud6m4Jy

Or:

$ spl-token transfer NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ 1000 2mW9oGUbaJiCHtkhN5TNTaucY2ziJmAdcJtp5Ud6m4Jy

Upgrade original tokens into new tokens​

With all accounts in place, any original token holder may redeem new tokens whenever they want.

First, they must create a new token account to receive the tokens:

$ spl-token create-account NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ

Next, they perform the exchange:

$ spl-token-upgrade exchange o1d5Jt8z8vszx4FJ2gNJ3FZH34cer9sbparg7GVt7qm NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ
Burning tokens from account 4YfpfMzHYCCYVBJqvTG9VtTPLMuPzVBi77aMRxVB4TDg, receiving tokens into account JCaWYSvLZkja51RbToWBaV4kp1PhfddX64cTLUqpdMzE
Signature: 3Zs1PtMV7XyRpfX9k7cPg7Hd43URvBD3aYEnd6hb5deKvSWXrEW5yoRaCuqtYJSsoa2WtkdprTsHEh3VLYWEGhkb

The tool defaults to using associated token accounts for the user on the original and new token mints, and for the escrow authority on the new mint. It’s possible to specify each of these individually:

$ spl-token-upgrade exchange o1d5Jt8z8vszx4FJ2gNJ3FZH34cer9sbparg7GVt7qm NewnQeoDG4BbHRCodgjscuypfXdiixcWDPyLiseziQZ --burn-from 4YfpfMzHYCCYVBJqvTG9VtTPLMuPzVBi77aMRxVB4TDg --destination JCaWYSvLZkja51RbToWBaV4kp1PhfddX64cTLUqpdMzE --escrow 2mW9oGUbaJiCHtkhN5TNTaucY2ziJmAdcJtp5Ud6m4Jy
Burning tokens from account 4YfpfMzHYCCYVBJqvTG9VtTPLMuPzVBi77aMRxVB4TDg, receiving tokens into account JCaWYSvLZkja51RbToWBaV4kp1PhfddX64cTLUqpdMzE
Signature: 3P4o4Fxnm4yvB9i6jQzyniqNUqnNLsaQZmCw5q5n5J8nwv9wxJ73ZRYH3XNFT4ferDbCXMqc5egCkhZEkyfCxhgC

After the upgrade, the user may clean up the old token account to recover the rent-exempt lamports.

$ spl-token close o1d5Jt8z8vszx4FJ2gNJ3FZH34cer9sbparg7GVt7qm