Freeze Sol Payment guard

The Freeze Sol Payment guard allows minting frozen Assets by charging the payer an amount in SOL. Frozen Assets cannot be transferred or listed on any marketplaces until thawed.

Frozen Assets can be thawed by anyone as long as one of the following conditions is met:

• The Core Candy Machine has minted out.

• The Core Candy Machine was deleted.

• The configured Freeze Period — which can be a maximum of 30 days — has passed.

The funds are transferred to a "Freeze Escrow" account which must be initialized by the Candy Guard authority before minting can start. Once all Frozen Assets have been thawed, the funds can be unlocked and transferred to the configured destination account by the Candy Guard authority.

You may initialize the Freeze Escrow account, thaw Assets and unlock funds via the route instruction of this guard.

Initialize Freeze Escrow

①

Freeze Escrow PDA

Funds are transferred

to the escrow account

Mint Frozen Assets

②

Frozen AssetFrozen AssetFrozen Asset🕑

When all Assets have been minted

OR at the end of the freeze period.

Thaw Assets

③

Thawed AssetThawed AssetThawed Asset🕑

When all Assets have been thawed.

Unlock Funds

④

Freeze Escrow PDATreasuryReact Flow

Guard Settings

The Freeze Sol Payment guard contains the following settings:

• Lamports: The amount in SOL (or lamports) to charge the payer.

• Destination: The address of the wallet that should eventually receive all payments related to this guard.

Set up a Candy Machine using the Freeze Sol Payment guard

JavaScript

create(umi, {
  // ...
  guards: {
    freezeSolPayment: some({
      lamports: sol(1.5),
      destination: umi.identity.publicKey,
    }),
  },
})

API References: create, FreezeSolPayment

Mint Settings

The Freeze Sol Payment guard contains the following Mint Settings:

• Destination: The address of the wallet that should eventually receive all payments related to this guard.

Note that, if you’re planning on constructing instructions without the help of our SDKs, you will need to provide these Mint Settings and more as a combination of instruction arguments and remaining accounts. See the Candy Guard’s program documentation for more details.

Mint with the Freeze Sol Payment Guard

JavaScript

You may pass the Mint Settings of the Freeze Sol Payment guard using the mintArgs argument like so.

mintV1(umi, {
  // ...
  mintArgs: {
    freezeSolPayment: some({ destination: umi.identity.publicKey }),
  },
})

API References: mintV1, FreezeSolPaymentMintArgs

Route Instruction

The Freeze Sol Payment route instruction supports the following features.

• Overview
• Guard Settings
• Mint Settings
• Route Instruction

  • Initialize the Freeze Escrow
  • Thaw a Frozen Asset
  • Unlock Funds
• Stop Freezing Assets
• Freeze Escrows and Guard Groups

Initialize the Freeze Escrow

Path: initialize

When using the Freeze Sol Payment guard, we must initialize the Freeze Escrow account before minting can start. This will create a PDA account derived from the Destination attribute of the guard's settings.

The Freeze Escrow PDA account will keep track of several parameters such as:

• How many Frozen Assets were minted through this guard.

• When was the first Frozen Asset minted via this guard as the Freeze Period starts counting after that.

When initializing this Freeze Escrow account, we must provide the following arguments to the route instruction of the guard:

• Path = initialize: Selects the path to execute in the route instruction.

• Destination: The address of the wallet that should eventually receive all payments related to this guard.

• Period: The amount of time in seconds that the Freeze Period should last. This can be a maximum of 30 days (2,592,000 seconds) and it will start from the very first Frozen Asset minted via this guard. The Freeze Period provides a safety mechanism to ensure Frozen Assets can eventually be thawed even if the Candy Machine never mints out.

• Candy Guard Authority: The authority of the Candy Guard account as a Signer.

Candy Machine

Owner: Candy Machine Core Program

Candy GuardOwner: Candy Guard ProgramGuardsFreeze Sol Payment- Amount- Destination...

Route with Path

= Initialize

Candy Machine Guard Program

Initialize Freeze Escrow

Freeze Period

Freeze Escrow PDA

React Flow

Last but not least, the Freeze Escrow PDA account will receive the funds of all Frozen Assets minted through this guard.

Candy Machine

Owner: Candy Machine Core Program

Candy GuardOwner: Candy Guard ProgramGuardsFreeze Sol PaymentAmountDestination...

Freeze Escrow PDA

Route with

Path = Initialize

Candy Machine Guard Program

Access Control

Mint

Candy Machine Core Program

Mint Logic

Frozen Asset

React Flow

Initialize the Freeze Escrow

JavaScript

In the example below, we initialize the Freeze Escrow account with a maximum Freeze Period of 15 days and we use the current identity as the Candy Guard authority.

route(umi, {
  // ...
  guard: 'freezeSolPayment',
  routeArgs: {
    path: 'initialize',
    destination: umi.identity.publicKey,
    period: 15 * 24 * 60 * 60, // 15 days.
    candyGuardAuthority: umi.identity,
  },
})

API References: route, FreezeSolPaymentRouteArgsInitialize

Thaw a Frozen Asset

Path: thaw

Frozen Assets can be thawed by anyone as long as one of the following conditions is met:

• The Candy Machine has minted out.

• The Candy Machine was deleted.

• The configured Freeze Period — which can be a maximum of 30 days — has passed.

