Clarity language reference

This file contains the reference for the Clarity language.

Block Properties

The get-block-info function fetches property details for a block at a specified block height. For example:

(get-block-info time 10) ;; Returns 1557860301

Because the Clarity language is in pre-release, the block properties that are fetched are simulated properties from a SQLite database. The available property names are:

Property Definition
header-hash A 32-byte buffer containing the block hash.
burnchain-header-hash A 32-byte buffer that contains the hash from the proof of burn.
vrf-seed A 32-byte buffer containing the Verifiable Random Function (VRF) seed value used for the block.
time An integer value containing that roughly corresponds to when the block was mined. This is a Unix epoch timestamp in seconds.
Warning: The time does not increase monotonically with each block. Block times are accurate only to within two hours. See BIP113 for more information.

Supported types

This section lists the types available to smart contracts. The only atomic types supported by the Clarity are booleans, integers, fixed length buffers, and principals.

Int type

The integer type in the Clarity language is a 16-byte signed integer, which allows it to specify the maximum amount of microstacks spendable in a single Stacks transfer. The special BlockHeightInt you can obtain with the get-block-info function.

Bool type

Supports values of 'true or 'false.

Buffer type

Buffer types represent fixed-length byte buffers. Currently, the only way to construct a Buffer is using string literals, for example "alice.id" or hash160("bob.id")

All of the hash functions return buffers:

hash160 sha256 keccak256

The block properties header-hash, burnchain-header-hash, and vrf-seed are all buffers.

List type

Clarity supports lists of the atomic types. However, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join.

Principal type

Clarity provides this primitive for checking whether or not the smart contract transaction was signed by a particular principal. Principals represent a spending entity and are roughly equivalent to a Stacks address. The principal’s signature is not checked by the smart contract, but by the virtual machine. A smart contract function can use the globally defined tx-sender variable to obtain the current principal.

Smart contracts may also be principals (represented by the smart contract’s identifier). However, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. A smart contract uses the special variable contract-name to refer to its own principal.

Tuple type

To support the use of named fields in keys and values, Clarity allows the construction of named tuples using a function (tuple ...), for example

(define imaginary-number-a (tuple (real 1) (i 2)))
(define imaginary-number-b (tuple (real 2) (i 3)))

This allows for creating named tuples on the fly, which is useful for data maps where the keys and values are themselves named tuples. Values in a given mapping are set or fetched using:

Function Description
(fetch-entry map-name key-tuple) Fetches the value associated with a given key in the map, or returns none if there is no such value.
(set-entry! map-name key-tuple value-tuple) Sets the value of key-tuple in the data map
(insert-entry! map-name key-tuple value-tuple) Sets the value of key-tuple in the data map if and only if an entry does not already exist.
(delete-entry! map-name key-tuple) Deletes key-tuple from the data map.

To access a named value of a given tuple, the (get name tuple) function returns that item from the tuple.

Optional type

Represents an optional value. This is used in place of the typical usage of “null” values in other languages, and represents a type that can either be some value or none. Optional types are used as the return types of data-map functions.

Response type

Response types represent the result of a public function. Use this type to indicate and return data associated with the execution of the function. Also, the response should indicate whether the function error’ed (and therefore did not materialize any data in the database) or ran ok (in which case data materialized in the database).

Response types contain two subtypes – a response type in the event of ok (that is, a public function returns an integer code on success) and an err type (that is, a function returns a buffer on error).

Keyword reference

block-height

int

Returns the current block height of the Stacks blockchain as an int

Example

(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks.

contract-caller

principal

Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If contract-call! was used to invoke a function from a new contract, contract-caller changes to the calling contract’s principal. If as-contract is used to change the tx-sender context, contract-caller also changes to the same contract principal.

Example

(print contract-caller) ;; Will print out a Stacks address of the transaction sender

none

(optional ?)

Represents the none option indicating no value for a given optional (analogous to a null value).

Example

(define (only-if-positive (a int))
  (if (> a 0)
      (some a)
      none))
(only-if-positive 4) ;; Returns (some 4)
(only-if-positive (- 3)) ;; Returns none

tx-sender

principal

Returns the original sender of the current transaction, or if as-contract was called to modify the sending context, it returns that contract principal.

Example

(print tx-sender) ;; Will print out a Stacks address of the transaction sender

Function reference

* (multiply)

Syntax (* i1 i2...)

INPUT: int, ...
OUTPUT: int

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)

Syntax (+ i1 i2...)

