Forem: kenny

Bitcoin Unleashed - Understanding Bitcoin DeFi Resources

kenny — Tue, 05 Apr 2022 05:03:49 +0000

Catamaran Swaps

Website
Article on Catamaran Swaps and Bitcoin DeFi
Catamaran Swaps Code on GitHub
Deployed Catmaran Swaps Clarity Contract

Zest Protocol

Zest Protocol Website
Open Wishlist Grant

Learn Stacks Development

Starting 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.

Stacks Resources

kenny — Thu, 24 Feb 2022 17:38:58 +0000

Hey there Stacks devs!

In my journey as Dev Advocate for the Stacks Foundation, I constantly come across various resources for learning the basics and intricacies of Stacks.

Stacks is relatively new and can be confusing and contentious for people new to the space. This page is designed to be an ever-growing list of resources both for learning about Stacks itself and for building on it.

Eventually, once a single static blog post becomes infeasible to host all the resources on, I will convert this into a more user-friendly format, but this works for now.

If you come across anything you think should be added to this list, please reach out to me on Twitter!

Stacks Fundamentals

Stacks Website
How Stacks Works

Proof of Transfer

WTF is Proof of Transfer
Understanding Proof of Transfer
What Kind of Blockchain is Stacks?

Security and Connection to Bitcoin

Muneeb Ali Twitter Space

Developing on Stacks

Introduction to Full-Stack Web3 Development with Stacks
Clarity Universe
Clarity Book in-progress

Smart Contract Examples

Catamaran Swaps - Utilizing Bitcoin state in Clarity smart contracts

Community

My Twitter
Stacks Twitter
Stacks Foundation Twitter
Stacks Discord
Stacks Foundation

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.

Create & Connect

kenny — Mon, 23 Aug 2021 22:19:46 +0000

A Simple, Daily System to Launch and Grow a Successful Dev Career

I've recently become obsessed with the compounding effects of small, consistent, daily actions.

Nowhere is the benefit of this more apparent than in building a personal brand and growing a successful career.

The world is changing rapidly, traditional credentials no longer carry the weight they once did. The ubiquity of low-cost online sources of information means that a knowledge gap is no longer the main differentiating factor between candidates.

Anyone can go online, learn extremely valuable tech skills and use those to get a job. Thanks to places like FreeCodeCamp and Hashnode, you don't even need to pay anything in order for this to happen.

Take a second and really think about how incredible this is.

We humans tend to take things we currently have for granted, no matter how incredible they may have seemed even in the recent past.

The massive amount of information available to anyone with an internet connection has created an amazing amount of opportunity for people seeking to launch and grow a career on their own terms.

But it has also created two major problems in its wake. As is usually the case, our minds have not caught up with technological advances.

We are still used to having a clear-cut path to follow and wanting that clear-cut path.

The vast amount of tutorials, courses, and bootcamps has decentralized the learning content, but the tradeoff is that it is now up to us to forge our own path, because it won't be laid out for us.

Don't get me wrong, this is a good thing, but it is challenging.

The two problems both stem from this central concept, they are:

Figuring out exactly what you should learn and how
Getting noticed by the people that can move your career forward

This blog post seeks to provide a simple system that addresses both of these problems. I say simple, but simple does not always mean easy.

I named this system Create & Connect. It involves two very simple daily actions:

Creating and shipping something every day
Reaching out to one new person every day

That's it. These two simple actions when compounded daily have life-changing implications when done consistently over time.

My goal with this article is to give you a gameplan for launching and building a successful career as a developer from scratch, regardless of how busy you are.

It's broken up into three main parts:

Why This Works
How to Do It
A Step-by-Step Plan to Get Started Today

Let's do this.

Why This Works

There are multiple reasons why this system works, on both an external and internal level.

What I mean by that is that this system will not only help you establish a personal brand and a presence online while growing your network, but it will also help you to build the kind of discipline and persistence it takes to be able to be the person that ships things.

