In this tutorial, you learn how to implement a smart contract that stores and manipulates an integer value on the Stacks 2.0 blockchain. By the end of this tutorial, you will …
- Have experienced test-driven development with Clarity
- Understand more Clarity language design principles
- Have a working Clarity counter smart contract
- Step 1: Downloading counter starter project
- Step 2: Running tests
- Step 3: Developing a smart contract
- If you’re ready to deploy and execute the contract, try the Explorer Sandbox or following the instructions to run the contract in the command-line.
- Where to go next
Before you get started, you should complete the Hello World tutorial.
Step 1: Downloading counter starter project
In this step, you initialize a starter project with additional counter tutorial files:
Using your terminal, run the following command to create a new folder and initialize a new project:
mkdir counter; cd counter npm init clarity-starter
You must now select a template. Type
counter and hit ENTER:
? Template - one of [hello-world, counter]: counter
Finally, the project dependencies are installed and your project is ready for development. Because you already completed the Hello World tutorial, the project structure is familiar to you. The main difference is that we have additional tests for a new counter smart contract.
Step 2: Running tests
Smart contracts are often developed in a test-driven approach. This not only improves code quality, but also removes the need to push every iteration to the blockchain before executing it. We will do the same in this project. Now, let’s run the tests and review the results:
Still in the project root directory, run the following command:
You should see the following response:
counter contract test suite ✓ should have a valid syntax deploying an instance of the contract 1) should start at zero 2) should increment 3) should decrement 1 passing (734ms) 3 failing ... # error details npm ERR! Test failed. See above for more details.
It looks like we see some failed tests! That is on purpose - we will implement the new smart contract in the next steps! After every step in this tutorial, we will rerun the tests to ensure we’re on the right track.
Step 3: Developing a smart contract
Let’s get familiar with the tests to understand what the new smart contract should look like
Take a quick look at the test file associated with the counter smart contract:
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:
counterClient = new Client("SP3GWX3NE58KXHESRYE4DYQ1S31PQJTCRXB3PE9SB.counter", "counter", provider);
That tells us that the new smart contract is named
counterand that it should be found in the following file:
contracts/counter.clar. Note that the
contractsfolder is assumed as the base folder and that every Clarity file has the suffix
The file was already created during the project setup.
With the editor of your choice, open
contracts/counter.clarand add the following lines of code:
(define-data-var counter int 0) (define-public (get-counter) (ok (var-get counter)))
The first line initializes a new integer variable
counterwith the value set to
define-data-varstatement. It is important to note that all definition statements in Clarity need to be at the top of the file.
countervariable is stored in the data space associated with this particular smart contract. The variable is persisted and acts as the global shared state.
To provide access to the
countervariable 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
var-getstatement looks for a variable in the contract’s data space and returns it.
With that, you are ready to rerun the tests!
Run the tests and review the results:
You should now only see 2 failing tests!
should start at zerois passing, and you successfully build your first part of the contract. Congrats!
However, we don’t stop here. Let’s implement increment and decrement functions.
Add the following lines to the bottom of the
counter.clarfile and take a few seconds to review them:
(define-public (increment) (begin (var-set counter (+ (var-get counter) 1)) (ok (var-get counter))))
beginstatement 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.
var-setis used to set a new value for the
countervariable. The new value is constructed using the
+(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.
Finally, take a few minutes and implement a new public function
countervariable. 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 4 passed tests:
counter contract test suite ✓ should have a valid syntax (39ms) deploying an instance of the contract ✓ should start at zero ✓ should increment (133ms) ✓ should decrement (177ms) 4 passing (586ms)
Congratulations! You just implemented your first Clarity smart 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:
(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))))
If you’re ready to deploy and execute the contract, try the Explorer Sandbox or following the instructions to run the contract in the command-line.
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