INPUT: int, ...
OUTPUT: int

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)

Syntax (- i1 i2...)

INPUT: int, ...
OUTPUT: int

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)

Syntax (/ i1 i2...)

INPUT: int, ...
OUTPUT: int

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)

Syntax (< i1 i2)

INPUT: int, int
OUTPUT: bool

Compares two integers, returning true if i1 is less than i2 and false otherwise.

Example

(< 1 2) ;; Returns 'true
(< 5 2) ;; Returns 'false

<= (less than or equal)

Syntax (<= i1 i2)

INPUT: int, int
OUTPUT: bool

Compares two integers, returning true if i1 is less than or equal to i2 and false otherwise.

Example

(<= 1 1) ;; Returns 'true
(<= 5 2) ;; Returns 'false

> (greater than)

Syntax (> i1 i2)

INPUT: int, int
OUTPUT: bool

Compares two integers, returning true if i1 is greater than i2 and false otherwise.

Example

(> 1 2) ;; Returns 'false
(> 5 2) ;; Returns 'true

>= (greater than or equal)

Syntax (>= i1 i2)

INPUT: int, int
OUTPUT: bool

Compares two integers, returning true if i1 is greater than or equal to i2 and false otherwise.

Example

(>= 1 1) ;; Returns 'true
(>= 5 2) ;; Returns 'true

and

Syntax (and b1 b2 ...)

INPUT: bool, ...
OUTPUT: bool

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 (eq? (+ 1 2) 1) (eq? 4 4)) ;; Returns 'false
(and (eq? (+ 1 2) 3) (eq? 4 4)) ;; Returns 'true

as-contract

Syntax (as-contract expr)

INPUT: A
OUTPUT: A

The as-contract function switches the current context’s tx-origin value to the contract’s principal and executes expr with that context. It returns the resulting value of expr.

Example

(as-contract (print tx-sender)) ;; Returns 'CTcontract.name

begin

Syntax (begin expr1 expr2 expr3 ... expr-last)

INPUT: AnyType, ... A
OUTPUT: A

The begin function evaluates each of its input expressions, returning the return value of the last such expression.

Example

(begin (+ 1 2) 4 5) ;; Returns 5

contract-call!

Syntax (contract-call! contract-name function-name arg0 arg1 ...)

INPUT: ContractName, PublicFunctionName, Arg0, ...
OUTPUT: (response A B)

The contract-call! function executes the given public function of the given contract. You may not 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

(contract-call! tokens transfer 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 19) ;; Returns (ok 1)

contract-map-get

Syntax (contract-map-get contract-name map-name key-tuple)

INPUT: ContractName, MapName, tuple
OUTPUT: (optional (tuple))

The contract-map-get function looks up and returns an entry from a contract other than the current contract’s data map. The value is looked up using key-tuple. If there is no value associated with that key in the data map, the function returns a (none) option. Otherwise, it returns (some value).

Example

(expects! (contract-map-get names-contract names-map (tuple (name "blockstack")) (err 1))) ;; Returns (tuple (id 1337))
(expects! (contract-map-get names-contract names-map ((name "blockstack")) (err 1)));; Same command, using a shorthand for constructing the tuple

default-to

Syntax (default-to default-value option-value)

INPUT: A, (optional A)
OUTPUT: A

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

(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

Syntax (define-constant name expression)

INPUT: MethodSignature, MethodBody
OUTPUT: Not Applicable

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

Syntax (define-data-var var-name type value)

INPUT: VarName, TypeDefinition, Value
OUTPUT: Not Applicable

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 (set-size (value int))
  (var-set! size value))
(set-size 1)
(set-size 2)

define-fungible-token

Syntax (define-fungible-token token-name <total-supply>)

INPUT: TokenName, </code>
OUTPUT: Not Applicable

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-map

Syntax (define-map map-name ((key-name-0 key-type-0) ...) ((val-name-0 val-type-0) ...))

INPUT: MapName, KeyTupleDefinition, MapTupleDefinition
OUTPUT: Not Applicable

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 tuple type and value tuple type. These are defined using a list of name and type pairs, e.g., a key type might be ((id int)), which is a tuple with a single “id” field of type int.

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 (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

Syntax (define-non-fungible-token asset-name asset-identifier-type)

INPUT: AssetName, TypeSignature
OUTPUT: Not Applicable

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

Syntax (define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)

INPUT: MethodSignature, MethodBody
OUTPUT: Not Applicable

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

Syntax (define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)

INPUT: MethodSignature, MethodBody
OUTPUT: Not Applicable

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

Syntax (define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)

INPUT: MethodSignature, MethodBody
OUTPUT: Not Applicable

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))