The internal, mental changes you will get from this system are as beneficial, if not more so than the external personal branding and network benefits you'll get.

Consistently creating and shipping things every single day not only build discipline and habits but also will unleash this flood of creativity and help you start doing your best work.

Creativity is not a gift, it's not a fleeting mood. It's a choice, a habit. The more you create, the more creative you will become.

Creating every day will build your creativity muscle allowing you to make better stuff and get better at your craft, while simultaneously building your online presence in the process.

I've mentioned the concepts of an online presence and a network a few times now. I'll get into this in more detail in a future post, but the basic idea is that building a body of real work and getting that work in front of the right eyes is the best way to build a career you love.

The Create & Connect system allows you to do both.

This has the added benefit of eliminating decision fatigue and information overload. Your only goal is to complete the system each and every day.

The long-term goal of building a successful career will take care of itself if you show up every day and get these two things done.

By forcing yourself to create and ship something every day, you'll build a strong body of work and the discipline necessary to build valuable things even when you don't feel like it.

By reaching out to the right people every day, you'll build a network of people that can help bring you opportunities and propel your career forward.

Let's get into the practicalities of how to actually get this done.

How to Do It

Now we know why it's a good idea to do this stuff every day. Hopefully, you're convinced. If so, let's get into how to actually go about doing these things.

Please don't overcomplicate this. Just start and take action, today. Don't get hung up on questioning everything and making everything perfect. There lies madness.

Create

What exactly do we mean when we say "create"? All I really mean by this is creating something that did not exist before and making it publicly accessible.

For developers, this is mainly going to mean content and code.

So your goal for the "create" part of the system is to build and ship either a piece of a project or a piece of content every day.

For the code part, you'll need a GitHub account if you don't have one. In order for it to count, you need to be deploying something substantial to a GitHub repo. This could be a new feature, a bug fix, or even clarifying something in a README.

The other form of creating is publishing content.

The lowest barrier-to-entry method of doing this, by far, is creating a blog on Hashnode . This is actually my first post on Hashnode, and I'm kicking myself for not getting set up on this platform sooner.

It allows you to get your own blog up and running in minutes, and you can even hook it up to a custom domain, all for free.

If in doubt, start here.

However, you can also start a YouTube channel or a podcast if those formats are more your thing. I can't provide any insight there since I've done neither.

So every day you should either be shipping code or content, ideally both if you have the time.

Your next question is likely to be what exactly you should be making or writing about. Unfortunately, there's no easy answer here.

This is where most people get tripped up and fail. They either never start because they get overwhelmed with making a decision, or they give up after a few days.

Don't let that be you.

Remember, one of the main benefits of this daily habit is that it will steadily grow your creativity and your ability to ship over time. It will not be perfect or even necessarily very good in the beginning.

That's okay. The goal is to show up and ship every day.

I don't want to leave you hanging, so I'll provide a sample plan and idea for your first post in the step-by-step plan section below.

Connect

So you're creating something every day, now let's talk about getting in touch and connecting with someone new every day.

This one was a game-changer for me. Like a lot of developers, I'm an introvert, and the idea of networking makes me want to vomit. That's why we're not doing anything like that here.

All we are doing is reaching out to people we genuinely admire, telling them why we do and introducing ourselves. That's it.

This simple method is how I got my first job as a developer with no experience. I had a body of work because I had been creating every day, and I started reaching out to people whose work I admired introducing myself.

Again, don't overcomplicate this.

This involves an ongoing process and a daily routine.

The ongoing process is gathering a list of people as you go through your day that you admire. As you read content and come across interesting projects, keep a file of people and companies you would like to work for.

You can do this in a simple spreadsheet with the following columns:

Name
Company
Reason you admire them
Contact Date
Answered Date

Keep it simple.

Every time you come across someone whose work you admire and who you think you might like to work for, add them to this list.

