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:
(- 2 1 1) ;; Returns 0
(- 0 3) ;; Returns -3

/ (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:
(/ 2 3) ;; Returns 0
(/ 5 2) ;; Returns 2
(/ 4 2 2) ;; Returns 1

< (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, 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, the <-comparable types are int and uint. Starting with Stacks 2.1, the <-comparable types are expanded to include string-ascii, string-utf8 and buff.
example:
(< 1 2) ;; Returns true
(< 5 2) ;; Returns false
(< "aaa" "baa") ;; Returns true
(< "aa" "aaa") ;; Returns true
(< 0x01 0x02) ;; Returns true
(< 5 u2) ;; Throws type error

<= (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 integers, returning true if i1 is less than or equal to i2 and false otherwise. i1 and i2 must be of the same type. Starting with Stacks 1.0, the <=-comparable types are int and uint. Starting with Stacks 2.1, the <=-comparable types are expanded to include string-ascii, string-utf8 and buff.
example:
(<= 1 1) ;; Returns true
(<= 5 2) ;; Returns false
(<= "aaa" "baa") ;; Returns true
(<= "aa" "aaa") ;; Returns true
(<= 0x01 0x02) ;; Returns true
(<= 5 u2) ;; Throws type error

> (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 integers, returning true if i1 is greater than i2 and false otherwise. i1 and i2 must be of the same type. Starting with Stacks 1.0, the >-comparable types are int and uint. Starting with Stacks 2.1, the >-comparable types are expanded to include string-ascii, string-utf8 and buff.
example:
(> 1 2) ;; Returns false
(> 5 2) ;; Returns true
(> "baa" "aaa") ;; Returns true
(> "aaa" "aa") ;; Returns true
(> 0x02 0x01) ;; Returns true
(> 5 u2) ;; Throws type error

>= (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 integers, returning true if i1 is greater than or equal to i2 and false otherwise. i1 and i2 must be of the same type. Starting with Stacks 1.0, the >=-comparable types are int and uint. Starting with Stacks 2.1, the >=-comparable types are expanded to include string-ascii, string-utf8 and buff.
example:
(>= 1 1) ;; Returns true
(>= 5 2) ;; Returns true
(>= "baa" "aaa") ;; Returns true
(>= "aaa" "aa") ;; Returns true
(>= 0x02 0x01) ;; Returns true
(>= 5 u2) ;; Throws type error

and​

Introduced in: Clarity 1
input: bool, ...
output: bool
signature: (and b1 b2 ...)
description:
Returns true if all boolean inputs are true. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns false, the function short-circuits, and no subsequent arguments are evaluated.
example:
(and true false) ;; Returns false
(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false
(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true

append​

Introduced in: Clarity 1
input: list A, A
output: list
signature: (append (list 1 2 3 4) 5)
description:
The append function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1.
example:
(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5)

as-contract​

Introduced in: Clarity 1
input: A
output: A
signature: (as-contract expr)
description:
The as-contract function switches the current context's tx-sender value to the contract's principal and executes expr with that context. It returns the resulting value of expr.
example:
(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test

as-max-len?​

Introduced in: Clarity 1
input: sequence_A, uint
output: (optional sequence_A)
signature: (as-max-len? sequence max_length)
description:
The as-max-len? function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns (some sequence), otherwise it returns none. Applicable sequence types are (list A), buff, string-ascii and string-utf8.
example:
(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2))
(as-max-len? (list 1 2 3) u2) ;; Returns none
(as-max-len? "hello" u10) ;; Returns (some "hello")
(as-max-len? 0x010203 u10) ;; Returns (some 0x010203)

asserts

Introduced in: Clarity 1
input: bool, C
output: bool
signature: (asserts! bool-expr thrown-value)
description:
The asserts! function admits a boolean argument and asserts its evaluation: if bool-expr is true, asserts! returns true and proceeds in the program execution. If the supplied argument is returning a false value, asserts! returns thrown-value and exits the current control-flow.
example:
(asserts! (is-eq 1 1) (err 1)) ;; Returns true

at-block​

Introduced in: Clarity 1
input: (buff 32), A
output: A
signature: (at-block id-block-hash expr)
description:
The at-block function evaluates the expression expr as if it were evaluated at the end of the block indicated by the block-hash argument. The expr closure must be read-only.
Note: The block identifying hash must be a hash returned by the id-header-hash block information property. This hash uniquely identifies Stacks blocks and is unique across Stacks forks. While the hash returned by header-hash is unique within the context of a single fork, it is not unique across Stacks forks.
The function returns the result of evaluating expr.
example:
(define-data-var data int 1)
(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0
(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0

begin​

Introduced in: Clarity 1
input: AnyType, ... A
output: A
signature: (begin expr1 expr2 expr3 ... expr-last)
description:
The begin function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked.
example:
(begin (+ 1 2) 4 5) ;; Returns 5

bit-and​

Introduced in: Clarity 2
input: int, ... | uint, ...
output: int | uint
signature: (bit-and i1 i2...)
description:
Returns the result of bitwise and'ing a variable number of integer inputs.
example:
(bit-and 24 16) ;; Returns 16
(bit-and 28 24 -1) ;; Returns 24
(bit-and u24 u16) ;; Returns u16
(bit-and -128 -64) ;; Returns -128
(bit-and 28 24 -1) ;; Returns 24

bit-not​

Introduced in: Clarity 2
input: int | uint
output: int | uint
signature: (bit-not i1)
description:
Returns the one's compliement (sometimes also called the bitwise compliment or not operator) of i1, effectively reversing the bits in i1. In other words, every bit that is 1 in ì1will be0in the result. Conversely, every bit that is0ini1will be1` in the result.
example:
(bit-not 3) ;; Returns -4
(bit-not u128) ;; Returns u340282366920938463463374607431768211327
(bit-not 128) ;; Returns -129
(bit-not -128) ;; Returns 127

bit-or​

Introduced in: Clarity 2
input: int, ... | uint, ...
output: int | uint
signature: (bit-or i1 i2...)
description:
Returns the result of bitwise inclusive or'ing a variable number of integer inputs.
example:
(bit-or 4 8) ;; Returns 12
(bit-or 1 2 4) ;; Returns 7
(bit-or 64 -32 -16) ;; Returns -16
(bit-or u2 u4 u32) ;; Returns u38

bit-shift-left​

Introduced in: Clarity 2
input: int, uint | uint, uint
output: int | uint
signature: (bit-shift-left i1 shamt)
description:
Shifts all the bits in i1 to the left by the number of places specified in shamt modulo 128 (the bit width of Clarity integers).
Note that there is a deliberate choice made to ignore arithmetic overflow for this operation. In use cases where overflow should be detected, developers should use *, /, and pow instead of the shift operators.
example:
(bit-shift-left 2 u1) ;; Returns 4
(bit-shift-left 16 u2) ;; Returns 64
(bit-shift-left -64 u1) ;; Returns -128
(bit-shift-left u4 u2) ;; Returns u16
(bit-shift-left 123 u9999999999) ;; Returns -170141183460469231731687303715884105728
(bit-shift-left u123 u9999999999) ;; Returns u170141183460469231731687303715884105728
(bit-shift-left -1 u7) ;; Returns -128
(bit-shift-left -1 u128) ;; Returns -1

bit-shift-right​

Introduced in: Clarity 2
input: int, uint | uint, uint
output: int | uint
signature: (bit-shift-right i1 shamt)
description:
Shifts all the bits in i1 to the right by the number of places specified in shamt modulo 128 (the bit width of Clarity integers). When i1 is a uint (unsigned), new bits are filled with zeros. When i1 is an int (signed), the sign is preserved, meaning that new bits are filled with the value of the previous sign-bit.
Note that there is a deliberate choice made to ignore arithmetic overflow for this operation. In use cases where overflow should be detected, developers should use *, /, and pow instead of the shift operators.
example:
(bit-shift-right 2 u1) ;; Returns 1
(bit-shift-right 128 u2) ;; Returns 32
(bit-shift-right -64 u1) ;; Returns -32
(bit-shift-right u128 u2) ;; Returns u32
(bit-shift-right 123 u9999999999) ;; Returns 0
(bit-shift-right u123 u9999999999) ;; Returns u0
(bit-shift-right -128 u7) ;; Returns -1
(bit-shift-right -256 u1) ;; Returns -128
(bit-shift-right 5 u2) ;; Returns 1
(bit-shift-right -5 u2) ;; Returns -2

bit-xor​

Introduced in: Clarity 2
input: int, ... | uint, ...
output: int | uint
signature: (bit-xor i1 i2...)
description:
Returns the result of bitwise exclusive or'ing a variable number of integer inputs.
example:
(bit-xor 1 2) ;; Returns 3
(bit-xor 120 280) ;; Returns 352
(bit-xor -128 64) ;; Returns -64
(bit-xor u24 u4) ;; Returns u28
(bit-xor 1 2 4 -1) ;; Returns -8

buff-to-int-be​

Introduced in: Clarity 2
input: (buff 16)
output: int
signature: (buff-to-int-be (buff 16))
description:
Converts a byte buffer to a signed integer use a big-endian encoding. The byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as this function uses a big-endian encoding, the input behaves as if it is zero-padded on the left.
Note: This function is only available starting with Stacks 2.1.
example:
(buff-to-int-be 0x01) ;; Returns 1
(buff-to-int-be 0x00000000000000000000000000000001) ;; Returns 1
(buff-to-int-be 0xffffffffffffffffffffffffffffffff) ;; Returns -1
(buff-to-int-be 0x) ;; Returns 0

buff-to-int-le​

Introduced in: Clarity 2
input: (buff 16)
output: int
signature: (buff-to-int-le (buff 16))
description:
Converts a byte buffer to a signed integer use a little-endian encoding. The byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as this function uses a little-endian encoding, the input behaves as if it is zero-padded on the right.
Note: This function is only available starting with Stacks 2.1.
example:
(buff-to-int-le 0x01) ;; Returns 1
(buff-to-int-le 0x01000000000000000000000000000000) ;; Returns 1
(buff-to-int-le 0xffffffffffffffffffffffffffffffff) ;; Returns -1
(buff-to-int-le 0x) ;; Returns 0

buff-to-uint-be​

Introduced in: Clarity 2
input: (buff 16)
output: uint
signature: (buff-to-uint-be (buff 16))
description:
Converts a byte buffer to an unsigned integer use a big-endian encoding. The byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as this function uses a big-endian encoding, the input behaves as if it is zero-padded on the left.
Note: This function is only available starting with Stacks 2.1.
example:
(buff-to-uint-be 0x01) ;; Returns u1
(buff-to-uint-be 0x00000000000000000000000000000001) ;; Returns u1
(buff-to-uint-be 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455
(buff-to-uint-be 0x) ;; Returns u0

buff-to-uint-le​

Introduced in: Clarity 2
input: (buff 16)
output: uint
signature: (buff-to-uint-le (buff 16))
description:
Converts a byte buffer to an unsigned integer use a little-endian encoding.. The byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as this function uses a little-endian encoding, the input behaves as if it is zero-padded on the right.
Note: This function is only available starting with Stacks 2.1.
example:
(buff-to-uint-le 0x01) ;; Returns u1
(buff-to-uint-le 0x01000000000000000000000000000000) ;; Returns u1
(buff-to-uint-le 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455
(buff-to-uint-le 0x) ;; Returns u0

concat​

Introduced in: Clarity 1
input: sequence_A, sequence_A
output: sequence_A
signature: (concat sequence1 sequence2)
description:
The concat function takes two sequences of the same type, and returns a concatenated sequence of the same type, with the resulting sequence_len = sequence1_len + sequence2_len. Applicable sequence types are (list A), buff, string-ascii and string-utf8.
example:
(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4)
(concat "hello " "world") ;; Returns "hello world"
(concat 0x0102 0x0304) ;; Returns 0x01020304

contract-call?​

Introduced in: Clarity 1
input: ContractName, PublicFunctionName, Arg0, ...
output: (response A B)
signature: (contract-call? .contract-name function-name arg0 arg1 ...)
description:
The contract-call? function executes the given public function of the given contract. You may not use this function to call a public function defined in the current contract. If the public function returns err, any database changes resulting from calling contract-call? are aborted. If the function returns ok, database changes occurred.
example:
;; instantiate the sample-contracts/tokens.clar contract first!
(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19)

contract-of​

Introduced in: Clarity 1
input: Trait
output: principal
signature: (contract-of .contract-name)
description:
The contract-of function returns the principal of the contract implementing the trait.
example:
(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)
(define-public (forward-get-balance (user principal) (contract <token-a-trait>))
(begin
(ok (contract-of contract)))) ;; returns the principal of the contract implementing <token-a-trait>

default-to​

Introduced in: Clarity 1
input: A, (optional A)
output: A
signature: (default-to default-value option-value)
description:
The default-to function attempts to 'unpack' the second argument: if the argument is a (some ...) option, it returns the inner value of the option. If the second argument is a (none) value, default-to it returns the value of default-value.
example:
(define-map names-map { name: (string-ascii 12) } { id: int })
(map-set names-map { name: "blockstack" } { id: 1337 })
(default-to 0 (get id (map-get? names-map (tuple (name "blockstack"))))) ;; Returns 1337
(default-to 0 (get id (map-get? names-map (tuple (name "non-existant"))))) ;; Returns 0

define-constant​

Introduced in: Clarity 1
input: MethodSignature, MethodBody
output: Not Applicable
signature: (define-constant name expression)
description:
define-constant is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant.
Like other kinds of definition statements, define-constant may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
example:
(define-constant four (+ 2 2))
(+ 4 four) ;; Returns 8

define-data-var​

Introduced in: Clarity 1
input: VarName, TypeDefinition, Value
output: Not Applicable
signature: (define-data-var var-name type value)
description:
define-data-var is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract.
Persisted variable are defined with a type and a value.
Like other kinds of definition statements, define-data-var may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
example:
(define-data-var size int 0)
(define-private (set-size (value int))
(var-set size value))
(set-size 1)
(set-size 2)

define-fungible-token​

Introduced in: Clarity 1
input: TokenName, <uint>
output: Not Applicable
signature: (define-fungible-token token-name <total-supply>)
description:
define-fungible-token is used to define a new fungible token class for use in the current contract.
The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the ft-mint? function will never be able to create more than total-supply tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of ft-mint? will result in a runtime error and abort.
Like other kinds of definition statements, define-fungible-token may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
Tokens defined using define-fungible-token may be used in ft-transfer?, ft-mint?, and ft-get-balance functions
example:
(define-fungible-token stacks)
(define-fungible-token limited-supply-stacks u100)

define-map​

Introduced in: Clarity 1
input: MapName, TypeDefinition, TypeDefinition
output: Not Applicable
signature: (define-map map-name key-type value-type)
description:
define-map is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract.
Maps are defined with a key type and value type, often these types are tuple types.
Like other kinds of definition statements, define-map may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
example:
(define-map squares { x: int } { square: int })
(define-private (add-entry (x int))
(map-insert squares { x: 2 } { square: (* x x) }))
(add-entry 1)
(add-entry 2)
(add-entry 3)
(add-entry 4)
(add-entry 5)

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:
define-non-fungible-token is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type asset-identifier-type. Asset identifiers are unique identifiers.
Like other kinds of definition statements, define-non-fungible-token may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
Assets defined using define-non-fungible-token may be used in nft-transfer?, nft-mint?, and nft-get-owner? functions
example:
(define-non-fungible-token names (buff 50))

define-private​

Introduced in: Clarity 1
input: MethodSignature, MethodBody
output: Not Applicable
signature: (define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)
description:
define-private is used to define private functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract.
Like other kinds of definition statements, define-private may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
Private functions may return any type.
example:
(define-private (max-of (i1 int) (i2 int))
(if (> i1 i2)
i1
i2))
(max-of 4 6) ;; Returns 6

define-public​

Introduced in: Clarity 1
input: MethodSignature, MethodBody
output: Not Applicable
signature: (define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)
description:
define-public is used to define a public function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain.
Like other kinds of definition statements, define-public may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
Public functions must return a ResponseType (using either ok or err). Any datamap modifications performed by a public function is aborted if the function returns an err type. Public functions may be invoked by other contracts via contract-call?.
example:
(define-public (hello-world (input int))
(begin
(print (+ 2 input))
(ok input)))

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) (arg-name-1 arg-type-1) ...) function-body)
description:
define-read-only is used to define a public read-only function for a smart contract. Such functions are callable from other smart contracts.
Like other kinds of definition statements, define-read-only may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via contract-call?.
example:
(define-read-only (just-return-one-hundred)
(* 10 10))

define-trait​

Introduced in: Clarity 1
input: VarName, [MethodSignature]
output: Not Applicable
signature: (define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))
description:
define-trait is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as a function argument in order to be called dynamically with contract-call?.
Traits are defined with a name, and a list functions, defined with a name, a list of argument types, and return type.
In Clarity 1, a trait type can be used to specify the type of a function parameter. A parameter with a trait type can be used as the target of a dynamic contract-call?. A principal literal (e.g. ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.foo) may be passed as a trait parameter if the specified contract implements all of the functions specified by the trait. A trait value (originating from a parameter with trait type) may also be passed as a trait parameter if the types are the same.
Beginning in Clarity 2, a trait can be used in all of the same ways that a built-in type can be used, except that it cannot be stored in a data var or map, since this would inhibit static analysis. This means that a trait type can be embedded in a compound type (e.g. (optional <my-trait>) or (list 4 <my-trait>)) and a trait value can be bound to a variable in a let or match expression. In addition to the principal literal and trait value with matching type allowed in Clarity 1, Clarity 2 also supports implicit casting from a compatible trait, meaning that a value of type trait-a may be passed to a parameter with type trait-b if trait-a includes all of the requirements of trait-b (and optionally additional functions).
Like other kinds of definition statements, define-trait may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body).
example:
(define-trait token-trait
((transfer? (principal principal uint) (response uint uint))
(get-balance (principal) (response uint uint))))

element-at​

Introduced in: Clarity 1
input: sequence_A, uint
output: (optional A)
signature: (element-at? sequence index)
description:
The element-at? function returns the element at index in the provided sequence. Applicable sequence types are (list A), buff, string-ascii and string-utf8, for which the corresponding element types are, respectively, A, (buff 1), (string-ascii 1) and (string-utf8 1). In Clarity1, element-at must be used (without the ?). The ? is added in Clarity2 for consistency -- built-ins that return responses or optionals end in ?. The Clarity1 spelling is left as an alias in Clarity2 for backwards compatibility.
example:
(element-at? "blockstack" u5) ;; Returns (some "s")
(element-at? (list 1 2 3 4 5) u5) ;; Returns none
(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4)
(element-at? "abcd" u1) ;; Returns (some "b")
(element-at? 0xfb01 u1) ;; Returns (some 0x01)

element-at?​

Introduced in: Clarity 2
input: sequence_A, uint
output: (optional A)
signature: (element-at? sequence index)
description:
The element-at? function returns the element at index in the provided sequence. Applicable sequence types are (list A), buff, string-ascii and string-utf8, for which the corresponding element types are, respectively, A, (buff 1), (string-ascii 1) and (string-utf8 1). In Clarity1, element-at must be used (without the ?). The ? is added in Clarity2 for consistency -- built-ins that return responses or optionals end in ?. The Clarity1 spelling is left as an alias in Clarity2 for backwards compatibility.
example:
(element-at? "blockstack" u5) ;; Returns (some "s")
(element-at? (list 1 2 3 4 5) u5) ;; Returns none
(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4)
(element-at? "abcd" u1) ;; Returns (some "b")
(element-at? 0xfb01 u1) ;; Returns (some 0x01)

err​

Introduced in: Clarity 1
input: A
output: (response A B)
signature: (err value)
description:
The err function constructs a response type from the input value. Use err for creating return values in public functions. An err value indicates that any database changes during the processing of the function should be rolled back.
example:
(err true) ;; Returns (err true)

filter​

Introduced in: Clarity 1
input: Function(A) -> bool, sequence_A
output: sequence_A
signature: (filter func sequence)
description:
The filter function applies the input function func to each element of the input sequence, and returns the same sequence with any elements removed for which func returned false. Applicable sequence types are (list A), buff, string-ascii and string-utf8, for which the corresponding element types are, respectively, A, (buff 1), (string-ascii 1) and (string-utf8 1). The func argument must be a literal function name.
example:
(filter not (list true false true false)) ;; Returns (false false)
(define-private (is-a (char (string-utf8 1)))
(is-eq char u"a"))
(filter is-a u"acabd") ;; Returns u"aa"
(define-private (is-zero (char (buff 1)))
(is-eq char 0x00))
(filter is-zero 0x00010002) ;; Returns 0x0000

fold​

Introduced in: Clarity 1
input: Function(A, B) -> B, sequence_A, B
output: B
signature: (fold func sequence_A initial_B)
description:
The fold function condenses sequence_A into a value of type B by recursively applies the function func to each element of the input sequence and the output of a previous application of func.
fold uses initial_B in the initial application of func, along with the first element of sequence_A. The resulting value of type B is used for the next application of func, along with the next element of sequence_A and so on. fold returns the last value of type B returned by these successive applications func.
Applicable sequence types are (list A), buff, string-ascii and string-utf8, for which the corresponding element types are, respectively, A, (buff 1), (string-ascii 1) and (string-utf8 1). The func argument must be a literal function name.
example:
(fold * (list 2 2 2) 1) ;; Returns 8
(fold * (list 2 2 2) 0) ;; Returns 0
;; calculates (- 11 (- 7 (- 3 2)))
(fold - (list 3 7 11) 2) ;; Returns 5
(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20)))
(unwrap-panic (as-max-len? (concat a b) u20)))
(fold concat-string "cdef" "ab") ;; Returns "fedcab"
(fold concat-string (list "cd" "ef") "ab") ;; Returns "efcdab"
(define-private (concat-buff (a (buff 20)) (b (buff 20)))
(unwrap-panic (as-max-len? (concat a b) u20)))
(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102

from-consensus-buff?​

Introduced in: Clarity 2
input: type-signature(t), buff
output: (optional t)
signature: (from-consensus-buff? type-signature buffer)
description:
from-consensus-buff? is a special function that will deserialize a buffer into a Clarity value, using the SIP-005 serialization of the Clarity value. The type that from-consensus-buff? tries to deserialize into is provided by the first parameter to the function. If it fails to deserialize the type, the method returns none.
example:
(from-consensus-buff? int 0x0000000000000000000000000000000001) ;; Returns (some 1)
(from-consensus-buff? uint 0x0000000000000000000000000000000001) ;; Returns none
(from-consensus-buff? uint 0x0100000000000000000000000000000001) ;; Returns (some u1)
(from-consensus-buff? bool 0x0000000000000000000000000000000001) ;; Returns none
(from-consensus-buff? bool 0x03) ;; Returns (some true)
(from-consensus-buff? bool 0x04) ;; Returns (some false)
(from-consensus-buff? principal 0x051fa46ff88886c2ef9762d970b4d2c63678835bd39d) ;; Returns (some SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)
(from-consensus-buff? { abc: int, def: int } 0x0c00000002036162630000000000000000000000000000000003036465660000000000000000000000000000000004) ;; Returns (some (tuple (abc 3) (def 4)))

ft-burn?​

Introduced in: Clarity 1
input: TokenName, uint, principal
output: (response bool uint)
signature: (ft-burn? token-name amount sender)
description:
ft-burn? is used to decrease the token balance for the sender principal for a token type defined using define-fungible-token. The decreased token balance is not transfered to another principal, but rather destroyed, reducing the circulating supply.
On a successful burn, it returns (ok true). In the event of an unsuccessful burn it returns one of the following error codes:
(err u1) -- sender does not have enough balance to burn this amount or the amount specified is not positive
example:
(define-fungible-token stackaroo)
(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)
(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)

ft-get-balance​

Introduced in: Clarity 1
input: TokenName, principal
output: uint
signature: (ft-get-balance token-name principal)
description:
ft-get-balance returns token-name balance of the principal principal. The token type must have been defined using define-fungible-token.
example:
(define-fungible-token stackaroo)
(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)
(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100

ft-get-supply​

Introduced in: Clarity 1
input: TokenName
output: uint
signature: (ft-get-supply token-name)
description:
ft-get-balance returns token-name circulating supply. The token type must have been defined using define-fungible-token.
example:
(define-fungible-token stackaroo)
(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)
(ft-get-supply stackaroo) ;; Returns u100

ft-mint?​

Introduced in: Clarity 1
input: TokenName, uint, principal
output: (response bool uint)
signature: (ft-mint? token-name amount recipient)
description:
ft-mint? is used to increase the token balance for the recipient principal for a token type defined using define-fungible-token. The increased token balance is not transfered from another principal, but rather minted.
If a non-positive amount is provided to mint, this function returns (err 1). Otherwise, on successfuly mint, it returns (ok true).
example:
(define-fungible-token stackaroo)
(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)

ft-transfer?​

Introduced in: Clarity 1
input: TokenName, uint, principal, principal
output: (response bool uint)
signature: (ft-transfer? token-name amount sender recipient)
description:
ft-transfer? is used to increase the token balance for the recipient principal for a token type defined using define-fungible-token by debiting the sender principal. In contrast to stx-transfer?, any user can transfer the assets. When used, relevant guards need to be added.
This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes:
(err u1) -- sender does not have enough balance to transfer (err u2) -- sender and recipient are the same principal (err u3) -- amount to send is non-positive
example:
(define-fungible-token stackaroo)
(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)
(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)
(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1)

get​

Introduced in: Clarity 1
input: KeyName, (tuple) | (optional (tuple))
output: A
signature: (get key-name tuple)
description:
The get function fetches the value associated with a given key from the supplied typed tuple. If an Optional value is supplied as the inputted tuple, get returns an Optional type of the specified key in the tuple. If the supplied option is a (none) option, get returns (none).
example:
(define-map names-map { name: (string-ascii 12) } { id: int })
(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true
(get id (tuple (name "blockstack") (id 1337))) ;; Returns 1337
(get id (map-get? names-map (tuple (name "blockstack")))) ;; Returns (some 1337)
(get id (map-get? names-map (tuple (name "non-existent")))) ;; Returns none

get-block-info?​

Introduced in: Clarity 1
input: BlockInfoPropertyName, uint
output: (optional buff) | (optional uint)
signature: (get-block-info? prop-name block-height)
description:
The get-block-info? function fetches data for a block of the given Stacks block height. The value and type returned are determined by the specified BlockInfoPropertyName. If the provided block-height does not correspond to an existing block prior to the current block, the function returns none. The currently available property names are as follows:
burnchain-header-hash: This property returns a (buff 32) value containing the header hash of the burnchain (Bitcoin) block that selected the Stacks block at the given Stacks chain height.
id-header-hash: This property returns a (buff 32) value containing the index block hash of a Stacks block. This hash is globally unique, and is derived from the block hash and the history of accepted PoX operations. This is also the block hash value you would pass into (at-block).
header-hash: This property returns a (buff 32) value containing the header hash of a Stacks block, given a Stacks chain height. *WARNING this hash is not guaranteed to be globally unique, since the same Stacks block can be mined in different PoX forks. If you need global uniqueness, you should use id-header-hash.
miner-address: This property returns a principal value corresponding to the miner of the given block. WARNING In Stacks 2.1, this is not guaranteed to be the same principal that received the block reward, since Stacks 2.1 supports coinbase transactions that pay the reward to a contract address. This is merely the address of the principal that produced the block.
time: This property returns a uint value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. Note: this does not increase monotonically with each block and block times are accurate only to within two hours. See BIP113 for more information.
New in Stacks 2.1:
block-reward: This property returns a uint value for the total block reward of the indicated Stacks block. This value is only available once the reward for the block matures. That is, the latest block-reward value available is at least 101 Stacks blocks in the past (on mainnet). The reward includes the coinbase, the anchored block's transaction fees, and the shares of the confirmed and produced microblock transaction fees earned by this block's miner. Note that this value may be smaller than the Stacks coinbase at this height, because the miner may have been punished with a valid PoisonMicroblock transaction in the event that the miner published two or more microblock stream forks.
miner-spend-total: This property returns a uint value for the total number of burnchain tokens (i.e. satoshis) spent by all miners trying to win this block.
miner-spend-winner: This property returns a uint value for the number of burnchain tokens (i.e. satoshis) spent by the winning miner for this Stacks block. Note that this value is less than or equal to the value for miner-spend-total at the same block height.
example:
(get-block-info? time u0) ;; Returns (some u1557860301)
(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb)
(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4)

get-burn-block-info?​

Introduced in: Clarity 2
input: BurnBlockInfoPropertyName, uint
output: (optional buff) | (optional (tuple (addrs (list 2 (tuple (hashbytes (buff 32)) (version (buff 1))))) (payout uint)))
signature: (get-burn-block-info? prop-name block-height)
description:
The get-burn-block-info? function fetches data for a block of the given burnchain block height. The value and type returned are determined by the specified BlockInfoPropertyName. Valid values for block-height only include heights between the burnchain height at the time the Stacks chain was launched, and the last-processed burnchain block. If the block-height argument falls outside of this range, then none shall be returned.
The following BlockInfoPropertyName values are defined:
  • The header-hash property returns a 32-byte buffer representing the header hash of the burnchain block at burnchain height block-height.
  • The pox-addrs property returns a tuple with two items: a list of up to two PoX addresses that received a PoX payout at that block height, and the amount of burnchain tokens paid to each address (note that per the blockchain consensus rules, each PoX payout will be the same for each address in the block-commit transaction). The list will include burn addresses -- that is, the unspendable addresses that miners pay to when there are no PoX addresses left to be paid. During the prepare phase, there will be exactly one burn address reported. During the reward phase, up to two burn addresses may be reported in the event that some PoX reward slots are not claimed.
The addrs list contains the same PoX address values passed into the PoX smart contract:
  • They each have type signature (tuple (hashbytes (buff 32)) (version (buff 1)))
  • The version field can be any of the following:
    • 0x00 means this is a p2pkh address, and hashbytes is the 20-byte hash160 of a single public key
    • 0x01 means this is a p2sh address, and hashbytes is the 20-byte hash160 of a redeemScript script
    • 0x02 means this is a p2wpkh-p2sh address, and hashbytes is the 20-byte hash160 of a p2wpkh witness script
    • 0x03 means this is a p2wsh-p2sh address, and hashbytes is the 20-byte hash160 of a p2wsh witness script
    • 0x04 means this is a p2wpkh address, and hashbytes is the 20-byte hash160 of the witness script
    • 0x05 means this is a p2wsh address, and hashbytes is the 32-byte sha256 of the witness script
    • 0x06 means this is a p2tr address, and hashbytes is the 32-byte sha256 of the witness script
example:
(get-burn-block-info? header-hash u677050) ;; Returns (some 0xe67141016c88a7f1203eca0b4312f2ed141531f59303a1c267d7d83ab6b977d8)
(get-burn-block-info? pox-addrs u677050) ;; Returns (some (tuple (addrs ( (tuple (hashbytes 0x395f3643cea07ec4eec73b4d9a973dcce56b9bf1) (version 0x00)) (tuple (hashbytes 0x7c6775e20e3e938d2d7e9d79ac310108ba501ddb) (version 0x01)))) (payout u123)))

hash160​

Introduced in: Clarity 1
input: buff|uint|int