In the world of smart contracts, everything is a blockchain transaction. You use tokens in your wallet to deploy a smart contract in a transaction, and each call to that contract after it's published is a transaction, too. That means that at each step, tokens are being exchanged as transaction fees. This tutorial introduces you to this mode of programming, which transforms blockchains into powerful state machines capable of executing complex logic.
In the world of smart contracts, everything is a blockchain transaction. You use tokens in your wallet to deploy a smart
contract in a transaction, and each call to that contract after it's published is a transaction, too. That means that at
each step, you must exchange tokens as transaction fees. This tutorial introduces you to this mode of programming, which
transforms blockchains into powerful state machines capable of executing complex logic.
Clarity, the smart contracting language used on the Stacks Blockchain, is based on LISP and uses its parenthesized notation. Clarity is an [interpreted language](https://en.wikipedia.org/wiki/Interpreted_language), and [decidable](https://en.wikipedia.org/wiki/Recursive_language). To learn more basics about the language, see the [Introduction to Clarity](/write-smart-contracts/overview) topic.
Clarity, the smart contracting language used on the Stacks Blockchain, is a LISP-based language and uses its
parenthesized notation. Clarity is an [interpreted language](https://en.wikipedia.org/wiki/Interpreted_language), and
[decidable](https://en.wikipedia.org/wiki/Recursive_language). To learn more basics about the language, see the
[Introduction to Clarity](/write-smart-contracts/overview) topic.
By the end of this tutorial, you:
By the end of this tutorial, you:
@ -25,17 +31,26 @@ By the end of this tutorial, you:
## Prerequisites
## Prerequisites
This tutorial uses a virtual development environment in a browser, as such you must have a web browser capable of
running the virtual development environment, and an active internet connection for the duration of the tutorial. You
must also have a [Github account](https://www.github.com) to log in to the development environment.
### Check the Stacks 2.0 status
### 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](https://stacks-status.com/) and confirm that all systems are operational. If some systems seem to have issues, it's best to wait until they're back up before you proceed with the next steps.
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](https://stacks-status.com/) and confirm that all systems are operational. If some systems seem to have
issues, it's best to wait until they're back up before you proceed with the next steps.
## Step 1: open the playground
## Step 1: open the playground
To avoid setting things up on your machine, you can run all instructions inside a virtual container inside your browser window, using a project called Gitpod.
To avoid setting things up on your machine, you can run all instructions inside a virtual container inside your browser
window, using a project called Gitpod.
**[Open this Gitpod in a new browser window](https://gitpod.io/#https://github.com/agraebe/clarity-onboarding-playground)**
**[Open this Gitpod in a new browser window](https://gitpod.io/#https://github.com/agraebe/clarity-onboarding-playground)**
Gitpod will require you to login with a Github account. Follow the steps described on the screen. Once completed, you can see code editor window:
Gitpod requires you to login with a Github account. Follow the steps described on the screen. Once completed, you can
@ -49,7 +64,8 @@ Using the terminal window on the bottom of the screen, run the following command
npm init clarity-starter
npm init clarity-starter
```
```
After the starter project is loaded up, you have to select a project template (using your arrow keys). Select `Hello World`, which is the default, by hitting ENTER.
After the starter project loads, select a project template with the arrow keys. Select `Hello World`, which is the
default, and press Enter.
```bash
```bash
? Select a project template: (Use arrow keys)
? Select a project template: (Use arrow keys)
@ -57,13 +73,15 @@ After the starter project is loaded up, you have to select a project template (u
Counter
Counter
```
```
Next, you need to name the project folder. Hit ENTER to accept the default:
Next, you need to name the project folder. Press Enter to accept the default:
```bash
```bash
? Project name: (clarity-hello-world)
? Project name: (clarity-hello-world)
```
```
Wait a few seconds while all project dependencies install. Once completed, you can see a new folder on the left side of the screen (`clarity-hello-world`). This is the location of your new Clarity project. Open the project folder and get familiar with the structure.
Wait while all project dependencies install. Once completed, you can see a new folder on the left side of the screen
(`clarity-hello-world`). This is the location of your new Clarity project. Open the project folder and get familiar with
the structure.
## Step 3: review the contract
## Step 3: review the contract
@ -79,13 +97,19 @@ You can see that `()` (parentheses) enclose the program and each statement. The
(ok val))
(ok val))
```
```
On the first line, a new public function `say-hi` is declared. Public functions are callable from other smart contracts, enabling developers to break complex tasks into smaller, simpler smart contracts (an exercise in [separating concerns](https://en.wikipedia.org/wiki/Separation_of_concerns)).
The first line of the contract declares the new public function `say-hi`. Public functions are callable from other smart
contracts, enabling developers to break complex tasks into smaller, simpler smart contracts (an exercise in
-> To create private functions, you would use the `define-private` keyword. Only the current smart contract can run private functions. Other contract can only call public functions.
-> To create private functions, you would use the `define-private` keyword. Only the current smart contract can run
private functions. Other contract can only call public functions.
The function doesn't take any parameters and simply returns "hello world" using the [`ok`](/references/language-functions#ok) response constructor.
The function doesn't take any parameters and simply returns "hello world" using the
The second function, `echo-number`, is a [read-only function](/references/language-functions#define-read-only). Read-only functions are also public, but as the name implies, they can not change any variables or datamaps. `echo-number` takes an input parameter of the type `int`.
The second function, `echo-number`, is a [read-only function](/references/language-functions#define-read-only).
Read-only functions are also public, but as the name implies, they can not change any variables or datamaps.
`echo-number` takes an input parameter of the type `int`.
-> Clarity supports a variety of other [types](/references/language-types)
-> Clarity supports a variety of other [types](/references/language-types)
@ -95,7 +119,8 @@ In the following steps, you can use this sample contract to deploy and run on th
## Step 4: create a Stacks account
## Step 4: create a Stacks account
The container you are using comes pre-installed with Stacks CLI. Back inside the terminal, run the following command to create a new [Stacks 2.0 account](/understand-stacks/accounts):
The container you are using comes pre-installed with Stacks CLI. Back inside the terminal, run the following command to
create a new [Stacks 2.0 account](/understand-stacks/accounts):
@ -123,9 +148,11 @@ Review your new Stacks account details by opening up the file `cli_keychain.json
## Step 5: obtain testing tokens
## Step 5: obtain testing tokens
Uploading and calling smart contracts requires you to pay network fees to process the transactions. You need to get some testnet tokens, so you can pay the fees in the next steps.
Uploading and calling smart contracts requires you to pay network fees to process the transactions using STX tokens. You
need to get some testnet tokens, so you can pay the fees in the next steps.
The **STX faucet** is an API endpoint you can call to request testnet tokens for the new account. In the terminal, run the following command:
The **STX faucet** is an API endpoint you can call to request testnet tokens for the new account. In the terminal, run
the following command:
```bash
```bash
# replace <stx_address> with `address` property from your keychain
# replace <stx_address> with `address` property from your keychain
@ -150,7 +177,8 @@ You need to wait up to a minute for the transaction to complete. Type the follow
stx balance -t <stx_address>
stx balance -t <stx_address>
```
```
Once the transaction is successfully processed, you can see that your new balance is `500000`. This equals 0.5 Stacks (STX) tokens.
Once the transaction is successfully processed, you can see that your new balance is `500000`. This equals 0.5 STX
tokens.
```json
```json
{
{
@ -164,7 +192,8 @@ Once the transaction is successfully processed, you can see that your new balanc
## Step 6: deploy the contract
## Step 6: deploy the contract
A deployed contract on the Testnet is like a cloud function (comparable to serverless functions). It allows you to execute code remotely on the Stacks 2.0 network.
A deployed contract on the Testnet is like a cloud function (comparable to serverless functions). It allows you to
execute code remotely on the Stacks 2.0 network.
Now, you can deploy the reviewed contract file (`hello-world.clar`). Inside the terminal, run the following command:
Now, you can deploy the reviewed contract file (`hello-world.clar`). Inside the terminal, run the following command:
@ -180,15 +209,25 @@ The command returns a new contract deploy transaction ID:
The `deploy_contract` command takes the file contents and deploys a new contract with the name `hello-world`. With that name, the fully qualified contract identifier for the new account is `STNBNMTXV9ERHEDCQA3WE2S4PTF8ANSC24EBDKS2.hello-world`.
The `deploy_contract` command takes the file contents and deploys a new contract with the name `hello-world`. With that
name, the fully qualified contract identifier for the new account is
~> Your address is different. The contract identifier is essentially a naming convention to address deployed contract.
It's based on the dot notation: `<address>.<contract_id>`
Ideally, you should estimate the minimal fees you need to pay. Factors like the size of the contract (among others)
determine the estimate. For this tutorial, you can keep it simple and accept the default fee of `2000` (0.02 STX).
~> Your address is different. The contract identifier is essentially a naming convention to address deployed contract. It's based on the dot notation: `<address>.<contract_id>`
The testnet can take several minutes to deploy the contract. You can monitor the status of the deployment on the testnet
Explorer using the URL format `https://explorer.stacks.co/txid/<transaction_id>?chain=testnet`. Note that you can't
complete the next step of this tutorial until the contract is confirmed in Explorer.
Ideally, you should estimate the minimal fees you need to pay. Factors like the size of the contract (amongst others) determine the estimate. For this tutorial, you can keep it simple and accept the default fee of `2000` (equals 0.02 STX).
You have to wait up to a minute for the contract to broadcast to the network. In the meantime, you can open the transaction with the Explorer. Notice that every deployed smart contracts' source code is publicly verifiable.
-> The contract deploy operation increases the `nonce` of your account. [Read more about nonces](/understand-stacks/network#nonces)
-> Keep in mind that this operation increases the `nonce` of your account. [Read more about nonces](/understand-stacks/network#nonces)
When the contract deploy transaction is confirmed, proceed to the next step.
## Step 7: call the public method
## Step 7: call the public method
@ -202,19 +241,23 @@ As soon as the contract deploys, you can call one of its methods. In this exampl
The command looks up the contract method definition on the network, identifies that it requires an input parameter, and asks you for an integer to set `val`. Enter 42 and hit ENTER.
The command looks up the contract method definition on the network, identifies that it requires an input parameter, and
asks you for an integer to set `val`. Enter 42 and press Enter.
```bash
```bash
42
42
```
```
The method is now executed on the network. This can take a while. Once completed, the corresponding transaction contains the response with the value you just entered, `42`:
The method is now executed on the network. This can take a while. Once completed, the corresponding transaction contains
the response with the value you just entered, `42`:
```bash
```bash
(ok 42)
(ok 42)
```
```
=> **Congratulations!** You can now deploy your smart contract and call public functions on the Testnet using the CLI. You just deployed your smart contract and called a public function on the testnet of the Stacks blockchain using the Stacks CLI.
=> **Congratulations!** You can now deploy your smart contract and call public functions on the Testnet using the CLI.
You just deployed your smart contract and called a public function on the testnet of the Stacks blockchain using the
Patrick Gray
4 years ago
pgray-hiro
