mirror of https://github.com/lukechilds/docs.git
Alex Graebe
5 years ago
6 changed files with 25 additions and 223 deletions
@ -1,175 +0,0 @@ |
|||||
--- |
|
||||
layout: core |
|
||||
description: "Blockstack Clarity: Token Tutorial" |
|
||||
permalink: /:collection/:path.html |
|
||||
--- |
|
||||
# Tutorial: Token |
|
||||
|
|
||||
| Experience | | **Advanced** | |
|
||||
| Duration | | **30 minutes** | |
|
||||
|
|
||||
In this tutorial, you learn ... By the end of this tutorial, you will ... |
|
||||
|
|
||||
* |
|
||||
|
|
||||
## Overview |
|
||||
|
|
||||
* TOC |
|
||||
{:toc} |
|
||||
|
|
||||
<div class="uk-card uk-card-default uk-card-body"> |
|
||||
<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 <a href='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><a href='https://forum.blockstack.org/c/clarity' target='_blank'>Smart Contracts</a></strong> topic in the Blockstack Forum. |
|
||||
</p> |
|
||||
</div> |
|
||||
|
|
||||
## Pre-requisites |
|
||||
|
|
||||
Before you get started with this tutorial, you should complete the [Hello World](tutorial.html) and the [Counter](tutorial-counter.html) tutorials. |
|
||||
|
|
||||
## Step 1: Download token tutorial project |
|
||||
|
|
||||
1. Initialize a starter project with additional token tutorial files: |
|
||||
|
|
||||
```bash |
|
||||
npm init clarity-starter --token-tutorial |
|
||||
``` |
|
||||
|
|
||||
2. Confirm the new project name: |
|
||||
|
|
||||
```bash |
|
||||
? Project name (clarity-token-project) |
|
||||
``` |
|
||||
|
|
||||
## Step 2: Running tests |
|
||||
|
|
||||
Just like in the Counter tutorial, we will use test-driven development to implement our Token smart contract. Let's run the tests and review the results: |
|
||||
|
|
||||
1. Run the following command: |
|
||||
|
|
||||
```bash |
|
||||
npm test |
|
||||
``` |
|
||||
|
|
||||
You should see the following response: |
|
||||
|
|
||||
```bash |
|
||||
... |
|
||||
``` |
|
||||
|
|
||||
## Step 3: Developing the smart contract |
|
||||
|
|
||||
Let's get familiar with the tests to understand what the new smart contract should look like |
|
||||
|
|
||||
1. Take a quick look at the test file associated with the counter smart contract: |
|
||||
|
|
||||
```shell |
|
||||
cat test/counter.ts |
|
||||
``` |
|
||||
|
|
||||
You should be familiar with the test set up from the Hello World tutorial. Notice how the instance of the smart contract is created on line 8: |
|
||||
|
|
||||
```js |
|
||||
counterClient = new Client("SP3GWX3NE58KXHESRYE4DYQ1S31PQJTCRXB3PE9SB.counter", "sample/counter", provider); |
|
||||
``` |
|
||||
|
|
||||
That tells us that the new smart contract is named `counter` and that we need to start by creating a new file for the smart contract: `contracts/sample/counter.clar`. Note that the `contracts` folder is assumed as the base folder and that every Clarity file has the suffix `.clar`. |
|
||||
|
|
||||
2. Let's create the new file: |
|
||||
|
|
||||
```shell |
|
||||
touch contracts/sample/counter.clar |
|
||||
``` |
|
||||
|
|
||||
3. With the editor of your choice, open the file and add the following lines of code: |
|
||||
|
|
||||
```cl |
|
||||
(define-data-var counter int 0) |
|
||||
|
|
||||
(define-public (get-counter) |
|
||||
(ok (var-get counter)) |
|
||||
) |
|
||||
``` |
|
||||
|
|
||||
The first line initializes a new integer variable `counter` with the value set to `0` using the [`define-data-var`](https://docs.blockstack.org/core/smart/clarityref#define-data-var) statement. It is important to note that all definition statements in Clarity need to be at the top of the file. |
|
||||
|
|
||||
To provide access to the variable from outside of the current smart contract, we need to declare a public get method for this variable. The last lines of the code add a public `get-counter` method. The [`var-get`](https://docs.blockstack.org/core/smart/clarityref#var-get) statement looks for a variable in the contract's data map and returns it. |
|
||||
|
|
||||
With that, you are ready to rerun the tests! |
|
||||
|
|
||||
4. Run the tests and review the results: |
|
||||
|
|
||||
```shell |
|
||||
npm test |
|
||||
``` |
|
||||
|
|
||||
You should now only see 2 failing tests! `should start at zero` is passing, and you successfully build your first part of the contract. Congrats! |
|
||||
|
|
||||
However, we don't stop here. Let's implement increment and decrement methods. |
|
||||
|
|
||||
5. Add the following lines to the bottom of the `counter.clar` file and take a few seconds to review them: |
|
||||
|
|
||||
```cl |
|
||||
(define-public (increment) |
|
||||
(begin |
|
||||
(var-set counter (+ (var-get counter) 1)) |
|
||||
(ok (var-get counter)) |
|
||||
) |
|
||||
) |
|
||||
``` |
|
||||
|
|
||||
First, the [`begin`](https://docs.blockstack.org/core/smart/clarityref#begin) statement evaluates the multi-line expressions and returns the value of the last expression. In this case, it is used to set a new value and return the new value. |
|
||||
|
|
||||
Next, a [`var-set`](https://docs.blockstack.org/core/smart/clarityref#var-set) is used to set a new value for the `counter` variable. The new value is constructed using the [`+`](https://docs.blockstack.org/core/smart/clarityref#-add) (add) statement. This statement takes a number of integers and returns the result. Along with add, Clarity provides statements to subtract, multiply, and divide integers. Find more details in the [Clarity language reference](https://docs.blockstack.org/core/smart/clarityref). |
|
||||
|
|
||||
6. Finally, take a few minutes and implement a new public method `decrement` to subtract `1` from the `counter` variable. You should have all knowledge needed to succeed at this! |
|
||||
|
|
||||
Done? Great! Run the tests and make sure all of them are passing. You are looking for 7 successful tests: |
|
||||
|
|
||||
```shell |
|
||||
counter contract test suite |
|
||||
✓ should have a valid syntax |
|
||||
deploying an instance of the contract |
|
||||
✓ should start at zero |
|
||||
✓ should increment (95ms) |
|
||||
✓ should decrement (92ms) |
|
||||
|
|
||||
hello world contract test suite |
|
||||
✓ should have a valid syntax |
|
||||
deploying an instance of the contract |
|
||||
✓ should return 'hello world' |
|
||||
✓ should echo number |
|
||||
|
|
||||
|
|
||||
7 passing (518ms) |
|
||||
``` |
|
||||
|
|
||||
**Congratulations! You just implemented your first Clarity smart contract.** |
|
||||
|
|
||||
7. Here is how the final smart contract file should look like. Note that you can find the `decrement` method in here - in case you want to compare with your own implementation: |
|
||||
|
|
||||
```cl |
|
||||
(define-data-var counter int 0) |
|
||||
(define-public (increment) |
|
||||
(begin |
|
||||
(var-set counter (+ (var-get counter) 1)) |
|
||||
(ok (var-get counter)) |
|
||||
) |
|
||||
) |
|
||||
(define-public (decrement) |
|
||||
(begin |
|
||||
(var-set counter (- (var-get counter) 1)) |
|
||||
(ok (var-get counter)) |
|
||||
) |
|
||||
) |
|
||||
(define-public (get-counter) |
|
||||
(ok (var-get counter)) |
|
||||
) |
|
||||
``` |
|
||||
|
|
||||
## Where to go next |
|
||||
|
|
||||
{:.no_toc} |
|
||||
|
|
||||
* <a href="tutorial-token.html">Next tutorial: Writing a token management smart contract</a> |
|
||||
* <a href="clarityRef.html">Clarity language reference</a> |
|
||||
Loading…
Reference in new issue