Hiro Docs

Function Signature

(unwrap! option-input thrown-value)

Input: (optional A) | (response A B), C
Output: A

Why it matters

The unwrap! function is crucial for:

Unpacking optional and response types to access their inner values.
Implementing logic that requires handling optional and response types.
Ensuring data integrity by validating the unpacking process.
Simplifying the process of handling optional and response types in smart contracts.

When to use it

Use unwrap! when you need to:

Unpack optional and response types to access their inner values.
Implement logic that requires handling optional and response types.
Validate the unpacking process to ensure data integrity.
Handle optional and response types in your smart contract.

Best Practices

Ensure the input value is an optional or response type.
Use meaningful variable names for better readability.
Combine with other error handling functions for comprehensive error management.
Handle the possible error cases to ensure robust contract behavior.

Practical Example: Unpacking an Optional Value

Let's implement a function that retrieves a value from a map and unpacks it using unwrap!:

(define-map user-info { user-id: principal } { name: (string-ascii 20), age: uint })

(define-public (get-user-age (user principal))
  (let ((user-data (unwrap! (map-get? user-info { user-id: user }) (err "User not found"))))
    (ok (get age user-data))
  )
)

;; Usage
(map-set user-info { user-id: tx-sender } { name: "Alice", age: u30 })
(get-user-age tx-sender) ;; Returns (ok u30)
(get-user-age 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns (err "User not found")

This example demonstrates:

Using unwrap! to unpack an optional value from a map.
Implementing a public function to handle the unpacking process.
Handling both successful and error cases.

Common Pitfalls

Using unwrap! with values that are not optional or response types, causing runtime errors.
Assuming the unpacking will always succeed, leading to unhandled error cases.
Not handling all possible conditions, resulting in incomplete error management.
Overlooking the need for proper error handling and validation.

try!: Unpacks optional and response types, returning none or the err value if unpacking fails.
unwrap-panic: Unpacks optional and response types, throwing a runtime error if unpacking fails.
default-to: Provides a default value if an optional is none.

The unwrap! function is a fundamental tool for unpacking optional and response types in Clarity smart contracts. It allows developers to implement logic that requires handling optional and response types, ensuring data integrity and simplifying the unpacking process. When used effectively, unwrap! enhances the reliability and maintainability of your smart contract code by providing a clear and concise way to handle optional and response types.

unwrap!