Functions
Function reference
- (subtract)
Signature: (- i1 i2...)
Input: int, ... | uint, ...
Output: int | uint
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(- ) ;; Returns 0(- ) ;; Returns -3
* (multiply)
Signature: (* i1 i2...)
Input: int, ... | uint, ...
Output: int | uint
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(* ) ;; Returns 6(* ) ;; Returns 10(* ) ;; Returns 8
/ (divide)
Signature: (/ i1 i2...)
Input: int, ... | uint, ...
Output: int | uint
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(/ ) ;; Returns 0(/ ) ;; Returns 2(/ ) ;; Returns 1
+ (add)
Signature: (+ i1 i2...)
Input: int, ... | uint, ...
Output: int | uint
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(+ ) ;; Returns 6
< (less than)
Signature: (< i1 i2)
Input: int, int | uint, uint
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(< ) ;; Returns true(< ) ;; Returns false
<= (less than or equal)
Signature: (<= i1 i2)
Input: int, int | uint, uint
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(<= ) ;; Returns true(<= ) ;; Returns false
> (greater than)
Signature: (> i1 i2)
Input: int, int | uint, uint
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(> ) ;; Returns false(> ) ;; Returns true
>= (greater than or equal)
Signature: (>= i1 i2)
Input: int, int | uint, uint
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(>= ) ;; Returns true(>= ) ;; Returns true
and
Signature: (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 (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false (and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true(and ) ;; Returns false(and (is-eq (+ ) ) (is-eq )) ;; Returns false(and (is-eq (+ ) ) (is-eq )) ;; Returns true
append
Signature: (append (list 1 2 3 4) 5)
Input: list A, A
Output: list
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)(append (list ) ) ;; Returns (1 2 3 4 5)
as-contract
Signature: (as-contract expr)
Input: A
Output: 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 tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test
as-max-len?
Signature: (as-max-len? buffer u10)
Input: buff|list, uint
Output: (optional buff|list)
The as-max-len? function takes a length N (must be a literal) and a buffer or list argument, which must be typed as a list
or buffer of length M and outputs that same list or buffer, but typed with max length N.
This function returns an optional type with the resulting sequence. If the input sequence is less than
or equal to the supplied max-len, it returns (some <sequence>), otherwise it returns none.
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? (list ) ) ;; Returns (some (2 2 2))(as-max-len? (list ) ) ;; Returns none
asserts!
Signature: (asserts! bool-expr thrown-value)
Input: bool, C
Output: bool
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(asserts! (is-eq ) (err )) ;; Returns true
at-block
Signature: (at-block id-block-hash expr)
Input: (buff 32), A
Output: A
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(define-data-var data int )(at-block x block-height) ;; Returns u0(at-block (get-block-info? id-header-hash ) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0
begin
Signature: (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.
Note: intermediary statements returning a response type must be checked.
Example
(begin (+ 1 2) 4 5) ;; Returns 5(begin (+ ) ) ;; Returns 5
concat
Signature: (concat buff-a buff-b)
Input: (buff, buff)|(list, list)
Output: buff|list
The concat function takes two buffers or two lists with the same entry type,
and returns a concatenated buffer or list of the same entry type, with max_len = max_len_a + max_len_b.
Example
(concat "hello " "world") ;; Returns "hello world"(concat "hello " "world") ;; Returns "hello world"
contract-call?
Signature: (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 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);; instantiate the sample-contracts/tokens.clar contract first!(as-contract (contract-call? .tokens mint! )) ;; Returns (ok u19)
contract-of
Signature: (contract-of .contract-name)
Input: Trait
Output: principal
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>(use-trait token-a-trait .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
Signature: (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
(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-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: })(default-to (get id (map-get? names-map (tuple (name "blockstack"))))) ;; Returns 1337(default-to (get id (map-get? names-map (tuple (name "non-existant"))))) ;; Returns 0
define-constant
Signature: (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-constant four (+ ))(+ four) ;; Returns 8
define-data-var
Signature: (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-private (set-size (value int)) (var-set size value)) (set-size 1) (set-size 2)(define-data-var size int )(define-private (set-size (value int)) (var-set size value))(set-size )(set-size )
define-fungible-token
Signature: (define-fungible-token token-name <total-supply>)
Input: TokenName, <uint>
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-fungible-token limited-supply-stacks u100)(define-fungible-token stacks)(define-fungible-token limited-supply-stacks )
define-map
Signature: (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-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-map squares { x: int } { square: int })(define-private (add-entry (x int)) (map-insert squares { x: } { square: (* x x) }))(add-entry )(add-entry )(add-entry )(add-entry )(add-entry )
define-non-fungible-token
Signature: (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-non-fungible-token names (buff ))
define-private
Signature: (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-private (max-of (i1 int) (i2 int)) (if (> i i) i i))(max-of ) ;; Returns 6
define-public
Signature: (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-public (hello-world (input int)) (begin (print (+ input)) (ok input)))
define-read-only
Signature: (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))(define-read-only (just-return-one-hundred) (* ))
define-trait
Signature: (define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))
Input: VarName, [MethodSignature]
Output: Not Applicable
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 function arguments 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.
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))))(define-trait token-trait ((transfer? (principal principal uint) (response uint uint)) (get-balance (principal) (response uint uint))))
element-at
Signature: (element-at sequence index)
Input: buff|list A, uint
Output: (optional buff|A)
The element-at function returns the element at index in the provided sequence.
If index is greater than or equal to (len sequence), this function returns none.
For strings and buffers, this function will return 1-length strings or buffers.
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 "blockstack" ) ;; Returns (some "s")(element-at (list ) ) ;; Returns none(element-at (list ) (+ )) ;; Returns (some 4)(element-at "abcd" ) ;; Returns (some "b")(element-at xfb ) ;; Returns (some 0x01)
err
Signature: (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)(err ) ;; Returns (err true)
filter
Signature: (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 (false false)(filter not (list )) ;; Returns (false false)
fold
Signature: (fold func list initial-value)
Input: Function(A, B) -> B, (list A), B
Output: B
The fold special form 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 returned by the successive applications. Note that the first argument is not evaluated thus
has to 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 (fold concat "cdef" "ab") ;; Returns "fedcab" (fold concat (list "cd" "ef") "ab") ;; Returns "efcdab"(fold * (list ) ) ;; Returns 8(fold * (list ) ) ;; Returns 0;; calculates (- 11 (- 7 (- 3 2)))(fold - (list ) ) ;; Returns 5 (fold concat "cdef" "ab") ;; Returns "fedcab"(fold concat (list "cd" "ef") "ab") ;; Returns "efcdab"
ft-burn?
Signature: (ft-burn? token-name amount sender)
Input: TokenName, uint, principal
Output: (response bool uint)
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.
If a non-positive amount is provided to burn, this function returns (err 1). Otherwise, on successfuly burn, it
returns (ok true).
Example
(define-fungible-token stackaroo) (ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) (ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)(define-fungible-token stackaroo)(ft-mint? stackaroo ) ;; Returns (ok true)(ft-burn? stackaroo ) ;; Returns (ok true)
ft-get-balance
Signature: (ft-get-balance token-name principal)
Input: TokenName, principal
Output: uint
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(define-fungible-token stackaroo)(ft-mint? stackaroo )(ft-get-balance stackaroo ) ;; Returns u100
ft-get-supply
Signature: (ft-get-supply token-name)
Input: TokenName
Output: uint
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(define-fungible-token stackaroo)(ft-mint? stackaroo )(ft-get-supply stackaroo) ;; Returns u100
ft-mint?
Signature: (ft-mint? token-name amount recipient)
Input: TokenName, uint, principal
Output: (response bool uint)
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)(define-fungible-token stackaroo)(ft-mint? stackaroo ) ;; Returns (ok true)
ft-transfer?
Signature: (ft-transfer? token-name amount sender recipient)
Input: TokenName, uint, principal, principal
Output: (response bool uint)
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 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)(define-fungible-token stackaroo)(ft-mint? stackaroo )(ft-transfer? stackaroo ) ;; Returns (ok true)(ft-transfer? stackaroo ) ;; Returns (err u1)
get
Signature: (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
(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(define-map names-map { name: (string-ascii ) } { id: int })(map-insert names-map { name: "blockstack" } { id: }) ;; Returns true(get id (tuple (name "blockstack") (id ))) ;; 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?
Signature: (get-block-info? prop-name block-height-expr)
Input: BlockInfoPropertyName, BlockHeightInt
Output: (optional buff) | (optional uint)
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 prior to the current block, the function returns none. The currently available property names
are time, header-hash, burnchain-header-hash, id-header-hash, miner-address, 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, id-header-hash, and vrf-seed properties return a 32-byte buffer.
The miner-address property returns a principal corresponding to the miner of the given block.
The id-header-hash is the block identifier value that must be used as input to the at-block function.
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-block-info? time ) ;; Returns (some u1557860301)(get-block-info? header-hash ) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb)(get-block-info? vrf-seed ) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4)
hash160
Signature: (hash160 value)
Input: buff|uint|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(hash160 ) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f
if
Signature: (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(if ) ;; Returns 1(if (> ) ) ;; Returns 2
impl-trait
Signature: (impl-trait trait-identifier)
Input: TraitIdentifier
Output: Not Applicable
impl-trait can be use for asserting that a contract is fully implementing a given trait.
Additional checks are being performed when the contract is being published, rejecting the deployment if the
contract is violating the trait specification.
Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait).
Like other kinds of definition statements, impl-trait may only be used at the top level of a smart contract
definition (i.e., you cannot put such a statement in the middle of a function body).
Example
(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)(impl-trait .token-a.token-trait)
index-of
Signature: (index-of sequence item)
Input: buff|list A, buff|A
Output: (optional uint)
The index-of function returns the first index at which item can be
found in the provided sequence (using is-eq checks).
If this item is not found in the sequence (or an empty string/buffer is supplied), this
function returns none.
Example
(index-of "blockstack" "b") ;; Returns (some u0) (index-of "blockstack" "k") ;; Returns (some u4) (index-of "blockstack" "") ;; Returns none (index-of (list 1 2 3 4 5) 6) ;; Returns none (index-of 0xfb01 0x01) ;; Returns (some u1)(index-of "blockstack" "b") ;; Returns (some u0)(index-of "blockstack" "k") ;; Returns (some u4)(index-of "blockstack" "") ;; Returns none(index-of (list ) ) ;; Returns none(index-of xfb x) ;; Returns (some u1)
is-eq
Signature: (is-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, (is-eq ...) will not short-circuit. All values supplied to
is-eq must be the same type.
Example
(is-eq 1 1) ;; Returns true (is-eq true false) ;; Returns false (is-eq "abc" 234 234) ;; Throws type error(is-eq ) ;; Returns true(is-eq ) ;; Returns false(is-eq "abc" ) ;; Throws type error
is-err
Signature: (is-err value)
Input: (response A B)
Output: bool
is-err tests a supplied response value, returning true if the response was an err,
and false if it was an ok.
Example
(is-err (ok 1)) ;; Returns false (is-err (err 1)) ;; Returns true(is-err (ok )) ;; Returns false(is-err (err )) ;; Returns true
is-none
Signature: (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
(define-map names-map { name: (string-ascii 12) } { id: int }) (map-set names-map { name: "blockstack" } { id: 1337 }) (is-none (get id (map-get? names-map { name: "blockstack" }))) ;; Returns false (is-none (get id (map-get? names-map { name: "non-existant" }))) ;; Returns true(define-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: })(is-none (get id (map-get? names-map { name: "blockstack" }))) ;; Returns false(is-none (get id (map-get? names-map { name: "non-existant" }))) ;; Returns true
is-ok
Signature: (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(is-ok (ok )) ;; Returns true(is-ok (err )) ;; Returns false
is-some
Signature: (is-some value)
Input: (optional A)
Output: bool
is-some tests a supplied option value, returning true if the option value is (some ...),
and false if it is a none.
Example
(define-map names-map { name: (string-ascii 12) } { id: int }) (map-set names-map { name: "blockstack" } { id: 1337 }) (is-some (get id (map-get? names-map { name: "blockstack" }))) ;; Returns true (is-some (get id (map-get? names-map { name: "non-existant" }))) ;; Returns false(define-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: })(is-some (get id (map-get? names-map { name: "blockstack" }))) ;; Returns true(is-some (get id (map-get? names-map { name: "non-existant" }))) ;; Returns false
keccak256
Signature: (keccak256 value)
Input: buff|uint|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(keccak256 ) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4
len
Signature: (len buffer)
Input: buff|list
Output: uint
The len function returns the length of a given buffer or list.
Example
(len "blockstack") ;; Returns u10 (len (list 1 2 3 4 5)) ;; Returns u5(len "blockstack") ;; Returns u10(len (list )) ;; Returns u5
let
Signature: (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.
let bindings are sequential: when a let binding is evaluated, it may refer to prior binding.
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.
Note: intermediary statements returning a response type must be checked
Example
(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 (let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23(let ((a ) (b (+ ))) (print a) (print b) (+ a b)) ;; Returns 20(let ((a ) (c (+ a )) (d (+ c )) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23
list
Signature: (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)(list (+ ) ) ;; Returns (3 4 5)
log2
Signature: (log2 n)
Input: int | uint
Output: int | uint
Returns the power to which the number 2 must be raised to to obtain the value n, rounded down to the nearest integer. Fails on a negative numbers.
Example
(log2 u8) ;; Returns u3 (log2 8) ;; Returns 3 (log2 u1) ;; Returns u0 (log2 1000) ;; Returns 9(log ) ;; Returns u3(log ) ;; Returns 3(log ) ;; Returns u0(log ) ;; Returns 9
map
Signature: (map func list-A list-B ... list-N)
Input: Function(A, B, ..., N) -> X, (list A1 A2 ... Am), (list B1 B2 ... Bm), ..., (list N1 N2 ... Nm)
Output: (list X)
The map function applies the input function func to each element of the
input lists, and outputs a list containing the outputs from those function applications.
Example
(map not (list true false true false)) ;; Returns (false true false true) (map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9)(map not (list )) ;; Returns (false true false true)(map + (list ) (list ) (list )) ;; Returns (3 6 9)
map-delete
Signature: (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
(define-map names-map { name: (string-ascii 10) } { id: int }) (map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true (map-delete names-map { name: "blockstack" }) ;; Returns true (map-delete names-map { name: "blockstack" }) ;; Returns false (map-delete names-map (tuple (name "blockstack"))) ;; Same command, using a shorthand for constructing the tuple(define-map names-map { name: (string-ascii ) } { id: int })(map-insert names-map { name: "blockstack" } { id: }) ;; Returns true(map-delete names-map { name: "blockstack" }) ;; Returns true(map-delete names-map { name: "blockstack" }) ;; Returns false(map-delete names-map (tuple (name "blockstack"))) ;; Same command, using a shorthand for constructing the tuple
map-get?
Signature: (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
(define-map names-map { name: (string-ascii 10) } { id: int }) (map-set names-map { name: "blockstack" } { id: 1337 }) (map-get? names-map (tuple (name "blockstack"))) ;; Returns (some (tuple (id 1337))) (map-get? names-map { name: "blockstack" }) ;; Same command, using a shorthand for constructing the tuple(define-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: })(map-get? names-map (tuple (name "blockstack"))) ;; Returns (some (tuple (id 1337)))(map-get? names-map { name: "blockstack" }) ;; Same command, using a shorthand for constructing the tuple
map-insert
Signature: (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.
Note: the value-tuple requires 1 additional byte for storage in the materialized blockchain state,
and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1.
Example
(define-map names-map { name: (string-ascii 10) } { id: int }) (map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true (map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns false (map-insert names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple(define-map names-map { name: (string-ascii ) } { id: int })(map-insert names-map { name: "blockstack" } { id: }) ;; Returns true(map-insert names-map { name: "blockstack" } { id: }) ;; Returns false(map-insert names-map (tuple (name "blockstack")) (tuple (id ))) ;; Same command, using a shorthand for constructing the tuple
map-set
Signature: (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.
Note: the value-tuple requires 1 additional byte for storage in the materialized blockchain state,
and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1.
Example
(define-map names-map { name: (string-ascii 10) } { id: int }) (map-set names-map { name: "blockstack" } { id: 1337 }) ;; Returns true (map-set names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple(define-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: }) ;; Returns true(map-set names-map (tuple (name "blockstack")) (tuple (id ))) ;; Same command, using a shorthand for constructing the tuple
match
Signature: (match opt-input some-binding-name some-branch none-branch) |
(match-resp input ok-binding-name ok-branch err-binding-name err-branch)
Input: (optional A) name expression expression | (response A B) name expression name expression
Output: C
The match function is used to test and destructure optional and response types.
If the input is an optional, it tests whether the provided
input is a some or none option, and evaluates some-branch or
none-branch in each respective case.
Within the some-branch, the contained value of the input
argument is bound to the provided some-binding-name name.
Only one of the branches will be evaluated (similar to if statements).
If the input is a response, it tests whether the provided input is
an ok or err response type, and evaluates ok-branch or
err-branch in each respective case.
Within the ok-branch, the contained ok value of the input
argument is bound to the provided ok-binding-name name.
Within the err-branch, the contained err value of the input
argument is bound to the provided err-binding-name name.
Only one of the branches will be evaluated (similar to if statements).
Note: Type checking requires that the type of both the ok and err parts of the
response object be determinable. For situations in which one of the parts of a response
is untyped, you should use unwrap-panic or unwrap-err-panic instead of match.
Example
(define-private (add-10 (x (optional int))) (match x value (+ 10 value) 10)) (add-10 (some 5)) ;; Returns 15 (add-10 none) ;; Returns 10 (define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) (match x value (+ to-add value) err-value (err err-value))) (add-or-pass-err (ok 5) 20) ;; Returns 25 (add-or-pass-err (err "ERROR") 20) ;; Returns (err "ERROR")(define-private (add (x (optional int))) (match x value (+ value) ))(add (some )) ;; Returns 15(add none) ;; Returns 10(define-private (add-or-pass-err (x (response int (string-ascii ))) (to-add int)) (match x value (+ to-add value) err-value (err err-value)))(add-or-pass-err (ok ) ) ;; Returns 25(add-or-pass-err (err "ERROR") ) ;; Returns (err "ERROR")
merge
Signature: (merge tuple { key1: val1 })
Input: tuple, tuple
Output: tuple
The merge function returns a new tuple with the combined fields, without mutating the supplied tuples.
Example
(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) (map-insert users { id: 1337 } { name: "john", address: none }) ;; Returns true (let ((user (unwrap-panic (map-get? users { id: 1337 })))) (merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name "john"))(define-map users { id: int } { name: (string-ascii ), address: (optional principal) })(map-insert users { id: } { name: "john", address: none }) ;; Returns true(let ((user (unwrap-panic (map-get? users { id: })))) (merge user { address: (some ) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name "john"))
mod
Signature: (mod i1 i2)
Input: int, int | uint, uint
Output: int | uint
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 2 (mod 5 2) ;; Returns 1 (mod 7 1) ;; Returns 0(mod ) ;; Returns 2(mod ) ;; Returns 1(mod ) ;; Returns 0
nft-burn?
Signature: (nft-burn? asset-class asset-identifier recipient)
Input: AssetName, A, principal
Output: (response bool uint)
nft-burn? is used to burn an asset and remove that asset's owner from 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 doesn't exist, this function will return an error with the following error code:
(err u1)
Otherwise, on successfuly burn, it returns (ok true).
Example
(define-non-fungible-token stackaroo (string-ascii 40)) (nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) (nft-burn? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)(define-non-fungible-token stackaroo (string-ascii ))(nft-mint? stackaroo "Roo" ) ;; Returns (ok true)(nft-burn? stackaroo "Roo" ) ;; Returns (ok true)
nft-get-owner?
Signature: (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 (string-ascii 40)) (nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) (nft-get-owner? stackaroo "Roo") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) (nft-get-owner? stackaroo "Too") ;; Returns none(define-non-fungible-token stackaroo (string-ascii ))(nft-mint? stackaroo "Roo" )(nft-get-owner? stackaroo "Roo") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)(nft-get-owner? stackaroo "Too") ;; Returns none
nft-mint?
Signature: (nft-mint? asset-class asset-identifier recipient)
Input: AssetName, A, principal
Output: (response bool uint)
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 u1)
Otherwise, on successfuly mint, it returns (ok true).
Example
(define-non-fungible-token stackaroo (string-ascii 40)) (nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)(define-non-fungible-token stackaroo (string-ascii ))(nft-mint? stackaroo "Roo" ) ;; Returns (ok true)
nft-transfer?
Signature: (nft-transfer? asset-class asset-identifier sender recipient)
Input: AssetName, A, principal, principal
Output: (response bool uint)
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 u1) -- sender does not own the asset
(err u2) -- sender and recipient are the same principal
(err u3) -- asset identified by asset-identifier does not exist
Example
(define-non-fungible-token stackaroo (string-ascii 40)) (nft-mint? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) (nft-transfer? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) (nft-transfer? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) (nft-transfer? stackaroo "Stacka" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3)(define-non-fungible-token stackaroo (string-ascii ))(nft-mint? stackaroo "Roo" )(nft-transfer? stackaroo "Roo" ) ;; Returns (ok true)(nft-transfer? stackaroo "Roo" ) ;; Returns (err u1)(nft-transfer? stackaroo "Stacka" ) ;; Returns (err u3)
not
Signature: (not b1)
Input: bool
Output: bool
Returns the inverse of the boolean input.
Example
(not true) ;; Returns false (not (is-eq 1 2)) ;; Returns true(not ) ;; Returns false(not (is-eq )) ;; Returns true
ok
Signature: (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)(ok ) ;; Returns (ok 1)
or
Signature: (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 (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true (or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false (or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true(or ) ;; Returns true(or (is-eq (+ ) ) (is-eq )) ;; Returns true(or (is-eq (+ ) ) (is-eq )) ;; Returns false(or (is-eq (+ ) ) (is-eq )) ;; Returns true
pow
Signature: (pow i1 i2)
Input: int, int | uint, uint
Output: int | uint
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(pow ) ;; Returns 8(pow ) ;; Returns 4(pow ) ;; Returns 7
principal-of?
Signature: (principal-of? public-key)
Input: (buff 33)
Output: (response principal uint)
The principal-of? function returns the principal derived from the provided public key.
If the public-key is invalid, it will return the error code (err u1)..
Example
(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP)(principal-of? xadbdebfbdbcfddcaecedbeba) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP)
Signature: (print expr)
Input: A
Output: A
The print function evaluates and returns its input expression. On Stacks 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(print (+ )) ;; Returns 6
secp256k1-recover?
Signature: (secp256k1-recover? message-hash signature)
Input: (buff 32), (buff 65)
Output: (response (buff 33) uint)
The secp256k1-recover? function recovers the public key used to sign the message which sha256 is message-hash
with the provided signature.
If the signature does not match, it will return the error code (err u1)..
If the signature is invalid, it will return the error code (err u2)..
The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes.
Example
(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110)(secpk-recover? xdebebecebeacdedeedaecf xebebdebeeeebbfccdccbfccaafcfcfdafeecacda) ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110)
secp256k1-verify
Signature: (secp256k1-verify message-hash signature public-key)
Input: (buff 32), (buff 64) | (buff 65), (buff 33)
Output: bool
The secp256k1-verify function verifies that the provided signature of the message-hash
was signed with the private key that generated the public key.
The message-hash is the sha256 of the message.
The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes.
Example
(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true (secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false(secpk-verify xdebebecebeacdedeedaecf xebebdebeeeebbfccdccbfccaafcfcfdafeecacda xadbdebfbdbcfddcaecedbeba) ;; Returns true(secpk-verify xdebebecebeacdedeedaecf xebebdebeeeebbfccdccbfccaafcfcfdafeecacda xadbdebfbdbcfddcaecedbeba) ;; Returns true(secpk-verify x x xadbdebfbdbcfddcaecedbeba) ;; Returns false
sha256
Signature: (sha256 value)
Input: buff|uint|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(sha256 ) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb
sha512
Signature: (sha512 value)
Input: buff|uint|int
Output: (buff 64)
The sha512 function computes SHA512(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
(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34(sha512 ) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34
sha512/256
Signature: (sha512/256 value)
Input: buff|uint|int
Output: (buff 32)
The sha512/256 function computes SHA512/256(x) (the SHA512 algorithm with the 512/256 initialization vector, truncated
to 256 bits) of the inputted value.
If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the
integer.
Example
(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86(sha512/256 ) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86
some
Signature: (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(some ) ;; Returns (some 1)(is-none (some )) ;; Returns false
sqrti
Signature: (sqrti n)
Input: int | uint
Output: int | uint
Returns the largest integer that is less than or equal to the square root of n. Fails on a negative numbers.
Example
(sqrti u11) ;; Returns u3 (sqrti 1000000) ;; Returns 1000 (sqrti u1) ;; Returns u1 (sqrti 0) ;; Returns 0(sqrti ) ;; Returns u3(sqrti ) ;; Returns 1000(sqrti ) ;; Returns u1(sqrti ) ;; Returns 0
stx-burn?
Signature: (stx-burn? amount sender)
Input: uint, principal
Output: (response bool uint)
stx-burn? debits the sender principal's STX holdings by amount, destroying
the STX. The sender principal must be equal to the current context's tx-sender.
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 u3) -- amount to send is non-positive
(err u4) -- the sender principal is not the current tx-sender
Example
(as-contract (stx-burn? u60 tx-sender)) ;; Returns (ok true) (as-contract (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4)(as-contract (stx-burn? tx-sender)) ;; Returns (ok true)(as-contract (stx-burn? )) ;; Returns (err u4)
stx-get-balance
Signature: (stx-get-balance owner)
Input: principal
Output: uint
stx-get-balance is used to query the STX balance of the owner principal.
This function returns the STX balance of the owner principal. In the event that the owner
principal isn't materialized, it returns 0.
Example
(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 (stx-get-balance (as-contract tx-sender)) ;; Returns u1000(stx-get-balance ) ;; Returns u0(stx-get-balance (as-contract tx-sender)) ;; Returns u1000
stx-transfer?
Signature: (stx-transfer? amount sender recipient)
Input: uint, principal, principal
Output: (response bool uint)
stx-transfer? is used to increase the STX balance for the recipient principal
by debiting the sender principal. The sender principal must be equal to the current context's tx-sender.
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
(err u4) -- the sender principal is not the current tx-sender
Example
(as-contract (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) (as-contract (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4)(as-contract (stx-transfer? tx-sender )) ;; Returns (ok true)(as-contract (stx-transfer? tx-sender)) ;; Returns (err u4)
to-int
Signature: (to-int u)
Input: uint
Output: int
Tries to convert the uint argument to an int. Will cause a runtime error and abort if the supplied argument is >= pow(2, 127)
Example
(to-int u238) ;; Returns 238(to-int ) ;; Returns 238
to-uint
Signature: (to-uint i)
Input: int
Output: uint
Tries to convert the int argument to a uint. Will cause a runtime error and abort if the supplied argument is negative.
Example
(to-uint 238) ;; Returns u238(to-uint ) ;; Returns u238
try!
Signature: (try! option-input)
Input: (optional A) | (response A B)
Output: A
The try! function attempts to 'unpack' the first argument: if the argument is
an option type, and the argument is a (some ...) option, try! returns the inner value of the
option. If the argument is a response type, and the argument is an (ok ...) response, try! returns
the inner value of the ok. If the supplied argument is either an (err ...) or a none value,
try! returns either none or the (err ...) value from the current function and exits the current control-flow.
Example
(define-map names-map { name: (string-ascii 12) } { id: int }) (map-set names-map { name: "blockstack" } { id: 1337 }) (try! (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337)) (define-private (checked-even (x int)) (if (is-eq (mod x 2) 0) (ok x) (err false))) (define-private (double-if-even (x int)) (ok (* 2 (try! (checked-even x))))) (double-if-even 10) ;; Returns (ok 20) (double-if-even 3) ;; Returns (err false)(define-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: })(try! (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337))(define-private (checked-even (x int)) (if (is-eq (mod x ) ) (ok x) (err )))(define-private (double-if-even (x int)) (ok (* (try! (checked-even x)))))(double-if-even ) ;; Returns (ok 20)(double-if-even ) ;; Returns (err false)
tuple
Signature: (tuple (key0 expr0) (key1 expr1) ...)
Input: (key-name A), (key-name-2 B), ...
Output: (tuple (key-name A) (key-name-2 B) ...)
The tuple special form 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.
There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}
Example
(tuple (name "blockstack") (id 1337)) ;; using tuple {name: "blockstack", id: 1337} ;; using curly brackets(tuple (name "blockstack") (id )) ;; using tuple {name: "blockstack", id: 1337} ;; using curly brackets
unwrap-err-panic
Signature: (unwrap-err-panic response-input)
Input: (response A B)
Output: B
The unwrap-err function attempts to 'unpack' the first argument: if the argument
is an (err ...) response, unwrap returns the inner value of the err.
If the supplied argument is an (ok ...) value,
unwrap-err throws a runtime error, aborting any further processing of the current transaction.
Example
(unwrap-err-panic (err 1)) ;; Returns 1 (unwrap-err-panic (ok 1)) ;; Throws a runtime exception(unwrap-err-panic (err )) ;; Returns 1(unwrap-err-panic (ok )) ;; Throws a runtime exception
unwrap-err!
Signature: (unwrap-err! response-input thrown-value)
Input: (response A B), C
Output: B
The unwrap-err! function attempts to 'unpack' the first argument: if the argument
is an (err ...) response, unwrap-err! returns the inner value of the err.
If the supplied argument is an (ok ...) value,
unwrap-err! returns thrown-value from the current function and exits the current control-flow.
Example
(unwrap-err! (err 1) false) ;; Returns 1(unwrap-err! (err ) ) ;; Returns 1
unwrap-panic
Signature: (unwrap-panic option-input)
Input: (optional A) | (response A B)
Output: A
The unwrap function attempts to 'unpack' its argument: if the argument is
an option type, and the argument is a (some ...) option, this function returns the inner value of the
option. If the argument is a response type, and the argument is an (ok ...) response, it returns
the inner value of the ok. If the supplied argument is either an (err ...) or a (none) value,
unwrap throws a runtime error, aborting any further processing of the current transaction.
Example
(define-map names-map { name: (string-ascii 12) } { id: int }) (map-set names-map { name: "blockstack" } { id: 1337 }) (unwrap-panic (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337)) (unwrap-panic (map-get? names-map { name: "non-existant" })) ;; Throws a runtime exception(define-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: })(unwrap-panic (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337))(unwrap-panic (map-get? names-map { name: "non-existant" })) ;; Throws a runtime exception
unwrap!
Signature: (unwrap! option-input thrown-value)
Input: (optional A) | (response A B), C
Output: A
The unwrap! function attempts to 'unpack' the first argument: if the argument is
an option type, and the argument is a (some ...) option, unwrap! returns the inner value of the
option. If the argument is a response type, and the argument is an (ok ...) response, unwrap! returns
the inner value of the ok. If the supplied argument is either an (err ...) or a (none) value,
unwrap! returns thrown-value from the current function and exits the current control-flow.
Example
(define-map names-map { name: (string-ascii 12) } { id: int }) (map-set names-map { name: "blockstack" } { id: 1337 }) (define-private (get-name-or-err (name (string-ascii 12))) (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) (ok raw-name))) (get-name-or-err "blockstack") ;; Returns (ok (tuple (id 1337))) (get-name-or-err "non-existant") ;; Returns (err 1)(define-map names-map { name: (string-ascii ) } { id: int })(map-set names-map { name: "blockstack" } { id: })(define-private (get-name-or-err (name (string-ascii ))) (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err )))) (ok raw-name)))(get-name-or-err "blockstack") ;; Returns (ok (tuple (id 1337)))(get-name-or-err "non-existant") ;; Returns (err 1)
use-trait
Signature: (use-trait trait-alias trait-identifier)
Input: VarName, TraitIdentifier
Output: Not Applicable
use-trait is used to bring a trait, defined in another contract, to the current contract. Subsequent
references to an imported trait are signaled with the syntax <trait-alias>.
Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait).
Like other kinds of definition statements, use-trait may only be used at the top level of a smart contract
definition (i.e., you cannot put such a statement in the middle of a function body).
Example
(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (forward-get-balance (user principal) (contract <token-a-trait>)) (begin (ok 1)))(use-trait token-a-trait .token-a.token-trait)(define-public (forward-get-balance (user principal) (contract <token-a-trait>)) (begin (ok )))
var-get
Signature: (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
(define-data-var cursor int 6) (var-get cursor) ;; Returns 6(define-data-var cursor int )(var-get cursor) ;; Returns 6
var-set
Signature: (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
(define-data-var cursor int 6) (var-get cursor) ;; Returns 6 (var-set cursor (+ (var-get cursor) 1)) ;; Returns true (var-get cursor) ;; Returns 7(define-data-var cursor int )(var-get cursor) ;; Returns 6(var-set cursor (+ (var-get cursor) )) ;; Returns true(var-get cursor) ;; Returns 7
xor
Signature: (xor i1 i2)
Input: int, int | uint, uint
Output: int | uint
Returns the result of bitwise exclusive or'