Clarity "Hello, World" Deployed on Stacks mainnet
Clarity "Hello, World!" deployed on Stacks

        
        Clarity is a relatively new language that brings smart contracts to Bitcoin.


  It is decidable which means programs must necessarily terminate
  It is interpreted and broadcasted on the network as-is


Clarity is being actively developed by Stacks, Hiro, & Algorand. — Here’s how to deploy a “Hello, World!” smart contract on Stacks mainnet.

Prerequisites


  Clarinet ^0.23.1
  Git ^2.33.0
  VS Code ^1.63.2 or Sublime Text ^4126 with Clarity syntax highlighting


Steps

1. Create a new Clarinet project:

$ clarinet new clarity-hello-world

Creating directory clarity-hello-world
Created file clarity-hello-world/contracts
Created file clarity-hello-world/settings
Created file clarity-hello-world/tests
Created file clarity-hello-world/Clarinet.toml
Created file clarity-hello-world/settings/Mainnet.toml
Created file clarity-hello-world/settings/Testnet.toml
Created file clarity-hello-world/settings/Devnet.toml
Created file clarity-hello-world/.vscode
Created file clarity-hello-world/.vscode/settings.json
Created file clarity-hello-world/.vscode/tasks.json
Created file clarity-hello-world/.gitignore


2. Create a Git repository:

$ cd clarity-hello-world
$ git init

Initialized empty Git repository in /clarity-hello-world/.git/


3. Add the project on Git:

$ git add .
$ git commit -m "Add empty project"

[master (root-commit) 1c57404] Add empty project
 5 files changed, 163 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 .vscode/settings.json
 create mode 100644 .vscode/tasks.json
 create mode 100644 Clarinet.toml
 create mode 100644 settings/Devnet.toml


4. Add a new Clarity contract to the project:

$ clarinet contract new hello-world

Created file contracts/hello-world.clar
Created file tests/hello-world_test.ts
Updated Clarinet.toml with contract hello-world


Clarinet added for us two files which you will discuss in a moment:

Created file contracts/hello-world.clar
Created file tests/hello-world_test.ts


Clarinet also modified the project file called Clarinet.toml in order to reflect the fact that you have added a new contract called hello-world:

Updated Clarinet.toml with contract hello-world


At this point let’s pause and look at what Git shows us:

$ git status

On branch master
Changes not staged for commit:
 modified: Clarinet.toml
Untracked files:
 contracts/
 tests/
no changes added to commit (use "git add" and/or "git commit -a")


Now if you git diff inside Clarinet.toml you can see the actual changes:

$ git diff Clarinet.toml

diff --git a/Clarinet.toml b/Clarinet.toml
index 62aab1c..712cec9 100644
--- a/Clarinet.toml
+++ b/Clarinet.toml
@@ -1,10 +1,11 @@
 [project]
 name = "clarity-hello-world"
 authors = []
+description = ""
 telemetry = true
+requirements = []
 analysis = ["check_checker"]
+costs_version = 2
+[contracts.hello-world]
+path = "contracts/hello-world.clar"
+depends_on = []


Let’s inform Git about our latest changes before moving on with the actual contract code:

$ git commit -m "Add contract hello-world"

[master 40a9650] Add contract hello-world
 3 files changed, 47 insertions(+), 4 deletions(-)
 create mode 100644 contracts/hello-world.clar
 create mode 100644 tests/hello-world_test.ts


To recap, those 3 files changed (mentioned in the Git output above) are the ones Clarinet touched:

Created file contracts/hello-world.clar
Created file tests/hello-world_test.ts
Updated Clarinet.toml with contract hello-world


5. Add functions to the contract:

Open contracts/hello-world.clar. It should look similar to this:

;; hello-world
;; <add a description here>
;; constants
;;
;; data maps and vars
;;
;; private functions
;;
;; public functions
;;


For this tutorial, you will add two Clarity functions to the contract.

Add a public function

The first function is a public function called say-hi.

;; public functions
;;
(define-public (say-hi) (ok "hello world"))


What public means in Clarity is that the function is callable from other smart contracts.

The function doesn’t take any parameters and simply returns “hello world” using the ok response constructor.

Add a read-only function

The second function is a read-only function called echo-number.

;; private functions
;;
(define-read-only (echo-number (val int)) (ok val))


What read-only means is that the function can’t change internal state (variables, maps, etc).

This time the function takes an input parameter of type int and returns the value passed in using the ok response constructor.

The full contracts/hello-world.clar file should look like this:

;; hello-world
;; <add a description here>
;; constants
;;
;; data maps and vars
;;
;; private functions
;;
(define-read-only (echo-number (val int)) (ok val))
;; public functions
;;
(define-public (say-hi) (ok "hello world"))


Or in terms of git diff:

$ git diff contracts/hello-world.clar

diff --git a/contracts/hello-world.clar b/contracts/hello-world.clar
index 4f55c4d..faa51ef 100644
--- a/contracts/hello-world.clar
+++ b/contracts/hello-world.clar
@@ -10,6 +10,8 @@
;; private functions
 ;;
