Functions
The complete reference guide to all Clarity functions.
* (multiply)
Introduced in: Clarity 1
input: int, ... | uint, ...
output: int | uint
signature: (* i1 i2...)
description: Multiplies a variable number of integer inputs and returns the result. In the event of an overflow, throws a runtime error.
example:
(* 2 3) ;; Returns 6
(* 5 2) ;; Returns 10
(* 2 2 2) ;; Returns 8+ (add)
Introduced in: Clarity 1
input: int, ... | uint, ...
output: int | uint
signature: (+ i1 i2...)
description: Adds a variable number of integer inputs and returns the result. In the event of an overflow, throws a runtime error.
example:
(+ 1 2 3) ;; Returns 6- (subtract)
Introduced in: Clarity 1
input: int, ... | uint, ...
output: int | uint
signature: (- i1 i2...)
description: Subtracts a variable number of integer inputs and returns the result. In the event of an underflow, throws a runtime error.
example:
/ (divide)
Introduced in: Clarity 1
input: int, ... | uint, ...
output: int | uint
signature: (/ i1 i2...)
description: Integer divides a variable number of integer inputs and returns the result. In the event of division by zero, throws a runtime error.
example:
< (less than)
Introduced in: Clarity 1
input: int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff
output: bool
signature: (< i1 i2)
description:
Compares two integers (or other comparable types), returning true if i1 is less than i2 and false otherwise. i1 and i2 must be of the same type.
Starting with Stacks 1.0: comparable types are
intanduint.Starting with Stacks 2.1: comparable types also include
string-ascii,string-utf8andbuff.
example:
<= (less than or equal)
Introduced in: Clarity 1
input: int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff
output: bool
signature: (<= i1 i2)
description:
Compares two values, returning true if i1 is less than or equal to i2. Types must match. Same type support notes as <.
example:
> (greater than)
Introduced in: Clarity 1
input: int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff
output: bool
signature: (> i1 i2)
description:
Compares two values, returning true if i1 is greater than i2. Types must match. Same type support notes as <.
example:
>= (greater than or equal)
Introduced in: Clarity 1
input: int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff
output: bool
signature: (>= i1 i2)
description:
Compares two values, returning true if i1 is greater than or equal to i2. Types must match. Same type support notes as <.
example:
and
Introduced in: Clarity 1
input: bool, ...
output: bool
signature: (and b1 b2 ...)
description:
Returns true if all boolean inputs are true. Arguments are evaluated in-order and lazily (short-circuits on false).
example:
append
Introduced in: Clarity 1
input: list A, A
output: list
signature: (append (list 1 2 3 4) 5)
description: Takes a list and a value of the same entry type, and returns a new list with max_len += 1 (effectively appending the value).
example:
as-contract?
Introduced in: Clarity 4
Input:
((with-stx|with-ft|with-nft|with-stacking)*|with-all-assets-unsafe): The set of allowances (at most 128) to grant during the evaluation of the body expressions. Note thatwith-all-assets-unsafeis mutually exclusive with other allowances.AnyType* A: The Clarity expressions to be executed within the context, with the final expression returning typeA, whereAis not aresponse
Output: (response A uint)
Signature: (as-contract? ((with-stx|with-ft|with-nft|with-stacking)*|with-all-assets-unsafe) expr-body1 expr-body2 ... expr-body-last)
Description: Switches the current context's tx-sender and contract-caller values to the contract's principal and executes the body expressions within that context, then checks the asset outflows from the contract against the granted allowances, in declaration order. If any allowance is violated, the body expressions are reverted and an error is returned. Note that the allowance setup expressions are evaluated before executing the body expressions. The final body expression cannot return a response value in order to avoid returning a nested response value from as-contract? (nested responses are error-prone). Returns:
(ok x)if the outflows are within the allowances, wherexis the result of the final body expression and has typeA.(err index)if an allowance was violated, whereindexis the 0-based index of the first violated allowance in the list of granted allowances, oru128if an asset with no allowance caused the violation.
Example:
as-max-len?
Introduced in: Clarity 1
input: sequence_A, uint
output: (optional sequence_A)
signature: (as-max-len? sequence max_length)
description:
If the sequence length ≤ max_length, returns (some sequence), otherwise none. Applies to (list A), buff, string-ascii, string-utf8.
example:
asserts!
Introduced in: Clarity 1
input: bool, C
output: bool
signature: (asserts! bool-expr thrown-value)
description:
If bool-expr is true, returns true and continues. If false, returns thrown-value and exits current control-flow.
example:
at-block
Introduced in: Clarity 1
input: (buff 32), A
output: A
signature: (at-block id-block-hash expr)
description:
Evaluates expr as if evaluated at the end of the block identified by id-block-hash. expr must be read-only. The block hash must be from id-header-hash.
example:
begin
Introduced in: Clarity 1
input: AnyType, ... A
output: A
signature: (begin expr1 expr2 expr3 ... expr-last)
description: Evaluates each expression in order and returns the value of the last expression. Note: intermediary statements returning a response type must be checked.
example:
bit-and
Introduced in: Clarity 2
input: int, ... | uint, ...
output: int | uint
signature: (bit-and i1 i2...)
description: Bitwise AND across a variable number of integer inputs.
example:
bit-not
Introduced in: Clarity 2
input: int | uint
output: int | uint
signature: (bit-not i1)
description:
Returns the one's complement (bitwise NOT) of i1.
example:
bit-or
Introduced in: Clarity 2
input: int, ... | uint, ...
output: int | uint
signature: (bit-or i1 i2...)
description: Bitwise inclusive OR across a variable number of integer inputs.
example:
bit-shift-left
Introduced in: Clarity 2
input: int, uint | uint, uint
output: int | uint
signature: (bit-shift-left i1 shamt)
description:
Shifts bits of i1 left by shamt modulo 128. Does not check for arithmetic overflow — use *, /, pow if overflow detection is needed.
example:
bit-shift-right
Introduced in: Clarity 2
input: int, uint | uint, uint
output: int | uint
signature: (bit-shift-right i1 shamt)
description:
Shifts bits of i1 right by shamt modulo 128. For uint fills with zeros; for int preserves sign bit. Does not check for arithmetic overflow.
example:
bit-xor
Introduced in: Clarity 2
input: int, ... | uint, ...
output: int | uint
signature: (bit-xor i1 i2...)
description: Bitwise exclusive OR across a variable number of integer inputs.
example:
buff-to-int-be
Introduced in: Clarity 2
input: (buff 16)
output: int
signature: (buff-to-int-be (buff 16))
description: Converts a buffer to a signed integer using big-endian encoding. Buffer up to 16 bytes; if fewer, it behaves as if left-zero-padded. Available starting Stacks 2.1.
example:
buff-to-int-le
Introduced in: Clarity 2
input: (buff 16)
output: int
signature: (buff-to-int-le (buff 16))
description: Converts a buffer to a signed integer using little-endian encoding. Up to 16 bytes; fewer bytes behave as right-zero-padded. Available starting Stacks 2.1.
example:
buff-to-uint-be
Introduced in: Clarity 2
input: (buff 16)
output: uint
signature: (buff-to-uint-be (buff 16))
description: Converts a buffer to an unsigned integer using big-endian encoding. Up to 16 bytes; fewer bytes behave as left-zero-padded. Available starting Stacks 2.1.
example:
buff-to-uint-le
Introduced in: Clarity 2
input: (buff 16)
output: uint
signature: (buff-to-uint-le (buff 16))
description: Converts a buffer to an unsigned integer using little-endian encoding. Up to 16 bytes; fewer bytes behave as right-zero-padded. Available starting Stacks 2.1.
example:
concat
Introduced in: Clarity 1
input: sequence_A, sequence_A
output: sequence_A
signature: (concat sequence1 sequence2)
description:
Concatenates two sequences of the same type. Applicable to (list A), buff, string-ascii, string-utf8.
example:
contract-call?
Introduced in: Clarity 1
input: ContractName, PublicFunctionName, Arg0, ...
output: (response A B)
signature: (contract-call? .contract-name function-name arg0 arg1 ...)
description:
Executes a public function on another contract (not the current contract). If that function returns err, any DB changes resulting from the call are aborted; if ok, DB changes occurred.
example:
contract-hash?
Introduced in: Clarity 4
Input: principal
Output: (response (buff 32) uint)
Signature: (contract-hash? contract-principal)
Description: Returns the SHA-512/256 hash of the code body of the contract principal specified as input, or an error if the principal is not a contract or the specified contract does not exist. Returns:
(ok 0x<hash>), where<hash>is the SHA-512/256 hash of the code body, on success(err u1)if the principal is not a contract principal(err u2)if the specified contract does not exist
Example:
contract-of
Introduced in: Clarity 1
input: Trait
output: principal
signature: (contract-of .contract-name)
description: Returns the principal of the contract implementing the trait.
example:
default-to
Introduced in: Clarity 1
input: A, (optional A)
output: A
signature: (default-to default-value option-value)
description:
If the second argument is (some v), returns v. If it is none, returns default-value.
example:
define-constant
Introduced in: Clarity 1
input: MethodSignature, MethodBody
output: Not Applicable
signature: (define-constant name expression)
description: Defines a private constant evaluated at contract launch. Must be top-level. Be mindful of definition order.
example:
define-data-var
Introduced in: Clarity 1
input: VarName, TypeDefinition, Value
output: Not Applicable
signature: (define-data-var var-name type value)
description: Defines a new persisted variable for the contract. Only modifiable by the contract. Must be top-level.
example:
define-fungible-token
Introduced in: Clarity 1
input: TokenName, <uint>
output: Not Applicable
signature: (define-fungible-token token-name <total-supply>)
description: Defines a fungible token class in the contract. Optional total supply caps minting. Must be top-level.
example:
define-map
Introduced in: Clarity 1
input: MapName, TypeDefinition, TypeDefinition
output: Not Applicable
signature: (define-map map-name key-type value-type)
description: Defines a data map stored by the contract. Must be top-level.
example:
define-non-fungible-token
Introduced in: Clarity 1
input: AssetName, TypeSignature
output: Not Applicable
signature: (define-non-fungible-token asset-name asset-identifier-type)
description: Defines an NFT class in the contract. Asset identifiers must be unique. Must be top-level.
example:
define-private
Introduced in: Clarity 1
input: MethodSignature, MethodBody
output: Not Applicable
signature: (define-private (function-name (arg-name-0 arg-type-0) ...) function-body)
description: Defines a private function callable only within the contract. Must be top-level.
example:
define-public
Introduced in: Clarity 1
input: MethodSignature, MethodBody
output: Not Applicable
signature: (define-public (function-name (arg-name-0 arg-type-0) ...) function-body)
description:
Defines a public transaction function. Must return a ResponseType (ok or err). DB changes are aborted if err. Must be top-level.
example:
define-read-only
Introduced in: Clarity 1
input: MethodSignature, MethodBody
output: Not Applicable
signature: (define-read-only (function-name (arg-name-0 arg-type-0) ...) function-body)
description: Defines a public read-only function. Cannot modify data maps or call mutating functions. May return any type. Must be top-level.
example:
define-trait
Introduced in: Clarity 1
input: VarName, [MethodSignature]
output: Not Applicable
signature: (define-trait trait-name ((func1-name (arg1-type ...) (return-type))))
description: Defines a trait (interface) other contracts can implement. Must be top-level. Notes about Clarity 1 vs Clarity 2 trait usage and implicit casting in Clarity 2 are included.
example:
element-at
Introduced in: Clarity 1
input: sequence_A, uint
output: (optional A)
signature: (element-at? sequence index)
description:
Returns the element at index in the sequence as an optional. Applicable types: (list A), buff, string-ascii, string-utf8. In Clarity 1 spelled element-at (alias).
example:
element-at?
Introduced in: Clarity 2
(Same as element-at; retained as Clarity 2 preferred spelling)
example: (see element-at above)
err
Introduced in: Clarity 1
input: A
output: (response A B)
signature: (err value)
description:
Constructs an err response. Use for returning errors from public functions; indicates DB changes should be rolled back.
example:
filter
Introduced in: Clarity 1
input: Function(A) -> bool, sequence_A
output: sequence_A
signature: (filter func sequence)
description:
Filters elements of a sequence by applying func to each element and keeping those where func returns true. func must be a literal function name. Applies to (list A), buff, string-ascii, string-utf8.
example:
fold
Introduced in: Clarity 1
input: Function(A, B) -> B, sequence_A, B
output: B
signature: (fold func sequence_A initial_B)
description:
Reduces a sequence to a single value by applying func cumulatively, starting with initial_B.
example:
(Examples showing string/buffer concatenation omitted here; see original for fuller set.)
from-consensus-buff?
Introduced in: Clarity 2
input: type-signature(t), buff
output: (optional t)
signature: (from-consensus-buff? type-signature buffer)
description:
Deserializes a buffer into a Clarity value using SIP-005 consensus serialization. Returns some on success, none on failure.
example:
ft-burn?
Introduced in: Clarity 1
input: TokenName, uint, principal
output: (response bool uint)
signature: (ft-burn? token-name amount sender)
description:
Burns (destroys) amount of token-name from sender's balance. On success returns (ok true). Error (err u1) - insufficient balance or non-positive amount.
example:
ft-get-balance
Introduced in: Clarity 1
input: TokenName, principal
output: uint
signature: (ft-get-balance token-name principal)
description:
Returns the token-name balance for principal. Token must be defined with define-fungible-token.
example:
ft-get-supply
Introduced in: Clarity 1
input: TokenName
output: uint
signature: (ft-get-supply token-name)
description:
Returns circulating supply for the token-name. Token must be defined with define-fungible-token.
example:
ft-mint?
Introduced in: Clarity 1
input: TokenName, uint, principal
output: (response bool uint)
signature: (ft-mint? token-name amount recipient)
description:
Mints amount of token-name to recipient. Non-positive amount returns (err 1). On success returns (ok true).
example:
ft-transfer?
Introduced in: Clarity 1
input: TokenName, uint, principal, principal
output: (response bool uint)
signature: (ft-transfer? token-name amount sender recipient)
description:
Transfers amount of token-name from sender to recipient (token must be defined in contract). Anyone can call; proper guards are expected. Returns (ok true) on success. Error codes: (err u1) insufficient balance, (err u2) sender==recipient, (err u3) non-positive amount.
example:
get
Introduced in: Clarity 1
input: KeyName, (tuple) | (optional (tuple))
output: A
signature: (get key-name tuple)
description:
Fetches value associated with key-name from a tuple. If an optional tuple is supplied and is none, returns none.
example:
get-block-info?
Introduced in: Clarity 1
input: BlockInfoPropertyName, uint
output: (optional buff) | (optional uint)
signature: (get-block-info? prop-name block-height)
description:
Fetches data for a Stacks block at given block height. If the height doesn't exist prior to current block, returns none. Property names and returned types described; newer Clarity versions split this into get-stacks-block-info? and get-tenure-info?. See original for full list of properties and notes.
example:
get-burn-block-info?
Introduced in: Clarity 2
input: BurnBlockInfoPropertyName, uint
output: (optional buff) | (optional (tuple ...))
signature: (get-burn-block-info? prop-name block-height)
description:
Fetches burnchain block data for the given burnchain height. Valid properties include header-hash and pox-addrs. See original for full tuple shape of pox-addrs.
example:
get-stacks-block-info?
Introduced in: Clarity 3
input: StacksBlockInfoPropertyName, uint
output: (optional buff), (optional uint)
signature: (get-stacks-block-info? prop-name stacks-block-height)
description:
Replacement for get-block-info? in Clarity 3; fetches Stacks block data for a given height. See original for property list and behavior differences before/after epoch 3.0.
example:
get-tenure-info?
Introduced in: Clarity 3
input: TenureInfoPropertyName, uint
output: (optional buff) | (optional uint)
signature: (get-tenure-info? prop-name stacks-block-height)
description:
Fetches tenure-related info at the given block height (burnchain header for tenure, miner address, time, vrf-seed, block reward, miner spend totals). Returns none if height is not prior to current block. See original for full notes.
example:
hash160
Introduced in: Clarity 1
input: buff|uint|int
output: (buff 20)
signature: (hash160 value)
description: Computes RIPEMD160(SHA256(x)). If input is an integer, it is hashed over its little-endian representation.
example:
if
Introduced in: Clarity 1
input: bool, A, A
output: A
signature: (if bool1 expr1 expr2)
description:
Conditional expression: evaluates and returns expr1 if bool1 is true, otherwise expr2. Both exprs must return the same type.
example:
impl-trait
Introduced in: Clarity 1
input: TraitIdentifier
output: Not Applicable
signature: (impl-trait trait-identifier)
description: Asserts that the contract implements the given trait. Checked at publish time. Must be top-level.
example:
index-of
Introduced in: Clarity 1
input: sequence_A, A
output: (optional uint)
signature: (index-of? sequence item)
description:
Returns first index of item in sequence using is-eq. Returns none if not found or if empty string/buffer. Clarity 1 spelling: index-of (alias).
example:
index-of?
Introduced in: Clarity 2
(Same as index-of; retained for Clarity 2)
int-to-ascii
Introduced in: Clarity 2
input: int | uint
output: (string-ascii 40)
signature: (int-to-ascii (int|uint))
description: Converts an integer to its ASCII string representation. Available starting Stacks 2.1.
example:
int-to-utf8
Introduced in: Clarity 2
input: int | uint
output: (string-utf8 40)
signature: (int-to-utf8 (int|uint))
description: Converts an integer to its UTF-8 string representation. Available starting Stacks 2.1.
example:
is-eq
Introduced in: Clarity 1
input: A, A, ...
output: bool
signature: (is-eq v1 v2...)
description:
Returns true if all inputs are equal. Unlike and, does not short-circuit. All arguments must be the same type.
example:
is-err / is-ok / is-none / is-some
Introduced in: Clarity 1
(is-err value)returnstrueifvalueis(err ...).(is-ok value)returnstrueifvalueis(ok ...).(is-none value)returnstrueifvalueisnone.(is-some value)returnstrueifvalueis(some ...).
examples:
is-standard
Introduced in: Clarity 2
input: principal
output: bool
signature: (is-standard standard-or-contract-principal)
description: Tests whether a principal matches the current network type (mainnet vs testnet) and therefore can spend tokens on that network. Available starting Stacks 2.1.
example:
keccak256
Introduced in: Clarity 1
input: buff|uint|int
output: (buff 32)
signature: (keccak256 value)
description: Computes KECCAK256(value). If input is an integer, it is hashed over its little-endian representation.
example:
len
Introduced in: Clarity 1
input: sequence_A
output: uint
signature: (len sequence)
description:
Returns length of a sequence. Applies to (list A), buff, string-ascii, string-utf8.
example:
let
Introduced in: Clarity 1
input: ((name1 AnyType) ...), AnyType, ... A
output: A
signature: (let ((name1 expr1) ...) expr-body1 ... expr-body-last)
description: Binds sequential variables then evaluates the body expressions in that context. Returns last body expression's value.
example:
list
Introduced in: Clarity 1
input: A, ...
output: (list A)
signature: (list expr1 expr2 expr3 ...)
description: Constructs a list from supplied values (must be same type).
example:
log2
Introduced in: Clarity 1
input: int | uint
output: int | uint
signature: (log2 n)
description: Returns floor(log2(n)). Fails on negative numbers.
example:
map
Introduced in: Clarity 1
input: Function(A, B, ..., N) -> X, sequence_A, sequence_B, ...
output: (list X)
signature: (map func sequence_A sequence_B ...)
description:
Applies func to each corresponding element of input sequences and returns a list of results. func must be a literal function name. Output is always a list.
example:
map-delete / map-get? / map-insert / map-set
Introduced in: Clarity 1
Operations for manipulating contract data maps:
(map-delete map-name key-tuple)— removes entry; returnstrueif removed,falseif none existed.(map-get? map-name key-tuple)— returns(some value)ornone.(map-insert map-name key-tuple value-tuple)— inserts only if key absent; returnstrueif inserted,falseif existed.(map-set map-name key-tuple value-tuple)— blind overwrite; returnstrue.
Examples exist in the original content (omitted here for brevity).
match
Introduced in: Clarity 1
input: (optional A) name expression expression | (response A B) name expression name expression
output: C
signature: (match opt-input some-binding-name some-branch none-branch) | (match-resp input ok-binding-name ok-branch err-binding-name err-branch)
description:
Destructures optional and response types and evaluates only the matching branch. See original for type-checking caveats.
example:
merge
Introduced in: Clarity 1
input: tuple, tuple
output: tuple
signature: (merge tuple { key1: val1 })
description: Returns a new tuple combining fields (non-mutating).
example:
mod
Introduced in: Clarity 1
input: int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff
output: int | uint
signature: (mod i1 i2)
description: Returns remainder of integer division; division by zero throws runtime error.
example:
nft-burn? / nft-get-owner? / nft-mint? / nft-transfer?
Introduced in: Clarity 1
NFT operations for assets defined with define-non-fungible-token:
(nft-mint? asset-class asset-identifier recipient)— mint; returns(ok true)or(err u1)if exists.(nft-get-owner? asset-class asset-identifier)— returns(some owner)ornone.(nft-transfer? asset-class asset-identifier sender recipient)— transfer; returns(ok true)or errors.(nft-burn? asset-class asset-identifier sender)— burn; returns(ok true)or errors.
Examples present in original content.
not
Introduced in: Clarity 1
input: bool
output: bool
signature: (not b1)
description: Boolean negation.
example:
ok
Introduced in: Clarity 1
input: A
output: (response A B)
signature: (ok value)
description:
Constructs an ok response. Use for successful public function returns.
example:
or
Introduced in: Clarity 1
input: bool, ...
output: bool
signature: (or b1 b2 ...)
description:
Returns true if any input is true. Evaluated in-order and lazily (short-circuits on true).
example:
pow
Introduced in: Clarity 1
input: int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff
output: int | uint
signature: (pow i1 i2)
description: Returns i1^i2. Throws runtime error on overflow. Special-case rules for 0^0, i1==1, etc. Throws runtime error if exponent negative or > u32::MAX.
example:
principal-construct?
Introduced in: Clarity 2
input: (buff 1), (buff 20), [(string-ascii 40)]
output: (response principal { error_code: uint, principal: (option principal) })
signature: (principal-construct? (buff 1) (buff 20) [(string-ascii 40)])
description:
Constructs a standard or contract principal from version byte and hash bytes, optionally with contract name. Returns ok with principal or err tuple with error code and optional principal. Available starting Stacks 2.1.
example: (see original for many examples)
principal-destruct?
Introduced in: Clarity 2
input: principal
output: (response (tuple ...) (tuple ...))
signature: (principal-destruct? principal-address)
description:
Decomposes a principal into {version, hash-bytes, name} tuple. Returns ok if version matches network, otherwise err. Available starting Stacks 2.1.
example: (see original)
principal-of?
Introduced in: Clarity 1
input: (buff 33)
output: (response principal uint)
signature: (principal-of? public-key)
description:
Derives the principal from a compressed public key. Returns (err u1) if invalid. Note: pre-2.1 bug returned testnet principals irrespective of network; fixed in 2.1.
example:
print
Introduced in: Clarity 1
input: A
output: A
signature: (print expr)
description: Evaluates and returns its argument. On dev nodes prints to STDOUT.
example:
replace-at?
Introduced in: Clarity 2
input: sequence_A, uint, A
output: (optional sequence_A)
signature: (replace-at? sequence index element)
description:
Returns a new sequence with element at index replaced. Returns none if index out of bounds.
example:
restrict-assets?
Introduced in: Clarity 4
Input:
asset-owner:principal: The principal whose assets are being protected.((with-stx|with-ft|with-nft|with-stacking)*): The set of allowances (at most 128) to grant during the evaluation of the body expressions .AnyType* A: The Clarity expressions to be executed within the context, with the final expression returning typeA, whereAis not aresponse
Output: (response A uint)
Signature: (restrict-assets? asset-owner ((with-stx|with-ft|with-nft|with-stacking)*) expr-body1 expr-body2 ... expr-body-last)
Description: Executes the body expressions, then checks the asset outflows against the granted allowances, in declaration order. If any allowance is violated, the body expressions are reverted and an error is returned. Note that the asset-owner and allowance setup expressions are evaluated before executing the body expressions. The final body expression cannot return a response value in order to avoid returning a nested response value from restrict-assets? (nested responses are error-prone). Returns:
(ok x)if the outflows are within the allowances, wherexis the result of the final body expression and has typeA.(err index)if an allowance was violated, whereindexis the 0-based index of the first violated allowance in the list of granted allowances, oru128if an asset with no allowance caused the violation.
Example:
secp256k1-recover?
Introduced in: Clarity 1
input: (buff 32), (buff 65)
output: (response (buff 33) uint)
signature: (secp256k1-recover? message-hash signature)
description:
Recovers the public key from a signature over message-hash. Returns (err u1) if signature doesn't match, (err u2) if signature invalid.
example: (see original)
secp256k1-verify
Introduced in: Clarity 1
input: (buff 32), (buff 64) | (buff 65), (buff 33)
output: bool
signature: (secp256k1-verify message-hash signature public-key)
description:
Verifies that signature of message-hash was produced by public-key. Signature is 64 or 65 bytes.
example: (see original)
secp256r1-verify
Input: (buff 32), (buff 64), (buff 33)
Output: bool
Signature: (secp256r1-verify message-hash signature public-key)
Description: The secp256r1-verify function verifies that the provided signature of the message-hash was produced by the private key corresponding to public-key. The message-hash is the SHA-256 hash of the message. The signature must be 64 bytes (compact signature). Returns true if the signature is valid for the given public-key and message hash, otherwise returns false.
Example:
sha256 / sha512 / sha512/256
Introduced in: Clarity 1
Hash functions:
(sha256 value)→(buff 32)(sha512 value)→(buff 64)(sha512/256 value)→(buff 32)
If integer supplied, hashed over little-endian representation.
examples:
slice?
Introduced in: Clarity 2
input: sequence_A, uint, uint
output: (optional sequence_A)
signature: (slice? sequence left-position right-position)
description:
Returns subsequence [left, right). If left==right returns empty sequence. Returns none if out of bounds or right < left.
example:
some
Introduced in: Clarity 1
input: A
output: (optional A)
signature: (some value)
description:
Constructs (some value).
example:
sqrti
Introduced in: Clarity 1
input: int | uint
output: int | uint
signature: (sqrti n)
description: Returns floor(sqrt(n)). Fails on negative numbers.
example:
string-to-int? / string-to-uint?
Introduced in: Clarity 2
input: (string-ascii 1048576) | (string-utf8 262144)
output: (optional int) / (optional uint)
signature: (string-to-int? str) / (string-to-uint? str)
description:
Parse string to int/uint. Returns (some value) on success, none on failure. Available starting Stacks 2.1.
example:
stx-account
Introduced in: Clarity 2
input: principal
output: (tuple (locked uint) (unlock-height uint) (unlocked uint))
signature: (stx-account owner)
description:
Query the STX account for owner. Returns locked, unlock-height, and unlocked amounts (microstacks). Available starting Clarity 2.
example:
stx-burn?
Introduced in: Clarity 1
input: uint, principal
output: (response bool uint)
signature: (stx-burn? amount sender)
description:
Destroys amount of STX from sender (microstacks). sender must be current tx-sender. Returns (ok true) on success. Error codes: (err u1) insufficient balance, (err u3) non-positive amount, (err u4) sender not tx-sender.
example:
stx-get-balance
Introduced in: Clarity 1
input: principal
output: uint
signature: (stx-get-balance owner)
description:
Returns STX balance (microstacks) of owner. If owner not materialized returns 0.
example:
stx-transfer-memo?
Introduced in: Clarity 2
input: uint, principal, principal, buff
output: (response bool uint)
signature: (stx-transfer-memo? amount sender recipient memo)
description:
Same as stx-transfer? but includes a memo buffer. Returns same error codes as stx-transfer?.
example:
stx-transfer?
Introduced in: Clarity 1
input: uint, principal, principal
output: (response bool uint)
signature: (stx-transfer? amount sender recipient)
description:
Transfers STX (microstacks) from sender to recipient. sender must be current tx-sender. Returns (ok true) or errors: (err u1) insufficient funds, (err u2) same principal, (err u3) non-positive amount, (err u4) sender not tx-sender.
example:
to-ascii?
Introduced in: Clarity 4
Input: int | uint | bool | principal | (buff 524284) | (string-utf8 262144)
Output: (response (string-ascii 1048571) uint)
Signature: (to-ascii? value)
Description: Returns the string-ascii representation of the input value in an ok response on success. The only error condition is if the input type is string-utf8 and the value contains non-ASCII characters, in which case, (err u1) is returned. Note that the limitation on the maximum sizes of buff and string-utf8 inputs is due to the Clarity value size limit of 1MB. The (string-utf8 262144) is the maximum allowed size of a string-utf8 value, and the (buff 524284) limit is chosen because the ASCII representation of a buff is 0x followed by two ASCII characters per byte in the buff. This means that the ASCII representation of a (buff 524284) is 2 + 2 * 524284 = 1048570 characters at 1 byte each, and the remainder is required for the response value wrapping the string-ascii.
Example:
to-consensus-buff?
Introduced in: Clarity 2
input: any
output: (optional buff)
signature: (to-consensus-buff? value)
description:
Serializes a Clarity value using SIP-005 consensus serialization. If serialized size fits into a buffer, returns (some buff), else none. During type checking the maximal possible buffer length is inferred. Available starting Clarity 2.
example:
to-int
Introduced in: Clarity 1
input: uint
output: int
signature: (to-int u)
description:
Converts uint to int. Runtime error if argument >= 2^127.
example:
to-uint
Introduced in: Clarity 1
input: int
output: uint
signature: (to-uint i)
description:
Converts int to uint. Runtime error if argument is negative.
example:
try!
Introduced in: Clarity 1
input: (optional A) | (response A B)
output: A
signature: (try! option-input)
description:
Unpacks (some v) or (ok v) returning v. If input is none or (err ...), try! returns the current function's none or (err ...) and exits control-flow.
example: (see original for longer usage)
tuple
Introduced in: Clarity 1
input: (key-name A), ...
output: (tuple (key-name A) ...)
signature: (tuple (key0 expr0) (key1 expr1) ...)
description:
Constructs a typed tuple. Shorthand using curly braces { key: val, ... } is available.
example:
unwrap! / unwrap-err! / unwrap-err-panic / unwrap-panic
Introduced in: Clarity 1
Utilities for unpacking optionals and responses with different failure behaviors:
(unwrap! option-or-response thrown-value)— returns inner value or returnsthrown-valuefrom current function.(unwrap-err! response-input thrown-value)— returns err value or returnsthrown-valueif ok.(unwrap-err-panic response-input)— returns err inner value or throws runtime error if ok.(unwrap-panic option-or-response)— returns inner value or throws runtime error if none/err.
example: (see original for usage)
use-trait
Introduced in: Clarity 1
input: VarName, TraitIdentifier
output: Not Applicable
signature: (use-trait trait-alias trait-identifier)
description: Imports an external trait under an alias for use in the contract (must be top-level).
example:
var-get / var-set
Introduced in: Clarity 1
(var-get var-name)— returns the value of a data var.(var-set var-name expr)— sets the data var; returnstrue.
example:
with-all-assets-unsafe
Introduced in: Clarity 4
Input: None
Output: Not applicable
Signature: (with-all-assets-unsafe)
Description: Grants unrestricted access to all assets of the contract to the enclosing as-contract? expression. Note that this is not allowed in restrict-assets? and will trigger an analysis error, since usage there does not make sense (i.e. just remove the restrict-assets? instead). Security Warning: This should be used with extreme caution, as it effectively disables all asset protection for the contract. This dangerous allowance should only be used when the code executing within the as-contract? body is verified to be trusted through other means (e.g. checking traits against an allow list, passed in from a trusted caller), and even then the more restrictive allowances should be preferred when possible.
Example:
with-ft
Input:
contract-id:principal: The contract defining the FT asset.token-name:(string-ascii 128): The name of the FT or"*"for any FT defined incontract-id.amount:uint: The amount of FT to grant access to.
Output: Not applicable
Signature: (with-ft contract-id token-name amount)
Description: Adds an outflow allowance for amount of the fungible token defined in contract-id with name token-name from the asset-owner of the enclosing restrict-assets? or as-contract? expression. Note that token-name should match the name used in the define-fungible-token call in the contract. When "*" is used for the token name, the allowance applies to all FTs defined in contract-id.
Example:
with-nft
Input:
contract-id:principal: The contract defining the NFT asset.token-name:(string-ascii 128): The name of the NFT or"*"for any NFT defined incontract-id.identifiers:(list 128 T): The identifiers of the token to grant access to.
Output: Not applicable
Signature: (with-nft contract-id token-name identifiers)
Description: Adds an outflow allowance for the non-fungible token(s) identified by identifiers defined in contract-id with name token-name from the asset-owner of the enclosing restrict-assets? or as-contract? expression. Note that token-name should match the name used in the define-non-fungible-token call in the contract. When "*" is used for the token name, the allowance applies to all NFTs defined in contract-id.
Example:
with-stacking
Input:
amount:uint: The amount of uSTX that can be locked.
Output: Not applicable
Signature: (with-stacking amount)
Description: Adds a stacking allowance for amount uSTX from the asset-owner of the enclosing restrict-assets? or as-contract? expression. This restricts calls to the active PoX contract that either delegate funds for stacking or stack directly, ensuring that the locked amount is limited by the amount of uSTX specified.
Example:
with-stx
Input:
amount:uint: The amount of uSTX to grant access to.
Output: Not applicable
Signature: (with-stx amount)
Description: Adds an outflow allowance for amount uSTX from the asset-owner of the enclosing restrict-assets? or as-contract? expression.
Example:
xor
Introduced in: Clarity 1
input: int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff
output: int | uint
signature: (xor i1 i2)
description:
Bitwise exclusive OR of i1 and i2.
example:
Last updated
Was this helpful?