Then, every day, choose one person from the list, find their email, and send them a simple, short email telling them what you specifically admire about their work and introducing yourself, what you are working on, and what your goals are.

Don't be sleazy about this. I see a lot of advice out there to just initiate a conversation or provide a compliment and then follow up later with what you really want.

I don't like that approach.

Be direct. Networking is only sleazy because people try to pretend it's something it's not.

In this email you want to accomplish a few things:

Make sure the person knows this email was written specifically for them
Provide a genuine reason why you are interested in them
Tell them about what your goals are and why that relates to your interest in them

Let's look at an example. Let's say I'm just beginning my development journey and have been really interested in building UIs in React. I've created quite a few things and have written a few blog posts on Hashnode about it.

I come across a company that says they use React in their front end. I really like what the company does and I think it would be cool to work for them, so I decide to find the contact information of the founder, Chris, and reach out.

Note that it doesn't always have to be, and in some cases shouldn't be, the founder. If the company is larger, you may be better off reaching out to another developer or manager rather than a founder or C-level exec. Use your judgment here.

I use Hunter to find his email address and write the following:

*Hi Chris,

My name is Kenny. You don't know me but I'm a React developer and wanted to reach out to let you know how awesome I think Acme is.

I recently read your post on why the NFT ecosystem is blowing up and how Acme is playing a role in that and thought it was really interesting. The fact that Acme provides a platform for non-technical people to get into the world of NFTs is huge and will play a big role in making blockchain accessible to more people.

I've been building a lot in React and noticed that the frontend of your platform is built with React. I'm just getting started in my dev journey but am looking to meet people I'd love to work for.

You seem like one of those people.

Do you have any room on your team for an eager-to-learn React developer to help you build out an amazing UI for Acme?

I'd absolutely love to work for you. You can check out some of my work on GitHub and my writing on my blog to get to know me better.

Looking forward to hearing from you!

Kenny*

Simple. Honest. Direct.

Those are the key elements you want to hit when sending out emails like this. Something very similar to this led to my first job.

Keep in mind that the goal of these emails is not necessarily to get hired, although that is certainly possible and would be awesome.

The main goal is to get on peoples' radar and start meeting people so that even if now is not a good time and you are not a good fit for them, you are on their mind when that changes, or they can refer you to others who you might be a better fit for.

If you want to really blow them out of the water, build a small custom project just for them and send it over. I recommend taking a look at Crash for more on that.

Now that you know why this works and how to do it, let's go over a sample daily plan you can use to get started.

Your Step-by-Step Plan

Get Your Foundation Set Up

If you don't already have a GitHub and Hashnode account (or another public blog) set up, do that now. If you prefer to use YouTube or a podcast, get that set up.

You need to have a foundation to build on before you start building.

Block Out Time

This part is usually overlooked but super important. Block out time to do these things on your calendar and stick to it every day.

I recommend an hour per day if you are able, but do what you can with your particular schedule.

Create Something

My favorite way of creating things is by following a course or tutorial and then creating something unique on my own using the same concept.

So find a course or tutorial you like, follow along to learn the basics, then build something on your own that utilizes the same concepts.

This is how you'll learn the best and what will stand out most in your portfolio.

This is your task for the first day.

Write Something

Now that you made something, write about it! Take what you just made and walk people through how you did it, lessons learned, challenges overcome, etc.

Your only goal is to share what you are learning and working on. You don't have to pretend to be an authority on something if you aren't. Focus on learning and building in public.

You can continue with this alternating creating and writing if it works for you, or you can write as you go and ship code and a blog post on the same day.

Experiment with both to see what works best for you.

Start Your List

As you go through your day and read content and interact with people, start developing that list of people to contact we talked about earlier.

Write Your First Email

Now take one of those people and write your first email using the template I gave you above. Be sure to modify it to suit your communication style.

That's it. You now have a blueprint for building a successful dev career.

