Hiro Docs

Function Signature

(stx-burn? amount sender)

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

Why it matters

The stx-burn? function is crucial for:

Decreasing the STX holdings of a principal by burning the specified amount.
Implementing logic that requires reducing the circulating supply of STX.
Ensuring data integrity by validating the burn operation.
Simplifying the process of handling STX burning in smart contracts.

When to use it

Use stx-burn? when you need to:

Decrease the STX holdings of a principal by burning the specified amount.
Implement logic that requires reducing the circulating supply of STX.
Validate the burn operation to ensure data integrity.
Handle STX burning operations in your smart contract.

Best Practices

Ensure the amount is positive and the sender has sufficient balance.
Use meaningful variable names for better readability.
Combine with other STX functions for comprehensive account management.
Handle the possible error cases to ensure robust contract behavior.

Practical Example: Burning STX from an Account

Let's implement a function that burns a specified amount of STX from the tx-sender:

(define-public (burn-stx (amount uint))
  (stx-burn? amount tx-sender)
)

;; Usage
(burn-stx u50) ;; Returns (ok true)

This example demonstrates:

Using stx-burn? to burn a specified amount of STX from the tx-sender.
Implementing a public function to handle the STX burning operation.
Handling both successful and error cases.

Common Pitfalls

Using stx-burn? with a non-positive amount, causing the operation to fail.
Assuming the burn operation will always succeed, leading to unhandled error cases.
Not handling all possible conditions, resulting in incomplete account management.
Overlooking the need for proper error handling and validation.

stx-get-balance: Queries the STX balance of a principal.
stx-transfer?: Transfers STX from one principal to another.
stx-account: Queries detailed STX account information.

The stx-burn? function is a fundamental tool for burning STX from a principal's account in Clarity smart contracts. It allows developers to implement logic that requires reducing the circulating supply of STX, ensuring data integrity and simplifying STX burning operations. When used effectively, stx-burn? enhances the reliability and maintainability of your smart contract code by providing a clear and concise way to handle STX burning operations.

stx-burn?