Freeze / Unfreeze

This page describes how to freeze and unfreeze SPL token accounts in Toolther (UI path: /freeze_authority). Freezing prevents a specific account from transferring or receiving the token until it is thawed. This is useful for compliance flows, vesting incidents, or incident response.

Note: Freezing acts on token accounts (ATAs), not on the mint itself. You need Freeze Authority for the token.

1. Prerequisites

Connected wallet (Phantom, Solflare, Backpack, or Ledger via Solflare).
Network selected (Devnet or Mainnet) matching your wallet network.
Your wallet must currently hold the Freeze Authority of the mint.
Target account must be a valid SPL token account for that mint (typically an Associated Token Account).
Sufficient SOL to pay transaction fees.

2. Page Layout

Header: Connect Wallet and network/explorer controls.
Main card: “Select Token to Manage Authority” with refresh and token selector.
Action area: inputs for target Owner Address (or Token Account), a resolver to find the ATA, and buttons Freeze / Unfreeze.
Sidebar (desktop) or mobile action list: quick links for Freeze/Unfreeze, Revoke Freeze Authority, How to use.

3. Step-by-Step: Freeze

Connect your wallet and ensure network alignment.
Load tokens: Click refresh in the main card to discover mints where you have Freeze Authority.
Select the mint to administer.
Choose the account to freeze:
- Paste the Owner Address (wallet address) and click Resolve to find its Associated Token Account (ATA) for this mint, or paste a Token Account address directly.
Confirm the action:
- Click Freeze and approve the transaction in your wallet.
Verify in the explorer link that the target token account is now frozen.

4. Step-by-Step: Unfreeze

Repeat steps 1–4 above.
Click Unfreeze and approve in wallet.
Verify the account status is thawed (unfrozen) in the explorer.

5. Field Details and Validation

Token selector: lists mints where your wallet appears as Freeze Authority.
Owner Address: a Solana public key; the UI resolves it to the owner’s ATA for the selected mint.
Token Account (optional): paste directly to bypass ATA resolution.
State guardrails: the button disables if the account is already in the requested state (already frozen or already unfrozen).

6. Behavior and Scope

Freezing affects only the specified token account, not the entire mint or other holders.
A frozen account cannot transfer or receive the token. Balance stays unchanged.
Unfreezing restores full functionality.
Marketplaces/DEXes will fail transfers involving frozen accounts.

7. Governance and Safety Patterns

Use multisig as Freeze Authority for operational safety and auditability.
Maintain an incident runbook: when to freeze, who can authorize, and how to document.
Consider time-bound or rules-based control using a program-owned PDA as Freeze Authority.
If your policy is to never freeze, revoke Freeze Authority after launch.

8. Fees and Costs

Only network transaction fees in SOL. No rent for freezing or unfreezing.

9. Troubleshooting

No tokens found: Click refresh; make sure your wallet is the current Freeze Authority and the network matches.
Not authorized: The connected wallet is not the Freeze Authority of that mint.
Invalid account: Ensure the token account belongs to the same mint. If you used owner address, resolve the ATA again.
Hardware wallet prompts: Some devices require multiple approvals; follow on-screen instructions.

10. Programmatic Equivalent (TypeScript)

SPL Token (Classic)

import { Connection, PublicKey } from "@solana/web3.js";
import { freezeAccount, thawAccount } from "@solana/spl-token";

async function freezeTokenAccount(
  connection: Connection,
  payer: any,                 // Signer (wallet adapter or Keypair)
  tokenAccount: PublicKey,    // SPL token account to freeze
  mint: PublicKey,            // Token mint address
  freezeAuthority: any        // Signer that holds Freeze Authority
) {
  const sig = await freezeAccount(
    connection,
    payer,
    tokenAccount,
    mint,
    freezeAuthority
  );
  console.log("Freeze tx:", sig);
}

async function unfreezeTokenAccount(
  connection: Connection,
  payer: any,
  tokenAccount: PublicKey,
  mint: PublicKey,
  freezeAuthority: any
) {
  const sig = await thawAccount(
    connection,
    payer,
    tokenAccount,
    mint,
    freezeAuthority
  );
  console.log("Thaw tx:", sig);
}

Token‑2022

import { Connection, PublicKey } from "@solana/web3.js";
import { freezeAccount, thawAccount, TOKEN_2022_PROGRAM_ID } from "@solana/spl-token";

async function freeze2022(
  connection: Connection,
  payer: any,
  tokenAccount: PublicKey,
  mint: PublicKey,
  freezeAuthority: any
) {
  const sig = await freezeAccount(
    connection,
    payer,
    tokenAccount,
    mint,
    freezeAuthority,
    undefined,                 // multiSigners if using multisig
    undefined,                 // confirmOptions
    TOKEN_2022_PROGRAM_ID
  );
  console.log("Freeze (2022) tx:", sig);
}

async function thaw2022(
  connection: Connection,
  payer: any,
  tokenAccount: PublicKey,
  mint: PublicKey,
  freezeAuthority: any
) {
  const sig = await thawAccount(
    connection,
    payer,
    tokenAccount,
    mint,
    freezeAuthority,
    undefined,
    undefined,
    TOKEN_2022_PROGRAM_ID
  );
  console.log("Thaw (2022) tx:", sig);
}

Notes:

For multisig, pass the multisig pubkey and the signer set via the multiSigners parameter.
Ensure the tokenAccount belongs to the mint. If unsure, derive/lookup the ATA for (owner, mint).

11. Verification Checklist

Transaction confirmed in explorer.
Token account state reflects the requested action (frozen or unfrozen).
Log the transaction signature for audit and incident records.

Revoke Freeze Authority – finalize policy to disable freezing.
Authorities & Safety – overview of token authorities.
SPL vs Token‑2022 – compatibility notes when using freeze features.

PreviousMint NextUpdate Metadata

Last updated 4 days ago