Hiro Docs

Using the asserts! function for conditional assertions in Clarity smart contracts.

Function Signature

(asserts! bool-expr thrown-value)

Input:
- bool-expr: A boolean expression
- thrown-value: The value to be returned if the assertion fails
Output: bool or thrown-value

Why it matters

The asserts! function is crucial for:

Implementing conditional checks in smart contracts.
Enforcing preconditions before executing critical operations.
Providing meaningful error responses when conditions are not met.
Improving contract security by validating inputs and state.

When to use it

Use the asserts! function when you need to:

Validate conditions before proceeding with contract execution.
Ensure certain requirements are met before performing sensitive operations.
Provide clear error messages or codes when conditions are not satisfied.
Implement guard clauses to protect against invalid inputs or states.

Best Practices

Use asserts! early in functions to validate preconditions.
Provide meaningful error values that can be easily interpreted by users or other contracts.
Combine multiple conditions using and or or for complex assertions.
Consider using asserts! in combination with unwrap! for handling optional values.

Practical Example: Token Transfer with Balance Check

Let's implement a simple token transfer function that uses asserts! to check the sender's balance:

(define-map Balances principal uint)

(define-public (transfer (amount uint) (recipient principal))
  (let
    (
      (senderBalance (default-to u0 (map-get? Balances tx-sender)))
    )
    (asserts! (>= senderBalance amount) (err u1)) ;; Insufficient balance
    (asserts! (not (is-eq tx-sender recipient)) (err u2)) ;; Can't send to self
    
    (map-set Balances tx-sender (- senderBalance amount))
    (map-set Balances recipient (+ (default-to u0 (map-get? Balances recipient)) amount))
    (ok true)
  )
)

(map-set Balances tx-sender u1000) ;; Set the sender's balance to 1000

;; Usage
(transfer u100 'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5) ;; Returns (ok true)
(transfer u100 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM) ;; Returns (err u2) Can't send to self
(transfer u1000 'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5) ;; Returns (err u1) Insufficient balance

This example demonstrates:

Using asserts! to check if the sender has sufficient balance before transferring.
Using asserts! to prevent sending tokens to oneself.
Providing different error codes for different types of failures.

Common Pitfalls

Forgetting to handle the error case when calling functions that use asserts!.
Using asserts! excessively, which can make code harder to read and maintain.
Providing vague or unhelpful error values when assertions fail.

unwrap!: Used to extract values from optionals with a fallback error.
unwrap-panic: Similar to unwrap! but causes a panic instead of returning an error.
try!: Used for propagating errors in a chain of operations.

The asserts! function is a powerful tool for implementing conditional checks and enforcing invariants in Clarity smart contracts. By using it effectively, developers can create more robust and secure contracts that gracefully handle edge cases and provide meaningful feedback when conditions are not met.

asserts!