Clarity- smart contract language reference
Clarity language reference
This file contains the reference for the Clarity language.
Block Properties
Supported types
Int type
Bool type
Buffer type
List type
Principal type
Tuple type
Optional type
Response type
Native variables
block-height
contract-name
tx-sender
Clarity function reference
* (multiply)
+ (add)
- (subtract)
/ (divide)
< (less than)
<= (less than or equal)
> (greater than)
>= (greater than or equal)
and
as-contract
begin
contract-call!
default-to
define-data-var
define-map
define-public
define-read-only
define
delete-entry!
eq?
err
expects!
expects-err!
fetch-contract-entry
fetch-entry
fetch-var
filter
fold
get-block-info
get
hash160
if
insert-entry!
is-none?
is-ok?
keccak256
let
list
map
mod
not
ok
or
pow
print
set-entry!
set-var!
sha256
tuple
xor
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).
Native variables
The Clarity language includes native variables you can use in your contract.
block-height
The height of a block in the Stacks blockchain. Block height is the number of blocks in the chain between any given block and the very first block in the blockchain. You can obtain a block-height via the get-block-info function.
contract-name
Represents the current contract.
tx-sender
Represents the current principal. This variable does not change during inter-contract calls. This means that if a transaction invokes a function in a given smart contract, that function is able to make calls into other smart contracts on your behalf. This enables a wide variety of applications, but it comes with some dangers for users of smart contracts. Static analysis of Clarity contracts guarantees the language allows clients to deduce which functions a given smart contract will ever call. Good clients should always warn users about any potential side effects of a given transaction.
Clarity function reference
* (multiply)
Syntax (* i1 i2...)
Input type:
int, ...
Output type:
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 type:
int, ...
Output type:
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 type:
int, ...
Output type:
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 type:
int, ...
Output type:
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 type:
int, int
Output type:
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 type:
int, int
Output type:
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 type:
int, int
Output type:
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 type:
int, int
Output type:
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 type:
bool, ...
Output type:
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 type:
A
Output type:
A
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 (print tx-sender)) ;; Returns 'CTcontract.name
begin
Syntax (begin expr1 expr2 expr3 ... expr-last)
Input type:
AnyType, ... A
Output type:
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 type:
ContractName, PublicFunctionName, Arg0, ...
Output type:
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)
default-to
Syntax (default-to default-value option-value)
Input type:
A, Optional(A)
Output type:
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 (fetch-entry names-map (tuple (name "blockstack"))))) ;; Returns 1337
(default-to 0 (get id (fetch-entry names-map (tuple (name "non-existant"))))) ;; Returns 0
define-data-var
Syntax (define-data-var var-name type value)
Input type:
VarName, TypeDefinition, Value
Output type:
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))
(set-var! size value))
(set-size 1)
(set-size 2)
define-map
Syntax (define-map map-name ((key-name-0 key-type-0) ...) ((val-name-0 val-type-0) ...))
Input type:
MapName, KeyTupleDefinition, MapTupleDefinition
Output type:
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))
(insert-entry! squares ((x 2)) ((square (* x x)))))
(add-entry 1)
(add-entry 2)
(add-entry 3)
(add-entry 4)
(add-entry 5)
define-public
Syntax (define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)
Input type:
MethodSignature, MethodBody
Output type:
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 type:
MethodSignature, MethodBody
Output type:
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))
define
Syntax (define (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)
Input type:
MethodSignature, MethodBody
Output type:
Not Applicable
define 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 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 (max-of (i1 int) (i2 int))
(if (> i1 i2)
i1
i2))
(max-of 4 6) ;; returns 6
delete-entry!
Syntax (delete-entry! map-name key-tuple)
Input type:
MapName, Tuple
Output type:
bool
The delete-entry! 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
(delete-entry! names-map (tuple (name "blockstack"))) ;; Returns 'true
(delete-entry! names-map (tuple (name "blockstack"))) ;; Returns 'false
(delete-entry! names-map ((name "blockstack"))) ;; Same command, using a shorthand for constructing the tuple
eq?
Syntax (eq? v1 v2...)
Input type:
A, A, ...
Output type:
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 type:
A
Output type:
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 type:
Optional(A) | Response(A,B), C
Output type:
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! (fetch-entry names-map (tuple (name "blockstack"))) (err 1)) ;; Returns (tuple (id 1337))
expects-err!
Syntax (expects-err! response-input thrown-value)
Input type:
Response(A,B), C
Output type:
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
fetch-contract-entry
Syntax (fetch-contract-entry contract-name map-name key-tuple)
Input type:
ContractName, MapName, Tuple
Output type:
Optional(Tuple)
The fetch-contract-entry 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! (fetch-contract-entry names-contract names-map (tuple (name "blockstack")) (err 1))) ;; Returns (tuple (id 1337))
(expects! (fetch-contract-entry names-contract names-map ((name "blockstack")) (err 1)));; Same command, using a shorthand for constructing the tuple
fetch-entry
Syntax (fetch-entry map-name key-tuple)
Input type:
MapName, Tuple
Output type:
Optional(Tuple)
The fetch-entry 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! (fetch-entry names-map (tuple (name "blockstack"))) (err 1)) ;; Returns (tuple (id 1337))
(expects! (fetch-entry names-map ((name "blockstack"))) (err 1)) ;; Same command, using a shorthand for constructing the tuple
fetch-var
Syntax (fetch-var var-name)
Input type:
VarName
Output type:
A
The fetch-var function looks up and returns an entry from a contract’s data map. The value is looked up using var-name.
Example
(fetch-var cursor) ;; Returns cursor
filter
Syntax (filter func list)
Input type:
Function(A) -> bool, (list A)
Output type:
(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 type:
Function(A, B) -> B, (list A)
Output type:
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
get-block-info
Syntax (get-block-info prop-name block-height-expr)
Input type:
BlockInfoPropertyName, BlockHeightInt
Output type:
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 type:
KeyName and Tuple | Optional(Tuple)
Output type:
AnyType
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 (fetch-entry names-map (tuple (name "blockstack")))) ;; Returns (some 1337)
(get id (fetch-entry names-map (tuple (name "non-existent")))) ;; Returns (none)
hash160
Syntax (hash160 value)
Input type:
buff|int
Output type:
(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 type:
bool, A, A
Output type:
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
insert-entry!
Syntax (insert-entry! map-name key-tuple value-tuple)
Input type:
MapName, TupleA, TupleB
Output type:
bool
The insert-entry! 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
(insert-entry! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'true
(insert-entry! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'false
(insert-entry! names-map ((name "blockstack")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple
is-none?
Syntax (is-none? value)
Input type:
Optional(A)
Output type:
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 (fetch-entry names-map (tuple (name "blockstack"))))) ;; Returns 'false
(is-none? (get id (fetch-entry names-map (tuple (name "non-existant"))))) ;; Returns 'true
is-ok?
Syntax (is-ok? value)
Input type:
Response(A,B)
Output type:
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 type:
buff|int
Output type:
(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-body)
Input type:
((name2 AnyType) (name2 AnyType) ...), A
Output type:
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 and return the value of expr-body.
Example
(let ((a 2) (b (+ 5 6 7))) (+ a b)) ;; Returns 20
list
Syntax (list expr1 expr2 expr3 ...)
Input type:
A, ...
Output type:
(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
Syntax (map func list)
Input type:
Function(A) -> B, (list A)
Output type:
(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 type:
int, int
Output type:
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
not
Syntax (not b1)
Input type:
bool
Output type:
bool
Returns the inverse of the boolean input.
Example
(not 'true) ;; Returns 'false
(not (eq? 1 2)) ;; Returns 'true
ok
Syntax (ok value)
Input type:
A
Output type:
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 type:
bool, ...
Output type:
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 type:
int, int
Output type:
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 type:
A
Output type:
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
set-entry!
Syntax (set-entry! map-name key-tuple value-tuple)
Input type:
MapName, TupleA, TupleB
Output type:
bool
The set-entry! 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
(set-entry! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'true
(set-entry! names-map ((name "blockstack")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple
set-var!
Syntax (set-var! var-name expr1)
Input type:
VarName, AnyType
Output type:
bool
The set-var! function sets the value associated with the input variable to the inputted value.
Example
(set-var! cursor (+ cursor 1)) ;; Returns 'true
sha256
Syntax (sha256 value)
Input type:
buff|int
Output type:
(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
tuple
Syntax (tuple ((key0 expr0) (key1 expr1) ...))
Input type:
(list (KeyName AnyType))
Output type:
Tuple
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))
xor
Syntax (xor i1 i2)
Input type:
int, int
Output type:
int
Returns the result of bitwise exclusive or’ing i1 with i2.
Example
(xor 1 2) ;; Returns 3
(xor 120 280) ;; Returns 352
This file contains the reference for the Clarity language.
Block Properties
Supported types
Int type
Bool type
Buffer type
List type
Principal type
Tuple type
Optional type
Response type
Native variables
block-height
contract-name
tx-sender
Clarity function reference
* (multiply)
+ (add)
- (subtract)
/ (divide)
< (less than)
<= (less than or equal)
> (greater than)
>= (greater than or equal)
and
as-contract
begin
contract-call!
default-to
define-data-var
define-map
define-public
define-read-only
define
delete-entry!
eq?
err
expects!
expects-err!
fetch-contract-entry
fetch-entry
fetch-var
filter
fold
get-block-info
get
hash160
if
insert-entry!
is-none?
is-ok?
keccak256
let
list
map
mod
not
ok
or
pow
set-entry!
set-var!
sha256
tuple
xor
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).
Native variables
The Clarity language includes native variables you can use in your contract.
block-height
The height of a block in the Stacks blockchain. Block height is the number of blocks in the chain between any given block and the very first block in the blockchain. You can obtain a block-height via the get-block-info function.
contract-name
Represents the current contract.
tx-sender
Represents the current principal. This variable does not change during inter-contract calls. This means that if a transaction invokes a function in a given smart contract, that function is able to make calls into other smart contracts on your behalf. This enables a wide variety of applications, but it comes with some dangers for users of smart contracts. Static analysis of Clarity contracts guarantees the language allows clients to deduce which functions a given smart contract will ever call. Good clients should always warn users about any potential side effects of a given transaction.
Clarity function reference
* (multiply)
Syntax (* i1 i2...)
Input type:
int, ...
Output type:
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 type:
int, ...
Output type:
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 type:
int, ...
Output type:
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 type:
int, ...
Output type:
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 type:
int, int
Output type:
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 type:
int, int
Output type:
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 type:
int, int
Output type:
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 type:
int, int
Output type:
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 type:
bool, ...
Output type:
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 type:
A
Output type:
A
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 (print tx-sender)) ;; Returns 'CTcontract.name
begin
Syntax (begin expr1 expr2 expr3 ... expr-last)
Input type:
AnyType, ... A
Output type:
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 type:
ContractName, PublicFunctionName, Arg0, ...
Output type:
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)
default-to
Syntax (default-to default-value option-value)
Input type:
A, Optional(A)
Output type:
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 (fetch-entry names-map (tuple (name "blockstack"))))) ;; Returns 1337
(default-to 0 (get id (fetch-entry names-map (tuple (name "non-existant"))))) ;; Returns 0
define-data-var
Syntax (define-data-var var-name type value)
Input type:
VarName, TypeDefinition, Value
Output type:
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))
(set-var! size value))
(set-size 1)
(set-size 2)
define-map
Syntax (define-map map-name ((key-name-0 key-type-0) ...) ((val-name-0 val-type-0) ...))
Input type:
MapName, KeyTupleDefinition, MapTupleDefinition
Output type:
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))
(insert-entry! squares ((x 2)) ((square (* x x)))))
(add-entry 1)
(add-entry 2)
(add-entry 3)
(add-entry 4)
(add-entry 5)
define-public
Syntax (define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)
Input type:
MethodSignature, MethodBody
Output type:
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 type:
MethodSignature, MethodBody
Output type:
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))
define
Syntax (define (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)
Input type:
MethodSignature, MethodBody
Output type:
Not Applicable
define 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 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 (max-of (i1 int) (i2 int))
(if (> i1 i2)
i1
i2))
(max-of 4 6) ;; returns 6
delete-entry!
Syntax (delete-entry! map-name key-tuple)
Input type:
MapName, Tuple
Output type:
bool
The delete-entry! 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
(delete-entry! names-map (tuple (name "blockstack"))) ;; Returns 'true
(delete-entry! names-map (tuple (name "blockstack"))) ;; Returns 'false
(delete-entry! names-map ((name "blockstack"))) ;; Same command, using a shorthand for constructing the tuple
eq?
Syntax (eq? v1 v2...)
Input type:
A, A, ...
Output type:
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 type:
A
Output type:
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 type:
Optional(A) | Response(A,B), C
Output type:
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! (fetch-entry names-map (tuple (name "blockstack"))) (err 1)) ;; Returns (tuple (id 1337))
expects-err!
Syntax (expects-err! response-input thrown-value)
Input type:
Response(A,B), C
Output type:
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
fetch-contract-entry
Syntax (fetch-contract-entry contract-name map-name key-tuple)
Input type:
ContractName, MapName, Tuple
Output type:
Optional(Tuple)
The fetch-contract-entry 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! (fetch-contract-entry names-contract names-map (tuple (name "blockstack")) (err 1))) ;; Returns (tuple (id 1337))
(expects! (fetch-contract-entry names-contract names-map ((name "blockstack")) (err 1)));; Same command, using a shorthand for constructing the tuple
fetch-entry
Syntax (fetch-entry map-name key-tuple)
Input type:
MapName, Tuple
Output type:
Optional(Tuple)
The fetch-entry 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! (fetch-entry names-map (tuple (name "blockstack"))) (err 1)) ;; Returns (tuple (id 1337))
(expects! (fetch-entry names-map ((name "blockstack"))) (err 1)) ;; Same command, using a shorthand for constructing the tuple
fetch-var
Syntax (fetch-var var-name)
Input type:
VarName
Output type:
A
The fetch-var function looks up and returns an entry from a contract’s data map. The value is looked up using var-name.
Example
(fetch-var cursor) ;; Returns cursor
filter
Syntax (filter func list)
Input type:
Function(A) -> bool, (list A)
Output type:
(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 type:
Function(A, B) -> B, (list A)
Output type:
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
get-block-info
Syntax (get-block-info prop-name block-height-expr)
Input type:
BlockInfoPropertyName, BlockHeightInt
Output type:
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 type:
KeyName and Tuple | Optional(Tuple)
Output type:
AnyType
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 (fetch-entry names-map (tuple (name "blockstack")))) ;; Returns (some 1337)
(get id (fetch-entry names-map (tuple (name "non-existent")))) ;; Returns (none)
hash160
Syntax (hash160 value)
Input type:
buff|int
Output type:
(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 type:
bool, A, A
Output type:
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
insert-entry!
Syntax (insert-entry! map-name key-tuple value-tuple)
Input type:
MapName, TupleA, TupleB
Output type:
bool
The insert-entry! 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
(insert-entry! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'true
(insert-entry! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'false
(insert-entry! names-map ((name "blockstack")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple
is-none?
Syntax (is-none? value)
Input type:
Optional(A)
Output type:
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 (fetch-entry names-map (tuple (name "blockstack"))))) ;; Returns 'false
(is-none? (get id (fetch-entry names-map (tuple (name "non-existant"))))) ;; Returns 'true
is-ok?
Syntax (is-ok? value)
Input type:
Response(A,B)
Output type:
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 type:
buff|int
Output type:
(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-body)
Input type:
((name2 AnyType) (name2 AnyType) ...), A
Output type:
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 and return the value of expr-body.
Example
(let ((a 2) (b (+ 5 6 7))) (+ a b)) ;; Returns 20
list
Syntax (list expr1 expr2 expr3 ...)
Input type:
A, ...
Output type:
(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
Syntax (map func list)
Input type:
Function(A) -> B, (list A)
Output type:
(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 type:
int, int
Output type:
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
not
Syntax (not b1)
Input type:
bool
Output type:
bool
Returns the inverse of the boolean input.
Example
(not 'true) ;; Returns 'false
(not (eq? 1 2)) ;; Returns 'true
ok
Syntax (ok value)
Input type:
A
Output type:
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 type:
bool, ...
Output type:
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 type:
int, int
Output type:
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
Syntax (print expr)
Input type:
A
Output type:
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
set-entry!
Syntax (set-entry! map-name key-tuple value-tuple)
Input type:
MapName, TupleA, TupleB
Output type:
bool
The set-entry! 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
(set-entry! names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Returns 'true
(set-entry! names-map ((name "blockstack")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple
set-var!
Syntax (set-var! var-name expr1)
Input type:
VarName, AnyType
Output type:
bool
The set-var! function sets the value associated with the input variable to the inputted value.
Example
(set-var! cursor (+ cursor 1)) ;; Returns 'true
sha256
Syntax (sha256 value)
Input type:
buff|int
Output type:
(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
tuple
Syntax (tuple ((key0 expr0) (key1 expr1) ...))
Input type:
(list (KeyName AnyType))
Output type:
Tuple
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))
xor
Syntax (xor i1 i2)
Input type:
int, int
Output type:
int
Returns the result of bitwise exclusive or’ing i1 with i2.
Example
(xor 1 2) ;; Returns 3
(xor 120 280) ;; Returns 352
