Get started with the Hedera Token Service - Part 3: How to Pause, Freeze, Wipe, and Delete NFTs
Nov 09, 2021
by Ed Marquez
Developer Evangelist

In Part 1 of the series, you saw how to mint and transfer an NFT using the Hedera Token Service (HTS). In Part 2, you saw how to enable and disable token KYC, update token properties (if a token is mutable), and schedule transactions. Now in Part 3, you will learn how to use HTS capabilities that help you manage your tokens. Specifically, you will learn how to:

  • Pause a token (stops all operations for a token ID)
  • Freeze an account (stops all token operations only for a specific account)
  • Wipe a token (wipe a partial or entire token balance for a specific account)
  • Delete a token (the token will remain on the ledger)

Note: To make sure you have everything you need to follow along, be sure to check out these getting started resources. There, you will see how to create a Hedera testnet account, and then you can configure your development environment. If you want the entire code used, skip to the Code Check section below.

Pause a Token

The pause transaction prevents a token from being involved in any kind of operation across all accounts. Specifying a <pauseKey> during the creation of a token is a requirement to be able to pause token operations. The code below shows you that this key must sign the pause transaction. Note that you can’t pause a token if it doesn’t have a pause key. Also keep in mind that if this key was not set during token creation, then a token update to add this key is not possible.

Pausing a token may be useful in cases where a third-party requests that you, as the administrator of a token, stop all operations for that token while something like an audit is conducted. The pause transaction provides you with a way to comply with requests of that nature.

In our example below, we pause the token, test that by trying a token transfer and checking the token pauseStatus, and then we unpause the token to enable operations again.

Code Snippet Background
   // PAUSE ALL TOKEN OEPRATIONS
    let tokenPauseTx = await new TokenPauseTransaction().setTokenId(tokenId).freezeWith(client).sign(pauseKey);
    let tokenPauseSubmitTx = await tokenPauseTx.execute(client);
    let tokenPauseRx = await tokenPauseSubmitTx.getReceipt(client);
    console.log(`- Token pause: ${tokenPauseRx.status}`);

    // TEST THE TOKEN PAUSE BY TRYING AN NFT TRANSFER (TREASURY -> ALICE)
    let tokenTransferTx3 = await new TransferTransaction()
        .addNftTransfer(tokenId, 3, treasuryId, aliceId)
        .freezeWith(client)
        .sign(treasuryKey);
    let tokenTransferSubmit3 = await tokenTransferTx3.execute(client);
    try {
        let tokenTransferRx3 = await tokenTransferSubmit3.getReceipt(client);
        console.log(`\n-NFT transfer Treasury->Alice status: ${tokenTransferRx3.status} \n`);
    } catch {
        // TOKEN QUERY TO CHECK PAUSE
        var tokenInfo = await tQueryFcn();
        console.log(`- NFT transfer unsuccessful: Token ${tokenId} is paused (${tokenInfo.pauseStatus})`);
    }

    // UNPAUSE ALL TOKEN OPERATIONS
    let tokenUnpauseTx = await new TokenUnpauseTransaction().setTokenId(tokenId).freezeWith(client).sign(pauseKey);
    let tokenUnpauseSubmitTx = await tokenUnpauseTx.execute(client);
    let tokenUnpauseRx = await tokenUnpauseSubmitTx.getReceipt(client);
    console.log(`- Token unpause: ${tokenUnpauseRx.status}\n`);
Code Snippet Background
    // TOKEN QUERY FUNCTION ==========================================
    async function tQueryFcn() {
        var tokenInfo = await new TokenInfoQuery().setTokenId(tokenId).execute(client);
        return tokenInfo;
    }

Console output:

2021 11 Blog Updates Get started with the Hedera Token Service P3 Image 1

Freeze a Token

Freezing an account stops transfers of the specified token for that account. Note that this transaction must be signed by the <freezeKey> of the token. Once a freeze executes, the specified account is marked as “Frozen” and will not be able to receive or send tokens unless unfrozen.

In our example below, we first freeze Alice’s account for the token ID we’re working with, we test the freeze by trying a token transfer, and then unfreeze Alice’s account so she can transact the token again.

