Forem: Stacks

Test-Driven Stacks Development with Clarinet

kenny — Wed, 30 Mar 2022 18:39:00 +0000

Make sure you check out the Refactoring section of this tutorial. The original implementation of this contract and the tests had a couple of gaps. I kept them in and added a refactoring section to help others learn from these fixes and the process. Big thanks to lnow for helping to point these issues out and rework them.

One of the most difficult things about smart contract and web3 development can be getting an effective development environment set up.

Since the blockchain itself is a critical piece of our development infrastructure, we need to do have some way of setting up our own local instance of the blockchain we are building for.

In the Ethereum world, Hardhat is a commonly used tool for local Ethereum development with Solidity.

In the Stacks world, we have Clarinet, which accomplishes something similar.

Clarinet allows us to not only get a Clarity smart contract project set up but also to create a local Stacks chain to interact with.

This makes it trivial to begin building Stacks apps without having to deploy our smart contracts to testnet and interact with them that way.

This can significantly cut down on our development time.

Other benefits of using Clarinet include Clarity syntax checking, deploying contracts to testnet and mainnet using the CLI, writing and executing a test suite, checking our code's test coverage, and running our contract cost analysis.

The Clarinet GitHub page does a great job of laying out all the different features of Clarinet if you are curious to learn more.

Hiro also recently released a series of screencasts going over the essentials of Clarinet.

Today, we're going to look at how to use Clarinet to build a Stacks app using TDD, or test-driven development. We'll write our tests, write a Clarity smart contract to get them to pass, check out costs and explore ways to optimize them and improve on what we'll be making here.

TDD seems annoying and unnecessary until you try it, and then it's magical.

This goes double for smart contract development, where the code is permanent, public, and often controls peoples' finances and other assets.

Getting a smart contract right the first time can save a lot of headaches and potential security issues down the road. Putting in the effort upfront to test your code well and getting a professional audit are significantly better options than having a security breach and having to migrate your contract after deploying.

Using TDD allows us to map out how our smart contract should function and get a mental roadmap of how we want it to work, and then write our smart contracts in order to get those tests to pass.

This helps both for thinking through what we want our code to do and ensuring that the entirety of our Clarity contracts are covered by robust tests.

In this tutorial, we'll use Clarinet to start a new project, create tests for our smart contracts, write the smart contracts themselves, check the syntax of those contracts, check the cost and explore optimization strategies, and deploy them to testnet, all using Clarinet.

Let's get started.

What We're Building

In this tutorial, we'll be building a simple app called Cargo. Cargo is a fictional, simple Stacks app designed to help facilitate tracking the progress a shipment makes throughout the supply chain.

In this particular app, we'll track a package's travel progress using a simple map, then explore ways to improve upon the implementation presented here.

We'll also go over some next steps for you to improve upon this project on your own in order to increase your learning.

You can find the completed code for this tutorial on GitHub.

Installing Clarinet

If you don't have Clarinet installed, you'll need to do that first. I can't do a better job than the Clarinet docs at showing that so I will refer you to them.

In order to run our local Stacks chain with clarinet integrate, you'll need to make sure you have Docker installed and running as well.

Setting Up a New Clarinet Project

Alright, let's get this thing going.

First up, let's set up our project with clarinet new cargo and then cd into that directory.

When you look in that directory you'll see some empty folders, contracts and tests, and you'll see a settings folder with three .toml files in it.

These files correspond to the settings for each of the three primary development environments.

Devnet.toml corresponds to our local chain when we run clarinet integrate.

Testnet.toml and Mainnet.toml correspond to the settings we want to use when we deploy to the Stacks testnet and mainnet, respectively.

Let's take a look at the Devnet.toml file, we'll look at the other two when we deploy at the end of the tutorial.

Here's what our Devnet.toml file looks like:

[network]
name = "devnet"
deployment_fee_rate = 10

[accounts.deployer]
mnemonic = "twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw"
balance = 100_000_000_000_000
# secret_key: 753b7cc01a1a2e86221266a154af739463fce51219d97e4f856cd7200c3bd2a601
# stx_address: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
# btc_address: mqVnk6NPRdhntvfm4hh9vvjiRkFDUuSYsH

[accounts.wallet_1]
mnemonic = "sell invite acquire kitten bamboo drastic jelly vivid peace spawn twice guilt pave pen trash pretty park cube fragile unaware remain midnight betray rebuild"
balance = 100_000_000_000_000
# secret_key: 7287ba251d44a4d3fd9276c88ce34c5c52a038955511cccaf77e61068649c17801
# stx_address: ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5
# btc_address: mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC

[accounts.wallet_2]
mnemonic = "hold excess usual excess ring elephant install account glad dry fragile donkey gaze humble truck breeze nation gasp vacuum limb head keep delay hospital"
balance = 100_000_000_000_000
# secret_key: 530d9f61984c888536871c6573073bdfc0058896dc1adfe9a6a10dfacadc209101
# stx_address: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG
# btc_address: muYdXKmX9bByAueDe6KFfHd5Ff1gdN9ErG

[accounts.wallet_3]
mnemonic = "cycle puppy glare enroll cost improve round trend wrist mushroom scorpion tower claim oppose clever elephant dinosaur eight problem before frozen dune wagon high"
balance = 100_000_000_000_000
# secret_key: d655b2523bcd65e34889725c73064feb17ceb796831c0e111ba1a552b0f31b3901
# stx_address: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC
# btc_address: mvZtbibDAAA3WLpY7zXXFqRa3T4XSknBX7

[accounts.wallet_4]
mnemonic = "board list obtain sugar hour worth raven scout denial thunder horse logic fury scorpion fold genuine phrase wealth news aim below celery when cabin"
balance = 100_000_000_000_000
# secret_key: f9d7206a47f14d2870c163ebab4bf3e70d18f5d14ce1031f3902fbbc894fe4c701
# stx_address: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND
# btc_address: mg1C76bNTutiCDV3t9nWhZs3Dc8LzUufj8

[accounts.wallet_5]
mnemonic = "hurry aunt blame peanut heavy update captain human rice crime juice adult scale device promote vast project quiz unit note reform update climb purchase"
balance = 100_000_000_000_000
# secret_key: 3eccc5dac8056590432db6a35d52b9896876a3d5cbdea53b72400bc9c2099fe801
# stx_address: ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB
# btc_address: mweN5WVqadScHdA81aATSdcVr4B6dNokqx

[accounts.wallet_6]
mnemonic = "area desk dutch sign gold cricket dawn toward giggle vibrant indoor bench warfare wagon number tiny universe sand talk dilemma pottery bone trap buddy"
balance = 100_000_000_000_000
# secret_key: 7036b29cb5e235e5fd9b09ae3e8eec4404e44906814d5d01cbca968a60ed4bfb01
# stx_address: ST3AM1A56AK2C1XAFJ4115ZSV26EB49BVQ10MGCS0
# btc_address: mzxXgV6e4BZSsz8zVHm3TmqbECt7mbuErt

[accounts.wallet_7]
mnemonic = "prevent gallery kind limb income control noise together echo rival record wedding sense uncover school version force bleak nuclear include danger skirt enact arrow"
balance = 100_000_000_000_000
# secret_key: b463f0df6c05d2f156393eee73f8016c5372caa0e9e29a901bb7171d90dc4f1401
# stx_address: ST3PF13W7Z0RRM42A8VZRVFQ75SV1K26RXEP8YGKJ
# btc_address: n37mwmru2oaVosgfuvzBwgV2ysCQRrLko7

[accounts.wallet_8]
mnemonic = "female adjust gallery certain visit token during great side clown fitness like hurt clip knife warm bench start reunion globe detail dream depend fortune"
balance = 100_000_000_000_000
# secret_key: 6a1a754ba863d7bab14adbbc3f8ebb090af9e871ace621d3e5ab634e1422885e01
# stx_address: ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5N7R21XCP
# btc_address: n2v875jbJ4RjBnTjgbfikDfnwsDV5iUByw

[accounts.wallet_9]
mnemonic = "shadow private easily thought say logic fault paddle word top book during ignore notable orange flight clock image wealth health outside kitten belt reform"
balance = 100_000_000_000_000
# secret_key: de433bdfa14ec43aa1098d5be594c8ffb20a31485ff9de2923b2689471c401b801
# stx_address: STNHKEPYEPJ8ET55ZZ0M5A34J0R3N5FM2CMMMAZ6
# btc_address: mjSrB3wS4xab3kYqFktwBzfTdPg367ZJ2d

[devnet]
disable_bitcoin_explorer = true
# disable_stacks_explorer = true
# disable_stacks_api = true
# working_dir = "tmp/devnet"
# stacks_node_events_observers = ["host.docker.internal:8002"]
# miner_mnemonic = "twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw"
# miner_derivation_path = "m/44'/5757'/0'/0/0"
# orchestrator_port = 20445
# bitcoin_node_p2p_port = 18444
# bitcoin_node_rpc_port = 18443
# bitcoin_node_username = "devnet"
# bitcoin_node_password = "devnet"
# bitcoin_controller_port = 18442
# bitcoin_controller_block_time = 30_000
# stacks_node_rpc_port = 20443
# stacks_node_p2p_port = 20444
# stacks_api_port = 3999
# stacks_api_events_port = 3700
# bitcoin_explorer_port = 8001
# stacks_explorer_port = 8000
# postgres_port = 5432
# postgres_username = "postgres"
# postgres_password = "postgres"
# postgres_database = "postgres"
# bitcoin_node_image_url = "quay.io/hirosystems/bitcoind:devnet"
# stacks_node_image_url = "localhost:5000/stacks-node:devnet"
# stacks_api_image_url = "blockstack/stacks-blockchain-api:latest"
# stacks_explorer_image_url = "blockstack/explorer:latest"
# bitcoin_explorer_image_url = "quay.io/hirosystems/bitcoin-explorer:devnet"
# postgres_image_url = "postgres:alpine"

# Send some stacking orders
[[devnet.pox_stacking_orders]]
start_at_cycle = 3
duration = 12
wallet = "wallet_1"
slots = 2
btc_address = "mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC"

[[devnet.pox_stacking_orders]]
start_at_cycle = 3
duration = 12
wallet = "wallet_2"
slots = 1
btc_address = "muYdXKmX9bByAueDe6KFfHd5Ff1gdN9ErG"

[[devnet.pox_stacking_orders]]
start_at_cycle = 3
duration = 12
wallet = "wallet_3"
slots = 1
btc_address = "mvZtbibDAAA3WLpY7zXXFqRa3T4XSknBX7"

There's a lot going on here, but it's actually pretty simple. All we are doing is declaring the name of the network, setting the amount of STX we want to pay to deploy a contract on it, and then instantiating a bunch of different principals (Stacks addresses) with some test STX.

The first one is the deployer address and the rest are just other accounts we can use to test our contracts.

At the bottom we are setting up a bunch of stuff that will determine how our local chain will actually run.

Most of these are ports and postgres configurations that you'll never need to touch, but if you ever do, now you know where they are.

We also have a config item at the very bottom that is setting up one of our wallets to be a stacker, which will automatically set our chain up with a PoX workflow with accounts 1, 2, and 3 stacking their STX tokens and earning BTC, all happening on our local Clarinet chain.

Creating a Smart Contract

Let's create our Cargo smart contract with clarinet contract new cargo.

This will create both the smart contract Clarity contract itself in the contracts folder as well as the test file in the tests folder.

Writing Tests

The first thing we are going to do is write a failing test describing what we want our contract to do.

The generated test file took care of all the boilerplate setup for us, so all we need to do is write our actual tests.

Here's what you should have in that cargo_test.ts file right now:


import { Clarinet, Tx, Chain, Account, types } from 'https://deno.land/x/clarinet@v0.14.0/index.ts';
import { assertEquals } from 'https://deno.land/std@0.90.0/testing/asserts.ts';

