Introduction

Token Upgrade UI provides a client interface to upgrade tokens to the new format of a token (Token Extension).

Contents

🚀 packages/app

Demo application powered by Next.js.

It demonstrates how to integrate the TokenUpgrade component and its functionality into a project with React under the hood.

Use the button down here to launch it on Vercel.

Bear in mind it will require some configuration:

• Set NEXT_PUBLIC_TOKEN_UPGRADE_PROGRAM_ID environment variable and provide the address of the deployed token-upgrade program.
• Set all other env variables to the proper values.
• The root directory should lead to the packages/app directory.
• node@18.x

Usage

To upgrade a token except for the program, you should have:

• replacement token (Token Extension)
• escrow account
• escrow should have enough replacement tokens for future upgrades

To create a replacement token, you use @solana/spl-token.

The spl-token-upgrade CLI creates an escrow.

Having all these, you can mint some tokens with ease.

There is a scripts/issue-tokens.mts script to demonstrate the complete flow. It will create all the needed tokens and accounts. The same is true for minting. You can use it on devnet like so:

SOLANA_TOKEN_UPGRADE_CLI=<%path_to_upgrade_cli%> \
    pnpx tsx ./scripts/issue-tokens.mts $HOLDER_ADDRESS

• HOLDER_ADDRESS - wallet to hold tokens
• <%path_to_upgrade_cli%> - path to a spl-token-upgrade cli at your system

Do not forget to declare the proper ID for your source code version.

Upon execution, the script will provide a query string with all the needed addresses. You can launch the application and paste it into a browser.

⚙️ packages/ui

The package contains the TokenUpgrade component and the blocks from which it is built.

Basic usage

Use this sample to integrate the component.

import { TokenUpgrade } from "@solana/token-upgrade-ui"

const EXPLORER_URL = "https://explorer.solana.com"
const OuterComponent = () => (
  <TokenUpgrade
    escrow={/* escrow address */}
    explorerUrl={EXPLORER_URL}
    onUpgradeStart={() =>
      console.log({ message: "Upgrading token..." })
    }
    onUpgradeEnd={({ signature }) =>
      console.log({
        message: "Token upgraded",
        link: EXPLORER_URL + `/tx/${signature}`,
      })
    }
    tokenAddress={/* token address to upgrade */}
    tokenExtAddress={/* token extension address */}
    tokenUpgradeProgramId={/* deployed upgrade program address */}
  />
)

If you do not need the UI, core functions can be used.

import { 
  createUpgradeTokenInstruction, // construct upgrade instruction
  upgradeToken, // build upgrade transaction
  useTokenUpgrade // hook to upgrade a token
} from "@solana/token-upgrade-ui"

🔒 packages/shared

Shared configuration for both packages.

Development

🛠️ Setup

pnpm it
# Install & check

💪 Build

pnpm dev
# Launch the demo application in watch mode.
# Scripts will track changes. 
# Use it for development

pnpm playground
# Launch Storybook. Use it to improve UI for components.

📋 Test & Quality control

pnpm lint
# Check code style

pnpm --filter "*" lint-fix
# Linting the source code

pnpm --filter "@solana/*ui" local:test-e2e
# Test the `upgrade token` scenario. 
# To run this properly env variables shall be tweaked. 
# See `packages/ui/tests/e2e.test.ts` for more info

pnpm --filter "@solana/*ui" local:test-smoke
# Run UI tests

📦 Release

pnpm build
# Build UI for a production

pnpm build-sb
# Build Storybook's artifacts

pnpm changeset $COMMAND
# Use `changeset` to prepare for a release

📒 Documentation

pnpm run docs
# Launch documentation