Permissioned Tokens with Token ACL (sRFC37)

┌─────────────────────────────────────────────────────┐
│           TRADITIONAL FROZEN TOKENS                 │
├─────────────────────────────────────────────────────┤
│                                                     │
│   1. User creates token account                     │
│      └─> Account is FROZEN ❄️                       │
│                                                     │
│   2. User contacts issuer support                   │
│      └─> "Please whitelist my wallet"               │
│                                                     │
│   3. Issuer manually verifies KYC                   │
│      └─> Delays, friction, poor UX                  │
│                                                     │
│   4. Issuer thaws account                           │
│      └─> Finally can receive tokens                 │
│                                                     │
│   ❌ Bad UX - users wait hours/days                 │
│                                                     │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│              TOKEN ACL FLOW                         │
├─────────────────────────────────────────────────────┤
│                                                     │
│   1. User creates token account                     │
│      └─> Account is FROZEN ❄️                       │
│                                                     │
│   2. User calls permissionless thaw                 │
│      └─> Token ACL checks Gate Program              │
│                                                     │
│   3. Gate Program validates user                    │
│      ├─> On allow list? ✅ THAW                     │
│      ├─> On block list? ❌ STAY FROZEN              │
│      └─> AllowAllEoas mode? ✅ THAW                 │
│                                                     │
│   4. Account thawed instantly!                      │
│      └─> User can receive tokens immediately        │
│                                                     │
│   ✅ Great UX - instant, self-service               │
│                                                     │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    TOKEN ACL ARCHITECTURE                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌──────────────┐      delegates       ┌─────────────────┐     │
│   │  Token Mint  │ ──────────────────→  │   MintConfig    │     │
│   │  (Token-22)  │   freeze authority   │   (Token ACL)   │     │
│   └──────────────┘                      └────────┬────────┘     │
│                                                  │              │
│                                                  │ calls        │
│                                                  ▼              │
│   ┌──────────────┐     validates        ┌─────────────────┐     │
│   │     User     │ ◄─────────────────── │  Gate Program   │     │
│   │   (wallet)   │                      │  (ABL/Custom)   │     │
│   └──────────────┘                      └─────────────────┘     │
│                                                  │              │
│                                         ┌────────┴────────┐     │
│                                         │                 │     │
│                                    ┌────▼────┐      ┌─────▼───┐ │
│                                    │ Allow   │      │ Block   │ │
│                                    │ Lists   │      │ Lists   │ │
│                                    └─────────┘      └─────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

pnpm add @solana/kit @solana-program/token-2022 @solana-program/system \
  @solana-program/compute-budget @token-acl/sdk @token-acl/abl-sdk \
  @solana/spl-token-metadata @solana/web3.js ws

import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  sendAndConfirmTransactionFactory,
  getSignatureFromTransaction,
  generateKeyPairSigner,
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstructions,
  signTransactionMessageWithSigners,
  lamports
} from "@solana/kit";

import { getCreateAccountInstruction } from "@solana-program/system";
import { getSetComputeUnitLimitInstruction } from "@solana-program/compute-budget";

import {
  TOKEN_2022_PROGRAM_ADDRESS,
  getInitializeMintInstruction,
  getInitializeTokenMetadataInstruction,
  getUpdateTokenMetadataFieldInstruction,
  tokenMetadataField,
  AccountState,
  getMintSize,
  getPreInitializeInstructionsForMintExtensions,
  extension
} from "@solana-program/token-2022";

import { pack } from "@solana/spl-token-metadata";
import { PublicKey } from "@solana/web3.js";

// Token ACL SDK
import {
  getCreateConfigInstruction,
  findMintConfigPda,
  getTogglePermissionlessInstructionsInstruction,
  findThawExtraMetasAccountPda
} from "@token-acl/sdk";

// ABL Gate Program SDK
import {
  getCreateListInstruction,
  getSetupExtraMetasInstruction,
  getAddWalletInstruction,
  findListConfigPda,
  findWalletEntryPda,
  ABL_PROGRAM_ADDRESS,
  Mode
} from "@token-acl/abl-sdk";

// TLV sizes for Token-2022 extensions
const TYPE_SIZE = 2;
const LENGTH_SIZE = 2;