+(define-read-only (echo-number (val int)) (ok val))
;; public functions
 ;;
+(define-public (say-hi) (ok "hello world"))


Now you will run clarinet check in order to see whether the code you have added type-checks:

$ clarinet check

✔ Syntax of 1 contract(s) successfully checked


6. Interact with the contract:

In the project root directory (clarity-hello-world) launch the local Clarinet console.

When the Clarinet console is started, it shows a summary of the available contracts (in this case hello-world) and the simulated wallets in memory:

$ clarinet console

clarity-repl v0.21.0
Enter "::help" for usage hints.
Connected to a transient in-memory database.

Contracts
+---------------------------------------+-------------------------+
| Contract identifier                   | Public functions        |
+---------------------------------------+-------------------------+
| ST1PQHQKV0RJXZFY1DGX8M....hello-world | (echo-number (val int)) |
|                                       | (say-hi)                |
+---------------------------------------+-------------------------+
Initialized balances
+-----------------------------------------------+-----------------+
| Address                                       | STX             |
+-----------------------------------------------+-----------------+
| ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VG... (deployer) | 100000000000000 |
+-----------------------------------------------+-----------------+
| ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2... (wallet_1) | 100000000000000 |
+-----------------------------------------------+-----------------+
| ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6... (wallet_2) | 100000000000000 |
+-----------------------------------------------+-----------------+
[...]
+-----------------------------------------------+-----------------+
| STNHKEPYEPJ8ET55ZZ0M5A34J0R3N5F... (wallet_9) | 100000000000000 |
+-----------------------------------------------+-----------------+
>>


This console is a Clarinet read-eval-print loop (REPL) that executes Clarity code instantly when a function is called.

The console provides the ability to interact with a contract using Clarity commands.

Call the say-hi function with the following command:

>> (contract-call? .hello-world say-hi)

(ok "hello world")


Next, call the echo-number function:

>> (contract-call? .hello-world echo-number 1337)

(ok 1337)


Next, try calling the echo-number function with an incorrect type, in this case an unsigned integer:

>> (contract-call? .hello-world echo-number u1337)

:1:42: error: expecting expression of type 'int', found 'uint'(contract-call? .hello-world echo-number u1337)
                                                                                                       ^~~~


Exit the Clarinet console/REPL by hitting CTRL-C twice. Then track on Git the latest changes:

$ git add contracts/hello-world.clar
$ git commit -m "Add public functions"

[master 1a3ee48] Add public functions
 1 file changed, 2 insertions(+)


7. Deploy the contract on Stacks mainnet:

Remember that in step 1 we got a bunch of files created by Clarinet

[...]

Created file clarity-hello-world/contracts
Created file clarity-hello-world/settings
Created file clarity-hello-world/tests
Created file clarity-hello-world/Clarinet.toml
Created file clarity-hello-world/settings/Mainnet.toml
Created file clarity-hello-world/settings/Testnet.toml
Created file clarity-hello-world/settings/Devnet.toml
Created file clarity-hello-world/.vscode
Created file clarity-hello-world/.vscode/settings.json
Created file clarity-hello-world/.vscode/tasks.json
Created file clarity-hello-world/.gitignore


Those files under settings control (among other things) the deployment process of the contracts.

For mainnet, edit settings/Mainnet.toml and provide the seed phrase of the deployer account:

[network]
name = "mainnet"
node_rpc_address = "https://stacks-node-api.mainnet.stacks.co"
deployment_fee_rate = 10

[accounts.deployer]
mnemonic = "<YOUR PRIVATE MAINNET MNEMONIC HERE>"


If there are no funds on the deployer account, Clarinet will throw an error:

$ clarinet publish --mainnet

{
   "error":"transaction rejected",
   "reason":"NotEnoughFunds",
   "reason_data":{
      "actual":"0x00000000000000000000000000000000",
      "expected":"0x00000000000000000000000000000910"
   },
   "txid":"85f71b70e724e5c79b116fc45623a5575c833709c28cfb4125301..."
}


Notice the expected value; that is the amount of network fee that must be paid:

HEX: 0x00000000000000000000000000000910
DEC:     2320
STX: 0.002320 (2320 / 100000)


Once there are funds in the deployer account, Clarinet can proceed with the publish:

$ clarinet publish --mainnet

Contract hello-world broadcasted in mempool
(txid: 85f71b70e724e5c79b116fc45623a5575c833709c28cfb4..., nonce: 0)


Here’s the actual transaction as shown on the explorer: 0x85f71b70e724e5c79b116fc45623a5575c833709c28cfb4125301e9cf5f51a15

Summary

With Clarinet, deploying on Stacks mainnet is pretty straightforward:


  Create a new Clarinet project
  Create a Git repository for the project
  Add the project on the Git repository
  Add a new Clarity contract to the project
  Add functions to the Clatity contract
  Interact with the Clatity contract locally
  Deploy the Clarity contract on Stacks mainnet


Next: Clarity property-based testing primer.

      