Please don't overthink this. The most important thing is to actually take action and do something. Yes, it will be hard and uncomfortable, anything worth doing always is.

But the more you do it the easier it gets, the better you'll be at it, and the more opportunities will come your way.

My name is Kenny. I write in-depth, practical guides on JavaScript development and building a fulfilling career as a developer.

Read more of my stuff and get notified whenever I write something new at my personal site: krgrs.dev

Mastering the Mental Aspect of Learning to Code and Getting Hired

kenny — Fri, 15 Jan 2021 19:27:46 +0000

I've been talking to a lot of aspiring developers lately about their biggest struggles with getting their first jobs.

In those conversations, I've heard a lot about people struggling with the mental side of learning to code and leveraging that knowledge into a job.

Things like:

How do I know when I've learned enough?
I'm struggling with the confidence to know that I'm ready

Our minds are complicated beasts, and mindset struggles like these are very common.

Rather than give a concrete answer to these questions, I want to talk about shifting the way you view web development itself, as well as the process of launching and building a career in a way that will potentially make the questions themselves irrelevant.

One, because I don't think there is a concrete straightforward answer to this. Mindset issues are tough because we all have our own experiences, personality traits, and biases that lead us to believe certain things.

And two, because shifting the way you view the development industry and the job-hunting process will have far-reaching positive side-effects to the way you go about launching and growing your career.

For some people, these questions are stemming from a confidence issue of not feeling ready enough, for others they are coming from a place of just genuinely not knowing when the right time to start looking for jobs is.

I think for most it's probably a combination of both, which then feed off of each other and can cause all kinds of doubt and anxiety to creep in.

Add in getting rejected or ghosted by employers, and you have a recipe for immense frustration.

So what can we do about this? Let's talk about a few mental shifts and then get into some of the practical things you can do to address these issues.

Learn to accept what you cannot control while maximizing what you can control

Rejection is inevitable on the road to your first job. There are certain things that are just outside of our control.

Two people may follow the exact same process to get hired and for one person it may take a week and for another, it may take 6 months.

Don't waste energy focusing on the things that are outside of your control, instead focus on the parts you can control, stick to them consistently, and make that your measure of success.

For example, you cannot control exactly who will read your resume, what their biases are, what kind of mood they are in, who else has already applied to the job, what order they see your resume in, and countless other little things that all go into effect in a hiring process.

But you can control maximizing your online presence so as many people see you as possible, you can control optimizing that presence and your resume to give yourself the best chance of standing out, you can create a compelling portfolio so when someone comes across it, you convince them of your skills.

Getting a job is this balancing act between luck and action. Yes, luck plays a factor in almost everything, but you can drastically influence the amount of luck that comes your way by taking action on smart strategies.

Understand that coding is a never-ending process of learning for everyone

Nobody has achieved mastery of coding. As soon as you think you have, you stop learning. Embrace being a lifelong learner.

Not only is this the way to make sure you continue improving and continue learning, but it's the most impressive attitude to have for potential employers, especially at entry-level jobs.

Employers will of course expect some level of technical skill, and having experience can definitely help demonstrate that.

But every single employer I've talked to has said that for a junior dev, personality traits like enthusiasm and being willing and eager to learn and be coached are as important, if not more so, than technical skill.

Embrace your newness by becoming a lifelong learner. Whenever you feel inadequate in your code, remember a few things.

Everyone (and I mean everyone) feels that way sometimes, even people who have been doing it for years.

I've been coding in JS for 6 years professionally, not a ton of time but a decent amount, and I still have to Google stuff every day, and still feel totally inadequate when I read and watch some tutorials and courses online.

Know that those polished tutorials you watch and read and courses came with tons of preparation, frustration, Googling error messages, asking questions, and self-doubt.

Imposter syndrome is a sign that you know you still have a lot to learn. Temper that self-doubt with the confidence that comes from putting in the work and meet in the middle at humility. As long as you are honest and continually working on improving, you're good and you are not an imposter.