Clarinet.test({
    name: "Ensure that <...>",
    async fn(chain: Chain, accounts: Map<string, Account>) {
        let block = chain.mineBlock([
            /* 
             * Add transactions with: 
             * Tx.contractCall(...)
            */
        ]);
        assertEquals(block.receipts.length, 0);
        assertEquals(block.height, 2);

        block = chain.mineBlock([
            /* 
             * Add transactions with: 
             * Tx.contractCall(...)
            */
        ]);
        assertEquals(block.receipts.length, 0);
        assertEquals(block.height, 3);
    },
});

This starter test file is already doing quite a bit for us. Up at the top we are importing the Clarinet Deno testing library.

I recommend going through that actual file to get a handle on the different things this testing library allows us to do.

The Clarinet class is our actual test runner, and we are calling test to initiate the test process.

In there we pass in our test name and function. We'll create a new one of these for each test we run. In this function we are passing chain and accounts which will handle setting up a mocknet Stacks chain and our set of mock accounts for testing purposes. This corresponds to the same list of accounts from that Devnet.toml file we saw earlier.

Then within the function we are mining two blocks and checking for the correct block height after mining. We can add transactions within individual blocks where we see the TX.contractCall(..) comment.

But what are the block.receipts? Whenever we mine a block on the Stacks chain, a receipt is generated for each transaction that was processed in that block that gives us information about the transaction.

Since we aren't processing any transactions in these blocks yet, we have no receipts.

If we run clarinet test right now everything should pass, since we aren't checking for much other than our mocknet for our test suite running and mining successfully.

Before we get started writing our tests, let's think about what we need our smart contract to do and outline a couple of test cases.

For this simple application, we're really only going to have one main piece of functionality, and that will be updating a package's shipping status.

But even this one use case brings up a couple of test cases. We'll likely want to make sure only certain addresses can update shipping status.

Maybe we can keep a simple map of each shipment where we store the shipper as a principal type along with all the other shipment data in a tuple.

There is actually a more efficient way to do this, but we'll implement it this way in this tutorial and explore a possible refactor at the end.

So here are the test cases we might need for this:

A user should be able to successfully create a new shipment
The shipper should be able to successfully update their shipment status
A user should not be able to update another shipper's shipment status
A user should be able to read the current status of a shipment

I like to phrase my test cases in human-readable form, in a user story-ish format, describing what the functionality is actually doing, rather than defining the specific technical implementation in the test case name.

I find that this way, it's easier to wrap our heads around what the contract should be doing, then we can change the technical implementation as needed without needing to change the test case itself.

Remember that the blockchain is public by default, so all of the shipping statuses of all packages will be publicly viewable, hence the last test case is generic and applies to all users.

If we wanted to make this data private, we would need to change up our approach a bit, something we'll explore further down below when we look at optimizing costs.

We aren't going to be storing a history of all our shipment updates directly within our map in our smart contract. Why not?

Again, this is something that requires a shift in thinking from traditional web2 apps. The blockchain itself is, by design, a historical record of all transactions. So we don't need to store this history in our contract directly, Stacks does it for us.

Clarity has a built-in at-block function that changes the context of whatever expression is passed to it to that particular block.

So we can pull our shipment status map data from any previous block by passing in the block number and pulling the relevant map data.

We won't be implementing this particular piece of functionality in this tutorial, but here's what it could look like if you want to explore it on your own.

We could store the block height of when the shipment was created and when it arrived and use that to create a range of time when the shipment was in transit.

In our UI, we could take these block heights and extrapolate out time estimates from those and allow the user to look up what the status was at a certain point in time.

Alright let's get to writing our tests.

First up:

A user should be able to successfully create a new shipment

Here's the test for this particular user story:

Clarinet.test({
    name: "A user should be able to successfully create a new shipment",
    async fn(chain: Chain, accounts: Map<string, Account>) {
        const shipper = accounts.get('wallet_1')!.address;
        const receiver = accounts.get('wallet_2')!.address
        let block = chain.mineBlock([
            // Call the create-new-shipment function, passing in the starting location as the only parameter
            Tx.contractCall(
                'cargo',
                'create-new-shipment',
                [types.ascii('Denver'), types.principal(receiver)],
                shipper
            )

        ]);
        console.log(types)
        const result = block.receipts[0].result;
        // Check for the success message
        result.expectOk().expectAscii('Shipment created successfully')
    },
});

First we create the test and give it a name. I like to name them based on the user stories created above.

Then we are creating the actual test function itself and passing in the chain and accounts. These are generated by Clarinet and allow us to actually interact with our testing mocknet.

Inside the function we initiate mining a block with the chain.mineBlock function, and inside that is where we call our contract, thus initiating a transaction, with Tx.contractCall.

We need to pass some parameters to tell the contractCall function what to actually call.

First we pass the name of our contract, cargo.

Then the name of the function we want to call within that contract, create-new-shipment.

Then we pass in any parameters the function needs. In this case, we need to pass in a starting location to the function and a receiver address, which has been defined above the block creation.

Finally we pass in the principal of the transaction sender, again defined up above. In our case we are using the second generated wallet address.

You can see the structure of the accounts map by adding a simple console.log(accounts) statement if you are curious how those are structured.

Note the types.ascii and types.principal functions we are passing our arguments to. That needs to be the same type that our Clarity function accepts in our contract.

Now if we run clarinet test this will of course fail because we don't even have that function to call.

In this case it is failing because we have no transaction receipt, because our transaction isn't actually doing anything yet.

Let's jump over to our contract and write this function.

One thing to remember when doing TDD is that we only want to add functionality incrementally as we create tests.

So right now we are only adding enough to this contract to get this test to pass. We'll add additional functionality like auth checking as we write more failing tests.

Let's define our first public function.

;; cargo
;; a simple decentralized shipment tracker

;; constants

;; data maps and vars
(define-data-var last-shipment-id uint u0)
(define-map shipments uint {location: (string-ascii 25), status: (string-ascii 25), shipper: principal, receiver: principal})

;; private functions
;;

;; public functions
(define-public (create-new-shipment (starting-location (string-ascii 25)) (receiver principal))
    (let
        (
            (new-shipment-id (+ (var-get last-shipment-id) u1))
        )
        ;; #[filter(starting-location, receiver)]
        (map-set shipments new-shipment-id {location: starting-location, status: "In Transit", shipper: tx-sender, receiver: receiver})
        (ok "Shipment created successfully")
    )
)

The first thing we are doing here is defining a data-var and a map in order to keep track of our shipment ids and our shipment data.

Then we are creating the actual function that will handle creating this new shipment. You can see that the parameters that we are accepting here match up with the parameters we passed in our test.

We are first setting the value of our new id, and then adding this particular item to our map. After we run the map-set then we return an ok response with the expected test.

Run clarinet test again and our test should pass.

What's this ;; #[filter(starting-location, receiver)] line?

This is another feature of Clarinet called the check-checker that warns us about any untrusted input in our contract.

You can read more about it here but in our case we want the user to be able to pass in whatever they want for the starting-location and receiver fields, so we are telling the check checker to filter out these particular variables when checking for untrusted input.

Syntax Checking

One of the other very helpful features of Clarinet that you may have noticed is syntax checking.

Throughout the process of developing our smart contract, Clarinet will help us to make sure we are formatting things correctly and have the right syntax.

This can help greatly in our workflow and make it so we can write better contracts faster.

There are two ways to check the syntax. You can run clarinet check in the main Clarinet folder.

Or if you use VS Code, you can use the Clarity extension to automatically run syntax checks when you save your files.

Now, let's get back to building out our tests. We have the first one passing, and have confirmed that a user can successfully create a new shipment.

Let's add our next test case.

The shipper should be able to successfully update their shipment status

Here's what test for this particular functionality would look like:

Clarinet.test({
    name: "A user should be able to update their shipment",
    async fn(chain: Chain, accounts: Map<string, Account>) {
        const shipper = accounts.get('wallet_1')!.address;
        let block = chain.mineBlock([
            // Call the update-shipment function, passing in the shipment id and current location
            Tx.contractCall(
                'cargo',
                'update-shipment',
                [types.uint(1), types.ascii('Phoenix')],
                shipper
            )

        ]);
        const result = block.receipts[0].result;
        // Check for the success message
        result.expectOk().expectAscii('Shipment updated successfully')
    },
});

This is very similar to the first test, except we are calling an update function and passing in a couple of different parameters to find the correct shipment and to update the location.

Running clarinet test results in a failing test, so let's write that new function.

(define-public (update-shipment (shipment-id uint) (current-location (string-ascii 25)))
    (let
        (
            (previous-shipment (unwrap! (map-get? shipments shipment-id) err-shipment-not-found))
            (new-shipment-info (merge previous-shipment {location: current-location}))
        )
        ;; #[filter(shipment-id)]
        (map-set shipments shipment-id new-shipment-info)
        (ok "Shipment updated successfully")
    )
)

We are also adding a constant for our error message up top:

;; constants
(define-constant err-shipment-not-found (err u100))

Here we are first getting the existing shipment, and returning an error if it doesn't exist. We don't want to add a new shipment here.

Then we are creating a new tuple of the shipment info by merging the existing info with the new location.

Tuples are immutable once created, so we need to create a new tuple but with only the relevant information updated.

Then we are taking that information and using it to update the shipments map using the corresponding shipment id that was passed into the function and returning a success message.

If we run this now, it will fail with our shipment-not-found-error.

That's because in our test case, we aren't creating a new shipment before attempting to update it. So we need to add in some code to create a new shipment.

Let's update this test to first create a new shipment in the first block, then update it in the second block.

Clarinet.test({
    name: "A user should be able to update their shipment",
    async fn(chain: Chain, accounts: Map<string, Account>) {
        const shipper = accounts.get('wallet_1')!.address;
        const receiver = accounts.get('wallet_2')!.address
        let block = chain.mineBlock([
            // Call the create-new-shipment function, passing in the starting location as the only parameter
            Tx.contractCall(
                'cargo',
                'create-new-shipment',
                [types.ascii('Denver'), types.principal(receiver)],
                shipper
            )

        ]);
        assertEquals(block.receipts.length, 1);
        assertEquals(block.height, 2);
        block = chain.mineBlock([
            // Call the update-shipment function, passing in the shipment id and current location
            Tx.contractCall(
                'cargo',
                'update-shipment',
                [types.uint(1), types.ascii('Phoenix')],
                shipper
            )

        ]);
        const result = block.receipts[0].result;
        // Check for the success message
        result.expectOk().expectAscii('Shipment updated successfully')
    },
});

Now if we run clarinet test again, our test passes.

This has however brought up an additional use case we are not currently testing for. You'll notice this workflow as you practice TDD.

You'll do your best to create the best test cases at the beginning, but they will evolve as you build out your project.

We should a test to check and make sure that a user cannot update a shipment that doesn't exist. Because of the way map-set works, this would create a new shipment. We don't want that.

Our code actually does this already, but we should add in a test case to make sure that functionality doesn't break as we refactor.

Clarinet.test({
    name: "A user should not be able to update a shipment that does not exist",
    async fn(chain: Chain, accounts: Map<string, Account>) {
        const shipper = accounts.get('wallet_1')!.address;
        const receiver = accounts.get('wallet_2')!.address
        let block = chain.mineBlock([
            // Call the create-new-shipment function, passing in the starting location as the only parameter
            Tx.contractCall(
                'cargo',
                'create-new-shipment',
                [types.ascii('Denver'), types.principal(receiver)],
                shipper
            )

        ]);
        assertEquals(block.receipts.length, 1);
        assertEquals(block.height, 2);
        block = chain.mineBlock([
            // Call the update-shipment function, passing in the shipment id and current location
            Tx.contractCall(
                'cargo',
                'update-shipment',
                [types.uint(5), types.ascii('Phoenix')],
                shipper
            )

        ]);
        const result = block.receipts[0].result;
        // Check for the correct message defined in our constants
        result.expectErr().expectUint(100)
    },
});

This is very similar to the previous test case except we are passing in the id of a shipment that does not exist and checking that our function returns the correct error response.

This test will pass, since we built that functionality into our contract, but let's make sure it works by creating a failing test case.

Change the id of 5 to a 1 and the test should fail because the contract call succeeds.

Be sure to change it back before moving on to the next test case.

A user should not be able to update another shipper's shipment status

