@ -19,7 +19,13 @@ In this tutorial, you learn how to implement a smart contract that stores and ma
## Prerequisites
Before you get started, you should complete the [Hello World tutorial](tutorial).
=> Before you get started, you should complete the [Hello World tutorial](hello-world-tutorial).
### Check the Stacks 2.0 status
The Stacks 2.0 blockchain is currently in development and could experience resets and downtimes. To make sure you're not
running into any challenges related to the status of the network, please open up the [Status Checker](http://status.test-blockstack.com/)
and confirm that all systems are operational. If some systems seem to have issues, it is best to wait until they are back up before you proceed with the next steps.
## Step 1: Downloading counter starter project
@ -28,14 +34,17 @@ In this step, you initialize a starter project with additional counter tutorial
Using your terminal, run the following command to create a new folder and initialize a new project:
```bash
# create and go to new `counter` project folder
mkdir counter; cd counter
npm init clarity-starter
```
You must now select a template. Type `counter` and hit ENTER:
You will be asked to select a project template. Press down with your arrow keys to choose `Counter` and hit **ENTER**:
```bash
? Template - one of [hello-world, counter]: counter
? Select a project template: (Use arrow keys)
Hello World
❯ Counter
```
Finally, the project dependencies are installed and your project is ready for development. Because you already completed the [Hello World tutorial](tutorial), the project structure is familiar to you. The main difference is that we have additional tests for a new counter smart contract.
@ -75,15 +84,16 @@ It looks like we see some failed tests! That is on purpose - we will implement t
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:
1. In your editor, take a quick look at the test file associated with the counter smart contract:`test/counter.ts`
```bash
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:
You will see a [Mocha](https://mochajs.org/) test suite. This file describes the tests for the counter smart contract.
Notice how the smart contract is instantiated on line 8 of file `counter.ts`
@ -91,22 +101,43 @@ Let's get familiar with the tests to understand what the new smart contract shou
);
```
That tells us that the new smart contract is named `counter` and that it should be found in the following file: `contracts/counter.clar`. Note that the `contracts` folder is assumed as the base folder and that every Clarity file has the suffix `.clar`.
That tells us that the new smart contract is named `counter` and that it should be found in the following file:
`contracts/counter.clar`. Note that the `contracts` folder is assumed as the base folder and that every Clarity file
has the suffix `.clar`.
The file was already created during the project setup.
2. With the editor of your choice, open `contracts/counter.clar` and add the following lines of code:
2. Using your editor, open `contracts/counter.clar`. You will notice the file already includes some content:
```clarity
(define-data-var counter int 0)
;; define counter variable
;; increment method
;; decrement method
;; counter getter
```
(define-public (get-counter)
(ok (var-get counter)))
What you see are four one-line comments. In Clarity, a comment line is started with `;;`. As you can see, the
comments indicate the structure of the smart contract we are going to implement.
Let's declare a counter variable and define a public getter method:
```clarity
;; define counter variable
(define-data-var counter int 0)
...
;; counter getter
(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.
The [`define-data-var`](https://docs.blockstack.org/core/smart/clarityref#define-data-var) statement initializes a
new integer variable named `counter` and sets the value to `0`. It is important to note that all definition statements
in Clarity need to be at the top of the file.
The `counter` variable is stored in the data space associated with this particular smart contract. The variable is persisted and acts as the global shared state.
The `counter` variable is stored in the data space associated of the smart contract. The variable is persisted and
acts as the global shared state.
To provide access to the `counter` variable from outside of the current smart contract, we need to declare a public function to get it. The last lines of the code add a public `get-counter` function. The [`var-get`](https://docs.blockstack.org/core/smart/clarityref#var-get) statement looks for a variable in the contract's data space and returns it.
@ -122,20 +153,40 @@ Let's get familiar with the tests to understand what the new smart contract shou
However, we don't stop here. Let's implement increment and decrement functions.
4. Add the following lines to the bottom of the `counter.clar` file and take a few seconds to review them:
4. Add the following lines to the `counter.clar` file (below the increment method comment) and take a few seconds to review them:
```clarity
;; increment method
(define-public (increment)
(begin
(var-set counter (+ (var-get counter) 1))
(ok (var-get counter))))
(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).
5. Finally, take a few minutes and implement a new public function `decrement` to subtract `1` from the `counter` variable. You should have all knowledge needed to succeed at this!
5. Next, implement a new public function `decrement` to subtract `1` from the `counter` variable. You should have all knowledge needed to succeed at this!
Here is the final contract:
```clarity
(define-data-var counter int 0)
(define-public (get-counter)
(ok (var-get counter)))
(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))))
```
Done? Great! Run the tests and make sure all of them are passing. You are looking for 4 passed tests:
@ -149,31 +200,26 @@ Let's get familiar with the tests to understand what the new smart contract shou
4 passing (586ms)
```
**Congratulations! You just implemented your first Clarity smart contract.**
## Step 4: Deploy and call the contract
Here is how the final smart contract file should look like. Note that you can find the `decrement` function in here - in case you want to compare with your own implementation:
Your new smart contract is ready to be deployed to the Stacks 2.0 blockchain. You should be familiar with the steps
from the ["Hello, World" tutorial](https://docs.blockstack.org/core/smart/tutorial.html#deploy-the-contract).
```clarity
(define-data-var counter int 0)
As soon as you successfully deploy your contract, you can play around with the contract and verify the functionality by
calling all public methods you implemented. Here's a suggested order:
(define-public (get-counter)
(ok (var-get counter)))
- Call the `get-counter` method. It should return `0`
- Call the `increment` method and let the transaction complete
- Call the `get-counter` method. It should return `1`
- Call the `decrement` method and let the transaction complete
- Call the `get-counter` method. It should return `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))))
```
-> As you can see, read-only function calls don't require a transaction to complete. This is because the method doesn't require a state change.
> If you're ready to deploy and execute the contract, try [the Explorer Sandbox](tutorial.html#access-the-explorer-sandbox) or following [the instructions to run the contract in the command-line](tutorial.html#get-familiar-with-cli-optional).
=> Congratulations! You just implemented, deployed, and called your own Clarity smart contract.
With the completion of this tutorial, you:
- Experienced test-driven development with Clarity
- Understood more Clarity language design principles
- Developed a working Clarity counter smart contract
- Developed a working Clarity counter smart contract and called its public methods
Thomas Osmonson
5 years ago