So when you think that you don't know enough to start applying for jobs or are trying to wait for that magic moment when you feel confident enough to do a certain thing, know that it will likely never come.

You have to take action before you feel ready in order to develop confidence, more on this below.

Understand that a job hunt should be a continual process, not a set of concrete stages

A lot of people see the road to landing a job as a step-by-step progression where each stage is separate and one can only be started one the previous stage is finished:

Learn to code
Start applying
Get a job

I think this is where a lot of the "how do I know if I know enough?" questions stem from.

But let's look at this a little differently. Instead of viewing this process as a set of separate stages, look at it all as one continuous process that you are always working through.

So instead of learning and then applying until you find a job, you should be learning, building your portfolio, writing content, networking, and applying all at the same time, continuously.

That sounds like doing too many things at once, but each of these things can work together and help the others.

Here's what I mean.

Going through tutorials is great, but you are really only learning when you build something on your own, building something on your own also allows you to build up an effective portfolio that will stand out to employers.

Writing about what you are building not only helps you be more intentional in what you are learning and doing, it can also help cement what you are learning into your brain, and it adds another valuable signal to your online presence.

Finally, connecting with others and showing them what you are working on can provide helpful feedback on your work while also growing your visibility.

These things can all be done together as part of a system of daily and weekly actions that you complete. For an example of how to set up this system, refer to an article I recently wrote for FreeCodeCamp, How to Get a Job as a Professional Developer in 2021.

The main thing I want you to understand is that getting hired is not usually as simple as hitting a point of being "ready" or knowing "enough" and then starting to apply.

It's a continuous process of learning, building, and networking so that more and more people can find you and be impressed when they do.

Sending in applications is a part of this, but it is only a part and should be coupled with consistently learning, building, and networking.

But how can I start applying for jobs and networking if I am just getting started?

Applying for jobs and networking are not necessarily the same thing. You can be reaching out to people in the industry, building relationships immediately, even when all you are learning is HTML and CSS.

Building a network and online presence is something you should start doing immediately, as soon as you start learning.

Commit to writing one post per week going over what you are currently working on. Go over it from the perspective of someone teaching it.

Reach out to one new person each day introducing yourself. See Reach Out by Molly Beck for more information on how to do this right.

Then, I would start applying to jobs once you have a portfolio of one or two complete projects that solve real, unique problems.

What I mean is make something that does not yet exist and that you did not make by following a tutorial or course.

This thing should solve a real problem that you or someone else has, and it should be complete and usable.

Having complete projects shows that you are capable of building something from start to finish and that you understand the development cycle as a whole.

Finally, confidence is not something that you can achieve by just thinking differently.

Confidence is earned by repeatedly showing up and doing the work.

This is harder in the beginning because we have to take leaps of faith and take action without the confidence present.

But over time, as you continue to learn, continue to build, and continue to meet more people, your confidence will grow naturally.

Don't get me wrong, you will still occasionally struggle with imposter syndrome, we all do, but it will begin to happen less and less the more you do great work and get feedback on that great work so that you can continue to improve.

The only way you could be an imposter is if you do one of two extremes.

You flat out lie about your experience and abilities. But this is easily avoided by creating real things and pointing to them, letting your work and writing do the skill-demonstration for you.

The other way is if you get overconfident and think that you have little or nothing left to learn. Ironically, if you feel like you are an imposter, that's a big sign on its own that you are not because you are aware of how much you still have left to learn.

Mastering the mental side of becoming a developer is not something that will happen overnight, and it's not something that will happen without taking action.

Confidence comes from consistent action towards your goals. The best actions to take are building things that solve real problems, writing about those things, and building a network of people that can bring you opportunities.

If you would like a detailed, step-by-step walkthrough of exactly how to go about setting up an online presence, building real things, and networking, along with a community of myself and other developers to support and mentor you along the way, I think you'll like my course and mentoring group, Lever.

