Superstate Allowlist Program

TypeScript library for interacting with the Superstate Allowlist program on Solana. This library provides utilities for creating instructions, deriving PDAs, and working with allowlist functionality for SPL Token 2022 mints.

Installation

npm install @superstateinc/allowlist

Usage

Creating a Thaw Instruction

The main functionality of this library is to create thaw instructions for token accounts:

import {
  createThawInstruction,
  ThawInstructionParams,
  TOKEN_2022_PROGRAM_ID
} from '@superstateinc/allowlist';
import { PublicKey } from '@solana/web3.js';

// Define your parameters
const params: ThawInstructionParams = {
  allowlistProgramId: new PublicKey('SUPERSTATE_ALLOWLIST_PROGRAM_ID'),
  mint: new PublicKey('YOUR_TOKEN_MINT'),
  userTokenAccountOwner: new PublicKey('USER_WALLET_ADDRESS'),
  userTokenAccount: new PublicKey('USER_TOKEN_ACCOUNT'),
  tokenProgramId: TOKEN_2022_PROGRAM_ID, // Optional, defaults to Token 2022
};

// Create the instruction
const thawInstruction = createThawInstruction(params);

// Add to your transaction
transaction.add(thawInstruction);

PDA Derivation

You can also derive Program Derived Addresses (PDAs) used by the allowlist program:

import {
  getAllowlistProgramPda,
  getPrivateAllowlistPda,
  getPublicAllowedAccountPda,
  getPrivateAllowedAccountPda,
  getAdminPda
} from '@superstateinc/allowlist';
import { PublicKey } from '@solana/web3.js';

const programId = new PublicKey('SUPERSTATE_ALLOWLIST_PROGRAM_ID');
const mint = new PublicKey('YOUR_TOKEN_MINT');
const userWallet = new PublicKey('USER_WALLET_ADDRESS');

// Derive various PDAs
const [allowlistProgramPda, bump1] = getAllowlistProgramPda(programId);
const [privateAllowlistPda, bump2] = getPrivateAllowlistPda(mint, programId);
const [publicAllowedPda, bump3] = getPublicAllowedAccountPda(userWallet, programId);
const [privateAllowedPda, bump4] = getPrivateAllowedAccountPda(userWallet, mint, programId);
const [adminPda, bump5] = getAdminPda(programId);

Constants

The library exports useful constants:

import {
  TOKEN_2022_PROGRAM_ID,
  SYSTEM_PROGRAM_ID,
  AllowlistInstruction
} from '@superstateinc/allowlist';

console.log('Token 2022 Program:', TOKEN_2022_PROGRAM_ID.toString());
console.log('Thaw instruction discriminant:', AllowlistInstruction.Thaw);

API Reference

Functions

createThawInstruction(params: ThawInstructionParams): TransactionInstruction

Creates a thaw instruction for the allowlist program. This instruction thaws a user's token account if they are allowed on either the public allowlist or the private allowlist for the specific mint.

PDA Derivation Functions

• getAllowlistProgramPda(programId: PublicKey): [PublicKey, number]
• getPrivateAllowlistPda(mint: PublicKey, programId: PublicKey): [PublicKey, number]
• getPublicAllowedAccountPda(userAccount: PublicKey, programId: PublicKey): [PublicKey, number]
• getPrivateAllowedAccountPda(userAccount: PublicKey, mint: PublicKey, programId: PublicKey): [PublicKey, number]
• getAdminPda(programId: PublicKey): [PublicKey, number]

Types

ThawInstructionParams

interface ThawInstructionParams {
  allowlistProgramId: PublicKey;
  mint: PublicKey;
  userTokenAccountOwner: PublicKey;
  userTokenAccount: PublicKey;
  tokenProgramId?: PublicKey;
}

Account State Interfaces

• Admin
• PrivateAllowlist
• PublicAllowedAccount
• PrivateAllowedAccount

Constants

• TOKEN_2022_PROGRAM_ID: SPL Token 2022 program ID
• SYSTEM_PROGRAM_ID: System program ID
• AllowlistInstruction: Enum of all allowlist instruction discriminants

How It Works

The allowlist program supports both public and private allowlists:

• Public Allowlist: A global allowlist that applies to all tokens
• Private Allowlist: Token-specific allowlists for private instruments

The thaw instruction automatically:

1. Checks if the user is on the public allowlist
2. Checks if the user is on the private allowlist for the specific mint
3. Thaws the token account if the user is allowed

Requirements

• Solana Web3.js v1.87.6+
• SPL Token v0.4.1+
• Node.js 16+

License

MIT