"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.",
"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"
"signature":"(map-get map-name key-tuple)",
"description":"The `map-get` 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! (map-get names-map (tuple (name \"blockstack\"))) (err 1)) ;; Returns (tuple (id 1337))\n(expects! (map-get names-map ((name \"blockstack\"))) (err 1)) ;; Same command, using a shorthand for constructing the tuple\n"
"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"
"description":"The `contract-map-get` 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! (contract-map-get names-contract names-map (tuple (name \"blockstack\")) (err 1))) ;; Returns (tuple (id 1337))\n(expects! (contract-map-get names-contract names-map ((name \"blockstack\")) (err 1)));; Same command, using a shorthand for constructing the tuple\n"
"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"
"description":"The `map-set!` 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":"(map-set! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'true\n(map-set! names-map ((name \"blockstack\")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple\n"
"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"
"description":"The `map-insert!` 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":"(map-insert! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'true\n(map-insert! names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Returns 'false\n(map-insert! names-map ((name \"blockstack\")) ((id 1337))) ;; Same command, using a shorthand for constructing the tuple\n"
},
{
"name":"delete-entry!",
"name":"map-delete!",
"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"
"signature":"(map-delete! map-name key-tuple)",
"description":"The `map-delete!` 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":"(map-delete! names-map (tuple (name \"blockstack\"))) ;; Returns 'true\n(map-delete! names-map (tuple (name \"blockstack\"))) ;; Returns 'false\n(map-delete! names-map ((name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple\n"
},
{
"name":"tuple",
@ -230,7 +230,7 @@
"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"
"example":"(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337\n(get id (map-get names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337)\n(get id (map-get names-map (tuple (name \"non-existent\")))) ;; Returns (none)\n"
},
{
"name":"begin",
@ -296,14 +296,6 @@
"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",
"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",
@ -312,6 +304,14 @@
"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":"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.",
"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`.",
"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.",
"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",
"description":"`ft-get-balance` returns `token-name` balance of the principal `principal`.\nThe token type must have been defined using `define-fungible-token`.",
"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.",
"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",
"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",
"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",
"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",
"description":"`ft-get-balance` returns `token-name` balance of the principal `principal`.\nThe token type must have been defined using `define-fungible-token`.",
"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",
"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.",
"description":"`define-constant` is used to define a private constant value in a smart contract.\nThe expression passed into the definition is evaluated at contract launch, in the order that it is\nsupplied in the contract. This can lead to undefined function or undefined variable errors in the\nevent that a function or variable used in the expression has not been defined before the constant.\n\nLike other kinds of definition statements, `define-constant` 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",
"example":"\n(define-constant four (+ 2 2))\n(+ 4 four) ;; returns 8\n"
"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",
"description":"`define-private` 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-private` 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.",
"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",
"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!`.",
"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!`.",
"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).",
"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).",
"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!`.",
"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.",
"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",
"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!`.",
"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",
Mary Anthony
5 years ago