You can also follow me on Twitter for more tips and advice on building a successful dev career.

Self-taught devs: what's keeping you from landing your first job?

kenny — Mon, 14 Dec 2020 20:35:49 +0000

For all the self-taught developers here that have not been able to get jobs yet, I'm curious: what is your biggest obstacle to landing that first job?

Looking for a few aspiring developers for a career strategy session

kenny — Mon, 14 Dec 2020 20:28:59 +0000

Hey there!

I'm looking for a few aspiring self-taught developers that are struggling to get their first jobs.

For the last few years, I've been working on a process for self-taught developers to build credibility and land a job without previous experience.

The process is simple but extremely effective, and I'm looking for a few highly motivated self-taught developers to share it with.

If you're interested, send me an email at ken@kenrogers.co and we can set up a video chat to go over how it works. Should only take about 10 minutes to go over everything.

Thanks!

Getting Your First Job as a Self-taught Developer

kenny — Mon, 07 Dec 2020 22:13:50 +0000

Back in 2014, I got my first job as a junior developer with no formal education and no experience. You can read the full story if you're interested.

Article No Longer Available

But this post isn't about my story, it's about yours.

If you are a self-taught developer struggling to land that first job, stuck in an endless river of applications, resumes, and rejections, this post will give you a roadmap to building credibility, a real-world portfolio, a valuable network, and ultimately, getting that first job.

This post is going to be a minimum effective dose kind of article.

I took everything I know about how myself and others have gotten their first jobs and distilled it down into a simple, actionable process.

If you take what you learn here and actually apply it, I am very confident you will launch and grow a successful career as a developer.

You can read what I've written here, take a few hours to implement it, and have a complete system in place for getting a great job, and be miles ahead of other people that will continue to send their applications and resumes off into the abyss.

It will be broken up into 7 parts:

Changing your mindset
Establishing your online presence
Building a real-world portfolio
Writing your first post
Building a solid network
Creating a system
Growing from here

Let's get into it.

Changing your mindset

First, I want to tell you a few things that might take a bit of adjustment to your worldview.

Sending out applications to as many companies as possible is not the best way to get a job.
You do not need existing experience or credentials to get a great job

Let me explain why I believe these things and hopefully convince you of the same.

First, in regards to sending out applications.

Just because job boards exist and there are lots of jobs on those boards, does not mean they are the only places to find jobs.

They are the most obviously visible place to find jobs, but that's about it.

There are countless other positions waiting to be filled that will never be advertised publically or posted on a website.

In his post on getting a dev job without a degree, Josh Comeau notes that only 15% of the developers he polled got their job through the traditional application/job board process.

While this is technically just anecdotal evidence, it lines up with my own experience and the experience of most of the developers I know.

The methods in which a company goes about hiring say a lot about their priorities and values.

Smaller, "startup-style" companies that value innovation and efficiently solving problems over tradition and corporate structures tend to treat hiring developers in alignment with those values.

They will often not post jobs and look for talented developers through social media or their network.

Your goal is to be a part of that network and build up the skills necessary to impress them when they do find you or you find them.

Now on to the credentials issue.

Let's look at what value a degree or existing experience actually has for an employer, and see if there is a way we can replicate that value as self-taught developers without those things.

All hiring decisions are risk assessments:

"Will hiring this person bring more value (both monetarily and culturally) to the company than it will cost to hire them?"

If the answer to that question is yes to a higher degree than all other candidates, an offer is made.

Degrees and existing experience are signals to employers that tilt the scales in your favor in that risk assessment.

Degrees as signals are becoming less valuable every year. And experience can easily be replicated by taking the initiative to solve problems into your own hands.

When you combine that with the cultural signal you can send by writing, learning in public, and actively reaching out to new people, you can create a risk-minimizing signal stronger than both a degree and existing experience.