As it stands now, anybody can update any shipment, regardless of whether or not they are the shipper.

We don't want that. Only the shipper should be able to update the status. In a real-world application, we may want to have a collection of allowed addresses that can update the shipment, rather than only the shipper being able to update it.

We could do that by passing in a list of allowed addresses when we first create the shipment, and using the index-of function to see if the tx-sender is in that list.

I leave that as an exercise for the reader. For now, we will compare to a single principal, the shipper.

Here's the next test case:

Clarinet.test({
    name: "A user should not be able to update another shipper's shipment status",
    async fn(chain: Chain, accounts: Map<string, Account>) {
        const shipper = accounts.get('wallet_1')!.address;
        const receiver = accounts.get('wallet_2')!.address
        const stranger = accounts.get('wallet_3')!.address
        let block = chain.mineBlock([
            // Call the create-new-shipment function, passing in the starting location as the only parameter
            Tx.contractCall(
                'cargo',
                'create-new-shipment',
                [types.ascii('Denver'), types.principal(receiver)],
                shipper
            )

        ]);
        assertEquals(block.receipts.length, 1);
        assertEquals(block.height, 2);
        block = chain.mineBlock([
            // Call the update-shipment function, passing in the shipment id and current location
            // This should fail since it is being called by a stranger and not the shipper
            Tx.contractCall(
                'cargo',
                'update-shipment',
                [types.uint(1), types.ascii('Phoenix')],
                stranger
            )

        ]);
        const result = block.receipts[0].result;
        // Check for the correct error message defined in our constants
        result.expectErr().expectUint(101)
    },
});

Again, very similar to a previous test except we are instead passing in the stranger as the tx-sender, which corresponds to a different address on the chain.

And we are checking for an error of u101 when the transaction attempts to execute.

Our test should fail now because we are successfully updating the status, rather than erroring out.

Let's refactor our contract a bit to get this test to pass.

The two main things we need to add are a new error constant and an asserts! statement checking to see if the tx-sender is equal to the shipper.

Here's what our full contract looks like after making those changes.


;; cargo
;; a simple decentralized shipment tracker

;; constants
(define-constant err-shipment-not-found (err u100))
(define-constant err-tx-sender-unauthorized (err u101))

;; data maps and vars
(define-data-var last-shipment-id uint u0)
(define-map shipments uint {location: (string-ascii 25), status: (string-ascii 25), shipper: principal, receiver: principal})

;; private functions
;;

;; public functions
(define-public (create-new-shipment (starting-location (string-ascii 25)) (receiver principal))
    (let
        (
            (new-shipment-id (+ (var-get last-shipment-id) u1))
        )
        ;; #[filter(starting-location, receiver)]
        (map-set shipments new-shipment-id {location: starting-location, status: "In Transit", shipper: tx-sender, receiver: receiver})
        (ok "Shipment created successfully")
    )
)

(define-public (update-shipment (shipment-id uint) (current-location (string-ascii 25)))
    (let
        (
            (previous-shipment (unwrap! (map-get? shipments shipment-id) err-shipment-not-found))
            (shipper (get shipper previous-shipment))
            (new-shipment-info (merge previous-shipment {location: current-location}))
        )
        (asserts! (is-eq tx-sender shipper) err-tx-sender-unauthorized)
        ;; #[filter(shipment-id)]
        (map-set shipments shipment-id new-shipment-info)
        (ok "Shipment updated successfully")
    )
)

We've added a new error constant along with a check to make sure the sender of this transaction is the shipper of the shipment being edited.

Note the addition of the shipper variable in the let function where we get that information.

Run this test again and it should pass. Let's add the last test case.

A user should be able to read the current status of a shipment

This one is pretty straightforward. We simply want to make sure that we can easily read the shipment status of a shipment with a given id.

We'll set up a new test to call a read-only function and then get that function written.

First, the test:

Clarinet.test({
    name: "A user should be able to read the current status of a shipment",
    async fn(chain: Chain, accounts: Map<string, Account>) {
        const shipper = accounts.get('wallet_1')!.address;
        const receiver = accounts.get('wallet_2')!.address
        let block = chain.mineBlock([
            // Call the create-new-shipment function, passing in the starting location as the only parameter
            Tx.contractCall(
                'cargo',
                'create-new-shipment',
                [types.ascii('Denver'), types.principal(receiver)],
                shipper
            )

        ]);
        // Get the shipment information with an ID of 1
        const newShipment = chain.callReadOnlyFn(
            'cargo',
            'get-shipment',
            [types.uint(1)],
            receiver
        )
        // Now we want to check and see if this returns the shipment tuple we are expecting
        const expectedShipment = newShipment.result
        expectedShipment.expectOk()
        assertEquals(expectedShipment, `(ok {location: "Denver", receiver: ${receiver}, shipper: ${shipper}, status: "In Transit"})`)
    },
});

All we are doing at the bottom is checking that we get an ok response, and that it has the data we are expecting.

Right now when we run this it will fail because that function does not exist.

Let's create it.

(define-read-only (get-shipment (shipment-id uint))
    (ok (unwrap! (map-get? shipments shipment-id) err-shipment-not-found))
)

This is a simple read-only function that will take in a shipment id and attempt to grab the entry in our shipments map with that id.

The unwrap! function will attempt to grab that value and return the not found error we created if it doesn't exist.

Now when we run the test again it should pass.

Code Coverage

One more thing we can do before moving on is check to see how much of our code is covered by tests.

We can do this in just a few commands. Clarinet uses lcov to produce code coverage reports.

If you don't have that installed yet, you can do so on Mac with brew install lcov.

If you have Windows, lcov is available as a Chocolatey package.

Now, from inside your Clarinet directory, run clarinet test --coverage.

Once that finishes, you can generate the file with genhtml coverage.lcov and open it with open index.html.

According to this report we have 100% code coverage. Nice.

Refactoring

The astute reader may notice a couple of problems with the way the tests have been written so far, and an error with the contract itself.

Big thanks to lnow for pointing these issues out and helping work to write more robust tests.

There's one critical error with the way I've written the tests here. Because they are only checking for return statuses, and not for data actually changing on-chain, we can only verify they work on a surface level.

For example, this contract would actually cause all our tests to pass, which is obviously not what we want.

(define-public (create-new-shipment (starting-location (string-ascii 25)) (receiver principal) )
    (ok "Shipment created successfully")
)