eq?

Syntax (eq? v1 v2...)

INPUT: A, A, ...
OUTPUT: bool

Compares the inputted values, returning true if they are all equal. Note that unlike the (and ...) function, (eq? ...) will not short-circuit.

Example

(eq? 1 1) ;; Returns 'true
(eq? 1 'false) ;; Returns 'false
(eq? "abc" 234 234) ;; Returns 'false

err

Syntax (err value)

INPUT: A
OUTPUT: (response A B)

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)

expects!

Syntax (expects! option-input thrown-value)

INPUT: (optional A) | (response A B), C
OUTPUT: A

The expects! function attempts to ‘unpack’ the first argument: if the argument is an option type, and the argument is a (some ...) option, expects! returns the inner value of the option. If the argument is a response type, and the argument is an (ok ...) response, expects! returns the inner value of the ok. If the supplied argument is either an (err ...) or a (none) value, expects! returns thrown-value from the current function and exits the current control-flow.

Example

(expects! (map-get names-map (tuple (name "blockstack"))) (err 1)) ;; Returns (tuple (id 1337))

expects-err!

Syntax (expects-err! response-input thrown-value)

INPUT: (response A B), C
OUTPUT: B

The expects-err! function attempts to ‘unpack’ the first argument: if the argument is an (err ...) response, expects-err! returns the inner value of the err. If the supplied argument is an (ok ...) value, expects-err! returns thrown-value from the current function and exits the current control-flow.

Example

(expects-err! (err 1) 'false) ;; Returns 1

filter

Syntax (filter func list)

INPUT: Function(A) -> bool, (list A)
OUTPUT: (list A)

The filter function applies the input function func to each element of the input list, and returns the same list with any elements removed for which the func returned false.

Example

(filter not (list true false true false)) ;; Returns (list false false)

fold

Syntax (fold func list initial-value)

INPUT: Function(A, B) -> B, (list A)
OUTPUT: B

The fold function applies the input function func to each element of the input list and the output of the previous application of the fold function. When invoked on the first list element, it uses the initial-value as the second input. fold returns the last value return by the successive applications.

Example

(fold * (list 2 2 2) 1) ;; Returns 8
(fold * (list 2 2 2) 0) ;; Returns 0

ft-get-balance

Syntax (ft-get-balance token-name principal)

INPUT: TokenName, principal
OUTPUT: int

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 stackaroos)
(ft-get-balance stackaroos tx-sender)

ft-mint!

Syntax (ft-mint! token-name amount recipient)

INPUT: TokenName, int, principal
OUTPUT: (response bool int)

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 100 tx-sender)

ft-transfer!

Syntax (ft-transfer! token-name amount sender recipient)

INPUT: TokenName, int, principal, principal
OUTPUT: (response bool int)

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.

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 1)sender does not have enough balance to transfer (err 2)sender and recipient are the same principal (err 3) – amount to send is non-positive

Example

