Stacks Blockchain (beta) Functions

function

cv_some

stacks::cv_some wraps the given Clarity value in a Clarity Optional.

Inputs

  • Name
    clarity_value
    Description

    A Clarity Value.

Output

  • Name
    value
    Description

    The input Clarity value wrapped in a Clarity Optional.

Example using cv_some

output "some" { 
  value = stacks::cv_some(stacks::cv_bool(true))
}
// > some: 0x0a03
function

cv_none

stacks::cv_none returns the Clarity value None.

Inputs

    Output

    • Name
      value
      Description

      The Clarity value None.

    Example using cv_none

    output "none" { 
  value = stacks::cv_none()
}
// > none: 0x09
    function

    cv_bool

    stacks::cv_bool returns the given boolean as a Clarity bool.

    Inputs

    • Name
      clarity_value
      Description

      The boolean values true or false.

    Output

    • Name
      value
      Description

      The input boolean as a Clarity bool.

    Example using cv_bool

    output "my_bool" { 
  value = stacks::cv_bool(true)
}
// > my_bool: 0x03
    function

    cv_uint

    stacks::cv_uint returns the given number as a Clarity uint.

    Inputs

    • Name
      clarity_value
      Description

      A positive integer between 0 and 2128-1.

    Output

    • Name
      value
      Description

      The input integer as a Clarity uint.

    Example using cv_uint

    output "my_uint" { 
  value = stacks::cv_uint(1)
}
// > my_uint: 0x0100000000000000000000000000000001
    function

    cv_int

    stacks::cv_int returns the given number as a Clarity int.

    Inputs

    • Name
      clarity_value
      Description

      An integer between -2127 and 2127-1.

    Output

    • Name
      value
      Description

      The input integer as a Clarity int.

    Example using cv_int

    output "my_int" { 
  value = stacks::cv_int(-1)
}
// > my_int: 0x00FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
    function

    cv_principal

    stacks::cv_principal returns the given string as a Clarity principal. A Clarity principal represents a Stacks address on the blockchain.

    Clarity admits two different kinds of principals: standard principals and contract principals. Standard principals (e.g. SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE) are backed by a corresponding private key while contract principals (e.g. ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.pyth-oracle-v1) point to a smart contract.

    Inputs

    • Name
      clarity_value
      Description

      Any valid Clarity principal string.

    Output

    • Name
      value
      Description

      The input string as a Clarity principal.

    Example using cv_principal

    output "my_principal" { 
  value = stacks::cv_principal("SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE")
}
// > my_principal: 0x0516DEBC095099629BADB11B9D5335E874D12F1F1D45
    function

    cv_string_ascii

    stacks::cv_string_ascii returns the given string as a Clarity ASCII string.

    Inputs

    • Name
      clarity_value
      Description

      Any valid ASCII string.

    Output

    • Name
      value
      Description

      The input string as a Clarity ASCII string.

    Example using cv_string_ascii

    output "my_ascii" { 
  value = stacks::cv_string_ascii("my ascii string")
}
// > my_ascii: 0x0D0000000F6D7920617363696920737472696E67
    function

    cv_string_utf8

    stacks::cv_string_utf8 returns the given string as a Clarity UTF-8 string.

    Inputs

    • Name
      clarity_value
      Description

      Any valid UTF-8 string.

    Output

    • Name
      value
      Description

      The input string as a Clarity UTF-8 string.

    Example using cv_string_utf8

    output "my_utf8" { 
  value = stacks::cv_string_utf8("🍊")
}
// > my_utf8: 0x0E00000004F09F8D8A
    function

    cv_tuple

    stacks::cv_tuple returns the given object as a Clarity tuple.

    Inputs

    • Name
      clarity_value
      Description

      An object where each key is a string and each value is a valid Clarity value.

    Output

    • Name
      value
      Description

      The input object as a Clarity tuple.

    Example using cv_tuple

    output "my_tuple" { 
  value = stacks::cv_tuple({ "key": stacks::cv_uint(1) })
}
// > my_tuple: 0x0C00000001036B65790100000000000000000000000000000001
    function

    cv_buff

    stacks::cv_buff returns the given hex string as a Clarity buffer.

    Inputs

    • Name
      clarity_value
      Description

      A hex string.

    Output

    • Name
      value
      Description

      The input string as a Clarity buffer.

    Example using cv_buff

    output "my_buffer" { 
  value = stacks::cv_buff("0x010203") 
}
// > my_buffer: 0x0200000003010203
    function

    cv_ok

    stacks::cv_ok returns the given Clarity value wrapped in an Ok Clarity type.

    Inputs

    • Name
      clarity_value
      Description

      Any valid Clarity value.

    Output

    • Name
      value
      Description

      The input wrapped in an Ok Clarity type.

    Example using cv_ok

    output "ok" { 
  value = stacks::cv_ok(1) 
}
// > ok: 0x070100000000000000000000000000000001
    function

    cv_err

    stacks::cv_err returns the given Clarity value wrapped in an Err Clarity type.

    Inputs

    • Name
      clarity_value
      Description

      Any valid Clarity value.

    Output

    • Name
      value
      Description

      The input wrapped in an Err Clarity type.

    Example using cv_err

    output "err" { 
  value = stacks::cv_err(1) 
}
// > err: 0x080100000000000000000000000000000001
    function

    revert_if_account_sends_more_than

    stacks::revert_if_account_sends_more_than returns a post condition that will cancel a successfully executed transaction if the transaction results in the specified account sending more than the specified number of tokens. The default token is µSTX.

    Inputs

    • Name
      account_address
      Description

      The address of the account that the post condition will check. Use "signer" to apply this post condition to the transaction sender.

    • Name
      tokens_amount
      Description

      Threshold of tokens that triggers the revert action to prevent overspending.

    • Name
      token_id
      Description

      The asset identifier of the token to be checked. The default is µSTX if not provided.

    Output

    • Name
      value
      Description

      The post-condition, encoded as a buffer.

    Example using revert_if_account_sends_more_than

    action "my_tx" "stacks::call_contract" {
    contract_id = "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.some-contract"
    function_name = "some-function"
    function_args = []
    post_condition = [stacks::revert_if_account_sends_more_than("signer", 100)]
}
    function

    revert_if_account_not_sending_exactly

    stacks::revert_if_account_not_sending_exactly returns a post condition that will cancel a successfully executed transaction if the transaction does not result in the specified account sending exactly the specified number of tokens. The default token is µSTX.

    Inputs

    • Name
      account_address
      Description

      The address of the account that the post condition will check. Use "signer" to apply this post condition to the transaction sender.

    • Name
      tokens_amount
      Description

      The number of tokens required to be sent.

    • Name
      token_id
      Description

      The asset identifier of the token to be checked. The default is µSTX if not provided.

    Output

    • Name
      value
      Description

      The post-condition, encoded as a buffer.

    Example using revert_if_account_not_sending_exactly

    action "my_tx" "stacks::call_contract" {
    contract_id = "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.some-contract"
    function_name = "some-function"
    function_args = []
    post_condition = [stacks::revert_if_account_not_sending_exactly("signer", 100)]
}
    function

    revert_if_account_not_sending_at_least

    stacks::revert_if_account_not_sending_at_least returns a post condition that will cancel a successfully executed transaction if the transaction does not result in the specified account sending the minimum specified number of tokens. The default token is µSTX.

    Inputs

    • Name
      account_address
      Description

      The address of the account that the post condition will check. Use "signer" to apply this post condition to the transaction sender.

    • Name
      tokens_amount
      Description

      The minimum number of tokens required to be sent.

    • Name
      token_id
      Description

      The asset identifier of the token to be checked. The default is µSTX if not provided.

    Output

    • Name
      value
      Description

      The post-condition, encoded as a buffer.

    Example using revert_if_account_not_sending_at_least

    action "my_tx" "stacks::call_contract" {
    contract_id = "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.some-contract"
    function_name = "some-function"
    function_args = []
    post_condition = [stacks::revert_if_account_not_sending_at_least("signer", 100)]
}
    function

    revert_if_nft_not_owned_by_account

    stacks::revert_if_nft_not_owned_by_account returns a post condition that will cancel a successfully executed transaction if the transaction does not result in the specified account owning a specific NFT.

    Inputs

    • Name
      account_address
      Description

      The address of the account that the post condition will check.

    • Name
      contract_asset_id
      Description

      The NFT Contract Asset Id to check (<principal>.<contract_name>::<non_fungible_storage>).

    • Name
      asset_id
      Description

      The NFT Asset Id to check.

    Output

    • Name
      value
      Description

      The post-condition, encoded as a buffer.

    Example using revert_if_nft_not_owned_by_account

    action "my_tx" "stacks::call_contract" {
    contract_id = "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.some-contract"
    function_name = "some-function"
    function_args = []
    post_condition = [
        stacks::revert_if_nft_not_owned_by_account(
            "ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC", 
            "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.some-contract", 
            "nft_asset_id"
        )
    ]
}
    function

    revert_if_nft_owned_by_account

    stacks::revert_if_nft_owned_by_account returns a post condition that will cancel a successfully executed transaction if the transaction results in the specified account owning a specific NFT.

    Inputs

    • Name
      account_address
      Description

      The address of the account that the post condition will check.

    • Name
      contract_asset_id
      Description

      The NFT Contract Asset Id to check (<principal>.<contract_name>::<non_fungible_storage>).

    • Name
      asset_id
      Description

      The NFT Asset Id to check.

    Output

    • Name
      value
      Description

      The post-condition, encoded as a buffer.

    Example using revert_if_nft_owned_by_account

    action "my_tx" "stacks::call_contract" {
    contract_id = "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.some-contract"
    function_name = "some-function"
    function_args = []
    post_condition = [
        stacks::revert_if_nft_owned_by_account(
            "ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC", 
            "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.some-contract", 
            "nft_asset_id"
        )
    ]
}
    function

    decode_response

    stacks::decode_response returns the inner value of a Clarity Response as a Clarity buffer.

    Inputs

    • Name
      clarity_value
      Description

      Any Clarity Response ((ok <inner>) or (err <inner>)) type.

    Output

    • Name
      value
      Description

      The inner value that was wrapped in a Clarity Response type.

    Example using decode_response

    variable "ok_uint" {
    value = stacks::cv_ok(1)
}
output "ok" {
    value = variable.ok_uint
}
output "decoded_ok" {
    value = stacks::decode_response(variable.ok_uint)
} 
// > ok: 0x070100000000000000000000000000000001
// > decoded_ok: 0x0100000000000000000000000000000001
    function

    get_contract_from_clarinet_project

    stacks::get_contract_from_clarinet_project retrieves the source of a contract present in a Clarinet manifest.

    Inputs

    • Name
      contract_name
      Description

      Contract name of the contract source to fetch.

    • Name
      clarinet_manifest_path
      Description

      The path of the Clarinet.toml file. Defaults to ./Clarinet.toml.

    Output

    • Name
      value
      Description

      The source code of the contract

    Example using get_contract_from_clarinet_project

    variable "contract_source" {
    value = stacks::get_contract_from_clarinet_project("my-contract")
}
output "contract_source" {
    value = variable.contract_source
}

    Was this page helpful?