diff --git a/_core/smart/clarityRef.md b/_core/smart/clarityRef.md index 673e3808..7279f099 100644 --- a/_core/smart/clarityRef.md +++ b/_core/smart/clarityRef.md @@ -3,7 +3,7 @@ layout: core description: "Blockstack smart contracting language" permalink: /:collection/:path.html --- -# Clarity language reference +# Language Reference 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: @@ -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`. + ### Bool type Supports values of `'true` or `'false`. diff --git a/_core/smart/functions.md b/_core/smart/functions.md index 2dfc9a79..b8afda2b 100644 --- a/_core/smart/functions.md +++ b/_core/smart/functions.md @@ -3,7 +3,7 @@ layout: core description: "Blockstack smart contracting language" permalink: /:collection/:path.html --- -# Define functions and data maps +# Defining Functions and Maps {:.no_toc} Clarity includes _defines_ and native functions for creating user-defined functions. diff --git a/_core/smart/overview.md b/_core/smart/overview.md index 02bf0ec4..6e1ccc01 100644 --- a/_core/smart/overview.md +++ b/_core/smart/overview.md @@ -3,7 +3,7 @@ layout: core description: "Blockstack smart contracting language" permalink: /:collection/:path.html --- -# Welcome to Clarity +# Introduction {:.no_toc} 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}
-
Clarity is in pre-release
-

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 blockstack/blockstack-core repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the Smart Contracts topic in the Blockstack Forum. +

Early Release
+

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 blockstack/stacks-blockchain repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the Smart Contracts topic in the Blockstack Forum.

@@ -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. diff --git a/_core/smart/principals.md b/_core/smart/principals.md index 53f267ca..1b2f7e74 100644 --- a/_core/smart/principals.md +++ b/_core/smart/principals.md @@ -3,7 +3,7 @@ layout: core description: "Blockstack smart contracting language" permalink: /:collection/:path.html --- -# Principals +# Understanding Principals {:.no_toc} _Principals_ are a Clarity native type that represents a spending entity. This section discusses principals and how they are used in the Clarity. diff --git a/_core/smart/sdk-quickstart.md b/_core/smart/sdk-quickstart.md index 6435393c..84294fa3 100644 --- a/_core/smart/sdk-quickstart.md +++ b/_core/smart/sdk-quickstart.md @@ -12,8 +12,8 @@ You can use the software developer kit (SDK) to develop, test, and deploy Clarit {:toc}
-
Clarity is in pre-release
-

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 blockstack/blockstack-core repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the Smart Contracts topic in the Blockstack Forum. +

Early Release
+

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 blockstack/stacks-blockchain repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the Smart Contracts topic in the Blockstack Forum.

@@ -97,10 +97,10 @@ In this task, you generate a project scaffold — an initial set of director Your project should contain three directories: - | Directory |Description | - |---|---| - | `contracts` | Contains `.clar` files (Clarity contract files) here. | - | `test` | Contains files for testing your application. | + | Directory | Description | + | -------------- | --------------------------------------------------------- | + | `contracts` | Contains `.clar` files (Clarity contract files) here. | + | `test` | Contains files for testing your application. | | `node_modules` | Contains packages the project depends on. Added by `npm`. | The `contracts` directory contains a single file in `sample/hello-world.clar` file. diff --git a/_core/smart/tutorial.md b/_core/smart/tutorial.md index 6ff6066e..3ef105e3 100644 --- a/_core/smart/tutorial.md +++ b/_core/smart/tutorial.md @@ -3,95 +3,123 @@ layout: core description: "Blockstack smart contracting language" permalink: /:collection/:path.html --- -# Hello Clarity for the VM +# Hello Clarity -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}
-
Clarity is in pre-release
-

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 blockstack/blockstack-core repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the Smart Contracts topic in the Blockstack Forum. +

Early Release
+

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 blockstack/stacks-blockchain repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the Smart Contracts topic in the Blockstack Forum.

