Permanent Freeze Delegate

The Permanent Freeze Delegate Plugin provides irrevocable freeze authority that persists across transfers. Use it for soulbound tokens, collection-wide freezing, and permanent lock mechanisms.

Summary

The Permanent Freeze Delegate is a permanent plugin that can only be added at creation time. Unlike the regular Freeze Delegate, this authority persists forever and can freeze/thaw even after transfers.

• Can only be added at Asset/Collection creation
• Authority persists across transfers (never revoked)
• Uses forceApprove - can freeze even with other blocking plugins
• Collection-level freezing affects all Assets in the Collection

Out of Scope

Regular freeze delegate (see Freeze Delegate), temporary freezing, and Token Metadata freeze authority.

Quick Start

Jump to: Create Asset · Create Collection · Update (Thaw)

1. Add PermanentFreezeDelegate plugin at Asset/Collection creation
2. Set frozen: true for immediate freeze, or false to freeze later
3. The delegate can freeze/thaw at any time, even after transfers

Common Use Cases

• Soulbound tokens: Create non-transferable credentials, achievements, or memberships
• Collection-wide freeze: Freeze all Assets in a Collection with one plugin
• Permanent collateral: Lock Assets as collateral that survives ownership changes
• Game item permanence: Items that stay locked regardless of trades
• Compliance requirements: Assets that must remain frozen for regulatory reasons

Works With

Behaviours

• Asset: Allows the delegated address to freeze and thaw the NFT at any time.
• Collection: Allows the collection authority to freeze and thaw the whole collection at once. It does not allow to freeze a single asset in the collection using this delegate.

Arguments

Creating an Asset with a Permanent Freeze plugin

The following example shows how to create an Asset with a Permanent Freeze plugin.

import { publicKey } from '@metaplex-foundation/umi'
import { create } from '@metaplex-foundation/mpl-core'
const assetSigner = generateSigner(umi)
const delegate = publicKey('33333333333333333333333333333')
await create(umi, {
  asset: assetSigner,
  name: 'My NFT',
  uri: 'https://example.com/my-asset.json',
  plugins: [
    {
      type: 'PermanentFreezeDelegate',
      frozen: true,
      authority: { type: 'Address', address: delegate },
    },
  ],
}).sendAndConfirm(umi)

Updating the Permanent Freeze Delegate plugin on an Asset

The following example shows how to update the Permanent Freeze Delegate plugin on an Asset. Freeze or unfreeze it by setting the frozen argument to true or false respectively. It assumes that the signing wallet is the plugin authority.

import { updatePlugin } from '@metaplex-foundation/mpl-core'
const updateAssetResponse = await updatePlugin(umi, {
  asset: asset.publicKey,
  plugin: {
    type: "PermanentFreezeDelegate",
    frozen: false,
  },
}).sendAndConfirm(umi);

Creating a Collection with a Permanent Freeze plugin

The following example shows how to create a collection with a Permanent Freeze plugin.

import { generateSigner } from '@metaplex-foundation/umi'
import { createCollection } from '@metaplex-foundation/mpl-core'
const collectionSigner = generateSigner(umi)
await createCollection(umi, {
  collection: collectionSigner,
  name: "Frozen Collection",
  uri: "https://example.com/my-collection.json",
  plugins: [
      {
        type: 'PermanentFreezeDelegate',
        frozen: true,
        authority: { type: "UpdateAuthority"}, // The update authority can unfreeze it
      },
    ],
  }).sendAndConfirm(umi);

Updating a Collection with a Permanent Freeze plugin

The following example shows how to update the Permanent Freeze Delegate plugin on a Collection. Freeze or unfreeze it by setting the frozen argument to true or false respectively. It assumes that the signing wallet is the plugin authority.

import { updateCollectionPlugin } from '@metaplex-foundation/mpl-core'
const updateCollectionResponse =  await updateCollectionPlugin(umi, {
  collection: collectionSigner.publicKey,
  plugin: {
      type: "PermanentFreezeDelegate",
      frozen: false,
    },
  }).sendAndConfirm(umi);

Common Errors

Cannot add permanent plugin after creation

Permanent plugins can only be added at Asset/Collection creation. You cannot add a Permanent Freeze Delegate to an existing Asset.

Authority mismatch

Only the plugin authority can freeze/thaw. Verify you're signing with the correct keypair.

Notes

• On creation only: Cannot be added after Asset/Collection exists
• Force approve: Can freeze even with conflicting plugins
• Collection behavior: Freezes all Assets at once, not individually
• Persists forever: Authority is never revoked, even after transfers
• Use for soulbound tokens by setting frozen: true with authority None

FAQ

How do I create a soulbound (non-transferable) token?

Create the Asset with PermanentFreezeDelegate, set frozen: true, and set authority to None. The Asset can never be unfrozen or transferred.

What's the difference between Freeze Delegate and Permanent Freeze Delegate?

Regular Freeze Delegate authority is revoked on transfer and only works on Assets. Permanent Freeze Delegate persists forever, works on Collections, and uses forceApprove.

Can I freeze individual Assets in a Collection?

No. When Permanent Freeze Delegate is on a Collection, freezing affects all Assets at once. Use Asset-level Permanent Freeze Delegate for individual control.

Can a permanently frozen Asset be burned?

Only if there's also a Permanent Burn Delegate. Regular Burn Delegate cannot burn frozen Assets, but Permanent Burn Delegate uses forceApprove.

Related Plugins

• Freeze Delegate - Revocable freeze for temporary locking
• Permanent Transfer Delegate - Permanent transfer authority
• Permanent Burn Delegate - Burn even frozen Assets

Glossary