This file contains the reference for the Clarity language.
@ -18,7 +18,7 @@ The `get-block-info` function fetches property details for a block at a specifie
(get-block-info time 10) ;; Returns 1557860301
```
Because the Clarity language is in pre-release, the block properties that are fetched are simulated properties from a SQLite database. The available property names are:
Because the Clarity language is in early release, the block properties that are fetched are simulated properties from a SQLite database. The available property names are:
<tableclass="uk-table">
<tr>
@ -55,6 +55,12 @@ This section lists the types available to smart contracts. The only atomic types
The integer type in the Clarity language is a 16-byte signed integer, which allows it to specify the maximum amount of microstacks spendable in a single Stacks transfer. The special `BlockHeightInt` you can obtain with the `get-block-info` function.
### Uint type
The unsigned integer type (`uint`) in the Clarity language is a 16-byte unsigned integer. Using the unsigned type can ensure that any value underflows (negative numbers) will cause a transaction to be aborted.
Anywhere a developer wishes to use a literal unsigned integer (for example, incrementing or decrementing an input by a constant) the integer literal should use the `u` prefix, e.g., `u123`.
Clarity is Blockstack's smart contracting language for use with the Stacks blockchain. Clarity supports programmatic control over digital assets within the Stacks blockchain (for example, BNS names, Stacks tokens, and so forth). This section discusses the following topics:
@ -12,8 +12,8 @@ Clarity is Blockstack's smart contracting language for use with the Stacks block
{:toc}
<divclass="uk-card uk-card-default uk-card-body">
<h5>Clarity is in pre-release</h5>
<p>Clarity, its accompanying toolset, and the SDK are in pre-release. If you encounter issues with or have feature requests regarding Clarity, please create an issue on the <ahref='https://github.com/blockstack/blockstack-core/issues'target='_blank'>blockstack/blockstack-core</a> repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the <strong><ahref='https://forum.blockstack.org/c/clarity'target='_blank'>Smart Contracts</a></strong> topic in the Blockstack Forum.
<h5>Early Release</h5>
<p>Clarity and its accompanying toolset are in early release. If you encounter issues with or have feature requests regarding Clarity, please create an issue on the <ahref='https://github.com/blockstack/stacks-blockchain/issues'target='_blank'>blockstack/stacks-blockchain</a> repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the <strong><ahref='https://forum.blockstack.org/c/clarity'target='_blank'>Smart Contracts</a></strong> topic in the Blockstack Forum.
</p>
</div>
@ -42,11 +42,11 @@ Contracts can also call public functions from other smart contracts. The ability
Clarity is a list processing (LISP) language, as such it is not compiled. Omitting compilation prevents the possibility of error or bugs introduced at the compiler level. You can write Clarity smart contract programs on any operating system with a text editor. You can use any editor you are comfortable with such as Atom, Vim, or even Notepad. The Clarity files you create with an editor have a `.clar` extension.
Clarity is in pre-release and does not yet directly interact with the live Stacks blockchain. For the pre-release period you need a test environment to run Clarity contracts. Blockstack provides a Docker image called `clarity-developer-preview` that you can use or you can build a test environment locally from code. Either the Docker image or a local environment is sufficient for testing Clarity programming for standalone contracts.
Clarity is in easly release and does not yet directly interact with the live Stacks blockchain. For the early release period you need a test environment to run Clarity contracts. Blockstack provides a Docker image called `clarity-developer-preview` that you can use or you can build a test environment locally from code. Either the Docker image or a local environment is sufficient for testing Clarity programming for standalone contracts.
You use the `clarity-cli` command line to check, launch, and execute standalone Clarity contracts inside the virtual test environment. You can use this same command line to create simulate mining Stacks and inspecting a blockchain.
Blockstack expects that some decentralized applications (DApp) will want to make use of Clarity contracts as part of their applications. For this purpose, you should use the Clarity SDK, also in pre-release. The SDK is a development environment, testing framework, and deployment tool. It provides a library for safe interactions with Clarity contracts from a DApp written with the blockstack.js library. The SDK has a `clarity` command line for creating Clarity projects.
Blockstack expects that some decentralized applications (DApp) will want to make use of Clarity contracts as part of their applications. For this purpose, you should use the Clarity SDK, also in early release. The SDK is a development environment, testing framework, and deployment tool. It provides a library for safe interactions with Clarity contracts from a DApp written with the blockstack.js library. The SDK has a `clarity` command line for creating Clarity projects.
## Basic building blocks of Clarity contracts
@ -85,7 +85,7 @@ The easiest program to run in any language is a hello world program. In Clarity,
This program defines a single `hello-world` expression that is excuted when the contract launches. The `begin` is a native Clarity function that evaluates the expressions input to it and returns the value of the last expression. Here there is a single `print` expression. Both the `begin` and the `print` are enclosed in `()` parentheses.
For the pre-release, the Blockstack test environment includes the `clarity-cli` command for interacting with the contract and SQLite to support the data space. You create a SQLLite database to hold data related to Clarity contracts. This database simulates the blockchain by recording the contract activity.
For the early release, the Blockstack test environment includes the `clarity-cli` command for interacting with the contract and SQLite to support the data space. You create a SQLLite database to hold data related to Clarity contracts. This database simulates the blockchain by recording the contract activity.
You can't run even an a hello-world program without first initializing a Clarity contract's data space within the database. You can use the `clarity-cli initialize` command to set up the database.
@ -12,8 +12,8 @@ You can use the software developer kit (SDK) to develop, test, and deploy Clarit
{:toc}
<divclass="uk-card uk-card-default uk-card-body">
<h5>Clarity is in pre-release</h5>
<p>Clarity, its accompanying toolset, and the SDK are in pre-release. If you encounter issues with or have feature requests regarding Clarity, please create an issue on the <ahref='https://github.com/blockstack/blockstack-core/issues'target='_blank'>blockstack/blockstack-core</a> repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the <strong><ahref='https://forum.blockstack.org/c/clarity'target='_blank'>Smart Contracts</a></strong> topic in the Blockstack Forum.
<h5>Early Release</h5>
<p>Clarity and its accompanying toolset are in early release. If you encounter issues with or have feature requests regarding Clarity, please create an issue on the <ahref='https://github.com/blockstack/stacks-blockchain/issues'target='_blank'>blockstack/stacks-blockchain</a> repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the <strong><ahref='https://forum.blockstack.org/c/clarity'target='_blank'>Smart Contracts</a></strong> topic in the Blockstack Forum.
</p>
</div>
@ -97,10 +97,10 @@ In this task, you generate a project scaffold — an initial set of director
In this tutorial, you learn how to use Clarity, Blockstack's smart contracting language inside of a virtual environment. The environment is run using a Docker image. Use this tutorial to get a quick introduction to Clarity and the default Blockstack test environment.
| Audience | | **Beginners** |
| Duration | | **15 minutes** |
In this tutorial, you learn how to use Clarity, Blockstack's smart contracting language inside of a virtual environment. The environment is run using a [Docker](https://www.docker.com/) image. Use this tutorial to get a quick introduction to Clarity and the default Blockstack test environment.
By the end of this tutorial you will ...
* Have working test environment to run Clarity smart contracts
* Have access to a set of sample contracts to play with
* Understand basic Clarity language design principles
* Deploy and run your own smart contract
## Overview
* TOC
{:toc}
<divclass="uk-card uk-card-default uk-card-body">
<h5>Clarity is in pre-release</h5>
<p>Clarity and its accompanying toolset are in pre-release. If you encounter issues with or have feature requests regarding Clarity, please create an issue on the <ahref='https://github.com/blockstack/blockstack-core/issues'target='_blank'>blockstack/blockstack-core</a> repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the <strong><ahref='https://forum.blockstack.org/c/clarity'target='_blank'>Smart Contracts</a></strong> topic in the Blockstack Forum.
<h5>Early Release</h5>
<p>Clarity and its accompanying toolset are in early release. If you encounter issues with or have feature requests regarding Clarity, please create an issue on the <ahref='https://github.com/blockstack/stacks-blockchain/issues'target='_blank'>blockstack/stacks-blockchain</a> repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the <strong><ahref='https://forum.blockstack.org/c/clarity'target='_blank'>Smart Contracts</a></strong> topic in the Blockstack Forum.
</p>
</div>
## Before you begin (pre-requisites)
The Clarity language goes live in the next Stacks blockchain fork. Until the fork, you can run Clarity in a test environment. You run this test environment in a Docker container. Before you begin this tutorial, make sure you have <ahref="https://docs.docker.com"target="_blank">Docker installed on your workstation</a>.
The Clarity language goes live with the release of Stacks2.0. Until then, you can run Clarity in a test environment. You run this test environment in a Docker container. Before you begin this tutorial, make sure you have <ahref="https://docs.docker.com/get-docker/"target="_blank">Docker installed on your workstation</a>.
If, for some reason, you don't want to run the test environment with Docker, you can build and maintain a local environment. Instructions for downloading and building the environment are available in the `blockstack/blockstack-core` repository's <ahref='https://github.com/blockstack/blockstack-core'target='_blank'>README</a> file.
You can verify your Docker installation by running the following in your terminal:
```bash
docker verion
```
## Task 1: Set up the test environment
You should see the version of your Docker engine running on your workstation.
Blockstack publishes the `clarity-developer-preview` image on Docker hub. A container built from this image contains sample programs, the Blockstack Core, and tools for working with them. In this task, you use Docker to pull and run the image on your local workstation.
## Step 1: Set up the test environment
1. Pull the Blockstack core `clarity-developer-preview` image from Docker Hub.
In this step, you use the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) to pull and run the image on your local workstation.
1. Using your terminal, download the latest [Stacks 2.0 blockchain Docker image](https://hub.docker.com/r/blockstack/stacks-blockchain) from the Docker Hub:
2. Start the Blockstack Core test environment with a Bash shell.
2. Now, you can start the Stack2.0 test environment in your terminal:
```bash
$ docker run -it -v $HOME/blockstack-dev-data:/data/ blockstack/blockstack-core:clarity-developer-preview bash
docker run -it -v $HOME/blockstack-dev-data:/data/ blockstack/stacks-blockchain:latest bash
```
The command launches a container with the Clarity test environment and opens a bash shell into the container. The `-v` flag creates a local `$HOME/blockstack-dev-data` directory in your workstation and mounts it at the `/data` directory inside the container. The shell opens into the `src/blockstack-core` directory. This directory contains the source for a core and includes Clarity contract samples you can run.
The command opens a bash shell inside the Docker image, so that you can operate in the test environment.
3. List the contents of the `sample-programs` directory.
## Step 2: Review sample contracts
With a test environment running on your workstation, let's have a look at some sample contracts implemented with Clarity.
```bash
root@f88368ba07b2:/src/blockstack-core# ls sample-programs/
names.clar tokens.clar
```
1. Still inside the bash shell of the Docker image, list the contents of the `sample-contracts` directory.
```bash
ls sample-contracts/
```
The sample program's directory contains two simple Clarity programs. Clarity code files have a `.clar` suffix.
This directory contains a set of simple Clarity contracts. Note that all Clarity files have a `.clar` suffix.
4. Go ahead and display the contents of the `tokens.clar` program with the `cat` command.
2. Let's review the contents of `tokens.clar` with the `cat` command.
The next section gives you an introduction to the Clarity language by way of examining this program's code.
You should see the contract source code. Take a few minutes to review the content.
## Task 2: Review a simple Clarity program
Clarity is a programming language based on [LISP](https://en.wikipedia.org/wiki/Lisp_(programming_language)). Most notably, Clarity is designed for static analysis, not compiled, and **not** [Turing complete](https://en.wikipedia.org/wiki/Turing_completeness).
If you haven't already done so, use the `cat` or `more` command to display the `tokens.clar` file's code. Clarity is designed for static analysis; it is not a compiled language and is not Turing complete. It language is a LISP-like language. LISP is an acronym for list processing.
Let's go through the source code:
The first lines of the `tokens.clar` program contains a user-defined `get-balance` function.
Notice the program and each statement is enclosed in `()` (parentheses).
`get-balance` is a private function because it is constructed with the `define-private` call. To create public functions, you would use the `define-public` function. Public functions can be called from other contracts or even from the command line with the `clarity-cli`.
The first line defines a map for `tokens` with the account-balance key-value pairs. The `account` key is of the [`principal`](https://docs.blockstack.org/core/smart/clarityref#principal-type) type. Principals represent a spending entity and are roughly equivalent to a Stacks address. The `balance` value is an unsigned integer ([`uint`](https://docs.blockstack.org/core/smart/clarityref#uint-type)). Along with principals and signed/unsigned integers, Clarity supports the following types:
Notice the program is enclosed in `()` (parentheses) and each statement as well. The `get-balance` function takes an `account` argument of the special type `principal`. Principals represent a spending entity and are roughly equivalent to a Stacks address.
On line 2 and 3, a `get-balance` function is declared as a private function. To create public functions, you would use the `define-public` function. Public functions can be called from DApps, CLIs, or other contracts.
The `get-balance` function returns the value (`balance`) for the key provided (`account`). Using `default-to`, an unsigned integer `0` (note the `u0` literal to differentiate between signed integers) is returned if the account key cannot be found in the `tokens` map.
Along with the `principal` types, Clarity supports booleans, integers, and fixed-length buffers. Variables are created via `let` binding, but there is no support for mutating functions like `set`.
Let's look at the next method definition. The private method `token-credit!` is defined below. It takes a principal and unsigned integer as input parameters:
The next sequence of lines shows an `if` statement that allows you to set conditions for execution in the language.
On the first line of the method, we see how conditions can be used with the [`if`](https://docs.blockstack.org/core/smart/clarityref#if) statement. The if statement takes a boolean argument and two expressions. The first expression is executed when the boolean argument evalutes true. In this case, [`err`](https://docs.blockstack.org/core/smart/clarityref#int-type) is used to return an error response type with the error message provided.
--> TODO
Variables are created via [`let`](https://docs.blockstack.org/core/smart/clarityref#let) binding, but there is no support for mutating functions like `set`.
Every smart contract has both a data space and code. The data space of a contract may only interact with that contract. This particular function is interacting with a map named `tokens`. The `set-entry!` function is a native function that sets the value associated with the input key to the inputted value in the `tokens` data map. Because `set-entry!` mutates data so it has an `!` exclamation point; this is by convention in Clarity.
Every smart contract has both a data space and code. The data space of a contract may only interact with that contract. This particular function is interacting with a map named `tokens` (defined on line 1). The [`map-set`](https://docs.blockstack.org/core/smart/clarityref#map-set) function sets the value associated with the input key to the inputted value in the `tokens` data map.
In the first `token-transfer` public function, you see that it calls the private `get-balance` function and passes it `tx-sender`. The `tx-sender` is a globally defined variable that represents the current principal.
In the first `token-transfer` public function, you see that it calls the private `get-balance` function and passes it `tx-sender`. The `tx-sender` is a globally defined variable that represents the current principal.
@ -115,10 +143,10 @@ The final two lines of the program pass a principal, represented by a Stacks add
Smart contracts may call other smart contracts using a `contract-call!` function. This ability means that if a transaction invokes a function in a given smart contract, that function is able to make calls into other smart contracts on your behalf. The ability to read and do a static analysis of Clarity code allows clients to learn which functions a given smart contract will ever call. Good clients should always warn users about any potential side effects of a given transaction.
Take a moment to `cat` the contents of the `sample-programs/names.clar` file.
Take a moment to `cat` the contents of the `sample-contracts/names.clar` file.
```bash
cat sample-programs/names.clar
cat sample-contracts/names.clar
````
Which `tokens.clar` function is being called?
@ -139,7 +167,7 @@ In this task, you interact with the the contracts using the `clarity-cli` comman
@ -181,7 +209,7 @@ In this task, you interact with the the contracts using the `clarity-cli` comman
You use the `launch` command to instantiate a contract on the Stacks blockchain. If you have dependencies between contracts, for example `names.clar` is dependent on `tokens.clar`, you must launch the dependency first.
The database exists on your local workstation and persists through restarts of the container. You can use this database to explore the transactional effects of your Clarity programs. The SQLite database includes a single `data_table` and a set of `marf` structures.
Alex Graebe
5 years ago