That process is what we'll be covering throughout this guide and what I cover in detail in Create & Connect.

Establishing your online presence

The first step in creating these signals is to build up a presence online.

If employers can’t find you, they can’t hire you.

If your online presence online is contained in the faceless resume and applications you send to companies you are at an extreme disadvantage.

You don’t necessarily need a website at first, although I definitely recommend creating one at some point.

For now, a profile at these three websites is a great starting point:

Dev
LinkedIn
GitHub

Be sure to fill it out with a relevant bio and a good headshot.

These three sites will serve as your bases of operations for writing, showing off your code skills, and networking, respectively.

We’ll cover each of these three components next.

Building a real-world portfolio

Now that you have a basic online presence set up, it’s time to actually use it and fill it with relevant information about what you can do.

A major mistake I see new and aspiring developers making is only having toy apps or apps made by following tutorials and courses.

If you want to establish credibility and send a strong signal to employers, you need to show that you can solve real problems.

You aren’t ultimately paid as a developer to write code. You are paid to solve problems using code as the mechanism.

So fill your portfolio with real projects that solve real problems.

Think about problems you face in your own life that could be wolves with code, then build something to solve them.

If you can’t think of any, ask people you know what their problems are and solve those.

If you want to be a real overachiever, make a list of companies you want to work for, build something for them, and then reach out to them expressing your interest in working for them and show them what you made.

Writing your first post

Writing is one of the most powerful things you can do for your career, especially if you are new to the game.

I credit writing as one of the primary reasons I have the job I do now.

It allows you to communicate your thought and problem-solving process and serves as a living portfolio and a constantly evolving record of your work and growth.

One of the biggest hurdles people run into is not knowing what to write about.

Fortunately, this problem is easily solved because of our real world projects.

Just write about the process of building it as if you are teaching someone.

So you can start a new series for each new project you create and go over what you did to build it and why.

Use a platform like Dev to write these. It’s extremely easy to use and has an active, engaged community.

Plus you can easily integrate it with a static site generator and have your posts automatically populate using Stackbit.

Building a solid network

Alright, you’ve got your portfolio in the works and you’ve started writing.

The third piece of the puzzle is actively reaching out and building relationships with people.

There are three groups of people I recommend doing this with:

Recruiters
Potential employers
Fellow developers

This doesn’t have to be complicated. Just be a genuine person who wants to build real relationships with people.

I got my first developer job by emailing local development shops introducing myself, saying I was an aspiring developer and wanted to meet some shops in town, and linking to my GitHub profile and my favorite project.

Use LinkedIn, Google, and social media to start reaching out to people and introducing yourself.

Creating a system

This is all well and good but it can be a bit overwhelming to try and tackle all of this.

It might seem easier to create your resume and have the same information on hand to fill out a hundred applications.

But that way lies madness.

The steps I’ve outlined here can be streamlined into a system of small daily actions you can take to progress your career.

The important thing is to block out time in your calendar for each component.

So every day block out as much time as you can for creating, writing, and connecting.

Then focus on that one thing during that time.

Create a recurring time block in your calendar and commit to that thing each day.

Over time these times blocks will add up and if you focus on completing those actions each day as your measure of success, you will quickly build up a solid portfolio of work and writing and a valuable network.

It can be as small as reaching out to one new person per day, coding your project for 30 minutes, and writing about what you did for 15 minutes.

You write Monday through Thursday and edit and post on Friday.

The takeaway is to figure out what schedule works for you, block time out to do it, and stick to it consistently.

Growing from here

These actions might seem small and simple but they can form the foundation for the rest of your career.

If you commit to doing these things consistently then over time you will build an incredibly valuable reputation in the industry and won’t have to worry about finding work.

Over time you can adjust your strategy and focus as you find what works, but for right now the important thing is to just start.

If you follow what I’ve outlined here you will have a successful career.

