Solana Token Extension SDK

A simple SDK for interacting with Token Extensions on Solana, making it easier for developers to create and manage tokens with extended features without dealing with the complex details of the Solana Token Extensions Program.

Introduction

Solana Token Extensions (Token-2022) introduce a variety of new features to tokens on Solana, making them more flexible and customizable. This SDK is designed to simplify the use of these features, helping developers easily integrate them into their applications.

Features Overview

This SDK provides a comprehensive solution for working with Solana Token-2022 extensions:

Core Features

• Simple Token Creation: Create tokens with any combination of extensions using a fluent builder pattern
• Instructions-First API: All operations return instructions for wallet-adapter compatibility
• TypeScript Support: Full TypeScript type definitions for better development experience
• Error Handling: Comprehensive error checking and validation
• Simplified Account Management: Easy creation and management of token accounts

Token Operations

• Transfer: Transfer tokens between accounts with decimal validation
• Burn: Burn tokens from accounts
• Freeze/Thaw: Freeze and thaw token accounts
• Mint: Mint new tokens to accounts
• Fee Management: Harvest and withdraw transfer fees

Extensions Support

| Extension | Description | Key Functionality | |-----------|-------------|------------------| | Transfer Fee | Add fees to transfers | Automatic fee collection, withdrawal | | Metadata | Add on-chain metadata | Rich token information | | Non-Transferable | Soulbound tokens | Prevent secondary transfers | | Permanent Delegate | Delegate authority | Manage tokens without ownership | | Transfer Hook | Custom transfer logic | Execute programs on transfer | | Token Freeze | Freeze accounts | Prevent transfers from accounts | | Default Account State | Configure new accounts | Set initial state of accounts | | Interest-Bearing | Interest accrual | Tokens that grow over time | | Mint Close Authority | Close mint accounts | Recover rent from mints | | Confidential Transfer | Privacy features | Hide transfer amounts |

Current Features

The SDK currently supports the following Token Extensions:

• Transfer Fee: Create tokens with automatic transfer fees
• Metadata Pointer: Store and manage metadata for tokens
• Non-Transferable: Create non-transferable tokens (soulbound tokens)
• Permanent Delegate: Permanently delegate token management authority to another address
• Interest-Bearing: Create tokens that accrue interest over time
• Transfer Hook: Execute custom logic on token transfers through a separate program
• Confidential Transfer: Execute confidential token transfers that hide amounts
• Token Freeze: Freeze and thaw token accounts to prevent transfers
• Default Account State: Set the default state (frozen or initialized) for new token accounts
• Multiple Extensions: Create tokens with multiple extensions at once, including metadata
• Close Account: Close zero-balance token accounts and reclaim SOL rent

Core Token Features

The base Token class provides the following core functionality:

• Transfer: Transfer tokens between accounts with decimal checking
• Burn: Burn tokens from an account
• Account Management: Create or get token accounts easily

These core features work with all token extensions.

Wallet-Adapter Integration (No Keypair Required)

The SDK is designed to be fully compatible with wallet-adapter:

import { Connection, clusterApiUrl } from "@solana/web3.js";
import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { TokenBuilder } from "solana-token-extension-boost";

function YourComponent() {
  const { connection } = useConnection();
  const { publicKey, sendTransaction } = useWallet();

  const createToken = async () => {
    if (!publicKey) return;

    // Create a token with multiple extensions including metadata
    const tokenBuilder = new TokenBuilder(connection)
      .setTokenInfo(
        6, // decimals
        publicKey, // mint authority
        null // freeze authority
      )
      // Add metadata
      .addTokenMetadata(
        "My Token",
        "TKN",
        "https://example.com/metadata.json",
        { "website": "https://example.com" }
      )
      // Add TransferFee extension
      .addTransferFee(
        100, // 1% fee (basis points)
        BigInt(1_000_000), // max fee 1 token (with 6 decimals)
        publicKey, // config authority
        publicKey // withdraw authority
      );

    // Generate instructions instead of executing transaction directly
    const { instructions, signers, mint } = 
      await tokenBuilder.createTokenInstructions(publicKey);

    // Create transaction from instructions
    const transaction = tokenBuilder.buildTransaction(instructions, publicKey);
    
    // Sign with wallet
    const signature = await sendTransaction(transaction, connection, {
      signers: signers
    });

    console.log(`Token created: ${mint.toBase58()}`);
    console.log(`Transaction signature: ${signature}`);
  };

  return (
    <button onClick={createToken} disabled={!publicKey}>
      Create Token
    </button>
  );
}