async function createTokenACLMint() {
  // Setup RPC
  const rpc = createSolanaRpc("http://localhost:8899");
  const rpcSubscriptions = createSolanaRpcSubscriptions("ws://localhost:8900");
  const sendAndConfirm = sendAndConfirmTransactionFactory({
    rpc,
    rpcSubscriptions
  });

  // Load your payer keypair
  const payer = await loadKeypair("~/.config/solana/id.json");

  // Generate mint keypair
  const mint = await generateKeyPairSigner();
  console.log(`🪙  Mint: ${mint.address}`);

  // TokenMetadata config - includes 'token_acl' for auto-detection
  const TOKEN_NAME = "Compliant Token";
  const TOKEN_SYMBOL = "COMP";
  const TOKEN_URI = "";
  const TOKEN_ACL_KEY = "token_acl";

  // Define extensions
  const defaultAccountStateExtension = extension("DefaultAccountState", {
    state: AccountState.Frozen
  });
  const metadataPointerExtension = extension("MetadataPointer", {
    authority: payer.address,
    metadataAddress: mint.address
  });
  const extensions = [defaultAccountStateExtension, metadataPointerExtension];

  // Calculate mint size
  const baseMintSize = getMintSize(extensions);
  const metadataForSizing = {
    mint: new PublicKey(mint.address),
    name: TOKEN_NAME,
    symbol: TOKEN_SYMBOL,
    uri: TOKEN_URI,
    additionalMetadata: [[TOKEN_ACL_KEY, ABL_PROGRAM_ADDRESS]] as [
      string,
      string
    ][]
  };
  const metadataLen = pack(metadataForSizing).length;
  const totalSpace = baseMintSize + metadataLen + TYPE_SIZE + LENGTH_SIZE;

  // Get rent
  const mintRent = await rpc
    .getMinimumBalanceForRentExemption(BigInt(totalSpace))
    .send();

  // Get extension pre-initialization instructions
  const extensionInstructions = getPreInitializeInstructionsForMintExtensions(
    mint.address,
    extensions
  );

  // Build transaction
  const { value: blockhash } = await rpc.getLatestBlockhash().send();
  const createMintTx = pipe(
    createTransactionMessage({ version: 0 }),
    (tx) => setTransactionMessageFeePayer(payer.address, tx),
    (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
    (tx) =>
      appendTransactionMessageInstructions(
        [
          getSetComputeUnitLimitInstruction({ units: 400_000 }),
          getCreateAccountInstruction({
            payer,
            newAccount: mint,
            lamports: lamports(mintRent),
            space: baseMintSize,
            programAddress: TOKEN_2022_PROGRAM_ADDRESS
          }),
          ...extensionInstructions,
          getInitializeMintInstruction({
            mint: mint.address,
            decimals: 6,
            mintAuthority: payer.address,
            freezeAuthority: payer.address
          }),
          getInitializeTokenMetadataInstruction({
            metadata: mint.address,
            updateAuthority: payer.address,
            mint: mint.address,
            mintAuthority: payer,
            name: TOKEN_NAME,
            symbol: TOKEN_SYMBOL,
            uri: TOKEN_URI
          }),
          getUpdateTokenMetadataFieldInstruction({
            metadata: mint.address,
            updateAuthority: payer,
            field: tokenMetadataField("Key", [TOKEN_ACL_KEY]),
            value: ABL_PROGRAM_ADDRESS
          })
        ],
        tx
      )
  );

  // Sign and send
  const signedTx = await signTransactionMessageWithSigners(createMintTx);
  await sendAndConfirm(signedTx, { commitment: "confirmed" });

  console.log("✅ Mint created with TokenMetadata");
  return mint.address;
}

async function createTokenACLConfig(
  mintAddress: Address,
  payer: TransactionSigner
) {
  const [mintConfigPda] = await findMintConfigPda({ mint: mintAddress });
  console.log(`📋 MintConfig PDA: ${mintConfigPda}`);

  const createConfigIx = getCreateConfigInstruction({
    payer: payer.address,
    authority: payer,
    mint: mintAddress,
    mintConfig: mintConfigPda,
    gatingProgram: ABL_PROGRAM_ADDRESS
  });

  const { value: blockhash } = await rpc.getLatestBlockhash().send();
  const tx = pipe(
    createTransactionMessage({ version: 0 }),
    (tx) => setTransactionMessageFeePayer(payer.address, tx),
    (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
    (tx) => appendTransactionMessageInstructions([createConfigIx], tx)
  );

  const signedTx = await signTransactionMessageWithSigners(tx);
  await sendAndConfirm(signedTx, { commitment: "confirmed" });

  console.log("✅ Token ACL config created");
  console.log("   Freeze authority transferred to MintConfig PDA");

  return mintConfigPda;
}

async function enablePermissionlessThaw(
  mintConfigPda: Address,
  authority: TransactionSigner
) {
  const toggleIx = getTogglePermissionlessInstructionsInstruction({
    authority,
    mintConfig: mintConfigPda,
    thawEnabled: true,
    freezeEnabled: false // Optional: enable permissionless freeze too
  });

  // Send transaction...
  console.log("✅ Permissionless thaw enabled");
}

import {
  createThawPermissionlessIdempotentInstructionWithExtraMetas,
  TOKEN_ACL_PROGRAM_ADDRESS
} from "@token-acl/sdk";
import { fetchEncodedAccount } from "@solana/kit";

async function userThawsAccount(
  mintAddress: Address,
  userAta: Address,
  userAddress: Address,
  payer: TransactionSigner
) {
  // Account retriever function for the SDK
  const accountRetriever = async (addr: Address) => {
    return await fetchEncodedAccount(rpc, addr);
  };

  // The SDK handles all the complexity of fetching extra metas
  const thawIx =
    await createThawPermissionlessIdempotentInstructionWithExtraMetas(
      payer, // authority (signer)
      userAta, // token account to thaw
      mintAddress, // mint
      userAddress, // token account owner
      TOKEN_ACL_PROGRAM_ADDRESS, // Token ACL program
      accountRetriever // account fetcher
    );

  // Send transaction signed by payer...
  console.log("✅ Account thawed permissionlessly!");
}

import { createAndConfirmAssociatedTokenAccount } from "@solana/token-helpers";

// This automatically includes thaw instruction if mint has 'token_acl' metadata
const { signature, associatedTokenAddress } =
  await createAndConfirmAssociatedTokenAccount(
    rpc,
    rpcSubscriptions,
    payer,
    user.address,
    mintAddress,
    true // idempotent
  );

console.log(`✅ Account created AND thawed automatically!`);
console.log(`   ATA: ${associatedTokenAddress}`);

async function setupCompositeLists(
  mintAddress: Address,
  mintConfigPda: Address,
  payer: TransactionSigner
) {
  // Create ALLOW list
  const allowListSeed = /* unique seed for allow list */;
  const [allowListPda] = await findListConfigPda({
    authority: payer.address,
    seed: allowListSeed,
  });

  const createAllowListIx = getCreateListInstruction({
    authority: payer,
    listConfig: allowListPda,
    mode: Mode.Allow,
    seed: allowListSeed,
  });

  // Create BLOCK list
  const blockListSeed = /* unique seed for block list */;
  const [blockListPda] = await findListConfigPda({
    authority: payer.address,
    seed: blockListSeed,
  });

  const createBlockListIx = getCreateListInstruction({
    authority: payer,
    listConfig: blockListPda,
    mode: Mode.Block,
    seed: blockListSeed,
  });

  // Setup extra metas with BOTH lists
  const [thawExtraMetasPda] = await findThawExtraMetasAccountPda(
    { mint: mintAddress },
    { programAddress: ABL_PROGRAM_ADDRESS }
  );

  const setupMetasIx = getSetupExtraMetasInstruction({
    authority: payer,
    tokenAclMintConfig: mintConfigPda,
    mint: mintAddress,
    extraMetas: thawExtraMetasPda,
    lists: [allowListPda, blockListPda], // Both lists!
  });

  // Send transaction...
  console.log("✅ Composite lists created");
  console.log("   - Allow list: Only whitelisted users can thaw");
  console.log("   - Block list: Blocked users can NEVER thaw");
}

┌─────────────────────────────────────────────────────┐
│           COMPOSITE LIST LOGIC                      │
├─────────────────────────────────────────────────────┤
│                                                     │
│   User tries to thaw:                               │
│                                                     │
│   1. Check BLOCK list first                         │
│      └─> On block list? ❌ DENY (always)            │
│                                                     │
│   2. Check ALLOW list                               │
│      └─> On allow list? ✅ ALLOW                    │
│      └─> Not on allow list? ❌ DENY                 │
│                                                     │
│   Key insight: Block list ALWAYS wins!              │
│                                                     │
└─────────────────────────────────────────────────────┘

// Create allow list
const createListIx = getCreateListInstruction({
  authority: issuer,
  listConfig: allowListPda,
  mode: Mode.Allow,
  seed: mintAddress
});

// After KYC verification, add investor
await addToAllowList(allowListPda, kycVerifiedInvestor, issuer);

// Create block list
const createListIx = getCreateListInstruction({
  authority: complianceOfficer,
  listConfig: blockListPda,
  mode: Mode.Block,
  seed: mintAddress
});

// Block sanctioned address
await addToBlockList(blockListPda, sanctionedAddress, complianceOfficer);

const createListIx = getCreateListInstruction({
  authority: payer,
  listConfig: listConfigPda,
  mode: Mode.AllowAllEoas, // Regular wallets OK, PDAs blocked
  seed: mintAddress
});

# Install from crates.io
cargo install token-acl-cli

# Verify installation
token-acl --version

# Create a mint config (delegates freeze authority to Token ACL)
token-acl create-config <MINT_ADDRESS> \
  --gating-program GATEzzqxhJnsWF6vHRsgtixxSB8PaQdcqGEVTEHWiULz

# Enable permissionless thaw only (recommended for most use cases)
# - Users can self-service unfreeze after passing gate checks
# - Only authority can freeze accounts (security best practice)
token-acl set-instructions --enable-thaw --disable-freeze <MINT_ADDRESS>

# Enable both permissionless thaw AND freeze
# Use case: Allow anyone to freeze blocked users, or users to self-freeze
token-acl set-instructions --enable-thaw --enable-freeze <MINT_ADDRESS>

# Disable all permissionless operations (authority-only mode)
token-acl set-instructions --disable-thaw --disable-freeze <MINT_ADDRESS>

# Thaw an account permissionlessly (user self-service)
token-acl thaw-permissionless <MINT_ADDRESS> <TOKEN_ACCOUNT_ADDRESS>

# Thaw using authority (issuer operation)
token-acl thaw <MINT_ADDRESS> <TOKEN_ACCOUNT_ADDRESS>

# Freeze using authority (compliance enforcement)
token-acl freeze <MINT_ADDRESS> <TOKEN_ACCOUNT_ADDRESS>

# Creates associated token account and thaws it automatically
token-acl create-ata-and-thaw-permissionless --mint <MINT_ADDRESS> --owner <WALLET_ADDRESS>

# Install from crates.io
cargo install token-acl-gate-cli

# Verify installation (binary is named 'allow-block-list')
allow-block-list --version

# Create an ALLOW list (only whitelisted wallets can thaw)
allow-block-list create-list --mode allow

# Create a BLOCK list (blocked wallets cannot thaw)
allow-block-list create-list --mode block

# Create an ALLOW-ALL-EOAs list (all regular wallets can thaw)
allow-block-list create-list --mode allow-all-eoas

# Add wallet to a list (works for both allow and block lists)
allow-block-list add-wallet <LIST_ADDRESS> <WALLET_ADDRESS>

# Remove wallet from a list
allow-block-list remove-wallet <LIST_ADDRESS> <WALLET_ADDRESS>

# Apply a single list to a mint
allow-block-list apply-lists-to-mint <MINT_ADDRESS> <LIST_ADDRESS>

# Apply multiple lists (e.g., allow + block for composite compliance)
allow-block-list apply-lists-to-mint <MINT_ADDRESS> <ALLOW_LIST> <BLOCK_LIST>

# ============================================================================
# STEP 1: Configure Solana CLI
# ============================================================================
solana config set --url localhost

# ============================================================================
# STEP 2: Create Token22 Mint with Metadata + DefaultAccountState Extensions
# ============================================================================

# Create the mint with:
# - Token-2022 program
# - Freeze authority enabled
# - Default account state = frozen (all new accounts start frozen)
# - Metadata extension with token_acl field for auto-detection
spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --enable-freeze \
  --default-account-state frozen \
  --enable-metadata

# Output:
# Creating token 7KzLwpXMzKa8JiqYr2ookFjxLx1xMF4xM4YhVqPJpump
# Address: 7KzLwpXMzKa8JiqYr2ookFjxLx1xMF4xM4YhVqPJpump

# Save the mint address for use in subsequent commands
MINT=7KzLwpXMzKa8JiqYr2ookFjxLx1xMF4xM4YhVqPJpump

# Initialize the token metadata
spl-token initialize-metadata $MINT "Compliant Token" "COMP" "https://example.com/metadata.json"

# Add the token_acl field for wallet auto-detection
# This tells wallets/SDKs which gate program to use for thaw
spl-token update-metadata $MINT token_acl GATEzzqxhJnsWF6vHRsgtixxSB8PaQdcqGEVTEHWiULz

# Verify the token was created correctly
spl-token display $MINT

# ============================================================================
# STEP 3: Create Token ACL Config
# ============================================================================

# This transfers freeze authority from your wallet to the Token ACL MintConfig PDA
token-acl create-config $MINT \
  --gating-program GATEzzqxhJnsWF6vHRsgtixxSB8PaQdcqGEVTEHWiULz

# Output:
# ✅ Config created for mint 7KzLwpXMzKa8JiqYr2ookFjxLx1xMF4xM4YhVqPJpump
# MintConfig PDA: 9xYzAbCdEfGhIjKlMnOpQrStUvWxYz123456789abc

# ============================================================================
# STEP 4: Create ABL Lists
# ============================================================================

# Create a block list for sanctions compliance
allow-block-list create-list --mode block

# Output:
# list_config: 5HnJkLmNoPqRsTuVwXyZ987654321defghijk
# seed: 3AbCdEfGhIjKlMnOpQrStUvWxYz123456789

# Save the block list address
BLOCK_LIST=5HnJkLmNoPqRsTuVwXyZ987654321defghijk

# ============================================================================
# STEP 5: Apply Lists to Mint
# ============================================================================

# Configure the block list to be used for this mint's permissionless operations
allow-block-list apply-lists-to-mint $MINT $BLOCK_LIST

# ============================================================================
# STEP 6: Enable Permissionless Thaw
# ============================================================================

# Allow users to thaw their own accounts (if not on block list)
# --enable-thaw: Users can self-service unfreeze after passing gate checks
# --disable-freeze: Only authority can freeze
token-acl set-instructions --enable-thaw --disable-freeze $MINT

# ============================================================================
# STEP 7: Manage Block List (Compliance Operations)
# ============================================================================

# To fully block a user, you need TWO steps:
# 1. Add to block list (prevents future thawing)
# 2. Freeze their token account (stops current usage)

# Step 7a: Add wallet to block list
# Replace with actual wallet address to block (must be valid base58 pubkey)
allow-block-list add-wallet $BLOCK_LIST <WALLET_TO_BLOCK>

# Step 7b: Freeze their existing token account (if they have one)
# This requires the token account address, not the wallet address
# spl-token address --verbose --token $MINT to get the token account address
# token-acl freeze <TOKEN_ACCOUNT_ADDRESS>

# Note: Adding to block list alone only prevents them from THAWING.
# If their account is already thawed, they can still use it until you freeze it!

# Later, if sanctions are lifted:
# 1. Remove from block list
# allow-block-list remove-wallet $BLOCK_LIST <WALLET_ADDRESS>
# 2. User can then thaw their account again

# ============================================================================
# STEP 8: User Creates Account and Thaws
# ============================================================================

# A user can now create their token account and thaw it in one command
# Use your own wallet or generate one: solana-keygen new --no-outfile
USER_WALLET=$(solana address)  # Uses your configured wallet
token-acl create-ata-and-thaw-permissionless --mint $MINT --owner $USER_WALLET

# Output:
# ✅ Created ATA: 8AbCdEfGhIjKlMnOpQrStUvWxYz123456789xyz
# ✅ Thawed successfully!

# ============================================================================
# STEP 9: Mint Tokens to User
# ============================================================================

# Now the issuer can mint tokens to the user's thawed account
spl-token mint $MINT 1000 --recipient-owner $USER_WALLET

# Verify balance
spl-token balance $MINT