My goal is to help 1,000 developers get hired in 2021. Here's how you can be a part of that 👉🏻 Launch Your Dev Career

If I had to start my career from scratch, this is exactly what I would do to land my first job.

Every developer should write. Here's how to get started

kenny — Wed, 25 Nov 2020 01:34:00 +0000

Writing is one of the most impactful, high-leverage things I have ever done for my career.

Writing has three main benefits that have made a big difference in my life and career:

It helps me solidify and ensures I understand my ideas and processes

There is something about writing that forces you to really process and articulate abstract ideas you may have floating around in your head.

When you go through the process of writing about something, you really have to think through what you are actually trying to say to make sure the reader can understand it.

This process leads to increased clarity for yourself along with the reader.

Demonstrates your skillset and problem-solving process

Portfolios are great, but they can sometimes suffer because they are static ways of demonstrating your work.

When you write alongside building things, it gives people a glimpse into your thought and problem-solving process, which can make your portfolio projects much more dynamic, engaging, and goes a long way towards communicating your value.

Communicates your values and cultural fit to potential employers

Finally, possibly my favorite benefit and often the most overlooked.

Writing can communicate your values to employers which can help them in determining whether or not you would be a good fit culturally within their company.

Though not talked bout as often, this component of career growth is often as important as technical skills.

By communicating your personality and values in your writing, you give people a look at who you are, what makes you tick, and what is important to you.

It allows people you have never met to get to know a little more, which can be extremely helpful when job hunting.

How to get started writing

Okay great, writing can help your career, but getting started can seem like a big hurdle.

Here's an easy way you can get started in the next 30 minutes with your first post.

First, create an account and fill out all the information here on Dev. This is an awesome place to start writing with a low barrier to actually getting started.

Next, start a new post and write about your story up until now and where you want to go as a developer.

Talk about where you came from, what other jobs you've had, why you want to be a developer, and what you've done so far to make that happen.

Then post it.

This is not meant to be read by thousands of people, it's not meant to be the best piece of writing you'll ever do.

It's meant to be the first piece of writing. The initial hurdle to jump.

Posting publicly is very important.

Put yourself out there. It's a fantastic way to grow.

After you write that post, comment here with a link to it so I can check it out!

Looking to land your first job as a developer? You may like my course and mentoring group, Launch Your Dev Career.

You can also follow me on Twitter for more tips on launching and building a successful, fulfilling career as a developer.

[Atomic Dev Tips] Be a Problem Solver

kenny — Thu, 05 Nov 2020 21:51:39 +0000

Atomic Dev Tips is an ongoing series of short, actionable, high-leverage posts on how to be the best developer you can be.

This is the first in that series of posts. Follow me here on Dev or on your social media platform of choice if you'd like to keep up with the series and any other content I create.

One of the most valuable things I've learned in my 6 years as a developer is the importance of viewing your primary role as being a problem solver.

You should not think of yourself as a developer, coder, or engineer. You should think of yourself first as someone who solves problems for people.

Code is just the tool you use to accomplish that goal.

This idea will bleed out into everything you do if you can make it a foundational part of your identity.

Instead of wondering what sample projects to build for your portfolio, start noticing annoyances in your own life and the lives of others.

When assigned a new project at work, you can have valuable input and feedback into the development cycle if you look at your role as a problem solver, not just someone who codes up someone else's solutions.

Cultivate the skill of being able to identify these problems and flesh out software-based solutions to them.

This problem-solving mentality is a major factor in success not only as a developer but in any career you choose, whether working for someone else or yourself.

This is one of the main principles at work in my workshop, Create & Connect, teaching aspiring developers how to land their first jobs.

Cultivating this mentality is how you can set yourself apart from other people who are just developing without understanding the underlying reasons behind why they are building things.

So, starting today, take note of the problems you see in your life. Keep an ongoing idea notebook, digital or analog, doesn't matter, and start writing them down.