TransferFee With Instructions API Example

import { Connection, clusterApiUrl } from "@solana/web3.js";
import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { TransferFeeToken } from "solana-token-extension-boost";

function TransferComponent({ mintAddress }) {
  const { connection } = useConnection();
  const { publicKey, sendTransaction } = useWallet();

  const transferTokens = async (destination, amount) => {
    if (!publicKey || !mintAddress) return;
    
    // Create TransferFeeToken instance
    const token = new TransferFeeToken(connection, mintAddress, {
      feeBasisPoints: 100, // 1%
      maxFee: BigInt(1_000_000), // 1 token (with 6 decimals)
      transferFeeConfigAuthority: publicKey, 
      withdrawWithheldAuthority: publicKey
    });
    
    // Find source token account
    const sourceAccount = await token.getAssociatedTokenAddress(publicKey);

    // Create transfer instruction
    const instruction = token.createTransferInstruction(
      sourceAccount,
      destination,
      publicKey,
      amount,
      6 // decimals
    );
    
    // Build and send transaction
    const transaction = new Transaction().add(instruction);
    const signature = await sendTransaction(transaction, connection);
    
    console.log(`Transfer complete: ${signature}`);
  };

  return (
    // Your component UI
  );
}

Token Freeze Example

import { Connection, clusterApiUrl } from "@solana/web3.js";
import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { TokenBuilder, TokenFreezeExtension } from "solana-token-extension-boost";
import { AccountState } from "@solana/spl-token";

function FreezeTokensComponent() {
  const { connection } = useConnection();
  const { publicKey, sendTransaction } = useWallet();

  // Create a token with Default Account State
  const createToken = async () => {
    if (!publicKey) return;

    const tokenBuilder = new TokenBuilder(connection)
      .setTokenInfo(
        6, // decimals
        publicKey, // mint authority
        publicKey  // freeze authority (required for freeze functionality)
      )
      .addTokenMetadata(
        "Frozen Token",
        "FRZT",
        "https://example.com/metadata.json",
        { "description": "A token with freeze capabilities" }
      )
      // Set default state for new accounts (Initialized or Frozen)
      .addDefaultAccountState(AccountState.Initialized);

    const { instructions, signers, mint } = 
      await tokenBuilder.createTokenInstructions(publicKey);
      
    // Create and send transaction
    // ...
  };

  // Freeze a token account
  const freezeAccount = async (account, mint) => {
    if (!publicKey) return;
    
    // Create a transaction to freeze the account
    const transaction = TokenFreezeExtension.prepareFreezeAccountTransaction(
      account, // token account to freeze
      mint,    // mint address
      publicKey, // freeze authority
      publicKey  // fee payer
    );
    
    // Sign and send transaction
    const signature = await sendTransaction(transaction, connection);
    console.log(`Account frozen: ${signature}`);
  };

  return (
    // Your component UI
  );
}

Close Account Example

import { Connection, clusterApiUrl } from "@solana/web3.js";
import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { CloseAccountExtension } from "solana-token-extension-boost";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Loader2 } from "lucide-react";
import { toast } from "sonner";
import { PublicKey } from "@solana/web3.js";
import { Transaction } from "@solana/web3.js";