(define-fungible-token stackaroo)
(ft-mint! stackaroo 100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)
(ft-transfer! stackaroo 50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (ok true)
(ft-transfer! stackaroo 60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (err 1)

get-block-info

Syntax (get-block-info prop-name block-height-expr)

INPUT: BlockInfoPropertyName, BlockHeightInt
OUTPUT: buff | int

The get-block-info function fetches data for a block of the given block height. The value and type returned are determined by the specified BlockInfoPropertyName. If the provided BlockHeightInt does not correspond to an existing block, the function is aborted. The currently available property names are time, header-hash, burnchain-header-hash, and vrf-seed.

The time property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. Warning: this does not increase monotonically with each block and block times are accurate only to within two hours. See BIP113 for more information.

The header-hash, burnchain-header-hash, and vrf-seed properties return a 32-byte buffer.

Example

(get-block-info time 10) ;; Returns 1557860301
(get-block-info header-hash 2) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb
(get-block-info vrf-seed 6) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4

get

Syntax (get key-name tuple)

INPUT: KeyName, (tuple) | (optional (tuple))
OUTPUT: A

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

(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)

hash160

Syntax (hash160 value)

INPUT: buff|int
OUTPUT: (buff 20)

The hash160 function computes RIPEMD160(SHA256(x)) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer.

Example

(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f

if

Syntax (if bool1 expr1 expr2)

INPUT: bool, A, A
OUTPUT: A

The if function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is true, the if function evaluates and returns expr1. If the boolean input is false, the if function evaluates and returns expr2.

Example

(if true 1 2) ;; Returns 1
(if (> 1 2) 1 2) ;; Returns 2

is-none?

Syntax (is-none? value)

INPUT: (optional A)
OUTPUT: bool

is-none? tests a supplied option value, returning true if the option value is (none), and false if it is a (some ...).

Example

(is-none? (get id (map-get names-map (tuple (name "blockstack"))))) ;; Returns 'false
(is-none? (get id (map-get names-map (tuple (name "non-existant"))))) ;; Returns 'true

is-ok?

Syntax (is-ok? value)

INPUT: (response A B)
OUTPUT: bool

is-ok? tests a supplied response value, returning true if the response was ok, and false if it was an err.

Example

(is-ok? (ok 1)) ;; Returns 'true
(is-ok? (err 1)) ;; Returns 'false

keccak256

Syntax (keccak256 value)

INPUT: buff|int
OUTPUT: (buff 32)

The keccak256 function computes KECCAK256(value) of the inputted value. Note that this differs from the NIST SHA-3 (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer.

Example

(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4

let

Syntax (let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)

INPUT: ((name2 AnyType) (name2 AnyType) ...), AnyType, ... A
OUTPUT: A

The let function accepts a list of variable name and expression pairs, evaluating each expression and binding it to the corresponding variable name. The context created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression.

Example

(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20

list

Syntax (list expr1 expr2 expr3 ...)

INPUT: A, ...
OUTPUT: (list A)

The list function constructs a list composed of the inputted values. Each supplied value must be of the same type.

Example

(list (+ 1 2) 4 5) ;; Returns [3 4 5]

map-delete!

Syntax (map-delete! map-name key-tuple)

INPUT: MapName, tuple
OUTPUT: bool

The map-delete! function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns true. If a value did not exist for this key in the data map, the function returns false.

Example

(map-delete! names-map (tuple (name "blockstack"))) ;; Returns 'true
(map-delete! names-map (tuple (name "blockstack"))) ;; Returns 'false
(map-delete! names-map ((name "blockstack"))) ;; Same command, using a shorthand for constructing the tuple

map-get

Syntax (map-get map-name key-tuple)

INPUT: MapName, tuple
OUTPUT: (optional (tuple))

The map-get function looks up and returns an entry from a contract’s data map. The value is looked up using key-tuple. If there is no value associated with that key in the data map, the function returns a (none) option. Otherwise, it returns (some value)

Example

(expects! (map-get names-map (tuple (name "blockstack"))) (err 1)) ;; Returns (tuple (id 1337))
(expects! (map-get names-map ((name "blockstack"))) (err 1)) ;; Same command, using a shorthand for constructing the tuple

map-insert!

Syntax (map-insert! map-name key-tuple value-tuple)

INPUT: MapName, tuple_A, tuple_B
OUTPUT: bool

The map-insert! function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns true. If a value already existed for this key in the data map, the function returns false.

Example

(map-insert! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'true
(map-insert! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'false
(map-insert! names-map ((name "blockstack")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple

map-set!

Syntax (map-set! map-name key-tuple value-tuple)

INPUT: MapName, tuple_A, tuple_B
OUTPUT: bool

The map-set! function sets the value associated with the input key to the inputted value. This function performs a blind update; whether or not a value is already associated with the key, the function overwrites that existing association.

Example

(map-set! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'true
(map-set! names-map ((name "blockstack")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple

map

Syntax (map func list)

INPUT: Function(A) -> B, (list A)
OUTPUT: (list B)

The map function applies the input function func to each element of the input list, and outputs a list containing the outputs from those function applications.

Example

(map not (list true false true false)) ;; Returns 'false true false true

mod

Syntax (mod i1 i2)

INPUT: int, int
OUTPUT: int

Returns the integer remainder from integer dividing i1 by i2. In the event of a division by zero, throws a runtime error.

Example

(mod 2 3) ;; Returns 0
(mod 5 2) ;; Returns 1
(mod 7 1) ;; Returns 0

nft-get-owner

Syntax (nft-get-owner asset-class asset-identifier)

INPUT: AssetName, A
OUTPUT: (optional principal)

nft-get-owner returns the owner of an asset, identified by asset-identifier, or none if the asset does not exist. The asset type must have been defined using define-non-fungible-token, and the supplied asset-identifier must be of the same type specified in that definition.

Example

(define-non-fungible-token stackaroo (buff 40))
(nft-get-owner stackaroo "Roo")

nft-mint!

Syntax (nft-mint! asset-class asset-identifier recipient)

INPUT: AssetName, A, principal
OUTPUT: (response bool int)

nft-mint! is used to instantiate an asset and set that asset’s owner to the recipient principal. The asset must have been defined using define-non-fungible-token, and the supplied asset-identifier must be of the same type specified in that definition.

If an asset identified by asset-identifier already exists, this function will return an error with the following error code:

(err 1)

Otherwise, on successfuly mint, it returns (ok 'true).

Example

(define-non-fungible-token stackaroo (buff 40))
(nft-mint! stackaroo "Roo" tx-sender)

nft-transfer!

Syntax (nft-transfer! asset-class asset-identifier sender recipient)

INPUT: AssetName, A, principal, principal
OUTPUT: (response bool int)

nft-transfer! is used to change the owner of an asset identified by asset-identifier from sender to recipient. The asset-class must have been defined by define-non-fungible-token and asset-identifier must be of the type specified in that definition.

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 1)sender does not own the asset (err 2)sender and recipient are the same principal (err 3) – asset identified by asset-identifier does not exist

Example

(define-non-fungible-token stackaroo (buff 40))
(nft-mint! stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)
(nft-transfer! stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (ok true)
(nft-transfer! stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (err 1)
(nft-transfer! stackaroo "Stacka" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (err 3)

not

Syntax (not b1)

INPUT: bool
OUTPUT: bool

Returns the inverse of the boolean input.

Example

(not 'true) ;; Returns 'false
(not (eq? 1 2)) ;; Returns 'true

ok

Syntax (ok value)

INPUT: A
OUTPUT: (response A B)

The ok function constructs a response type from the input value. Use ok for creating return values in public functions. An ok value indicates that any database changes during the processing of the function should materialize.

Example

(ok 1) ;; Returns (ok 1)

or

Syntax (or b1 b2 ...)

INPUT: bool, ...
OUTPUT: bool

Returns true if any 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

(or 'true 'false) ;; Returns 'true
(or (eq? (+ 1 2) 1) (eq? 4 4)) ;; Returns 'true
(or (eq? (+ 1 2) 1) (eq? 3 4)) ;; Returns 'false
(or (eq? (+ 1 2) 3) (eq? 4 4)) ;; Returns 'true

pow

Syntax (pow i1 i2)

INPUT: int, int
OUTPUT: int

Returns the result of raising i1 to the power of i2. In the event of an overflow, throws a runtime error.

Example

(pow 2 3) ;; Returns 8
(pow 2 2) ;; Returns 4
(pow 7 1) ;; Returns 7

print

Syntax (print expr)

INPUT: A
OUTPUT: A

The print function evaluates and returns its input expression. On Blockstack Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to STDOUT (standard output).

Example

(print (+ 1 2 3)) ;; Returns 6

sha256

Syntax (sha256 value)

INPUT: buff|int
OUTPUT: (buff 32)

The sha256 function computes SHA256(x) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer.

Example

(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb

some

Syntax (some value)

INPUT: A
OUTPUT: (optional A)

The some function constructs a optional type from the input value.

Example

(some 1) ;; Returns (some 1)
(is-none? (some 2)) ;; Returns 'false

tuple

Syntax (tuple ((key0 expr0) (key1 expr1) ...))

INPUT: (key-name A), (key-name-2 B), ...
OUTPUT: (tuple (key-name A) (key-name-2 B) ...)

The tuple function constructs a typed tuple from the supplied key and expression pairs. A get function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions’ paired key name.

Example

(tuple (name "blockstack") (id 1337))

var-get

Syntax (var-get var-name)

INPUT: VarName
OUTPUT: A

The var-get function looks up and returns an entry from a contract’s data map. The value is looked up using var-name.

Example

(var-get cursor) ;; Returns cursor

var-set!

Syntax (var-set! var-name expr1)

INPUT: VarName, AnyType
OUTPUT: bool

The var-set! function sets the value associated with the input variable to the inputted value.

Example

(var-set! cursor (+ cursor 1)) ;; Returns 'true

xor

Syntax (xor i1 i2)

INPUT: int, int
OUTPUT: int

Returns the result of bitwise exclusive or’ing i1 with i2.

Example

(xor 1 2) ;; Returns 3
(xor 120 280) ;; Returns 352