Code Snippet Background
    // FREEZE ALICE'S ACCOUNT FOR THIS TOKEN
    let tokenFreezeTx = await new TokenFreezeTransaction()
        .setTokenId(tokenId)
        .setAccountId(aliceId)
        .freezeWith(client)
        .sign(freezeKey);
    let tokenFreezeSubmit = await tokenFreezeTx.execute(client);
    let tokenFreezeRx = await tokenFreezeSubmit.getReceipt(client);
    console.log(`- Freeze Alice's account for token ${tokenId}: ${tokenFreezeRx.status}`);

    // TEST THE TOKEN FREEZE FOR THE ACCOUNT BY TRYING A TRANSFER (ALICE -> BOB)
    try {
        let tokenTransferTx4 = await new TransferTransaction()
            .addNftTransfer(tokenId, 2, aliceId, bobId)
            .addHbarTransfer(aliceId, 100)
            .addHbarTransfer(bobId, -100)
            .freezeWith(client)
            .sign(aliceKey);
        let tokenTransferTx4Sign = await tokenTransferTx4.sign(bobKey);
        let tokenTransferSubmit4 = await tokenTransferTx4Sign.execute(client);
        let tokenTransferRx4 = await tokenTransferSubmit4.getReceipt(client);
        console.log(`\n-NFT transfer Alice->Bob status: ${tokenTransferRx4.status} \n`);
    } catch {
        console.log(`- Operation unsuccessful: The account is frozen for this token`);
    }
    // UNFREEZE ALICE'S ACCOUNT FOR THIS TOKEN
    let tokenUnfreezeTx = await new TokenUnfreezeTransaction()
        .setTokenId(tokenId)
        .setAccountId(aliceId)
        .freezeWith(client)
        .sign(freezeKey);
    let tokenUnfreezeSubmit = await tokenUnfreezeTx.execute(client);
    let tokenUnfreezeRx = await tokenUnfreezeSubmit.getReceipt(client);
    console.log(`- Unfreeze Alice's account for token ${tokenId}: ${tokenUnfreezeRx.status}\n`);

Console output:

2021 11 Blog Updates Get started with the Hedera Token Service P3 Image 2

Wipe a Token

This operation wipes the provided amount of fungible or non-fungible tokens from the specified account. You see from the code below that this transaction must be signed by the token's <wipeKey>.

Wiping an account's tokens burns the tokens and decreases the total supply. Note that this transaction does not delete tokens from the treasury account. For that, you must use the Token Burn operation.

In this case, we wipe the NFT that Alice currently holds. We then check Alice’s balance and the NFT supply to see how these change with the wipe operation (these two values before the wipe are provided for comparison – see Part 2 for the details).

Code Snippet Background
    // WIPE THE TOKEN FROM ALICE'S ACCOUNT
    let tokenWipeTx = await new TokenWipeTransaction()
        .setAccountId(aliceId)
        .setTokenId(tokenId)
        .setSerials([2])
        .freezeWith(client)
        .sign(wipeKey);
    let tokenWipeSubmitTx = await tokenWipeTx.execute(client);
    let tokenWipeRx = await tokenWipeSubmitTx.getReceipt(client);
    console.log(`- Wipe token ${tokenId} from Alice's account: ${tokenWipeRx.status}`);

    // CHECK ALICE'S BALANCE
    aB = await bCheckerFcn(aliceId);
    console.log(`- Alice balance: ${aB[0]} NFTs of ID:${tokenId} and ${aB[1]}`);

    // TOKEN QUERY TO CHECK TOTAL TOKEN SUPPLY
    var tokenInfo = await tQueryFcn();
    console.log(`- Current NFT supply: ${tokenInfo.totalSupply}`);

Console output:

2021 11 Blog Updates Get started with the Hedera Token Service P3 Image 3

Delete a Token

After you delete a token it’s no longer possible to perform any operations for that token, and transactions resolve to the error TOKEN_WAS_DELETED. Note that the token remains in the ledger, and you can still retrieve some information about it.

The delete operation must be signed by the token <adminKey>. Remember from Part 1 that if this key is not set during token creation, then the token is immutable and deletion is not possible.

In our example, we delete the token and perform a query to double-check that the deletion was successful. Note that for NFTs, you can’t delete a specific serial ID. Instead, you delete the entire class of the NFT specified by the token ID.

Code Snippet Background
    // DELETE THE TOKEN
    let tokenDeleteTx = await new TokenDeleteTransaction().setTokenId(tokenId).freezeWith(client);
    let tokenDeleteSign = await tokenDeleteTx.sign(adminKey);
    let tokenDeleteSubmit = await tokenDeleteSign.execute(client);
    let tokenDeleteRx = await tokenDeleteSubmit.getReceipt(client);
    console.log(`\n- Delete token ${tokenId}: ${tokenDeleteRx.status}`);

    // TOKEN QUERY TO CHECK DELETION
    var tokenInfo = await tQueryFcn();
    console.log(`- Token ${tokenId} is deleted: ${tokenInfo.isDeleted}`);

Console output:

2021 11 Blog Updates Get started with the Hedera Token Service P3 Image 4

Conclusion

In this article, you saw key capabilities to help you manage your HTS tokens, including how to: pause, freeze, wipe, and delete tokens. If you haven’t already, be sure to check out Part 1 and Part 2 of this blog series to see examples of how to do even more with HTS – you will see how to mint NFTs, transfer NFTs, perform token KYC, schedule transactions, and more.

Continue learning more in our documentation and learning center!

Code Check

https://github.com/ed-marquez/hedera-sdk-js/blob/main/examples/hts-nftP3-pause-freeze-wipe-delete.js