@superstateinc/allowlist/README.md

TypeScript library for interacting with the Superstate Allowlist program on Solana

# 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

```bash
npm install @superstateinc/allowlist
```

## Usage

### Creating a Thaw Instruction

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

```typescript
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:

```typescript
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:

```typescript
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`
```typescript
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