## 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 Docker installed on your workstation. +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 Docker installed on your workstation. -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 README 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: ```bash - $ docker pull blockstack/blockstack-core:clarity-developer-preview - ``` + docker pull blockstack/stacks-blockchain:latest + ``` -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. ```bash - root@c28600552694:/src/blockstack-core# cat sample-programs/tokens.clar + cat sample-contracts/tokens.clar ``` - 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. + ```cl + (define-map tokens ((account principal)) ((balance uint))) + (define-private (get-balance (account principal)) + (default-to u0 (get balance (map-get? tokens (tuple (account account)))))) + ``` -```cl -(define-map tokens ((account principal)) ((balance uint))) -(define-private (get-balance (account principal)) - (default-to u0 (get balance (map-get? tokens (tuple (account account)))))) -``` + 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: + * [booleans](https://docs.blockstack.org/core/smart/clarityref#bool-type) + * [fixed-length buffers](https://docs.blockstack.org/core/smart/clarityref#buffer-type) + * [tuples](https://docs.blockstack.org/core/smart/clarityref#tuple-type) -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. + ```cl + (define-private (token-credit! (account principal) (amount uint)) + (if (<= amount u0) + (err "must move positive balance") + (let ((current-amount (get-balance account))) + (begin + (map-set tokens (tuple (account account)) + (tuple (balance (+ amount current-amount)))) + (ok amount))))) + ``` -```cl -(define-private (token-credit! (account principal) (amount uint)) - (if (<= amount u0) - (err "must move positive balance") - (let ((current-amount (get-balance account))) - (begin - (map-set tokens (tuple (account account)) - (tuple (balance (+ amount current-amount)))) - (ok amount))))) -``` + 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`. + - Describe: `token-credit`, `!`, `current-amount`, `begin`, `ok` -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. ```cl (define-public (token-transfer (to principal) (amount uint)) @@ -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 2. Type check the `names.clar` contract. ```bash - # clarity-cli check sample-programs/names.clar /data/db + # clarity-cli check sample-contracts/names.clar /data/db ``` You should get an error: @@ -153,7 +181,7 @@ In this task, you interact with the the contracts using the `clarity-cli` comman 3. Type check the `tokens.clar` contract, it should pass a check as it does not use the `contract-call` function: ```bash - # clarity-cli check sample-programs/tokens.clar /data/db + # clarity-cli check sample-contracts/tokens.clar /data/db Checks passed. ``` @@ -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. ```bash - # clarity-cli launch $DEMO_ADDRESS.tokens sample-programs/tokens.clar /data/db + # clarity-cli launch $DEMO_ADDRESS.tokens sample-contracts/tokens.clar /data/db Contract initialized! ``` @@ -190,7 +218,7 @@ In this task, you interact with the the contracts using the `clarity-cli` comman 7. Instantiate the `names.clar` contract and assign it to your `DEMO_ADDRESS` address. as well. ```bash - # clarity-cli launch $DEMO_ADDRESS.names sample-programs/names.clar /data/db + # clarity-cli launch $DEMO_ADDRESS.names sample-contracts/names.clar /data/db Contract initialized! ``` @@ -205,7 +233,7 @@ clarity-cli initialize /data/db As you work the contracts, data is added to the `db` database because you pass this database as a parameter, for example: ```bash -clarity-cli launch $DEMO_ADDRESS.tokens sample-programs/tokens.clar /data/db +clarity-cli launch $DEMO_ADDRESS.tokens sample-contracts/tokens.clar /data/db ``` 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. diff --git a/_data/navigation_core.yml b/_data/navigation_core.yml index f2bf3806..00298d54 100644 --- a/_data/navigation_core.yml +++ b/_data/navigation_core.yml @@ -1,4 +1,14 @@ -- title: Overview +- title: Smart Contracts + docs: + - core/smart/overview + - core/smart/tutorial + - core/smart/principals + - core/smart/functions + - core/smart/clarityRef + - core/smart/clarityCLI + - core/smart/sdk-quickstart + +- title: Naming Services docs: - core/naming/introduction - core/naming/architecture @@ -11,16 +21,6 @@ - core/naming/search - core/faq_technical -- title: Clarity Smart Contracts - docs: - - core/smart/overview - - core/smart/principals - - core/smart/functions - - core/smart/tutorial - - core/smart/clarityRef - - core/smart/clarityCLI - - core/smart/sdk-quickstart - - title: How to use BNS docs: - core/naming/pickname diff --git a/_data/navigation_home.yml b/_data/navigation_home.yml index 066090d5..cfe8fb82 100644 --- a/_data/navigation_home.yml +++ b/_data/navigation_home.yml @@ -1,24 +1,24 @@ # Categories home page navigation -- title: Evaluate the Blockstack Ecosystem - desc: Learn the components that make up the Blockstack Ecosystem. Understand the value a blockchain offers. - icon: info - doc: org/overview - -- title: Use Blockchain Applications - desc: Learn about the New Internet and blockchain applications. Create an identity and learn how to use it. - icon: settings - doc: browser/browser-introduction - -- title: Build Blockchain Applications +- title: Build Decentralized Apps desc: Learn how to build a blockchain application with Blockstack. Work through web and mobile tutorials. icon: code doc: develop/zero_to_dapp_1 -- title: Blockstack Core +- title: Build Smart Contracts desc: Work with our Core node, smart contracts, namespaces, zone files, and other advanced topics. icon: cog - doc: core/naming/introduction + doc: core/smart/overview + +- title: Use Blockchain Apps + desc: Learn about the New Internet and blockchain applications. Create an identity and learn how to use it. + icon: settings + doc: browser/browser-introduction + +- title: Evaluate the Blockstack Ecosystem + desc: Learn the components that make up the Blockstack Ecosystem. Understand the value a blockchain offers. + icon: info + doc: org/overview - title: Implement Storage with Gaia desc: Backend storage drivers and interactions between developer APIs and the Gaia service. diff --git a/_sass/syntax-highlighting/github.scss b/_sass/syntax-highlighting/github.scss index c85e1ed1..a2bc4214 100644 --- a/_sass/syntax-highlighting/github.scss +++ b/_sass/syntax-highlighting/github.scss @@ -3,8 +3,13 @@ */ +a>.highlight, +.highlighter-rouge { + color: inherit !important; +} -.highlight, .highlighter-rouge { +.highlight, +.highlighter-rouge { background-color: #F7F8FA; color: #5A6575; border: none; @@ -286,4 +291,4 @@ .highlight .il { color: #E56134 -} +} \ No newline at end of file