Note that since the funds in the Freeze Escrow are not transferrable until all Assets are thawed, this creates an incentive for the treasury to thaw all Assets as soon as possible.

To thaw a Frozen Asset, we must provide the following arguments to the route instruction of the guard:

• Path = thaw: Selects the path to execute in the route instruction.

• Destination: The address of the wallet that should eventually receive all payments related to this guard.

• Asset Address: The mint address of the Frozen Asset to thaw.

• Asset Owner: The address of the owner of the Frozen Asset to thaw.

Candy Machine

Candy Machine Core Program

Candy Guard

Candy Machine Guard Program

GuardsFreeze Sol PaymentAmountDestination...

Route with

Path = thaw

Candy Machine Core Program

Thaw a Frozen Asset

Freeze Escrow PDAFrozen AssetThawed AssetReact Flow

Thaw a frozen Asset

JavaScript

In the example below, we thaw a Frozen Asset that belongs to the current identity.

route(umi, {
  // ...
  guard: 'freezeSolPayment',
  routeArgs: {
    path: 'thaw',
    destination,
    nftMint: nftMint.publicKey,
    nftOwner: umi.identity.publicKey,
    nftTokenStandard: candyMachine.tokenStandard,
  },
})

API References: route, FreezeSolPaymentRouteArgsThaw

Unlock Funds

Path: unlockFunds

Once all Frozen Assets have been thawed, the treasury can unlock the funds from the Freeze Escrow account. This will transfer the funds to the configured Destination address.

To unlock the funds, we must provide the following arguments to the route instruction of the guard:

• Path = unlockFunds: Selects the path to execute in the route instruction.

• Destination: The address of the wallet that should eventually receive all payments related to this guard.

• Candy Guard Authority: The authority of the Candy Guard account as a Signer.

Transfer all funds from

the Freeze Escrow Account

Candy Machine

Owner: Candy Machine Core Program

Candy Guard

Candy Machine Guard Program

GuardsFreeze Sol PaymentAmountDestination...

Route with

Path = unlockFunds

Candy Machine Guard Program

Unlock funds from the escrow

Freeze Escrow PDADestination Wallet

Owner: Candy Machine Core Program

React Flow

Unlock Funds

JavaScript

In the example below, we unlock the funds from the Freeze Escrow account using the current identity as the Candy Guard authority.

route(umi, {
  // ...
  guard: 'freezeSolPayment',
  routeArgs: {
    path: 'unlockFunds',
    destination,
    candyGuardAuthority: umi.identity,
  },
})

API References: route, FreezeSolPaymentRouteArgsUnlockFunds

Stop Freezing Assets

It is possible to stop the freezing of Assets within a Freeze Sol Payment guard. In other words, new-minted Assets will no longer be frozen but existing Frozen Assets will remain frozen.

There are several ways of achieving this, which can be separated into two categories:

• ☀️ Can Thaw: Existing Frozen Assets can be thawed by anyone using the thaw path of the route instruction.

• ❄️ Cannot Thaw: Existing Frozen Assets cannot be thawed yet and we have to wait for one "Can Thaw" condition to be met.

With that in mind, here is the exhaustive list of ways to stop freezing Assets and whether or not each of them allows thawing existing Frozen Assets:

• The Candy Machine has minted out → ☀️ Can Thaw.

• The configured Freeze Period — which can be a maximum of 30 days — has passed → ☀️ Can Thaw.

• The Candy Machine account was deleted → ☀️ Can Thaw.

• The Candy Guard account was deleted → ❄️ Cannot Thaw.

• The Freeze Sol Payment guard was removed from the settings → ❄️ Cannot Thaw.

Freeze Escrows and Guard Groups

When using multiple Freeze Sol Payment guards within various Guard Groups, it is important to understand the relationship between a Freeze Sol Payment guard and a Freeze Escrow account.

The Freeze Escrow account is a PDA derived from a Destination address. This means that if multiple Freeze Sol Payment guards are configured to use the same Destination address, they will all share the same Freeze Escrow account.

Therefore, they will also share the same Freeze Period and all funds will be collected by the same escrow account. This also means, we only need to call the initialize route instruction once per configured Destination address. This implies that the route instruction is only required once per the configured Destination address. Same applies for unlockFunds. To thaw you can use whichever label you like provided that those shared the same escrow account.

It is also possible to use multiple Freeze Sol Payment guards with different Destination addresses. In this case, each Freeze Sol Payment guard will have its own Freeze Escrow account and its own Freeze Period.

The example below illustrates a Candy Machine with three Freeze Sol Payment guards in three groups such that:

• Groups 1 and 2 share the same Destination address and therefore the same Freeze Escrow account.

• Group 3 has its own Destination address and therefore its own Freeze Escrow account.

Candy Machine

Owner: Candy Machine Core Program

Candy GuardOwner: Candy Guard ProgramGuard Group 1Freeze Sol PaymentAmount = 1 SOLDestination A...Guard Group 2Freeze Sol PaymentAmount = 2 SOLDestination A...Guard Group 3Freeze Sol PaymentAmount = 3 SOLDestination B...

Freeze Escrow PDA

For Destination A

Route with

Path = Initialize

Candy Machine Guard Program

Initialize Freeze Escrow

Freeze Period A

Freeze Escrow PDA

For Destination B

Route with

Path = Initialize

Candy Machine Guard Program

Initialize Freeze Escrow

Freeze Period B