function CloseAccountsComponent() {
  const { connection } = useConnection();
  const { publicKey, sendTransaction } = useWallet();
  const [isLoading, setIsLoading] = useState(false);
  const [rentInfo, setRentInfo] = useState(null);

  // Tìm và đóng các tài khoản có số dư bằng 0 để lấy lại SOL
  const closeZeroBalanceAccounts = async () => {
    if (!publicKey) return;
    setIsLoading(true);

    try {
      // Khởi tạo extension
      const closeAccountExtension = new CloseAccountExtension(connection, new PublicKey("AnyMintAddress"));

      // Tìm tất cả tài khoản token có số dư bằng 0
      const zeroBalanceAccounts = await closeAccountExtension.findZeroBalanceAccounts(publicKey);
      const accounts = zeroBalanceAccounts.map(acc => acc.address);
      
      if (accounts.length === 0) {
        toast.info("Không tìm thấy tài khoản nào có số dư bằng 0");
        setIsLoading(false);
        return;
      }

      // Chuẩn bị transaction để đóng tài khoản (phù hợp với wallet-adapter)
      const { transaction, closeableAccounts, estimatedRent } = 
        await closeAccountExtension.prepareCloseAccountsTransaction(
          accounts,
          publicKey,
          {
            adminFeeReceiver: new PublicKey("AdminFeeReceiverAddress"),
            adminFeeBasisPoints: 1000 // 10%
          }
        );
      
      // Hiển thị thông tin về số SOL sẽ được hoàn trả
      setRentInfo({
        accounts: closeableAccounts.length,
        userRent: estimatedRent.userRent / 1_000_000_000,
        adminRent: estimatedRent.adminRent / 1_000_000_000
      });

      if (closeableAccounts.length > 0) {
        // Gửi transaction thông qua wallet-adapter
        const signature = await sendTransaction(transaction, connection);
        
        // Chờ xác nhận giao dịch
        const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash();
        await connection.confirmTransaction({
          signature,
          blockhash,
          lastValidBlockHeight
        });

        toast.success(`Đã đóng ${closeableAccounts.length} tài khoản thành công!`, {
          description: `Bạn đã nhận lại ${estimatedRent.userRent / 1_000_000_000} SOL`,
          action: {
            label: "Xem giao dịch",
            onClick: () => window.open(`https://solscan.io/tx/${signature}`, "_blank"),
          },
        });
      }
    } catch (error) {
      console.error("Lỗi khi đóng tài khoản:", error);
      toast.error(error instanceof Error ? error.message : "Lỗi khi đóng tài khoản");
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div className="space-y-4">
      <Button 
        onClick={closeZeroBalanceAccounts} 
        disabled={!publicKey || isLoading}
        className="w-full"
      >
        {isLoading ? (
          <div className="flex items-center gap-2">
            <Loader2 className="h-4 w-4 animate-spin" />
            <span>Đang đóng tài khoản...</span>
          </div>
        ) : (
          "Đóng các tài khoản token có số dư bằng 0"
        )}
      </Button>
      
      {rentInfo && (
        <div className="px-3 py-2 bg-green-50 border-green-200 rounded-lg">
          <p className="text-sm text-green-800">
            <strong>Thông tin phí thuê:</strong><br/>
            Số tài khoản: {rentInfo.accounts}<br/>
            Bạn sẽ nhận: <strong>{rentInfo.userRent} SOL</strong><br/>
            Phí admin: {rentInfo.adminRent} SOL
          </p>
        </div>
      )}
    </div>
  );
}

Examples

The SDK includes several examples to help you get started:

• Transfer Fee Examples (examples/transfer-fee/): Create and use tokens with transfer fees
• Transfer Hook Examples (examples/transfer-hook/): Create tokens with custom transfer hooks
• Token Freeze Examples (examples/token-freeze/): Freeze and thaw token accounts
• Multi-Extension Examples (examples/multi-extension-example/): Create tokens with multiple extensions at once
• Metadata Examples (examples/metadata/): Create tokens with metadata and other extensions
• Instructions API Examples (examples/instructions-api-example/): Examples of using the instructions API with wallet adapter

Run an example with:

ts-node examples/metadata/combined-extensions.ts

Key Features

Important features of the SDK include:

• Instructions API: All methods now return instructions rather than executing transactions directly, making them compatible with wallet adapters

  • createTokenInstructions(): Generate instructions to create a token
  • createTransferInstruction(): Generate instructions for transfers
  • createWithdrawFeesFromAccountsInstruction(): Generate instructions to withdraw fees

• Core Token Support: The base Token class provides essential functionality:

  • transfer(): Transfer tokens between accounts
  • burnTokens(): Burn tokens from an account
  • createOrGetTokenAccount(): Create or get existing token accounts

What's New in Current Version

The current version brings significant API changes to fully support wallet-adapter integration:

1. Removed All Keypair-Based Methods: All methods that required direct access to private keys (Keypair objects) have been removed. This is a breaking change but improves security by preventing private key exposure.

2. Instructions-First API Design: All token operations now follow the instructions pattern:

   • Create instructions using methods like createTokenInstructions()
   • Build transactions from instructions
   • Sign and send transactions with your wallet adapter

3. Complete Wallet Adapter Support: The SDK now works seamlessly with any wallet adapter implementation, letting users sign transactions without exposing private keys.

4. Simplified Integration: The separation of instruction creation from transaction execution makes the SDK more flexible for different frontend frameworks and wallet solutions.

Development Roadmap

The SDK already supports the following Token Extensions:

• ✅ Transfer Fee: Create tokens with automatic transfer fees
• ✅ Metadata Pointer: Store and manage metadata for tokens
• ✅ Non-Transferable: Create non-transferable tokens (soulbound tokens)
• ✅ Permanent Delegate: Permanently delegate token management authority to another address
• ✅ Interest-Bearing: Create tokens that accrue interest over time
• ✅ Transfer Hook: Execute custom logic on token transfers through a separate program
• ✅ Default Account State: Set default state for newly created token accounts
• ✅ Token Freeze: Freeze and thaw token accounts to prevent transfers
• ✅ Mint Close Authority: Define authority to close a mint account
• ✅ CPI Guard: Protect token operations from cross-program invocation (CPI) attacks
• ✅ Member Pointer: Link individual tokens to a token group via on-chain metadata
• ✅ Close Authority: Define who can close a specific token account

Installation

npm install solana-token-extension-boost

Documentation

For detailed documentation on all features and extensions, please refer to the docs directory.

The documentation is structured as follows:

• Documentation Overview: Start here to see all available documentation
• Token Extensions Guide: A comprehensive guide to token extensions
• [Extension-Specific Guides]:
  • Metadata Integration: How to create tokens with metadata
  • Transfer Fee: How to implement transfer fees
  • Transfer Hook: How to use transfer hooks
  • Token Freeze & DefaultAccountState: How to freeze accounts and set default states
  • Permanent Delegate: How to use permanent delegates
  • Non-Transferable: How to create non-transferable tokens
• [General Guides]:
  • Extension Compatibility: How to combine multiple extensions
  • Core Token Operations: How to perform basic token operations

Each guide includes detailed explanations, code examples, and best practices for using the relevant features.

Token Extensions Boost supports the following Solana Token-2022 extensions:

• Transfer Hook: Add custom logic that executes during token transfers
• Token Metadata: Store metadata directly on the token mint
• Non-Transferable: Create tokens that cannot be transferred, only minted and burned
• Token Freeze: Freeze tokens to prevent transfers and minting
• CPI Guard: Protect against Cross-Program Invocation attacks
• Token Groups: Group tokens together and track membership status
• Interest-Bearing: Create tokens that automatically accrue interest
• Default Account State: Set the default state for new token accounts
• Member Pointer: Link tokens to related data or accounts
• Mint Close Authority: Allow a mint account to be closed and recover rent
• Permanent Delegate: Set a permanent delegate for token accounts

Documentation can be found in the docs directory. Each extension has its own specific documentation:

• Transfer Hook
• Token Metadata
• Non-Transferable
• Token Freeze
• CPI Guard
• Token Groups
• Interest-Bearing
• Default Account State
• Member Pointer
• Mint Close Authority
• Permanent Delegate