Hiro Docs

Unpacking optional and response types and throwing runtime errors in Clarity smart contracts.

Function Signature

(unwrap-panic option-input)

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

Why it matters

The unwrap-panic 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 by throwing runtime errors when necessary.

When to use it

Use unwrap-panic 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 and throw runtime errors when necessary.

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 and Throwing a Runtime Error

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

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

(define-public (get-user-age (user principal))
  (let ((user-data (unwrap-panic (map-get? user-info { user-id: user }))))
    (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) ;; Throws a runtime exception

Common Pitfalls

Using unwrap-panic 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.

unwrap!: Unpacks optional and response types, returning a thrown value if unpacking fails.
unwrap-err!: Unpacks error responses, returning a thrown value if the response is ok.
try!: Unpacks optional and response types, returning none or the err value if unpacking fails.

The unwrap-panic function is a fundamental tool for unpacking optional and response types and throwing runtime errors 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-panic enhances the reliability and maintainability of your smart contract code by providing a clear and concise way to handle optional and response types and throw runtime errors when necessary.

unwrap-panic