mirror of https://github.com/lukechilds/docs.git
Moxiegirl
5 years ago
committed by
GitHub
GitHub
3 changed files with 549 additions and 425 deletions
@ -1,402 +1,502 @@ |
|||
[ |
|||
{ |
|||
"name": "+ (add)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(+ i1 i2...)", |
|||
"description": "Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error.", |
|||
"example": "(+ 1 2 3) ;; Returns 6" |
|||
}, |
|||
{ |
|||
"name": "- (subtract)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(- i1 i2...)", |
|||
"description": "Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error.", |
|||
"example": "(- 2 1 1) ;; Returns 0\n(- 0 3) ;; Returns -3\n" |
|||
}, |
|||
{ |
|||
"name": "* (multiply)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(* i1 i2...)", |
|||
"description": "Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error.", |
|||
"example": "(* 2 3) ;; Returns 6\n(* 5 2) ;; Returns 10\n(* 2 2 2) ;; Returns 8\n" |
|||
}, |
|||
{ |
|||
"name": "/ (divide)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(/ i1 i2...)", |
|||
"description": "Integer divides a variable number of integer inputs and returns the result. In the event of division by zero, throws a runtime error.", |
|||
"example": "(/ 2 3) ;; Returns 0\n(/ 5 2) ;; Returns 2\n(/ 4 2 2) ;; Returns 1\n" |
|||
}, |
|||
{ |
|||
"name": ">= (greater than or equal)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(>= i1 i2)", |
|||
"description": "Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise.", |
|||
"example": "(>= 1 1) ;; Returns 'true\n(>= 5 2) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "<= (less than or equal)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(> i1 i2)", |
|||
"description": "Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise.", |
|||
"example": "(<= 1 1) ;; Returns 'true\n(<= 5 2) ;; Returns 'false\n" |
|||
}, |
|||
{ |
|||
"name": "< (less than)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(< i1 i2)", |
|||
"description": "Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise.", |
|||
"example": "(< 1 2) ;; Returns 'true\n(< 5 2) ;; Returns 'false\n" |
|||
}, |
|||
{ |
|||
"name": "> (greater than)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(> i1 i2)", |
|||
"description": "Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise.", |
|||
"example": "(> 1 2) ;; Returns 'false\n(> 5 2) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "mod", |
|||
"input_type": "int, int", |
|||
"output_type": "int", |
|||
"signature": "(mod i1 i2)", |
|||
"description": "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\n(mod 5 2) ;; Returns 1\n(mod 7 1) ;; Returns 0\n" |
|||
}, |
|||
{ |
|||
"name": "pow", |
|||
"input_type": "int, int", |
|||
"output_type": "int", |
|||
"signature": "(pow i1 i2)", |
|||
"description": "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\n(pow 2 2) ;; Returns 4\n(pow 7 1) ;; Returns 7\n" |
|||
}, |
|||
{ |
|||
"name": "xor", |
|||
"input_type": "int, int", |
|||
"output_type": "int", |
|||
"signature": "(xor i1 i2)", |
|||
"description": "Returns the result of bitwise exclusive or'ing `i1` with `i2`.", |
|||
"example": "(xor 1 2) ;; Returns 3\n(xor 120 280) ;; Returns 352\n" |
|||
}, |
|||
{ |
|||
"name": "and", |
|||
"input_type": "bool, ...", |
|||
"output_type": "bool", |
|||
"signature": "(and b1 b2 ...)", |
|||
"description": "Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated.", |
|||
"example": "(and 'true 'false) ;; Returns 'false\n(and (eq? (+ 1 2) 1) (eq? 4 4)) ;; Returns 'false\n(and (eq? (+ 1 2) 3) (eq? 4 4)) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "or", |
|||
"input_type": "bool, ...", |
|||
"output_type": "bool", |
|||
"signature": "(or b1 b2 ...)", |
|||
"description": "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\n(or (eq? (+ 1 2) 1) (eq? 4 4)) ;; Returns 'true\n(or (eq? (+ 1 2) 1) (eq? 3 4)) ;; Returns 'false\n(or (eq? (+ 1 2) 3) (eq? 4 4)) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "not", |
|||
"input_type": "bool", |
|||
"output_type": "bool", |
|||
"signature": "(not b1)", |
|||
"description": "Returns the inverse of the boolean input.", |
|||
"example": "(not 'true) ;; Returns 'false\n(not (eq? 1 2)) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "eq?", |
|||
"input_type": "A, A, ...", |
|||
"output_type": "bool", |
|||
"signature": "(eq? v1 v2...)", |
|||
"description": "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\n(eq? 1 'false) ;; Returns 'false\n(eq? \"abc\" 234 234) ;; Returns 'false\n" |
|||
}, |
|||
{ |
|||
"name": "if", |
|||
"input_type": "bool, A, A", |
|||
"output_type": "A", |
|||
"signature": "(if bool1 expr1 expr2)", |
|||
"description": "The `if` function admits a boolean argument and two expressions \nwhich must return the same type. In the case that the boolean input is `true`, the\n`if` function evaluates and returns `expr1`. If the boolean input is `false`, the\n`if` function evaluates and returns `expr2`.", |
|||
"example": "(if true 1 2) ;; Returns 1\n(if (> 1 2) 1 2) ;; Returns 2" |
|||
}, |
|||
{ |
|||
"name": "let", |
|||
"input_type": "((name2 AnyType) (name2 AnyType) ...), A", |
|||
"output_type": "A", |
|||
"signature": "(let ((name1 expr1) (name2 expr2) ...) expr-body)", |
|||
"description": "The `let` function accepts a list of `variable name` and `expression` pairs,\nevaluating each expression and _binding_ it to the corresponding variable name. The _context_\ncreated 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" |
|||
}, |
|||
{ |
|||
"name": "fetch-var", |
|||
"input_type": "VarName", |
|||
"output_type": "A", |
|||
"signature": "(fetch-var var-name)", |
|||
"description": "The `fetch-var` function looks up and returns an entry from a contract's data map.\nThe value is looked up using `var-name`.", |
|||
"example": "(fetch-var cursor) ;; Returns cursor" |
|||
}, |
|||
{ |
|||
"name": "set-var!", |
|||
"input_type": "VarName, AnyType", |
|||
"output_type": "bool", |
|||
"signature": "(set-var! var-name expr1)", |
|||
"description": "The `set-var!` function sets the value associated with the input variable to the \ninputted value.", |
|||
"example": "(set-var! cursor (+ cursor 1)) ;; Returns 'true" |
|||
}, |
|||
{ |
|||
"name": "map", |
|||
"input_type": "Function(A) -> B, (list A)", |
|||
"output_type": "(list B)", |
|||
"signature": "(map func list)", |
|||
"description": "The `map` function applies the input function `func` to each element of the\ninput 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" |
|||
}, |
|||
{ |
|||
"name": "fold", |
|||
"input_type": "Function(A, B) -> B, (list A)", |
|||
"output_type": "B", |
|||
"signature": "(fold func list initial-value)", |
|||
"description": "The `fold` function applies the input function `func` to each element of the\ninput list _and_ the output of the previous application of the `fold` function. When invoked on\nthe first list element, it uses the `initial-value` as the second input. `fold` returns the last\nvalue return by the successive applications.", |
|||
"example": "(fold * (list 2 2 2) 1) ;; Returns 8\n(fold * (list 2 2 2) 0) ;; Returns 0" |
|||
}, |
|||
{ |
|||
"name": "list", |
|||
"input_type": "A, ...", |
|||
"output_type": "(list A)", |
|||
"signature": "(list expr1 expr2 expr3 ...)", |
|||
"description": "The `list` function constructs a list composed of the inputted values. Each\nsupplied value must be of the same type.", |
|||
"example": "(list (+ 1 2) 4 5) ;; Returns [3 4 5]" |
|||
}, |
|||
{ |
|||
"name": "fetch-entry", |
|||
"input_type": "MapName, Tuple", |
|||
"output_type": "Optional(Tuple)", |
|||
"signature": "(fetch-entry map-name key-tuple)", |
|||
"description": "The `fetch-entry` function looks up and returns an entry from a contract's data map.\nThe value is looked up using `key-tuple`.\nIf there is no value associated with that key in the data map, the function returns a (none) option. Otherwise,\nit returns (some value)", |
|||
"example": "(expects! (fetch-entry names-map (tuple (name \"blockstack\"))) (err 1)) ;; Returns (tuple (id 1337))\n(expects! (fetch-entry names-map ((name \"blockstack\"))) (err 1)) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "fetch-contract-entry", |
|||
"input_type": "ContractName, MapName, Tuple", |
|||
"output_type": "Optional(Tuple)", |
|||
"signature": "(fetch-contract-entry contract-name map-name key-tuple)", |
|||
"description": "The `fetch-contract-entry` function looks up and returns an entry from a\ncontract other than the current contract's data map. The value is looked up using `key-tuple`.\nIf there is no value associated with that key in the data map, the function returns a (none) option. Otherwise,\nit returns (some value).", |
|||
"example": "(expects! (fetch-contract-entry names-contract names-map (tuple (name \"blockstack\")) (err 1))) ;; Returns (tuple (id 1337))\n(expects! (fetch-contract-entry names-contract names-map ((name \"blockstack\")) (err 1)));; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "set-entry!", |
|||
"input_type": "MapName, TupleA, TupleB", |
|||
"output_type": "bool", |
|||
"signature": "(set-entry! map-name key-tuple value-tuple)", |
|||
"description": "The `set-entry!` function sets the value associated with the input key to the \ninputted value. This function performs a _blind_ update; whether or not a value is already associated\nwith the key, the function overwrites that existing association.", |
|||
"example": "(set-entry! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'true\n(set-entry! names-map ((name \"blockstack\")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "insert-entry!", |
|||
"input_type": "MapName, TupleA, TupleB", |
|||
"output_type": "bool", |
|||
"signature": "(insert-entry! map-name key-tuple value-tuple)", |
|||
"description": "The `insert-entry!` function sets the value associated with the input key to the \ninputted value if and only if there is not already a value associated with the key in the map.\nIf an insert occurs, the function returns `true`. If a value already existed for\nthis key in the data map, the function returns `false`.", |
|||
"example": "(insert-entry! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'true\n(insert-entry! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'false\n(insert-entry! names-map ((name \"blockstack\")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "delete-entry!", |
|||
"input_type": "MapName, Tuple", |
|||
"output_type": "bool", |
|||
"signature": "(delete-entry! map-name key-tuple)", |
|||
"description": "The `delete-entry!` function removes the value associated with the input key for\nthe given map. If an item exists and is removed, the function returns `true`.\nIf 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\n(delete-entry! names-map (tuple (name \"blockstack\"))) ;; Returns 'false\n(delete-entry! names-map ((name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "tuple", |
|||
"input_type": "(list (KeyName AnyType))", |
|||
"output_type": "Tuple", |
|||
"signature": "(tuple ((key0 expr0) (key1 expr1) ...))", |
|||
"description": "The `tuple` function constructs a typed tuple from the supplied key and expression pairs.\nA `get` function can use typed tuples as input to select specific values from a given tuple.\nKey names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and\nassociated with the expressions' paired key name.", |
|||
"example": "(tuple (name \"blockstack\") (id 1337))" |
|||
}, |
|||
{ |
|||
"name": "get", |
|||
"input_type": "KeyName and Tuple | Optional(Tuple)", |
|||
"output_type": "AnyType", |
|||
"signature": "(get key-name tuple)", |
|||
"description": "The `get` function fetches the value associated with a given key from the supplied typed tuple.\nIf an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in\nthe tuple. If the supplied option is a `(none)` option, get returns `(none)`.", |
|||
"example": "(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337\n(get id (fetch-entry names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337)\n(get id (fetch-entry names-map (tuple (name \"non-existent\")))) ;; Returns (none)\n" |
|||
}, |
|||
{ |
|||
"name": "begin", |
|||
"input_type": "AnyType, ... A", |
|||
"output_type": "A", |
|||
"signature": "(begin expr1 expr2 expr3 ... expr-last)", |
|||
"description": "The `begin` function evaluates each of its input expressions, returning the\nreturn value of the last such expression.", |
|||
"example": "(begin (+ 1 2) 4 5) ;; Returns 5" |
|||
}, |
|||
{ |
|||
"name": "hash160", |
|||
"input_type": "buff|int", |
|||
"output_type": "(buff 20)", |
|||
"signature": "(hash160 value)", |
|||
"description": "The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", |
|||
"example": "(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f" |
|||
}, |
|||
{ |
|||
"name": "sha256", |
|||
"input_type": "buff|int", |
|||
"output_type": "(buff 32)", |
|||
"signature": "(sha256 value)", |
|||
"description": "The `sha256` function computes `SHA256(x)` of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", |
|||
"example": "(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb" |
|||
}, |
|||
{ |
|||
"name": "keccak256", |
|||
"input_type": "buff|int", |
|||
"output_type": "(buff 32)", |
|||
"signature": "(keccak256 value)", |
|||
"description": "The `keccak256` function computes `KECCAK256(value)` of the inputted value.\nNote that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) \nis supplied the hash is computed over the little-endian representation of the integer.", |
|||
"example": "(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4" |
|||
}, |
|||
{ |
|||
"name": "print", |
|||
"input_type": "A", |
|||
"output_type": "A", |
|||
"signature": "(print expr)", |
|||
"description": "The `print` function evaluates and returns its input expression. On Blockstack Core\nnodes 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" |
|||
}, |
|||
{ |
|||
"name": "contract-call!", |
|||
"input_type": "ContractName, PublicFunctionName, Arg0, ...", |
|||
"output_type": "Response(A,B)", |
|||
"signature": "(contract-call! contract-name function-name arg0 arg1 ...)", |
|||
"description": "The `contract-call!` function executes the given public function of the given contract.\nYou _may not_ this function to call a public function defined in the current contract. If the public\nfunction returns _err_, any database changes resulting from calling `contract-call!` are aborted.\nIf the function returns _ok_, database changes occurred.", |
|||
"example": "(contract-call! tokens transfer 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 19) ;; Returns (ok 1)" |
|||
}, |
|||
{ |
|||
"name": "as-contract", |
|||
"input_type": "A", |
|||
"output_type": "A", |
|||
"signature": "(as-contract expr)", |
|||
"description": "The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ \nprincipal and executes `expr` with that context. It returns the resulting value of `expr`.", |
|||
"example": "(as-contract (print tx-sender)) ;; Returns 'CTcontract.name" |
|||
}, |
|||
{ |
|||
"name": "get-block-info", |
|||
"input_type": "BlockInfoPropertyName, BlockHeightInt", |
|||
"output_type": "buff | int", |
|||
"signature": "(get-block-info prop-name block-height-expr)", |
|||
"description": "The `get-block-info` function fetches data for a block of the given block height. The \nvalue and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does\nnot correspond to an existing block, the function is aborted. The currently available property names \nare `time`, `header-hash`, `burnchain-header-hash`, and `vrf-seed`. \n\nThe `time` property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds \nwhich roughly corresponds to when the block was mined. **Warning**: this does not increase monotonically with each block\nand block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. \n\nThe `header-hash`, `burnchain-header-hash`, and `vrf-seed` properties return a 32-byte buffer. \n", |
|||
"example": "(get-block-info time 10) ;; Returns 1557860301\n(get-block-info header-hash 2) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb\n(get-block-info vrf-seed 6) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4\n" |
|||
}, |
|||
{ |
|||
"name": "ok", |
|||
"input_type": "A", |
|||
"output_type": "Response(A,B)", |
|||
"signature": "(ok value)", |
|||
"description": "The `ok` function constructs a response type from the input value. Use `ok` for\ncreating return values in public functions. An _ok_ value indicates that any database changes during\nthe processing of the function should materialize.", |
|||
"example": "(ok 1) ;; Returns (ok 1)" |
|||
}, |
|||
{ |
|||
"name": "err", |
|||
"input_type": "A", |
|||
"output_type": "Response(A,B)", |
|||
"signature": "(err value)", |
|||
"description": "The `err` function constructs a response type from the input value. Use `err` for\ncreating return values in public functions. An _err_ value indicates that any database changes during\nthe processing of the function should be rolled back.", |
|||
"example": "(err 'true) ;; Returns (err 'true)" |
|||
}, |
|||
{ |
|||
"name": "default-to", |
|||
"input_type": "A, Optional(A)", |
|||
"output_type": "A", |
|||
"signature": "(default-to default-value option-value)", |
|||
"description": "The `default-to` function attempts to 'unpack' the second argument: if the argument is\na `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value,\n`default-to` it returns the value of `default-value`.", |
|||
"example": "(default-to 0 (get id (fetch-entry names-map (tuple (name \"blockstack\"))))) ;; Returns 1337\n(default-to 0 (get id (fetch-entry names-map (tuple (name \"non-existant\"))))) ;; Returns 0\n" |
|||
}, |
|||
{ |
|||
"name": "expects!", |
|||
"input_type": "Optional(A) | Response(A,B), C", |
|||
"output_type": "A", |
|||
"signature": "(expects! option-input thrown-value)", |
|||
"description": "The `expects!` function attempts to 'unpack' the first argument: if the argument is\nan option type, and the argument is a `(some ...)` option, `expects!` returns the inner value of the\noption. If the argument is a response type, and the argument is an `(ok ...)` response, `expects!` returns\n the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value,\n`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))" |
|||
}, |
|||
{ |
|||
"name": "expects-err!", |
|||
"input_type": "Response(A,B), C", |
|||
"output_type": "B", |
|||
"signature": "(expects-err! response-input thrown-value)", |
|||
"description": "The `expects-err!` function attempts to 'unpack' the first argument: if the argument\nis an `(err ...)` response, `expects-err!` returns the inner value of the `err`.\nIf the supplied argument is an `(ok ...)` value,\n`expects-err!` _returns_ `thrown-value` from the current function and exits the current control-flow.", |
|||
"example": "(expects-err! (err 1) 'false) ;; Returns 1" |
|||
}, |
|||
{ |
|||
"name": "is-ok?", |
|||
"input_type": "Response(A,B)", |
|||
"output_type": "bool", |
|||
"signature": "(is-ok? value)", |
|||
"description": "`is-ok?` tests a supplied response value, returning `true` if the response was `ok`,\nand `false` if it was an `err`.", |
|||
"example": "(is-ok? (ok 1)) ;; Returns 'true\n(is-ok? (err 1)) ;; Returns 'false" |
|||
}, |
|||
{ |
|||
"name": "is-none?", |
|||
"input_type": "Optional(A)", |
|||
"output_type": "bool", |
|||
"signature": "(is-none? value)", |
|||
"description": "`is-none?` tests a supplied option value, returning `true` if the option value is `(none)`,\nand `false` if it is a `(some ...)`.", |
|||
"example": "(is-none? (get id (fetch-entry names-map (tuple (name \"blockstack\"))))) ;; Returns 'false\n(is-none? (get id (fetch-entry names-map (tuple (name \"non-existant\"))))) ;; Returns 'true" |
|||
}, |
|||
{ |
|||
"name": "filter", |
|||
"input_type": "Function(A) -> bool, (list A)", |
|||
"output_type": "(list A)", |
|||
"signature": "(filter func list)", |
|||
"description": "The `filter` function applies the input function `func` to each element of the\ninput 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)" |
|||
}, |
|||
{ |
|||
"name": "define-map", |
|||
"input_type": "MapName, KeyTupleDefinition, MapTupleDefinition", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-map map-name ((key-name-0 key-type-0) ...) ((val-name-0 val-type-0) ...))", |
|||
"description": "`define-map` is used to define a new datamap for use in a smart contract. Such\nmaps are only modifiable by the current smart contract.\n\nMaps are defined with a key tuple type and value tuple type. These are defined using a list\nof name and type pairs, e.g., a key type might be `((id int))`, which is a tuple with a single \"id\"\nfield of type `int`.\n\nLike other kinds of definition statements, `define-map` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).", |
|||
"example": "\n(define-map squares ((x int)) ((square int)))\n(define (add-entry (x int))\n (insert-entry! squares ((x 2)) ((square (* x x)))))\n(add-entry 1)\n(add-entry 2)\n(add-entry 3)\n(add-entry 4)\n(add-entry 5)\n" |
|||
}, |
|||
{ |
|||
"name": "define-data-var", |
|||
"input_type": "VarName, TypeDefinition, Value", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-data-var var-name type value)", |
|||
"description": "`define-data-var` is used to define a new persisted variable for use in a smart contract. Such\nvariable are only modifiable by the current smart contract.\n\nPersisted variable are defined with a type and a value.\n\nLike other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).", |
|||
"example": "\n(define-data-var size int 0)\n(define (set-size (value int))\n (set-var! size value))\n(set-size 1)\n(set-size 2)\n" |
|||
}, |
|||
{ |
|||
"name": "define-public", |
|||
"input_type": "MethodSignature, MethodBody", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", |
|||
"description": "`define-public` is used to define a _public_ function and transaction for a smart contract. Public\nfunctions are callable from other smart contracts and may be invoked directly by users by submitting a transaction\nto the Stacks blockchain.\n\nLike other kinds of definition statements, `define-public` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nPublic functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by\na public function is aborted if the function returns an `err` type. Public functions may be invoked by other\ncontracts via `contract-call!`.", |
|||
"example": "\n(define-public (hello-world (input int))\n (begin (print (+ 2 input))\n (ok input)))\n" |
|||
}, |
|||
{ |
|||
"name": "define", |
|||
"input_type": "MethodSignature, MethodBody", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", |
|||
"description": "`define` is used to define _private_ functions for a smart contract. Private\nfunctions may not be called from other smart contracts, nor may they be invoked directly by users.\nInstead, these functions may only be invoked by other functions defined in the same smart contract.\n\nLike other kinds of definition statements, `define` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nPrivate functions may return any type.", |
|||
"example": "\n(define (max-of (i1 int) (i2 int))\n (if (> i1 i2)\n i1\n i2))\n(max-of 4 6) ;; returns 6\n" |
|||
}, |
|||
{ |
|||
"name": "define-read-only", |
|||
"input_type": "MethodSignature, MethodBody", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", |
|||
"description": "`define-read-only` is used to define a _public read-only_ function for a smart contract. Such\nfunctions are callable from other smart contracts.\n\nLike other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nRead-only functions may return any type. However, read-only functions\nmay not perform any datamap modifications, or call any functions which\nperform such modifications. This is enforced both during type checks and during\nthe execution of the function. Public read-only functions may\nbe invoked by other contracts via `contract-call!`.", |
|||
"example": "\n(define-read-only (just-return-one-hundred) \n (* 10 10))" |
|||
} |
|||
] |
|||
{ |
|||
"functions": [ |
|||
{ |
|||
"name": "+ (add)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(+ i1 i2...)", |
|||
"description": "Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error.", |
|||
"example": "(+ 1 2 3) ;; Returns 6" |
|||
}, |
|||
{ |
|||
"name": "- (subtract)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(- i1 i2...)", |
|||
"description": "Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error.", |
|||
"example": "(- 2 1 1) ;; Returns 0\n(- 0 3) ;; Returns -3\n" |
|||
}, |
|||
{ |
|||
"name": "* (multiply)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(* i1 i2...)", |
|||
"description": "Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error.", |
|||
"example": "(* 2 3) ;; Returns 6\n(* 5 2) ;; Returns 10\n(* 2 2 2) ;; Returns 8\n" |
|||
}, |
|||
{ |
|||
"name": "/ (divide)", |
|||
"input_type": "int, ...", |
|||
"output_type": "int", |
|||
"signature": "(/ i1 i2...)", |
|||
"description": "Integer divides a variable number of integer inputs and returns the result. In the event of division by zero, throws a runtime error.", |
|||
"example": "(/ 2 3) ;; Returns 0\n(/ 5 2) ;; Returns 2\n(/ 4 2 2) ;; Returns 1\n" |
|||
}, |
|||
{ |
|||
"name": ">= (greater than or equal)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(>= i1 i2)", |
|||
"description": "Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise.", |
|||
"example": "(>= 1 1) ;; Returns 'true\n(>= 5 2) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "<= (less than or equal)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(<= i1 i2)", |
|||
"description": "Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise.", |
|||
"example": "(<= 1 1) ;; Returns 'true\n(<= 5 2) ;; Returns 'false\n" |
|||
}, |
|||
{ |
|||
"name": "< (less than)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(< i1 i2)", |
|||
"description": "Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise.", |
|||
"example": "(< 1 2) ;; Returns 'true\n(< 5 2) ;; Returns 'false\n" |
|||
}, |
|||
{ |
|||
"name": "> (greater than)", |
|||
"input_type": "int, int", |
|||
"output_type": "bool", |
|||
"signature": "(> i1 i2)", |
|||
"description": "Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise.", |
|||
"example": "(> 1 2) ;; Returns 'false\n(> 5 2) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "mod", |
|||
"input_type": "int, int", |
|||
"output_type": "int", |
|||
"signature": "(mod i1 i2)", |
|||
"description": "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\n(mod 5 2) ;; Returns 1\n(mod 7 1) ;; Returns 0\n" |
|||
}, |
|||
{ |
|||
"name": "pow", |
|||
"input_type": "int, int", |
|||
"output_type": "int", |
|||
"signature": "(pow i1 i2)", |
|||
"description": "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\n(pow 2 2) ;; Returns 4\n(pow 7 1) ;; Returns 7\n" |
|||
}, |
|||
{ |
|||
"name": "xor", |
|||
"input_type": "int, int", |
|||
"output_type": "int", |
|||
"signature": "(xor i1 i2)", |
|||
"description": "Returns the result of bitwise exclusive or'ing `i1` with `i2`.", |
|||
"example": "(xor 1 2) ;; Returns 3\n(xor 120 280) ;; Returns 352\n" |
|||
}, |
|||
{ |
|||
"name": "and", |
|||
"input_type": "bool, ...", |
|||
"output_type": "bool", |
|||
"signature": "(and b1 b2 ...)", |
|||
"description": "Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated.", |
|||
"example": "(and 'true 'false) ;; Returns 'false\n(and (eq? (+ 1 2) 1) (eq? 4 4)) ;; Returns 'false\n(and (eq? (+ 1 2) 3) (eq? 4 4)) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "or", |
|||
"input_type": "bool, ...", |
|||
"output_type": "bool", |
|||
"signature": "(or b1 b2 ...)", |
|||
"description": "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\n(or (eq? (+ 1 2) 1) (eq? 4 4)) ;; Returns 'true\n(or (eq? (+ 1 2) 1) (eq? 3 4)) ;; Returns 'false\n(or (eq? (+ 1 2) 3) (eq? 4 4)) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "not", |
|||
"input_type": "bool", |
|||
"output_type": "bool", |
|||
"signature": "(not b1)", |
|||
"description": "Returns the inverse of the boolean input.", |
|||
"example": "(not 'true) ;; Returns 'false\n(not (eq? 1 2)) ;; Returns 'true\n" |
|||
}, |
|||
{ |
|||
"name": "eq?", |
|||
"input_type": "A, A, ...", |
|||
"output_type": "bool", |
|||
"signature": "(eq? v1 v2...)", |
|||
"description": "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\n(eq? 1 'false) ;; Returns 'false\n(eq? \"abc\" 234 234) ;; Returns 'false\n" |
|||
}, |
|||
{ |
|||
"name": "if", |
|||
"input_type": "bool, A, A", |
|||
"output_type": "A", |
|||
"signature": "(if bool1 expr1 expr2)", |
|||
"description": "The `if` function admits a boolean argument and two expressions \nwhich must return the same type. In the case that the boolean input is `true`, the\n`if` function evaluates and returns `expr1`. If the boolean input is `false`, the\n`if` function evaluates and returns `expr2`.", |
|||
"example": "(if true 1 2) ;; Returns 1\n(if (> 1 2) 1 2) ;; Returns 2" |
|||
}, |
|||
{ |
|||
"name": "let", |
|||
"input_type": "((name2 AnyType) (name2 AnyType) ...), AnyType, ... A", |
|||
"output_type": "A", |
|||
"signature": "(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)", |
|||
"description": "The `let` function accepts a list of `variable name` and `expression` pairs,\nevaluating each expression and _binding_ it to the corresponding variable name. The _context_\ncreated by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression.", |
|||
"example": "(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20" |
|||
}, |
|||
{ |
|||
"name": "fetch-var", |
|||
"input_type": "VarName", |
|||
"output_type": "A", |
|||
"signature": "(fetch-var var-name)", |
|||
"description": "The `fetch-var` function looks up and returns an entry from a contract's data map.\nThe value is looked up using `var-name`.", |
|||
"example": "(fetch-var cursor) ;; Returns cursor" |
|||
}, |
|||
{ |
|||
"name": "set-var!", |
|||
"input_type": "VarName, AnyType", |
|||
"output_type": "bool", |
|||
"signature": "(set-var! var-name expr1)", |
|||
"description": "The `set-var!` function sets the value associated with the input variable to the \ninputted value.", |
|||
"example": "(set-var! cursor (+ cursor 1)) ;; Returns 'true" |
|||
}, |
|||
{ |
|||
"name": "map", |
|||
"input_type": "Function(A) -> B, (list A)", |
|||
"output_type": "(list B)", |
|||
"signature": "(map func list)", |
|||
"description": "The `map` function applies the input function `func` to each element of the\ninput 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" |
|||
}, |
|||
{ |
|||
"name": "fold", |
|||
"input_type": "Function(A, B) -> B, (list A)", |
|||
"output_type": "B", |
|||
"signature": "(fold func list initial-value)", |
|||
"description": "The `fold` function applies the input function `func` to each element of the\ninput list _and_ the output of the previous application of the `fold` function. When invoked on\nthe first list element, it uses the `initial-value` as the second input. `fold` returns the last\nvalue return by the successive applications.", |
|||
"example": "(fold * (list 2 2 2) 1) ;; Returns 8\n(fold * (list 2 2 2) 0) ;; Returns 0" |
|||
}, |
|||
{ |
|||
"name": "list", |
|||
"input_type": "A, ...", |
|||
"output_type": "(list A)", |
|||
"signature": "(list expr1 expr2 expr3 ...)", |
|||
"description": "The `list` function constructs a list composed of the inputted values. Each\nsupplied value must be of the same type.", |
|||
"example": "(list (+ 1 2) 4 5) ;; Returns [3 4 5]" |
|||
}, |
|||
{ |
|||
"name": "fetch-entry", |
|||
"input_type": "MapName, tuple", |
|||
"output_type": "(optional (tuple))", |
|||
"signature": "(fetch-entry map-name key-tuple)", |
|||
"description": "The `fetch-entry` function looks up and returns an entry from a contract's data map.\nThe value is looked up using `key-tuple`.\nIf there is no value associated with that key in the data map, the function returns a (none) option. Otherwise,\nit returns (some value)", |
|||
"example": "(expects! (fetch-entry names-map (tuple (name \"blockstack\"))) (err 1)) ;; Returns (tuple (id 1337))\n(expects! (fetch-entry names-map ((name \"blockstack\"))) (err 1)) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "fetch-contract-entry", |
|||
"input_type": "ContractName, MapName, tuple", |
|||
"output_type": "(optional (tuple))", |
|||
"signature": "(fetch-contract-entry contract-name map-name key-tuple)", |
|||
"description": "The `fetch-contract-entry` function looks up and returns an entry from a\ncontract other than the current contract's data map. The value is looked up using `key-tuple`.\nIf there is no value associated with that key in the data map, the function returns a (none) option. Otherwise,\nit returns (some value).", |
|||
"example": "(expects! (fetch-contract-entry names-contract names-map (tuple (name \"blockstack\")) (err 1))) ;; Returns (tuple (id 1337))\n(expects! (fetch-contract-entry names-contract names-map ((name \"blockstack\")) (err 1)));; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "set-entry!", |
|||
"input_type": "MapName, tuple_A, tuple_B", |
|||
"output_type": "bool", |
|||
"signature": "(set-entry! map-name key-tuple value-tuple)", |
|||
"description": "The `set-entry!` function sets the value associated with the input key to the \ninputted value. This function performs a _blind_ update; whether or not a value is already associated\nwith the key, the function overwrites that existing association.", |
|||
"example": "(set-entry! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'true\n(set-entry! names-map ((name \"blockstack\")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "insert-entry!", |
|||
"input_type": "MapName, tuple_A, tuple_B", |
|||
"output_type": "bool", |
|||
"signature": "(insert-entry! map-name key-tuple value-tuple)", |
|||
"description": "The `insert-entry!` function sets the value associated with the input key to the \ninputted value if and only if there is not already a value associated with the key in the map.\nIf an insert occurs, the function returns `true`. If a value already existed for\nthis key in the data map, the function returns `false`.", |
|||
"example": "(insert-entry! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'true\n(insert-entry! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'false\n(insert-entry! names-map ((name \"blockstack\")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "delete-entry!", |
|||
"input_type": "MapName, tuple", |
|||
"output_type": "bool", |
|||
"signature": "(delete-entry! map-name key-tuple)", |
|||
"description": "The `delete-entry!` function removes the value associated with the input key for\nthe given map. If an item exists and is removed, the function returns `true`.\nIf 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\n(delete-entry! names-map (tuple (name \"blockstack\"))) ;; Returns 'false\n(delete-entry! names-map ((name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple\n" |
|||
}, |
|||
{ |
|||
"name": "tuple", |
|||
"input_type": "(key-name A), (key-name-2 B), ...", |
|||
"output_type": "(tuple (key-name A) (key-name-2 B) ...)", |
|||
"signature": "(tuple ((key0 expr0) (key1 expr1) ...))", |
|||
"description": "The `tuple` function constructs a typed tuple from the supplied key and expression pairs.\nA `get` function can use typed tuples as input to select specific values from a given tuple.\nKey names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and\nassociated with the expressions' paired key name.", |
|||
"example": "(tuple (name \"blockstack\") (id 1337))" |
|||
}, |
|||
{ |
|||
"name": "get", |
|||
"input_type": "KeyName, (tuple) | (optional (tuple))", |
|||
"output_type": "A", |
|||
"signature": "(get key-name tuple)", |
|||
"description": "The `get` function fetches the value associated with a given key from the supplied typed tuple.\nIf an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in\nthe tuple. If the supplied option is a `(none)` option, get returns `(none)`.", |
|||
"example": "(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337\n(get id (fetch-entry names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337)\n(get id (fetch-entry names-map (tuple (name \"non-existent\")))) ;; Returns (none)\n" |
|||
}, |
|||
{ |
|||
"name": "begin", |
|||
"input_type": "AnyType, ... A", |
|||
"output_type": "A", |
|||
"signature": "(begin expr1 expr2 expr3 ... expr-last)", |
|||
"description": "The `begin` function evaluates each of its input expressions, returning the\nreturn value of the last such expression.", |
|||
"example": "(begin (+ 1 2) 4 5) ;; Returns 5" |
|||
}, |
|||
{ |
|||
"name": "hash160", |
|||
"input_type": "buff|int", |
|||
"output_type": "(buff 20)", |
|||
"signature": "(hash160 value)", |
|||
"description": "The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", |
|||
"example": "(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f" |
|||
}, |
|||
{ |
|||
"name": "sha256", |
|||
"input_type": "buff|int", |
|||
"output_type": "(buff 32)", |
|||
"signature": "(sha256 value)", |
|||
"description": "The `sha256` function computes `SHA256(x)` of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", |
|||
"example": "(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb" |
|||
}, |
|||
{ |
|||
"name": "keccak256", |
|||
"input_type": "buff|int", |
|||
"output_type": "(buff 32)", |
|||
"signature": "(keccak256 value)", |
|||
"description": "The `keccak256` function computes `KECCAK256(value)` of the inputted value.\nNote that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) \nis supplied the hash is computed over the little-endian representation of the integer.", |
|||
"example": "(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4" |
|||
}, |
|||
{ |
|||
"name": "print", |
|||
"input_type": "A", |
|||
"output_type": "A", |
|||
"signature": "(print expr)", |
|||
"description": "The `print` function evaluates and returns its input expression. On Blockstack Core\nnodes 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" |
|||
}, |
|||
{ |
|||
"name": "contract-call!", |
|||
"input_type": "ContractName, PublicFunctionName, Arg0, ...", |
|||
"output_type": "(response A B)", |
|||
"signature": "(contract-call! contract-name function-name arg0 arg1 ...)", |
|||
"description": "The `contract-call!` function executes the given public function of the given contract.\nYou _may not_ this function to call a public function defined in the current contract. If the public\nfunction returns _err_, any database changes resulting from calling `contract-call!` are aborted.\nIf the function returns _ok_, database changes occurred.", |
|||
"example": "(contract-call! tokens transfer 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 19) ;; Returns (ok 1)" |
|||
}, |
|||
{ |
|||
"name": "as-contract", |
|||
"input_type": "A", |
|||
"output_type": "A", |
|||
"signature": "(as-contract expr)", |
|||
"description": "The `as-contract` function switches the current context's `tx-origin` value to the _contract's_ \nprincipal and executes `expr` with that context. It returns the resulting value of `expr`.", |
|||
"example": "(as-contract (print tx-sender)) ;; Returns 'CTcontract.name" |
|||
}, |
|||
{ |
|||
"name": "get-block-info", |
|||
"input_type": "BlockInfoPropertyName, BlockHeightInt", |
|||
"output_type": "buff | int", |
|||
"signature": "(get-block-info prop-name block-height-expr)", |
|||
"description": "The `get-block-info` function fetches data for a block of the given block height. The \nvalue and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does\nnot correspond to an existing block, the function is aborted. The currently available property names \nare `time`, `header-hash`, `burnchain-header-hash`, and `vrf-seed`. \n\nThe `time` property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds \nwhich roughly corresponds to when the block was mined. **Warning**: this does not increase monotonically with each block\nand block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. \n\nThe `header-hash`, `burnchain-header-hash`, and `vrf-seed` properties return a 32-byte buffer. \n", |
|||
"example": "(get-block-info time 10) ;; Returns 1557860301\n(get-block-info header-hash 2) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb\n(get-block-info vrf-seed 6) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4\n" |
|||
}, |
|||
{ |
|||
"name": "ok", |
|||
"input_type": "A", |
|||
"output_type": "(response A B)", |
|||
"signature": "(ok value)", |
|||
"description": "The `ok` function constructs a response type from the input value. Use `ok` for\ncreating return values in public functions. An _ok_ value indicates that any database changes during\nthe processing of the function should materialize.", |
|||
"example": "(ok 1) ;; Returns (ok 1)" |
|||
}, |
|||
{ |
|||
"name": "err", |
|||
"input_type": "A", |
|||
"output_type": "(response A B)", |
|||
"signature": "(err value)", |
|||
"description": "The `err` function constructs a response type from the input value. Use `err` for\ncreating return values in public functions. An _err_ value indicates that any database changes during\nthe processing of the function should be rolled back.", |
|||
"example": "(err 'true) ;; Returns (err 'true)" |
|||
}, |
|||
{ |
|||
"name": "some", |
|||
"input_type": "A", |
|||
"output_type": "(optional A)", |
|||
"signature": "(some value)", |
|||
"description": "The `some` function constructs a `optional` type from the input value.", |
|||
"example": "(some 1) ;; Returns (some 1)\n(is-none? (some 2)) ;; Returns 'false" |
|||
}, |
|||
{ |
|||
"name": "default-to", |
|||
"input_type": "A, (optional A)", |
|||
"output_type": "A", |
|||
"signature": "(default-to default-value option-value)", |
|||
"description": "The `default-to` function attempts to 'unpack' the second argument: if the argument is\na `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value,\n`default-to` it returns the value of `default-value`.", |
|||
"example": "(default-to 0 (get id (fetch-entry names-map (tuple (name \"blockstack\"))))) ;; Returns 1337\n(default-to 0 (get id (fetch-entry names-map (tuple (name \"non-existant\"))))) ;; Returns 0\n" |
|||
}, |
|||
{ |
|||
"name": "expects!", |
|||
"input_type": "(optional A) | (response A B), C", |
|||
"output_type": "A", |
|||
"signature": "(expects! option-input thrown-value)", |
|||
"description": "The `expects!` function attempts to 'unpack' the first argument: if the argument is\nan option type, and the argument is a `(some ...)` option, `expects!` returns the inner value of the\noption. If the argument is a response type, and the argument is an `(ok ...)` response, `expects!` returns\n the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value,\n`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))" |
|||
}, |
|||
{ |
|||
"name": "expects-err!", |
|||
"input_type": "(response A B), C", |
|||
"output_type": "B", |
|||
"signature": "(expects-err! response-input thrown-value)", |
|||
"description": "The `expects-err!` function attempts to 'unpack' the first argument: if the argument\nis an `(err ...)` response, `expects-err!` returns the inner value of the `err`.\nIf the supplied argument is an `(ok ...)` value,\n`expects-err!` _returns_ `thrown-value` from the current function and exits the current control-flow.", |
|||
"example": "(expects-err! (err 1) 'false) ;; Returns 1" |
|||
}, |
|||
{ |
|||
"name": "is-ok?", |
|||
"input_type": "(response A B)", |
|||
"output_type": "bool", |
|||
"signature": "(is-ok? value)", |
|||
"description": "`is-ok?` tests a supplied response value, returning `true` if the response was `ok`,\nand `false` if it was an `err`.", |
|||
"example": "(is-ok? (ok 1)) ;; Returns 'true\n(is-ok? (err 1)) ;; Returns 'false" |
|||
}, |
|||
{ |
|||
"name": "is-none?", |
|||
"input_type": "(optional A)", |
|||
"output_type": "bool", |
|||
"signature": "(is-none? value)", |
|||
"description": "`is-none?` tests a supplied option value, returning `true` if the option value is `(none)`,\nand `false` if it is a `(some ...)`.", |
|||
"example": "(is-none? (get id (fetch-entry names-map (tuple (name \"blockstack\"))))) ;; Returns 'false\n(is-none? (get id (fetch-entry names-map (tuple (name \"non-existant\"))))) ;; Returns 'true" |
|||
}, |
|||
{ |
|||
"name": "filter", |
|||
"input_type": "Function(A) -> bool, (list A)", |
|||
"output_type": "(list A)", |
|||
"signature": "(filter func list)", |
|||
"description": "The `filter` function applies the input function `func` to each element of the\ninput 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)" |
|||
}, |
|||
{ |
|||
"name": "nft-mint!", |
|||
"input_type": "AssetName, A, principal", |
|||
"output_type": "(response bool int)", |
|||
"signature": "(nft-mint! asset-class asset-identifier recipient)", |
|||
"description": "`nft-mint!` is used to instantiate an asset and set that asset's owner to the `recipient` principal.\nThe asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in\nthat definition.\n\nIf an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code:\n\n`(err 1)`\n\nOtherwise, on successfuly mint, it returns `(ok 'true)`.\n", |
|||
"example": "\n(define-non-fungible-token stackaroo (buff 40))\n(nft-mint! stackaroo \"Roo\" tx-sender)\n" |
|||
}, |
|||
{ |
|||
"name": "ft-mint!", |
|||
"input_type": "TokenName, int, principal", |
|||
"output_type": "(response bool int)", |
|||
"signature": "(ft-mint! token-name amount recipient)", |
|||
"description": "`ft-mint!` is used to increase the token balance for the `recipient` principal for a token\ntype defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but\nrather minted.\n\nIf a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it\nreturns `(ok 'true)`.\n", |
|||
"example": "\n(define-fungible-token stackaroo)\n(ft-mint! stackaroo 100 tx-sender)\n" |
|||
}, |
|||
{ |
|||
"name": "nft-transfer!", |
|||
"input_type": "AssetName, A, principal, principal", |
|||
"output_type": "(response bool int)", |
|||
"signature": "(nft-transfer! asset-class asset-identifier sender recipient)", |
|||
"description": "`nft-transfer!` is used to change the owner of an asset identified by `asset-identifier`\nfrom `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier`\nmust be of the type specified in that definition.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err 1)` -- `sender` does not own the asset\n`(err 2)` -- `sender` and `recipient` are the same principal\n`(err 3)` -- asset identified by asset-identifier does not exist\n", |
|||
"example": "\n(define-non-fungible-token stackaroo (buff 40))\n(nft-mint! stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(nft-transfer! stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (ok true)\n(nft-transfer! stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (err 1)\n(nft-transfer! stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (err 3)\n" |
|||
}, |
|||
{ |
|||
"name": "ft-transfer!", |
|||
"input_type": "TokenName, int, principal, principal", |
|||
"output_type": "(response bool int)", |
|||
"signature": "(ft-transfer! token-name amount sender recipient)", |
|||
"description": "`ft-transfer!` is used to increase the token balance for the `recipient` principal for a token\ntype defined using `define-fungible-token` by debiting the `sender` principal.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err 1)` -- `sender` does not have enough balance to transfer\n`(err 2)` -- `sender` and `recipient` are the same principal\n`(err 3)` -- amount to send is non-positive\n", |
|||
"example": "\n(define-fungible-token stackaroo)\n(ft-mint! stackaroo 100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(ft-transfer! stackaroo 50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (ok true)\n(ft-transfer! stackaroo 60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender) ;; returns (err 1)\n" |
|||
}, |
|||
{ |
|||
"name": "ft-get-balance", |
|||
"input_type": "TokenName, principal", |
|||
"output_type": "int", |
|||
"signature": "(ft-get-balance token-name principal)", |
|||
"description": "`ft-get-balance` returns `token-name` balance of the principal `principal`.\nThe token type must have been defined using `define-fungible-token`.", |
|||
"example": "\n(define-fungible-token stackaroos)\n(ft-get-balance stackaroos tx-sender)\n" |
|||
}, |
|||
{ |
|||
"name": "nft-get-owner", |
|||
"input_type": "AssetName, A", |
|||
"output_type": "(optional principal)", |
|||
"signature": "(nft-get-owner asset-class asset-identifier)", |
|||
"description": "`nft-get-owner` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist.\nThe asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in\nthat definition.", |
|||
"example": "\n(define-non-fungible-token stackaroo (buff 40))\n(nft-get-owner stackaroo \"Roo\")\n" |
|||
}, |
|||
{ |
|||
"name": "define-non-fungible-token", |
|||
"input_type": "AssetName, TypeSignature", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-non-fungible-token asset-name asset-identifier-type)", |
|||
"description": "`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract.\nIndividual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset\nidentifiers are _unique_ identifiers.\n\nLike other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nAssets defined using `define-non-fungible-token` may be used in `nft-transfer!`, `nft-mint!`, and `nft-get-owner` functions", |
|||
"example": "\n(define-non-fungible-token names (buff 50))\n" |
|||
}, |
|||
{ |
|||
"name": "define-fungible-token", |
|||
"input_type": "TokenName, <int>", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-fungible-token token-name <total-supply>)", |
|||
"description": "`define-fungible-token` is used to define a new fungible token class for use in the current contract.\n\nThe second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint!`\nfunction will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply\nof tokens passed that amount, that invocation of `ft-mint!` will result in a runtime error and abort.\n\nLike other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nTokens defined using `define-fungible-token` may be used in `ft-transfer!`, `ft-mint!`, and `ft-get-balance` functions", |
|||
"example": "\n(define-fungible-token stacks)\n" |
|||
}, |
|||
{ |
|||
"name": "define-map", |
|||
"input_type": "MapName, KeyTupleDefinition, MapTupleDefinition", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-map map-name ((key-name-0 key-type-0) ...) ((val-name-0 val-type-0) ...))", |
|||
"description": "`define-map` is used to define a new datamap for use in a smart contract. Such\nmaps are only modifiable by the current smart contract.\n\nMaps are defined with a key tuple type and value tuple type. These are defined using a list\nof name and type pairs, e.g., a key type might be `((id int))`, which is a tuple with a single \"id\"\nfield of type `int`.\n\nLike other kinds of definition statements, `define-map` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).", |
|||
"example": "\n(define-map squares ((x int)) ((square int)))\n(define (add-entry (x int))\n (insert-entry! squares ((x 2)) ((square (* x x)))))\n(add-entry 1)\n(add-entry 2)\n(add-entry 3)\n(add-entry 4)\n(add-entry 5)\n" |
|||
}, |
|||
{ |
|||
"name": "define-data-var", |
|||
"input_type": "VarName, TypeDefinition, Value", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-data-var var-name type value)", |
|||
"description": "`define-data-var` is used to define a new persisted variable for use in a smart contract. Such\nvariable are only modifiable by the current smart contract.\n\nPersisted variable are defined with a type and a value.\n\nLike other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).", |
|||
"example": "\n(define-data-var size int 0)\n(define (set-size (value int))\n (set-var! size value))\n(set-size 1)\n(set-size 2)\n" |
|||
}, |
|||
{ |
|||
"name": "define-public", |
|||
"input_type": "MethodSignature, MethodBody", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", |
|||
"description": "`define-public` is used to define a _public_ function and transaction for a smart contract. Public\nfunctions are callable from other smart contracts and may be invoked directly by users by submitting a transaction\nto the Stacks blockchain.\n\nLike other kinds of definition statements, `define-public` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nPublic functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by\na public function is aborted if the function returns an `err` type. Public functions may be invoked by other\ncontracts via `contract-call!`.", |
|||
"example": "\n(define-public (hello-world (input int))\n (begin (print (+ 2 input))\n (ok input)))\n" |
|||
}, |
|||
{ |
|||
"name": "define", |
|||
"input_type": "MethodSignature, MethodBody", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", |
|||
"description": "`define` is used to define _private_ functions for a smart contract. Private\nfunctions may not be called from other smart contracts, nor may they be invoked directly by users.\nInstead, these functions may only be invoked by other functions defined in the same smart contract.\n\nLike other kinds of definition statements, `define` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nPrivate functions may return any type.", |
|||
"example": "\n(define (max-of (i1 int) (i2 int))\n (if (> i1 i2)\n i1\n i2))\n(max-of 4 6) ;; returns 6\n" |
|||
}, |
|||
{ |
|||
"name": "define-read-only", |
|||
"input_type": "MethodSignature, MethodBody", |
|||
"output_type": "Not Applicable", |
|||
"signature": "(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", |
|||
"description": "`define-read-only` is used to define a _public read-only_ function for a smart contract. Such\nfunctions are callable from other smart contracts.\n\nLike other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nRead-only functions may return any type. However, read-only functions\nmay not perform any datamap modifications, or call any functions which\nperform such modifications. This is enforced both during type checks and during\nthe execution of the function. Public read-only functions may\nbe invoked by other contracts via `contract-call!`.", |
|||
"example": "\n(define-read-only (just-return-one-hundred) \n (* 10 10))" |
|||
} |
|||
], |
|||
"keywords": [ |
|||
{ |
|||
"name": "contract-caller", |
|||
"output_type": "principal", |
|||
"description": "Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, \nthe caller will be equal to the signing principal. If `contract-call!` was used to invoke a function from a new contract, `contract-caller`\nchanges to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes\nto the same contract principal.", |
|||
"example": "(print contract-caller) ;; Will print out a Stacks address of the transaction sender" |
|||
}, |
|||
{ |
|||
"name": "tx-sender", |
|||
"output_type": "principal", |
|||
"description": "Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that\ncontract principal.", |
|||
"example": "(print tx-sender) ;; Will print out a Stacks address of the transaction sender" |
|||
}, |
|||
{ |
|||
"name": "block-height", |
|||
"output_type": "int", |
|||
"description": "Returns the current block height of the Stacks blockchain as an int", |
|||
"example": "(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks." |
|||
}, |
|||
{ |
|||
"name": "none", |
|||
"output_type": "(optional ?)", |
|||
"description": "Represents the _none_ option indicating no value for a given optional (analogous to a null value).", |
|||
"example": "\n(define (only-if-positive (a int))\n (if (> a 0)\n (some a)\n none))\n(only-if-positive 4) ;; Returns (some 4)\n(only-if-positive (- 3)) ;; Returns none\n" |
|||
} |
|||
] |
|||
} |
|||
|
|||
Loading…
Reference in new issue