(define-public (update-shipment (shipment-id uint) (current-location (string-ascii 25)))
    (begin
        (asserts! (not (is-eq shipment-id u5)) (err u100))
        (asserts! (not (is-eq tx-sender 'ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC)) (err u101))
        (ok "Shipment updated successfully")
    )
)

(define-read-only (get-shipment (shipment-id uint))
    (ok {
        location: "Denver", 
        receiver: 'ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG, 
        shipper: 'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5,
        status: "In Transit"
    })
)

So we need to make a couple of adjustments to our tests to check for on-chain data.

We already have the piece we need to do this in our get-shipment function. So we need to add this and check what it returns as part of our tests to make sure shipments have been updated and added correctly.

That piece of code we use to check that we can successfully get a shipment from the chain? We need to add that at the bottom of our create-shipment test:

// Check that a shipment was created
const newShipment = chain.callReadOnlyFn(
    'cargo',
    'get-shipment',
    [types.uint(1)],
    receiver
)
// Now we want to check and see if this returns the shipment tuple we are expecting
const expectedShipment = newShipment.result
expectedShipment.expectOk()
assertEquals(expectedShipment, `(ok {location: "Denver", receiver: ${receiver}, shipper: ${shipper}, status: "In Transit"})`)

And our update-shipment test:

// Check that a shipment was updated
const newShipment = chain.callReadOnlyFn(
    "cargo",
    "get-shipment",
    [types.uint(1)],
    receiver
);
// Now we want to check and see if this returns the shipment tuple we are expecting
const expectedShipment = newShipment.result;
expectedShipment.expectOk();
assertEquals(
    expectedShipment,
    `(ok {location: "Phoenix", receiver: ${receiver}, shipper: ${shipper}, status: "In Transit"})`
);

Now we have some better tests that are actually checking that the things we want to happen on-chain are happening.

But we have another issue.

Right now, we only have tests to check if we can create a single shipment successfully, which means our tests have no way of verifying whether or not our shipment ID incrementer works correctly (spoiler alert: we never added it 🙃).

So let's first add a failing test to create multiple shipments.

Clarinet.test({
  name: "Multiple users should be able to successfully create multiple shipments",
  async fn(chain: Chain, accounts: Map<string, Account>) {
    const firstShipper = accounts.get("wallet_1")!.address;
    const firstReceiver = accounts.get("wallet_2")!.address;
    const firstLocation = "Denver";
    let block = chain.mineBlock([
      // Call the create-new-shipment function, passing in the starting location as the only parameter
      Tx.contractCall(
        "cargo",
        "create-new-shipment",
        [types.ascii(firstLocation), types.principal(firstReceiver)],
        firstShipper
      ),
    ]);
    const firstResult = block.receipts[0].result;
    // Check for the success message
    firstResult.expectOk().expectAscii("Shipment created successfully");
    // Check that a shipment was created
    const firstShipment = chain.callReadOnlyFn(
      "cargo",
      "get-shipment",
      [types.uint(1)],
      firstReceiver
    );
    // Now we want to check and see if this returns the shipment tuple we are expecting
    const firstExpectedShipment = firstShipment.result;
    firstExpectedShipment.expectOk();
    assertEquals(
      firstExpectedShipment,
      `(ok {location: "${firstLocation}", receiver: ${firstReceiver}, shipper: ${firstShipper}, status: "In Transit"})`
    );

    // Now let's create another shipment and perform the same checks
    const secondShipper = accounts.get("wallet_3")!.address;
    const secondReceiver = accounts.get("wallet_4")!.address;
    const secondLocation = "New York";
    block = chain.mineBlock([
      // Call the create-new-shipment function, passing in the starting location as the only parameter
      Tx.contractCall(
        "cargo",
        "create-new-shipment",
        [types.ascii(secondLocation), types.principal(secondReceiver)],
        secondShipper
      ),
    ]);
    const secondResult = block.receipts[0].result;
    // Check for the success message
    secondResult.expectOk().expectAscii("Shipment created successfully");
    // Check that a shipment was created
    const secondShipment = chain.callReadOnlyFn(
      "cargo",
      "get-shipment",
      [types.uint(2)],
      secondReceiver
    );
    // Now we want to check and see if this returns the shipment tuple we are expecting
    const secondExpectedShipment = secondShipment.result;
    secondExpectedShipment.expectOk();
    assertEquals(
      secondExpectedShipment,
      `(ok {location: "${secondLocation}", receiver: ${secondReceiver}, shipper: ${secondShipper}, status: "In Transit"})`
    );
  },
});

If we run clarinet test again this will fail with an err u100 If we check our contract, that corresponds to the shipment not found error.

Why is this happening?

If you look in our create-new-shipment function, we are getting the last-shipment-id but we are never updating that value when we update our map, so it will always get set to 1.

Let's fix that by modifying the function and then re-run our test.

We only need to add one line to make this work, add this right above the ok return.

(var-set last-shipment-id new-shipment-id)

And with that, our tests pass.

Alright, we have all our main tests and functionality written. But the way we store data here could be improved. Let's look at how we might refactor this while using Clarinet's cost optimization functions.

Cost Optimization

One thing to keep in mind when writing data to a blockchain via a smart contract is that we want to keep that amount of data to a minimum. Users pay for every byte of data.

Clarinet has a cost analysis function built into the testing harness, but there are currently some issues with the way it works.

Until those get sorted out, we'll need to analyze the costs of our functions manually using the console.

Another huge shoutout to lnow for pointing these out to me and helping me work through how to run manual cost analysis.

I very highly recommend reading through that GitHub issue to understand what the problem is and the discrepancy between running ::get_costs and clarinet test --costs.

Let's run a quick cost analysis by opening up the console with clarinet console.

We'll run a cost analysis on our create-shipment function and pass in some data.

::get_costs (contract-call? .cargo create-new-shipment "Denver" 'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5)

Remember your address will be different, I just used the first one generated when I entered the console.

We'll get our success output and a rundown of what it cost, it should look something like this. This is telling us how many bytes were consumed by each type of action on the left, and the upper limit of what can be done on the right.

The goal is to get the cost down as much as possible so we can have more transactions per block and cut down on write costs of writing data to the chain.

Remember when I said above that writing all that data into a map was not the best way to handle this?

This is why. We want to avoid writing that much data if possible.

Pay particular attention to the Write length (bytes) column.

This is just a sample app, in a real-world shipment tracker we would likely need a lot more data to be stored in that map.

A better option here would be to hash this data, store it in a traditional database, and use the on-chain hash of the data as the source of truth. That way we can compare the hash of the centralized data to the hash stored on-chain to maintain security and trustlessness without needing to store the data directly on-chain.

Another benefit of this is that we can keep data private while still verifying it is accurate. If we wanted the data to be public we could implement some sort of publicly viewable dashboard that showed the hash of the current data and that it was the same as what is on chain.

All of the UI code responsible for fetching the data and comparing the hash could be made open source so it is publicly viewable and verifiable. Users could determine for themselves if the data is to be trusted and act accordingly.

Remember, transparency is not necessarily the problem we are trying to solve for when building smart contracts. Transparency is easily solved with open source code.

We are trying to make something transparent and immutable/incorruptible. But that comes with tradeoffs, like every transaction having a cost.

We can create applications that are the best of both worlds by writing smart contracts that store a minimal amount of data while still keeping integrity.

This also makes it significantly easier to update our data structure in the future. It's out of the scope of this tutorial, but you can read more about this approach in the Clarity Book.

If you've read my first tutorial on Stacks development, you know I'm a fan of going out and practicing things on your own.

This is an excellent opportunity to do that. I have a few ideas for how you can flex your Stacks muscles in the "Practice on Your Own" section below, with some guidance.

But first, let's get this deployed to testnet using Clarinet.

Deploying

Clarinet makes deploying Clarity contracts very easy.

In fact, we literally only need one command:

clarinet publish --testnet

But before this will work we need to edit the Testnet.toml file in order to add our testnet address mnemonic so Clarinet knows what address to deploy with.

You can find this in the Hiro wallet by switching to testnet, selecting the address you want to deploy with, hitting the menu with the three dots, and selecting 'View Secret Key'.

Copy the memonic that shows there and paste it in the right spot in the Testnet.toml file.

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

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

Then you can go to the explorer and copy the tx id that was generated to view your deployed contract. You can see mine here.

Practice On Your Own

There are two major improvements we could make to our project as it stands right now, implementing hashing as discussed above to reduce contract costs and adding a UI.

Implementing the Hash Function

Here are the steps you would need to take to make this happen. Implementing this on your own would be great practice.

First, Modify the testing file to create the data structure in the form of an object and pass it to a function that will sha256 hash it, such as js-sha256.

You'll need to modify all of the test functions in order to correctly pass in this new data to the create and update functions.

Next you'll need to remove the get-shipment function and replace it with something that compares the data hash generated via JS with the one stored on chain.

Finally, you'll need to modify the Clarity functions to instead take in the data hash as a parameter and get the tests to pass.

In a real app, our tests would be mimicking us saving our data to an off-chain DB and then passing the hash of that saved data to our smart contract.

For more information on what this might look like, check out the Best Practices chapter of the Clarity Book.

Adding a UI and DB

We've got some smart contracts that are covered by tests now, but they aren't very useful if nobody can interact with them.

You've got a fully functioning smart contract with Clarinet, let's try adding a frontend and database to it.

This is something to try on your own to exercise your Stacks muscles and start learning how to build useful full-stack apps.

The concept of storing hashes of data instead of the data itself is super important to familiarize yourself with. It's important to remember that decentralized web development is different than traditional web development. We need to think about things differently.

Storing a hash of our data on the blockchain while storing the data itself in a traditional centralized database still allows us to maintain public, transparent, verifiable data integrity while keeping the benefits of centralized data storage, such as speed, easy upgradeability, and data privacy.

If we needed to add other data field to our shipment info down the road, this would be a major task if all this data were stored on the blockchain, but it's trivial with traditional data storage.

So, try this out for a project:

Utilizing Next.js, Tailwind CSS, Supabase, and Micro-Stacks, create a frontend for the smart contracts we wrote here.

This will likely be challenging, but will be an excellent exercise to practice the art of full-stack development with Stacks.

Be sure to tag me in the Stacks Discord if you need any help, kennny#0001.

Good luck!

Wrap Up and Next Steps

In this tutorial we've taken a brief look at how you can use Clarinet to aid in your Stacks development.

We've looked at testing, syntax checking, cost optimizations, and deployment.

But as always, this information won't really sink in unless you go out and practice it on your own. I've given you a few ideas to get your gears turning, but feel free to experiment and see how all this works for yourself.

I'm always available for help if you need anything on Discord and Twitter.

And if you haven't yet, be sure to check out start.stacks.org for a complete roadmap to get started in Stacks development.

Understanding Stacks Post Conditions

kenny — Fri, 11 Mar 2022 05:24:00 +0000

What Are Post Conditions?

Post conditions are one of my favorite features of Stacks. They are one of the many unique features of Stacks and Clarity that helps make it easier for developers to build safe applications and for users to be safer users of those applications.

If you aren't familiar with Stacks or Clarity, you can check out my Intro to Stacks tutorial, where we walk through the basics of what Stacks is and how to build a full-stack app on it.

Now, what exactly are post conditions?

Put simply, post conditions are a set of conditions that must be met before a user's transaction will execute. The primary goal behind post conditions is to limit the amount of damage that can be done to a user's assets due to a bug, intentional or otherwise.

How Post Conditions Work

Post conditions allow the developer of an application to append a set of conditions that must be met. If these conditions are not met, the transaction will abort and the user will only be out the transaction fee.

How might this look in practice?

Say we are building an NFT marketplace and a user wants to purchase an NFT for 20 STX. As the developers of that application, we can embed post conditions stating that the purchaser's transaction should not transfer more than 20 STX and that they should own one NFT of that specific type.

If contract execution would result in either of these two things not happening, the entire thing aborts and the purchaser loses nothing but the transaction fee.

It's crucial to note that post conditions are not something that is defined in a Clarity smart contract. They are meant to be separate from the contract so that the user has some control over what happens when they initiate a transaction outside of the contract itself.

So they are sent as part of the transaction when the user initiates it.

The post conditions will be shown prior to a user initiating a transaction in their wallet.

As web3 developers, it is our job to make sure we write code with good post conditions to safeguard our user's assets as much as possible.

Types of Post Conditions

We have three different types of post conditions to cover the three main types of assets on Stacks: NFTs, fungible tokens, and STX tokens.

All of these post conditions correspond to the transaction sender's account and assets.

Let's look at a few code examples pulled from the Stacks.js docs.

STX Post Condition

import {
  FungibleConditionCode,
  makeStandardSTXPostCondition,
  makeContractSTXPostCondition,
} from '@stacks/transactions';

// With a standard principal
const postConditionAddress = 'SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE';
const postConditionCode = FungibleConditionCode.GreaterEqual;
const postConditionAmount = 12345n;

const standardSTXPostCondition = makeStandardSTXPostCondition(
  postConditionAddress,
  postConditionCode,
  postConditionAmount
);

// With a contract principal
const contractAddress = 'SPBMRFRPPGCDE3F384WCJPK8PQJGZ8K9QKK7F59X';
const contractName = 'test-contract';

const contractSTXPostCondition = makeContractSTXPostCondition(
  contractAddress,
  contractName,
  postConditionCode,
  postConditionAmount
);

Here we've got the basic setup for a post condition for a STX transfer.

After we import the necessary packages, we are setting up a condition that says that the user with the specified address will transfer an amount of STX that will be greater than or equal to the specified amount.

So as the user, if we were to initiate this transaction with the Hiro Wallet, we would be presented with a condition that stated that we will be transferring at least 12,345 STX or the transaction will abort.

The second section is doing something similar, but in this case it is being applied to the contract, so we're saying that the contract will be transferring at least the specified amount, rather than the user.

Fungible Token Post Condition

import {
  FungibleConditionCode,
  createAssetInfo,
  makeStandardFungiblePostCondition,
} from '@stacks/transactions';

// With a standard principal
const postConditionAddress = 'SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE';
const postConditionCode = FungibleConditionCode.GreaterEqual;
const postConditionAmount = 12345n;
const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ';
const assetContractName = 'test-asset-contract';
const fungibleAssetInfo = createAssetInfo(assetAddress, assetContractName);

const standardFungiblePostCondition = makeStandardFungiblePostCondition(
  postConditionAddress,
  postConditionCode,
  postConditionAmount,
  fungibleAssetInfo
);

// With a contract principal
const contractAddress = 'SPBMRFRPPGCDE3F384WCJPK8PQJGZ8K9QKK7F59X';
const contractName = 'test-contract';
const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ';
const assetContractName = 'test-asset-contract';
const fungibleAssetInfo = createAssetInfo(assetAddress, assetContractName);

const contractFungiblePostCondition = makeContractFungiblePostCondition(
  contractAddress,
  contractName,
  postConditionCode,
  postConditionAmount,
  fungibleAssetInfo
);

The process here is similar. The main difference is that in addition to supplying the conditions for the transfer itself, since this corresponds to a custom SIP-010 token, we are also specifying the token info by referencing the contract name and address that defines the token.

NFT Post Condition

import {
  NonFungibleConditionCode,
  createAssetInfo,
  makeStandardNonFungiblePostCondition,
  makeContractNonFungiblePostCondition,
  bufferCVFromString,
} from '@stacks/transactions';

// With a standard principal
const postConditionAddress = 'SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE';
const postConditionCode = NonFungibleConditionCode.Sends;
const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ';
const assetContractName = 'test-asset-contract';
const assetName = 'test-asset';
const tokenAssetName = bufferCVFromString('test-token-asset');
const nonFungibleAssetInfo = createAssetInfo(assetAddress, assetContractName, assetName);

const standardNonFungiblePostCondition = makeStandardNonFungiblePostCondition(
  postConditionAddress,
  postConditionCode,
  nonFungibleAssetInfo,
  tokenAssetName
);

// With a contract principal
const contractAddress = 'SPBMRFRPPGCDE3F384WCJPK8PQJGZ8K9QKK7F59X';
const contractName = 'test-contract';

const contractNonFungiblePostCondition = makeContractNonFungiblePostCondition(
  contractAddress,
  contractName,
  postConditionCode,
  nonFungibleAssetInfo,
  tokenAssetName
);

This one is a bit different. Rather than specifying the amount that the transfer should be compared to, we are setting the condition that after this transaction executes, the specified address should own the specified NFT.

We could combine a couple of post conditions for this as well, and in fact this is what we are going to do in just a moment when we look at how to use post conditions in a sample app.

Let's say we are purchasing an NFT for 50 STX. We can add two post conditions that require that after the transaction executes we will transfer no more than 50 STX from our principal and that our principal will own the specified NFT.

Note that post conditions don't allow us to specify that we own a NFT with a particular identifier, only that we own one NFT of that particular name and contract.

We can see the different comparator codes for each type in the @stacks/transactions source code.

Sample App

Let's take everything we've learned about post conditions and use them to create a basic sample app using Stacks.js.

As always, reach out and let me know your feedback or if you notice any errors or potential improvements.

Our sample app is a very simple app where we can buy and sell a custom SIP-009 token. This will allow us to look at how to implement the sample post condition scenario outlined above.

Since we are focusing on the post conditions in this tutorial, I've created a sample repo with a completed frontend and contracts, the only thing missing is the set of post conditions.

In that same repo, I also have a separate branch with the completed code so you can compare.

First, download the starter code from GitHub and let's get it fired up.

You'll need npm installed on your system to follow along. I'm using Node 17. You can use nvm if you need to switch versions.

Switch into the frontend directory and run npm install and then npm run dev, then switch into the backend directory and run clarinet integrate to get everything up and running.

If you open up the fabulous-frogs.clar file you can see we have a simple contract setting up a SIP-009 NFT.

Pay particular attention to the mint function, as that is the function that we will be utilizing and to which we will be attaching post conditions.

(define-public (mint (recipient principal))
    (let
        (
            (token-id (+ (var-get last-token-id) u1))
        )
        (try! (stx-transfer? u50000000 tx-sender (as-contract tx-sender)))
        (try! (nft-mint? fabulous-frogs token-id recipient))
        (var-set last-token-id token-id)
        (ok token-id)
    )
)

This is a basic mint function that will first increment that token-id variable. Then, using that value as the context for the rest of the expressions (this is what the let function does) it will execute the other expressions.

In this case, we are first attempting to transfer 50 STX from the current user, tx-sender to the contract, (as-contract tx-sender).

If that succeeds, we then attempt to mint a new NFT using the newly calculated token-id, set a new last-token-id for the next round of minting, and return.

Now let's shift our focus to the frontend code and see what we need to do.

Here's what the initial index.tsx file looks like:

import { useState, useEffect } from 'react'
import type { NextPage } from 'next'
import Head from 'next/head'
import { StacksMocknet } from '@stacks/network'
import {
  AppConfig,
  UserSession,
  showConnect,
  openContractCall,
} from '@stacks/connect'
import {
  NonFungibleConditionCode,
  FungibleConditionCode,
  createAssetInfo,
  makeStandardNonFungiblePostCondition,
  makeStandardSTXPostCondition,
  bufferCVFromString,
  standardPrincipalCV,
} from '@stacks/transactions'

const Home: NextPage = () => {
  const appConfig = new AppConfig(['publish_data'])
  const userSession = new UserSession({ appConfig })
  const [error, setError] = useState('')
  const [loading, setLoading] = useState(true)
  const [userData, setUserData] = useState({})
  const [loggedIn, setLoggedIn] = useState(false)

  // Set up the network and API
  const network = new StacksMocknet()

  function authenticate() {
    showConnect({
      appDetails: {
        name: 'Fabulous Frogs',
        icon: 'https://assets.website-files.com/618b0aafa4afde65f2fe38fe/618b0aafa4afde2ae1fe3a1f_icon-isotipo.svg',
      },
      redirectTo: '/',
      onFinish: () => {
        window.location.reload()
      },
      userSession,
    })
  }

  useEffect(() => {
    if (userSession.isSignInPending()) {
      userSession.handlePendingSignIn().then((userData) => {
        setUserData(userData)
      })
    } else if (userSession.isUserSignedIn()) {
      setLoggedIn(true)
      setUserData(userSession.loadUserData())
    }
  }, [])

  const mint = async () => {
    const assetAddress = 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM'

    const functionArgs = [
      standardPrincipalCV(
        userSession.loadUserData().profile.stxAddress.testnet
      ),
    ]

    const options = {
      contractAddress: assetAddress,
      contractName: 'fabulous-frogs',
      functionName: 'mint',
      functionArgs,
      network,
      appDetails: {
        name: 'Fabulous Frogs',
        icon: 'https://assets.website-files.com/618b0aafa4afde65f2fe38fe/618b0aafa4afde2ae1fe3a1f_icon-isotipo.svg',
      },
      onFinish: (data: any) => {
        console.log(data)
      },
    }

    await openContractCall(options)
  }

  return (
    <div className="flex min-h-screen flex-col items-center justify-center py-2">
      <Head>
        <title>Fabulous Frogs</title>
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className="flex w-full flex-1 flex-col items-center justify-center px-20 text-center">
        <h1 className="text-6xl font-bold">Mint Your Fabulous Frog</h1>

        <p className="mt-4 w-full text-xl md:w-1/2">
          Fabulous Frogs are the most fabulous amphibians this side of the
          Mississippi. You can mint yours for only 50 STX.
        </p>

        <div className="mt-6 flex max-w-4xl flex-wrap items-center justify-around sm:w-full">
          {loggedIn ? (
            <button
              onClick={() => mint()}
              className="rounded bg-indigo-500 p-4 text-2xl text-white hover:bg-indigo-700"
            >
              Mint
            </button>
          ) : (
            <button
              className="bg-white-500 mb-6 rounded border-2 border-black py-2 px-4 font-bold hover:bg-gray-300"
              onClick={() => authenticate()}
            >
              Connect to Wallet
            </button>
          )}
        </div>
      </main>
    </div>
  )
}

export default Home

We have a basic auth system and a simple mint function. Right now there are no post conditions but everything else is working just fine.

You'll need to modify the assetAddress to the address of the NFT contract that Clarinet generates when you run clarinet integrate.

Also, if you have not already, you need to hook your local Hiro Wallet account to one of the Devnet accounts to get some test STX and interact with the site.

I show how to do this in my Stacks 101 article under the heading titled "Adding STX to Your Local Account".

If you try to mint an NFT using this, you'll notice that we have a default post condition of not transferring anything.

So if we try to run this now, it will fail.

We need to add two conditions:

We need to ensure that we are being transferred an instance of the Fabulous Frog NFT
We need to ensure that we are not transferring more than 50 STX

Let's do that now. Remember, if you want to compare you can view the completed code in this branch.

We can create and add both post conditions with the following code. Add this right below the line where we are declaring the assetAddress variable.

const postConditionAddress =
    userSession.loadUserData().profile.stxAddress.testnet
const nftPostConditionCode = NonFungibleConditionCode.Sends
const assetContractName = 'fabulous-frogs'
const assetName = 'fabulous-frogs'
const tokenAssetName = bufferCVFromString('fabulous-frogs')
const nonFungibleAssetInfo = createAssetInfo(
    assetAddress,
    assetContractName,
    assetName
)

const stxConditionCode = FungibleConditionCode.LessEqual;
const stxConditionAmount = 50000000; // denoted in microstacks

const postConditions = [
    makeStandardNonFungiblePostCondition(
    postConditionAddress,
    nftPostConditionCode,
    nonFungibleAssetInfo,
    tokenAssetName
    ),
    makeStandardSTXPostCondition(
    postConditionAddress,
    stxConditionCode,
    stxConditionAmount
    )
]

What we are doing here is first setting all the variables we will need in order to create the post conditions.

After we declare the variables, we are creating the actual post conditions and putting them in an array. We use the makeStandardNonFungiblePostCondition and makeStandardSTXPostCondition from the @stacks/transactions package to actually create this.

Most of this is pretty self-explanatory, we are just defining the type of asset that should be transferred and referencing it's contract and name in the NFT case.

All we are doing here is taking the identifying information from our NFT and putting into a format that the Stacks blockchain can understand.

That involves passing the result of a function called createAssetInfo, a function included in stacks.js into the post conditions. This takes the token name, contract name, and asset contract address and formats it to send with the transaction to the chain itself.

If you are curious, you can see what each of these pieces of data correspond to on chain by reading the SIP.

Why do we need to convert the token name to a buffer by using the bufferCVFromString function?

From the document linked above, referring to one of items required to be passed into the post condition body for an NFT condition:

"A variable-length asset name, which is the Clarity value that names the token instance, serialized according to the Clarity value serialization format."

Everything we are doing here is to convert our data into a format that can be passed to the chain to evaluate the post conditions that must be met.

I got the address here from the local Clarinet Devnet chain, so be sure to add yours by setting the assetAddress variable if you haven't already.

And in the case of the STX transfer, we are defining how much should be transferred (in microstacks) and the comparator.

For fungible and STX token conditions, we have 5 possible operators:

Equal
Greater
GreaterEqual
Less
LessEqual

And for the NFT conditions we only have two:

Sends
DoesNotSend

These come from constants in the @stacks/transactions package called FungibleConditionCode and NonFungibleConditionCode respectively.

The last thing we need to do is actually pass these conditions into our function call by adding them to the options object:

const options = {
    contractAddress: assetAddress,
    contractName: 'fabulous-frogs',
    functionName: 'mint',
    functionArgs,
    network,
    // Passing the post conditions here
    postConditions,
    appDetails: {
    name: 'Fabulous Frogs',
    icon: 'https://assets.website-files.com/618b0aafa4afde65f2fe38fe/618b0aafa4afde2ae1fe3a1f_icon-isotipo.svg',
    },
    onFinish: (data: any) => {
    console.log(data)
    },
}

And now if we try to run this again, it should work as expected.

These two simple examples show how we can construct post conditions for all sorts of scenarios so we can help to safeguard our apps against unexpected behavior.

If you were to change the NFT condition code from Sends to DoesNotSend, and try to Mint again, you'll notice that it fails by aborting due to supplied post conditions.

Why Post Conditions Are Useful

One of the most common frustrations with web3 and DeFi applications is that it is easy for people to screw up irreversibly. Post conditions allow the developer of a UI or the user (if their wallet allows for it) to declare up front what they expect to happen in clear language.

If that thing does not happen, they don't have to worry about losing their assets.

This adds one extra layer of security for users of our application. As an example, let's say that we were very careless in writing our smart contract and we accidentally priced the NFT at 500 STX instead of 50 by adding an extra 0.

If our UI says that it costs 50 STX, but the contract actually tries to transfer 500, we can add an extra layer of security and help safeguard against that error with our post conditions.

Post conditions are one of the many unique security features that makes Stacks an ideal chain on which to build robust decentralized software.

In my opinion, we are only beginning to see the benefits of post conditions, and as the UX for web3 apps gets better and better, I envision post conditions as being an essential security feature that will help both developers and users to be able to better protect their assets and not have to exclusively trust the developer of the smart contract.

It adds an additional layer of security to help secure users' assets that, as far as I'm aware (correct me if I'm wrong here), does not exist in other chains.

As always, please feel free to reach out to me directly or hop in the Stacks Discord if you have any questions or feedback.

Built on Bitcoin: An Introduction to Full-Stack Web3 Development with Stacks

kenny — Mon, 14 Feb 2022 22:13:00 +0000

When most people think of web3 development, the chain that immediately comes to mind is Ethereum. But did you know that it is possible to build completely decentralized web3 dapps on top of Bitcoin as well?

Enter Stacks, the biggest web3 project on Bitcoin. Stacks is a blockchain that allows us to build fully decentralized apps on top of Bitcoin, without modifying Bitcoin itself.

That's a simple statement, but there is a lot of amazing technology and a lot of interesting and sometimes controversial concepts packed into that simple sentence.

If you are not familiar with Stacks yet, I highly recommend diving in and learning about the basics.

At a high level, Stacks allows us to build fully decentralized software that ultimately settles on Bitcoin utilizing a unique consensus mechanism called Proof of Transfer.

Stacks is unique in that it is a Layer 1 chain with its own token that has its own smart contract language, and all Stacks transactions ultimately settle on Bitcoin.

This allows us to build fully expressive smart contracts and dapps that are secured by Bitcoin, without modifying Bitcoin itself.

If you are interested in a technical deep dive of how Stacks works and how it is different from other blockchain technologies, I highly recommend Jude Nelson's article, What Kind of Blockchain is Stacks?

This tutorial will serve as a practical introduction to actually building things on it using Clarity, Next, and Stacks.js.

The more I learn about Stacks and get involved in the community, the more I find myself fascinated by the ecosystem and the technology.

I wrote this tutorial for developers interested in getting started building dapps on Stacks.

It's designed to be an introductory tutorial, taking you from 0 to a complete, although simple, Stacks dapp.

If you are a seasoned JS developer and interested in building things on Stacks, you should be good. If you have experience writing smart contracts with another language like Solidity, even better.

I wrote this guide as a way to help get new developers started building on Stacks as fast as possible.

If anyone notices I have made a mistake or that something can be improved, please do let me know!

This tutorial is serving as an MVP of sorts for a more extensive full-stack Stacks dev guide I am working on so definitely reach out if you think something could be improved, added, removed, etc.

What is Stacks?

At a high level, it enables smart contracts on top of Bitcoin.

One of the main differentiators between Ethereum and Bitcoin is that Ethereum was programmable and had the capability to create smart contracts.

This is why the DeFi market exploded on the Ethereum blockchain. People could write code in Solidity and deploy that code as a smart contract to live forever on the blockchain.

Stacks brings this capability to Bitcoin. Stacks is working on bringing full-expressive smart contracts to Bitcoin, without modifying Bitcoin itself.

Along with related technologies like Lightning and DLCs, Stacks rounds out the dream team that will bring DeFi and smart contracts to the world's most secure blockchain and the soundest money the world has ever seen, Bitcoin.

This was one of the main advantages Ethereum had over Bitcoin, and now Bitcoin has that capability as well, without (and this is a key point) modifying Bitcoin itself.

Imagine getting involved in the Ethereum ecosystem when it was first blossoming and the amazing opportunity that would have been. I'm convinced that getting involved and building on Stacks is an equivalent (if not greater) opportunity today.

As a related benefit, because of Stacks' unique Proof of Transfer consensus mechanism, it is actually able to recycle Bitcoin's energy usage, so rather than adding to the environmental load, it extracts further benefit from the electricity Bitcoin already uses.

Because of the nature of the recycling of energy, Stacks actually uses less electricity than even PoS chains. In the words of Jude Nelson, "Bitcoin isn't wasted energy, it's simply under-utilized."

The Stacks Developer Ecosystem

We'll go over the process of building a complete (although basic) application using some of these throughout the tutorial.

Clarity

First, Clarity is the language that smart contracts are written in on Stacks. Think of this as the Stacks version of Solidity.

It has a different feel than languages like Solidity and JavaScript, so it can feel a bit weird at first, but you'll find that it clicks as you use it more and the simplicity is wonderful.

The cool thing about Clarity is that it has been intentionally designed to write safe smart contracts and make it difficult to write dangerous code and you can see what the code will do before running it.

The Stacks blockchain itself also has something to aid with writing secure contracts, post-conditions. These are conditions that have to be true when the contract finishes running. If they are not true, the contract function aborts. This can help with things like safeguarding funds in transfers.

Clarinet

Clarinet is a CLI that allows us to easily write, test, and deploy smart contracts.

If you're from the Ethereum world, this is similar to things like Hardhat or Truffle.

Clarinet is a part of our toolset that will allow us to build and test our contracts locally along with deploying them to a testnet and finally to mainnet.

We'll be using Clarinet in this tutorial but will not be covering testing our code. Testing is a complex topic that deserves its own post.

If you are interested in integrating testing into this project, Nikos Baxevanis has written an excellent introduction to testing with Clarinet using the app we're building here as a starting point.

Stacks.js

Stacks.js is how we can interact with our smart contracts from our frontend applications.

Again from the Ethereum world, this can be compared to ethers.js or web3.js.

This will help us with things like authentication, interacting with our storage system, interacting with smart contracts, and other things like stacking that we'll go over.

We're actually going to be using a few different packages in this tutorial, we'll cover them one at a time as we use them.

Gaia

Gaia is Stack's storage solution. It's a bit of a hybrid system in that it utilizes traditional cloud storage like Amazon S3.

Gaia allows us to store application and user data off-chain but still access it securely from our Stacks apps.

The blockchain should only be used to store critical metadata as it is expensive and slow to store data on the blockchain directly.

We won't be using Gaia in this particular tutorial, as we won't be storing any data off-chain, but I'm planning on writing a tutorial incorporating storage with Gaia in the future.

Awesome People and Organizations to Follow

Now that we've gone over the developer ecosystem, here's a list of people you should definitely follow on Twitter if you're looking to immerse yourself in the world of Stacks.

kenny - shameless plug, this is me
Stacks
Hiro
Stacks Foundation
Stacks Accelerator

This is just barely scratching the surface, but it will be a great jumping-off point for you to immerse yourself in the community.

What We'll Be Building

Throughout this series, we'll be building an app called Sup. Sup is a simple app that will allow visitors to our site to pay a specified amount of STX to post a message.

So visitors will be able to go to our site and pay a small fee in STX to post a message on our website.

We'll also display the currently logged-in user's message on the same page.

This basic app will be a great use case to get familiar with the various parts of the Stacks development ecosystem and the basics of the Clarity language.

We'll write our smart contracts in Clarity, use Clarinet as our development environment, and connect our frontend to the Stacks chain using stacks.js.

For the frontend, we'll be using Next and Tailwind.

Before going through this series, you should be familiar with the basics of building sites and apps with JS and React.

No existing knowledge of Stacks or Clarity is necessary, we'll be covering the basics here.

If at any point you get stuck, lost, or otherwise off track, you can compare your code to the Sup GitHub repo.

How to Use This Tutorial

If you've gone through many tutorials, you are probably familiar with the concept of tutorial hell.

This is where you get stuck endlessly consuming tutorials but never feel capable enough to actually build anything.

I'll let you in on a secret, tutorials aren't actually a great way to learn something.

Why am I writing one then?

Because they are a great way to be introduced to something and to get a high-level picture of how it works and how to stitch multiple technologies together.

But to actually learn, you need to struggle through the process of building something on your own.

So, go through this tutorial and follow along to get familiar with how it all works together.

Then, and this is critical, go and build something on your own from scratch. Something different.

Build it and deploy it for the world to see.

It will be hard and frustrating, but it's the only way to really learn.

I'm here to help if you need me, just reach out.

The Stacks Discord is another great place to go for help

Let's do this.

Project Setup

The first thing we need to do is get our dev environment set up with Clarinet and Next.

First, create a main project folder that will house both our smart contract code and our front-end Next app.

mkdir sup && cd sup

Now let's get the Next app set up with Tailwind by running:

npx create-next-app -e with-tailwindcss frontend

Change into that directory and run npm run dev to make sure everything is working.

If everything worked, you should be able to visit localhost:3000 and see the default template:

Leave that terminal window open and open up a new one to get our smart contracts set up with Clarinet.

Clarinet is super helpful in writing smart contracts because it allows us to deploy them on our own little localized blockchain. We can instantly create accounts and allocate STX to them and can run contracts without having to wait for them to process on a live chain.

Also, if you use VS Code, you may want to get the Clarity extension set up.

If you're on Mac you can install Clarinet with Homebrew.

brew install clarinet

Once we have Clarinet installed, we can instantiate a new project by changing into the main sup folder and running:

clarinet new backend

To install Clarinet on other systems, check Hiro's website.

Change into that directory and you'll see a few folders: contracts, settings, and tests. You'll also see a Clarinet.toml file for Clarinet configuration.

If we look inside the settings folder, we'll see a few config files that correspond to different networks.

When we use Clarinet to develop, we're working in the Devnet network, a localized Stacks network that runs in memory only. If you open up that file you'll see that we are setting up some mock accounts to work with.

[network]
name = "devnet"

[accounts.deployer]
mnemonic = "twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw"
balance = 100_000_000_000_000
# secret_key: 753b7cc01a1a2e86221266a154af739463fce51219d97e4f856cd7200c3bd2a601
# stx_address: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
# btc_address: mqVnk6NPRdhntvfm4hh9vvjiRkFDUuSYsH

[accounts.wallet_1]
mnemonic = "sell invite acquire kitten bamboo drastic jelly vivid peace spawn twice guilt pave pen trash pretty park cube fragile unaware remain midnight betray rebuild"
balance = 100_000_000_000_000
# secret_key: 7287ba251d44a4d3fd9276c88ce34c5c52a038955511cccaf77e61068649c17801
# stx_address: ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5
# btc_address: mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC

[accounts.wallet_2]
mnemonic = "hold excess usual excess ring elephant install account glad dry fragile donkey gaze humble truck breeze nation gasp vacuum limb head keep delay hospital"
balance = 100_000_000_000_000
# secret_key: 530d9f61984c888536871c6573073bdfc0058896dc1adfe9a6a10dfacadc209101
# stx_address: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG
# btc_address: muYdXKmX9bByAueDe6KFfHd5Ff1gdN9ErG

Now let's start learning some Clarity and write our first contract. We'll continue to use and learn more about Clarinet as we go.

Our First Smart Contract with Clarity

Before we get started, ensure that you are inside the sup/backend directory.

First up, let's create our contract with

clarinet contract new sup

This sup contract is what will handle users being able to post a message to our site.

After we run this, you'll notice a few things were created.

First, a sup.clar file was created in our contracts folder. This is where we'll actually write our contract.

Second, a sup_test.ts file was created in the tests folder. This is how we can test our file using the Clarinet testing harness, which is a tool for testing smart contracts in TypeScript.

As mentioned earlier, we're not going to be testing in this tutorial, but you can check out the generated code yourself and run clarinet test if you are curious.

And if you are interested in integrating testing into this project, Nikos Baxevanis has written an excellent introduction to testing with Clarinet using the app we're building here as a starting point.

Finally, it updated our Clarinet.toml file to reference the new contract:

[contracts.sup]
path = "contracts/sup.clar"
depends_on = []

Clarity is designed to be highly readable and was written intentionally to make it easier to write safe smart contracts. It is decidable, meaning you can know with certainty what code will do before you run it.

It is meant to be predictable and secure by default, making it as simple as possible to write secure smart contracts, which is extremely important, since once they are deployed, they are deployed forever.

Clarity may seem a bit strange at first, especially if you come from the world of JavaScript or Solidity, but once you start working with it you'll love the conciseness and simplicity.

The best way to learn is by doing, so let's write this smart contract and we'll go over what each line is doing as we go, covering Clarity concepts and syntax along the way.

Open up the sup.clar file that was created and let's get going.

Clarinet generates some placeholder content for us, which serves as a nice outline for creating our own contract:

Contract Documenting

First up, we can add a description by prefacing it with ;;, which is Clarity's syntax for code comments. Here is some helpful information on how to effectively document your contract.

We'll write:

'Smart contract to handle writing a message to the blockchain in exchange for a small fee in STX'

For the rest of the code, let's think through what we actually need our smart contract to do.

I always like to write out the functionality of my code before I start coding to help me get started.

Usually I do that in pseudo-code comments right inside my code files.

So for Sup, we need the site visitor to be able to post a message to the blockchain. As part of that process, we need them to be able to transfer a certain amount of STX from their wallet into our wallet.

This brings up a few different pieces of data that need to be created and used, as well as a couple of functions.

First, we need the user to be able to authenticate themselves and pass their address from the front end to the contract itself.

We'll handle the front end piece in a bit, but this will be handled by integrating with the Hiro Web Wallet.

We also need them to be able to type in a message and pass that through to our contract.

As far as functionality, we need a function that will allow the visitor to post a message.

We also need a couple of getter functions, which will handle retrieving the values of the variables we are storing, like the message.

Defining Variables and Constants

First let's define our address (the one we want people to transfer STX to) as a constant.

Constants in Clarity are values that will not change throughout our contract, but that we need to reference.

For now, let's create a constant for our address and for storing an error message.

If you don't have the Hiro Web Wallet installed and set up, go ahead and do that now, we'll be using it in a bit.

For now, let's use one of the addresses generated by Clarinet on our DevNet chain. We can use the address listed in accounts.deployer from our Devnet.toml file.

(define-constant receiver-address 'ST3QFME3CANQFQNR86TYVKQYCFT7QX4PRXM1V9W6H)

Here's our first piece of Clarity code. What we're doing here is saying that we want to define a new constant with define-constant.

We want to name that constant receiver-address and we want it to be a principal with the value of ST3QFME3CANQFQNR86TYVKQYCFT7QX4PRXM1V9W6H. Principals in Clarity can be thought of as user accounts corresponding to Stacks addresses.

In this case, you'll want to replace the address with one of the generated addresses from the Devnet.toml file.

The ' character is how we denote that we are setting a principal.

Note the parentheses. Everything in Clarity is wrapped in parentheses. It takes some getting used to and can be a bit difficult to keep track of.

If you use VS Code, you can enable a setting to highlight matching bracket pairs, which can make it easier to keep track of things in Clarity.

Add the following to your settings.json file in VS Code to enable this:

"editor.bracketPairColorization.enabled": true

Make sure to open up the Devnet.toml file and add that rather than using the address listed here. This is the address my local Clarinet instance generated, and yours will be different.

Next we need to get our variables set up. The main difference between constants and variables is that variables can change throughout a contract and constants cannot.

I like to define my constants and variables at the top of my contracts, but you can also define them at the bottom if you prefer.

For Sup we'll only need two variables, one to store the total amount of sups we have received and one to store a map of each message.

A map in Clarity can map together two types and pieces of data. In our case we want to map a message to a principal.

So the way our app will work is that when a visitor posts a message, it will add a new item to our messages map with the visitor's address as the key and the message content as the value.

We don't need a variable for the sender's address because Clarity has a built-in keyword called tx-sender that will get that for us.

Let's define those underneath the ;; data maps and vars comment.

(define-data-var total-sups uint u0)
(define-map messages principal (string-utf8 500))

The top line here is saying we want to define a new variable named total-sups, we want it to be an unsigned integer, and we want the default value to be an unsigned integer of 0.

The bottom line is saying we want to define a new map called messages. It will contain data pairs consisting of a principal corresponding to a utf8 string with a max of 500 characters.

And we can retrieve this string by looking up the address.

What this means is that we are creating a map of values where the key will be a principal and the value will be a string.

This is how we will keep track of all the messages people write on the site.

Remember that a blockchain is, in a way, a distributed database. So the data in this map will persist on the blockchain. We'll look at how to read from it later in this tutorial.

Consult the Clarity Book to learn more about the different types available to you in Clarity and how to declare them.

Side note, notice how these addresses begin with ST? That means that we are dealing with an address on a testnet. If it were on mainnet, the address would begin with SP or SM instead. Just something to be aware of.

Defining Functions

Next let's create a simple getter function to retrieve our stored variable.

We want to be able to call this getter function from our front end, so it needs to be public.

Underneath the ;; public functions heading we'll create that.

(define-read-only (get-sups)
  (var-get total-sups)
)

These are pretty simple, and are essentially saying we want to define a new read-only function (read-only because we aren't modifying any data, just reading it) called get-sups, that will then retrieve that value with var-get.

We also want to set up a getter function to access the message mapped to the currently logged in user.

(define-read-only (get-message (who principal))
    (map-get? messages who)
)

The map-get? is how we retrieve a value from a map, and here we are getting the entry whose principal value is equal to whatever we pass in to the function. In this read-only function, we are passing a variable called who with a type of principal. This is how we'll look up the right message in the map we created.

Read-only functions are able to be accessed both inside and outside our contract.

If an entry is found, it will return an optional, a some or a none value. Again, consult the Clarity book for more on what that means.

Now let's create the function that will actually handle writing the message to the blockchain and transferring the STX.

(define-public (write-sup (message (string-utf8 500)) (price uint))
    (begin
        (try! (stx-transfer? price tx-sender receiver-address))

        (map-set messages tx-sender message )

        (var-set total-sups (+ (var-get total-sups) u1))

        (ok "Sup written successfully")
    )
)

Alright there is a lot going on here so let's break it down.

First we are defining a public function called write-sup that will take two parameters, the message and the price.

Then we start a begin block, which groups multiple expressions, and returns the value of the last expression. This simple construct is needed because the body of a function is limited to one expression. You may be familiar with other programming languages that use curly braces { ... } for this same purpose.

The begin block allows us to wrap multiple function calls in one. To see what I mean, comment out the beginning and end of the begin block and run clarinet check. You'll see an error saying that the number of arguments is incorrect.

The first line of this block is using a try! function to transfer STX.

From the Clarity Book:

"The try! function takes an optional or a response type and will attempt to unwrap it. Unwrapping is the act of extracting the inner value and returning it."

In this case, we are attempting to evaluate the stx-transfer? function. The function returns a response type. If the call succeeds, it will return (ok true). The try! function unwraps the inner value and therefore returns true.

If it fails, it will return the error and exit the write-sup function. All Clarity functions with a ! at the end can exit the control flow early.

The stx-transfer? function takes in a few parameters: the price, denoted in microstacks, the principal sending the STX, and the principal receiving the STX.

Next we are setting the item value in our messages map that corresponds to the person sending the transaction to the passed message.

Finally, we are incrementing the value of our total-sups variable using the + operator.

This is saying: set the total-sups value to the current total-sups value plus 1.

The Polish notation used in Clarity can take some getting used to, but practice saying to yourself what the code is doing and you'll pick it up quickly.

A helpful mental model can be to think of the symbol as the function name, and the numbers being operated on as parameters.

Finally, if the function runs successfully we return a string saying so.

To check and see if we have any syntax errors, we can run clarinet check inside the backend folder of our project.

If you've followed along so far, it will output that the syntax is correct, but we have a warning regarding our message variable:

What's going on here?

Remember that Clarity is purpose-built to help us write secure code. In the spirit of that ethos, Clarinet has some checks that help us do the same thing.

Clarinet is helping us watch out for untrusted data. Blindly accepting untrusted user input is the cause for a large amount of software security vulnerabilities.

Since this is a public function, all of our data is untrusted if it is accepted as a parameter to our write-sup function.

This warning is being given as a result of a recent addition to Clarinet called the check-checker.

When we run clarinet check it will check to see if untrusted input data is being checked by our code to make sure it is legitimate.

In our case, we have the untrusted input source of message and are using that to modify our messages map.

To clear it and pass the check, we need to add some sort of check on the untrusted input. However, we actually do want the user to be able to put whatever they want here, since that's the whole point of adding the message.

We're not doing anything with this data except assigning it to the user's principal in our map, and the user should be able to write whatever they want.

So to get around this error and tell the check-checker all is well, we can add this right above the map-set call.

;; #[allow(unchecked_data)]

And with that, our check passes.

As the developer, it's your responsibility to add any checks that might need to be run in order to make sure only the data you are expecting is allowed to pass through to the function.

This feature is important to understand as it has security implications. I highly recommend reading Hiro's post on the topic.

You just wrote a Clarity smart contract. Let's switch over to the front end so we can actually use it now.

Creating the Front End with Next and Stacks.js

First let's just get some boilerplate front end code up and running. We're not focusing on learning React here so go ahead and just copy this and paste it into frontend/pages/index.tsx to update the main page of the Next app.

import { useState, useEffect } from "react";
import Head from "next/head";

export default function Home() {
  const [message, setMessage] = useState("");
  const [price, setPrice] = useState(5);
  const [userData, setUserData] = useState({});
  const [loggedIn, setLoggedIn] = useState(false);

  const handleMessageChange = (e) => {
    setMessage(e.target.value);
  };

  const handlePriceChange = (e) => {
    setPrice(e.target.value);
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    // Do Stacks things
  };

  return (
    <div className="flex flex-col items-center justify-center min-h-screen py-2">
      <Head>
        <title>Sup</title>
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className="flex flex-col items-center justify-center w-full flex-1 px-20 text-center">
        <h1 className="text-6xl font-bold mb-24">Sup</h1>
        <form onSubmit={handleSubmit}>
          <p>
            Say
            <input
              className="p-6 border rounded mx-2"
              type="text"
              value={message}
              onChange={handleMessageChange}
              placeholder="something"
            />
            for
            <input
              className="p-6 border rounded mx-2"
              type="number"
              value={price}
              onChange={handlePriceChange}
            />{" "}
            STX
          </p>
          <button
            type="submit"
            className="p-6 bg-green-500 text-white mt-8 rounded"
          >
            Post Message
          </button>
        </form>
      </main>
    </div>
  );
}

This is just setting up a basic React form.

Now we can start adding some functionality for interacting with Stacks.

Authentication

When we build web3 apps we do authentication a bit differently. Rather than setting up the typical user flow with a username or email and password, we simply allow the user to connect to our application with their wallet.

If you come from the Ethereum world, you're likely familiar with MetaMask or a similar browser-based wallet.

In the Stacks world the most common wallet is the Stacks Wallet built by Hiro.

Stacks.js comes with a connect package that we'll use to hook into the Hiro Wallet for Web and authenticate our wallet with our web app.

If you're curious about how authentication with the web wallet actually works, the Stacks website has some great documentation explaining the process.

We're going to focus on the practicalities of getting it implemented here.

The first thing we need to do is install the dependency. Make sure you are in the frontend folder and run

npm install @stacks/connect

Now open up that index file with all our React code and let's get this set up.

Add the following at the top of the file right under the other import statement.

import { AppConfig, UserSession, showConnect } from '@stacks/connect';

And this right above our state declarations:

const appConfig = new AppConfig(['publish_data']);
const userSession = new UserSession({ appConfig });

In a production app, you'd likely want to make this available globally using some sort of state management library like React Context or Zustand.

What we are doing here is initializing the auth configuration by telling connect that we need the publish_data permissions scope. This will allow us to actually publish data and interact with the app.

Next we need to set up the function to handle the authentication.

Add this right under our handleSubmit function.

function authenticate() {
    showConnect({
        appDetails: {
            name: "Sup",
            icon: "https://assets.website-files.com/618b0aafa4afde65f2fe38fe/618b0aafa4afde2ae1fe3a1f_icon-isotipo.svg",
        },
        redirectTo: "/",
        onFinish: () => {
            window.location.reload();
        },
        userSession,
    });
}

useEffect(() => {
    if (userSession.isSignInPending()) {
        userSession.handlePendingSignIn().then((userData) => {
            setUserData(userData);
        });
    } else if (userSession.isUserSignedIn()) {
        setLoggedIn(true);
        setUserData(userSession.loadUserData());
    }
}, []);

This is the function we'll call when we click the button to actually connect to our wallet, which we'll do in just a minute.

Note: If you get an error about not being able to find the regenerator-runtime package, running npm i regenerator-runtime should fix that.

This code is pretty self-explanatory, but at a high level it is calling the showConnect function which will trigger the Hiro wallet to show the connect window. The wallet will take care of the authentication functionality from there.

After it does so, it will run the onFinish function, we add any post-authentication work needs to be done there. In this case, we reload the page so our userSession gets picked up.

The appDetails passes a couple things that the Hiro window will show. For demo purposes, we're just giving it the Stacks logo.

The second part of this is a useEffect call that will run on page load and set our user session data, as well as setting our loggedIn state to true.

Now we need to add a button for the user to connect to the wallet. Let's add that right above our Sup h1 tag.

<div className="flex w-full items-end justify-center">
  <button
    className="bg-green-500 hover:bg-green-700 text-white font-bold py-2 px-4 rounded mb-6"
    onClick={() => authenticate()}
  >
    Connect to Wallet
  </button>
</div>

After you add that, switch to the testnet in your web wallet and let's see if it works.

In order to do that we first need to get a dev blockchain running using Clarinet so that we have something to work with.

Make sure you have Docker installed and switch into the backend folder. Once you're in there, run

clarinet integrate

This will set up a local blockchain on our system for testing purposes.

This will take a while to run the first time, and you'll see a crazy looking dashboard which will have the system log, service status, mempool summary, and a minimal block explorer.

Once everything has successfully started up, we can begin interacting with our app on the local DevNet chain.

Now let's use that data and display the Sup form if the user is logged in and the connect button if they are not.

We want to change the code a bit so that the form only shows up if we are logged in with our wallet. In addition, we only want the connect wallet button to show if we are not connected currently.

Swap out the code in the index file with the following:

import { useState, useEffect } from "react";
import Head from "next/head";
import { AppConfig, UserSession, showConnect } from "@stacks/connect";

export default function Home() {
  const appConfig = new AppConfig(["publish_data"]);
  const userSession = new UserSession({ appConfig });

  const [message, setMessage] = useState("");
  const [price, setPrice] = useState(5);
  const [userData, setUserData] = useState({});
  const [loggedIn, setLoggedIn] = useState(false);

  const handleMessageChange = (e) => {
    setMessage(e.target.value);
  };

  const handlePriceChange = (e) => {
    setPrice(e.target.value);
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    // Do Stacks things
  };

  function authenticate() {
    showConnect({
      appDetails: {
        name: "Sup",
        icon: "https://assets.website-files.com/618b0aafa4afde65f2fe38fe/618b0aafa4afde2ae1fe3a1f_icon-isotipo.svg",
      },
      redirectTo: "/",
      onFinish: () => {
        window.location.reload();
      },
      userSession,
    });
  }

  useEffect(() => {
    if (userSession.isSignInPending()) {
      userSession.handlePendingSignIn().then((userData) => {
        setUserData(userData);
      });
    } else if (userSession.isUserSignedIn()) {
      setLoggedIn(true);
      setUserData(userSession.loadUserData());
    }
  }, []);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen py-2">
      <Head>
        <title>Sup</title>
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className="flex flex-col items-center justify-center w-full flex-1 px-20 text-center">
        <div className="flex flex-col w-full items-center justify-center">
          <h1 className="text-6xl font-bold mb-24">Sup</h1>
          {loggedIn ? (
            <form onSubmit={handleSubmit}>
              <p>
                Say
                <input
                  className="p-6 border rounded mx-2"
                  type="text"
                  value={message}
                  onChange={handleMessageChange}
                  placeholder="something"
                />
                for
                <input
                  className="p-6 border rounded mx-2"
                  type="number"
                  value={price}
                  onChange={handlePriceChange}
                />{" "}
                STX
              </p>
              <button
                type="submit"
                className="p-6 bg-green-500 text-white mt-8 rounded"
              >
                Post Message
              </button>
            </form>
          ) : (
            <button
              className="bg-white-500 hover:bg-gray-300 border-black border-2 font-bold py-2 px-4 rounded mb-6"
              onClick={() => authenticate()}
            >
              Connect to Wallet
            </button>
          )}
        </div>
      </main>
    </div>
  );
}

Alright, we've got basic authentication going and we are conditionally displaying our form if we are connected to our wallet.

Now let's go ahead and see how we can use this form to actually post a message to the chain by paying STX.

Writing Data

The first thing we want to do here is set up our frontend so that when we submit the form, we are generating a new transaction to the Stacks blockchain.

There's a fair amount of setup we have to do to get this working properly on our local chain, so let's do that really quick.

When we ran clarinet integrate we started running a local Stacks chain on our machine at http://localhost:3999.

This gives us a lot of benefits, the main one being that we can test and interact with our smart contract without having to deploy it to a public testnet.

Adding STX to Your Local Account

In our app we need to interact as if we are a logged in user. So we need to hook our web wallet into our local DevNet chain and get logged in as the first account.

Here's how to do this:

Switch to the Devnet network in the web wallet user interface by hitting the menu button in the top right and selecting 'Change Network' and select 'Devnet'.

Then make sure a user account exists on that network and is currently logged in.

Next, hit that same menu button and select 'View Secret Key'

This will bring up the secret key used to authenticate that address. Take that secret key and copy it over to the memonic field in the Devnet.toml file for accounts.wallet_1.

Finally, take the account address from the Hiro Web Wallet and copy it over the stx_address field in the same file.

Do that, restart the DevNet, and you should have a bunch of STX in your Account 1.

Now we are ready to write the frontend code that will handle writing our message.

First we need a few new imports:

import { useState, useEffect } from "react";
import Head from "next/head";
import {
    AppConfig,
    UserSession,
    showConnect,
    openContractCall,
} from "@stacks/connect";
import { uintCV, stringUtf8CV } from "@stacks/transactions";
import { StacksMocknet } from "@stacks/network";

Let's add each of these pieces one by one and go over what they are doing.

First we need to set up our network with StacksMocknet. Mocknet is the same as localnet or DevNet.

Add this right below the state variable declarations:

// Set up the network
const network = new StacksMocknet();

Note that in a production application we would want to set up some sort of environment variable here to set the network based on what environment we were in.

Next up let's add a couple of other state variables to store the contract address and name, as well as the sup message itself and some loading variables. In a production app, we'd want to set up some sort of constants file and set these conditionally based on our environment.

const [supContractAddress, setSupContractAddress] = useState(
    "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM"
);
const [supContractName, setSupContractName] = useState("sup");
const [error, setError] = useState("");
const [loading, setLoading] = useState(true);

Quick note: Be sure to replace the contract address here with the deployer address generated on your system by clarinet integrate.

Next we need to update our handleSubmit function to call the write-sup function in our contract:

const handleSubmit = async (e) => {
    e.preventDefault();

    const functionArgs = [stringUtf8CV(message), uintCV(price * 1000000)];

    const options = {
        contractAddress: supContractAddress,
        contractName: "sup",
        functionName: "write-sup",
        functionArgs,
        network,
        appDetails: {
            name: "Sup",
            icon: window.location.origin + "/vercel.svg",
        },
        onFinish: (data) => {
            console.log("Stacks Transaction:", data.stacksTransaction);
            console.log("Transaction ID:", data.txId);
            console.log("Raw transaction:", data.txRaw);
        },
    };

    await openContractCall(options);
};

Alright we've got a few things going on here.

First we're creating a constant called functionArgs where we are setting up the arguments we need to pass to our function.

We are setting the price to be equal to price * 1000000 because in our contract, prices are denoted in microstacks. 1,000,000 microstacks is equal to 1 STX.

The other option here would be to set the price to 5000000 instead and do the conversion in our input field.

When we set up arguments to pass to a Clarity function, we need to turn them into Clarity variables. That's what we're doing here with the stringUtf8CV and uintCV functions.

You can see what all the different functions are in this file.

Next we're setting up an options object where we pass in everything we just set up and do some stuff after it finishes being called.

Finally, we actually call the contract.

But we have one more piece to add here. If you begin the process of submitting this transaction, you'll see a message at the top of the Hiro Web Wallet screen saying that no stx will be transferred:

But we set the price to be 5 STX, so what's going on here?

These are the post-conditions I mentioned earlier in the article.

If we try to run this now, it will fail because the supplied post-conditions were not met. What is actually happening here is that we didn't set up any post-conditions to tell our wallet that we were going to be transferring some STX.

So it defaulted to thinking nothing would be transferred. These post-conditions are one of the many built-in features of Clarity that can help us to write secure code.

To fix this we need to add some post-conditions.

Add the following underneath where we create the functionArgs constant:

const postConditionAddress = userSession.loadUserData().profile.stxAddress.testnet;
const postConditionCode = FungibleConditionCode.LessEqual;
const postConditionAmount = price * 1000000;
const postConditions = [
    makeStandardSTXPostCondition(
        postConditionAddress,
        postConditionCode,
        postConditionAmount
    ),
];

Update the imports:

import { useState, useEffect, useCallback } from "react";
import Head from "next/head";
import {
    AppConfig,
    UserSession,
    showConnect,
    openContractCall,
} from "@stacks/connect";
import {
    uintCV,
    stringUtf8CV,
    standardPrincipalCV,
    hexToCV,
    cvToHex,
    makeStandardSTXPostCondition,
    FungibleConditionCode,
} from "@stacks/transactions";
import { StacksMocknet } from "@stacks/network";

And pass in the post conditions to our contract call:

...
network,
postConditions,
appDetails: {
    name: "Sup",
    icon: window.location.origin + "/vercel.svg",
},
...

Now if we run this, we'll see the correct post-condition message and everything should run successfully.

Awesome! You just made an app that writes data to the Stacks blockchain and successfully transfers STX in the process.

Now let's go about reading that data.

Reading Data

Reading data is a bit more straightforward because we are going to be calling one of our read-only functions (get-messages in this case) and don't have to create a transaction, since we aren't modifying the blockchain.

For this we can use a function from the @stacks/transactions package called callReadOnlyFunction.

First, go ahead and import that.

import {
    uintCV,
    stringUtf8CV,
    standardPrincipalCV,
    hexToCV,
    cvToHex,
    makeStandardSTXPostCondition,
    FungibleConditionCode,
    callReadOnlyFunction
} from "@stacks/transactions";

Next we need to install another package in the frontend folder by running npm i @use-it/interval.

That is a custom hook that makes it easy to run a function on a certain interval, we'll get to that in a minute.

Import that, and let's get building.

import useInterval from "@use-it/interval";

Here's how we're going to handle getting the message. We're going to set up a callback function to fetch the message corresponding to the logged in user.

Then we're going to call that function on load and every 30 seconds to check to see if it has changed. Another option would be to use the API's websockets functionality which would give this app a better UX. I leave that as an exercise for the reader.

Let's add that below the handleSubmit call to get this going.

const getMessage = useCallback(async () => {
    if (
        userSession &&
        userSession.isUserSignedIn() &&
        userSession.loadUserData()
    ) {
        const userAddress = userSession.loadUserData().profile.stxAddress.testnet;
        const clarityAddress = standardPrincipalCV(userAddress);
        const options = {
            contractAddress: supContractAddress,
            contractName: supContractName,
            functionName: "get-message",
            network,
            functionArgs: [clarityAddress],
            senderAddress: userAddress,
        };

        const result = await callReadOnlyFunction(options);
        console.log(result);
    }
}, []);

// Run the getMessage function at load to get the message from the contract
useEffect(getMessage, [userSession]);

// Poll the Stacks API every 30 seconds looking for changes
useInterval(getMessage, 30000);

We also need to add a new state variable for storing the posted message.

const [postedMessage, setPostedMessage] = useState("none");

There's a fair amount going on here so let's walk through it.

The first thing we are doing here is defining a useCallback hook. If you jump down to the bottom of the code, we are running this function any time the userSession variable changes and re-running it every 30 seconds.

The getMessage function itself first checks to see if we are logged in and then sets up our read-only contract call with some options.

Take a look at the options here. When we are working with Clarity values, we need to do a bit of work to convert the values from the client into a format that Clarity can understand, hence the standardPrincipalCV(userAddress).

If you run this all, write a sup, you should see the value being logged to the console as soon as the transaction finishes processing.

Now we have one more step to go. We're going to actually display the message we have written.

We're pulling it in, we just need to add some logic to either display it if it exists, or to display some sort of 'not found' message if our smart contract returns none.

Now we need to change the console.log statement to set this when our get-message function finishes.

if (result.value) {
    setPostedMessage(result.value.data);
}

Final step: we need to conditionally display the message if it exists.

Add this right under the closing </form> tag. You'll also need to wrap both the form and this new addition in a fragment so React can render it correctly.

<div className="mt-12">
    {postedMessage !== "none" ? (
        <p>You said "{postedMessage}"</p>
    ) : (
        <p>You haven't posted anything yet.</p>
    )}
</div>

Now if we write our message and wait a bit for the transaction to process on the local chain and the block to settle, we'll see it display in the UI. Note that this could take a minute or two, you can monitor the progress in the Clarinet console.

Congratulations! You've just made your first complete, full-stack Stacks app.

All this code lives on GitHub if you need to compare with anything. This is only the beginning of your Stacks development journey, there's a lot more to learn and a lot more to build.

Where to Go From Here

You now have a basic Stacks app under your belt. If you are getting started on your Stacks development journey, there are a few things I recommend doing from here.

Get plugged in

I highly recommend joining the Stacks Discord. You can find me on Discord as kennny#0001 (that's three n's). My DMs and friend requests are open.

Feel free to tag me in the Stacks Discord or DM me with any questions, feedback, suggestions, or just to say hi.

I would also love to connect on Twitter.

Add features

By far the best way to learn is by building things on your own. You've built a solid foundation here and learned the fundamentals, but you need to build on your own to really cement the knowledge.

Here are a few ideas for features to add to this to further your learning:

Utilize the get-sups variable and getter we created on the frontend
Switch to websockets
Deploy to testnet
Run your own API node

Look into these topics and others and remember to reach out if you need any guidance!

Further your Clarity knowledge

The Stacks Foundation runs a class called Clarity Universe that teaches you smart contract development with Clarity from the ground up.

If you are interested in learning more about Clarity, sign up for the waitlist.

Work on a real project

The Stacks Foundation is interested in funding people building useful things for the Stacks Ecosystem. If you feel ready to use your knowledge to build something for the real world, apply for a grant.

Keep learning and practicing

Finally, be sure you continue your journey by learning and building as much as you can. I'm going to be creating lots of content targeted at helping devs build awesome things on Stacks, so if you have any feedback on how to improve this tutorial or suggestions for future content, I would absolutely love it if you reached out on Twitter or Discord.