Hiro Docs

Function Signature

(nft-burn? asset-class asset-identifier sender)

Input: AssetName, A, principal
Output: (response bool uint)

Why it matters

The nft-burn? function is crucial for:

1Reducing the circulating supply of a non-fungible token (NFT).
2Managing the lifecycle of NFTs by allowing their destruction.
3Ensuring data integrity by removing ownership records of burned NFTs.
4Simplifying the process of handling NFT burn operations in smart contracts.

When to use it

Use nft-burn? when you need to:

Reduce the circulating supply of an NFT.
Manage the lifecycle of NFTs by allowing their destruction.
Remove ownership records of burned NFTs.
Handle NFT burn operations in your smart contract.

Best Practices

Ensure the sender principal owns the NFT before attempting to burn it.
Use meaningful variable names for better readability.
Combine with other NFT functions for comprehensive NFT management.
Handle the possible error cases to ensure robust contract behavior.

Practical Example: Burning an NFT

Let's implement a function that burns an NFT owned by the sender:

(define-non-fungible-token Stackaroo (string-ascii 40))

(define-public (burn-nft (id (string-ascii 40)))
  (nft-burn? Stackaroo id tx-sender)
)

;; Usage
(nft-mint? Stackaroo "Roo" tx-sender) ;; Returns (ok true)
(burn-nft "Roo") ;; Returns (ok true)
(nft-burn? Stackaroo "Roo" tx-sender) ;; Returns (err u3) because the asset no longer exists

This example demonstrates:

1Using nft-burn? to burn an NFT owned by the sender.
2Implementing a public function to handle the burn operation.
3Handling both the successful burn and the case where the asset no longer exists.

Common Pitfalls

1Using nft-burn? without ensuring the sender owns the NFT, causing the operation to fail.
2Assuming the NFT will always exist, leading to unhandled error cases.
3Not handling all possible conditions, resulting in incomplete NFT management.
4Overlooking the need for proper error handling and validation.

nft-mint?: Mints a new non-fungible token.
nft-transfer?: Transfers ownership of a non-fungible token.
nft-get-owner?: Retrieves the owner of a non-fungible token.

The nft-burn? function is a fundamental tool for managing the lifecycle of non-fungible tokens in Clarity smart contracts. It allows developers to reduce the circulating supply of NFTs, manage their destruction, and ensure data integrity. When used effectively, nft-burn? enhances the reliability and maintainability of your smart contract code by providing a clear and concise way to handle NFT burn operations.

nft-burn?