Interact with Stacks blockchain on Testnet

Stacks is a layer 1 blockchain anchored directly to Bitcoin via the Proof of Transfer consensus mechanism bringing smart contracts to Bitcoin. To note, Smart contracts on Stacks do not alter any Bitcoin properties. There are a lot of misconceptions about Stacks being a Layer 2 or a side-chain because it cannot exist without Bitcoin and there is a great article by Jude Nelson which describes what kind of blockchain Stacks is, if you would like to familiarize yourself better. In short, Stacks is a Layer 1 but but cannot exist with a proof of burn chain and in case of Stacks the burn chain is Bitcoin.

In this tutorial, we will take a look at how to create Stacks account and load it with STX so that we can interact with smart contracts on testnet blockchain. But first let’s take a look at what Stacks Explorer and testnet is.

Stacks Explorer is the block explorer and analytics platform which lets you view and analyze assets, balances and transactions on the Stacks network. You can also interact with smart contracts using the sandbox and check fees on the Stacks Explorer.

testnet is a public chain like Goerli, Ropsten, Rinkeby on Ethereum, which is a separate chain from mainnet similar to a staging environment. Before contracts go live on mainnet, developers can use testnet to test their apps that function like mainnet and you can perform testing without taking the financial risk to execute the smart contracts. Also for that reason any user can make calls to the testnet contracts for free, to get a feel of what the transactions, blocks and responses behave like. Extra things to note are that testnet produces roughly 1 block every 10 minutes on average just like mainnet and it is rarely reset.

Let’s dive in the tutorial, and of course, if you have questions at any point, don’t hesitate to reach out in the Stacks Discord or visit Stacks or Hiro documents!

STEP 1: CREATE A STACKS ACCOUNT (ADDRESS)

We need a Stacks account to send and receive transactions. For this tutorial, we’ll use Hiro, a virtual wallet in the browser used to manage your Stacks account address. If you want to understand more about how transactions on Stacks work, read documentation on accounts, transactions and network from Stacks organization.

If you don’t already have a Hiro account, you can sign up for free here. I have Hiro wallet browser extension installed and if that is what you want, go Download for web.

When you are creating an account, or if you already have an account, make sure to switch over to the “testnet” test network (so that we’re not dealing with real money). To do that, click on the hamburger menu on the top right corner and Change Network to testnet.

All right! Now you have a Stacks Account setup 🎉. What do we do next? Let’s load it with STX. 👇

STEP 2: ADD STX FROM A FAUCET

One way to load free STX is Faucet and you can use it on the Stacks Explorer Sandbox to get started. FYI, these free STX you get have no value and are not exactly same as STX on mainnet.

Once you are on Sandbox, this is what you will see (checkout the image below) and make sure you are on the correct network, Testnet mode (on the menu bar) and also your browser link would show chain=testnet:

Now Connect your Wallet and again make sure you are on testnet network. After you connect to your account, you would now be able to see a pre-written contract load on the screen which you can deploy directly from sandbox. We will come back to writing and deploying later, but this is what it would look like:

Navigate to “Faucet” tab on the left sidebar, where now you can Request STX. You would shortly after receive 500 STX in your account.

✨ And we shall have some STX 🌟 in our account soon 💫

Alternately, if you would like to use the Stacks API to load free STX on testnet account, then you could call the Stacks Faucet API here

Your API request would look like this:

api uri: https://stacks-node-api.testnet.stacks.co/extended/v1/faucets/stx
method: POST
content-type: application/json
body:
        {
              "address": "ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ", ;; your testnet account address here
              "stacking": false
        }

The successful response would return a transaction ID, which you can use to view the transaction in the Stacks Explorer.

STEP 3: CHECK YOUR BALANCE

We should now be able to verify our balance. You can check the balance and the activity on the HIRO Wallet extension. Login to your HIRO wallet via extension, if you aren’t already logged in and you will be able to see 500 STX transferred to your account.

You can also get a picture of transactions on your account by clicking on the hamburger menu on top right, to verify if your STX transaction completed or not.

Wohooo! Our fake free money should be available any minute.

STEP 4: WRITE AND DEPLOY A CONTRACT ON TESTNET

Can we finally now interact with contracts on testnet? No. First we need to know which contract to interact with. There are a bunch of contracts deployed on testnet which you can test, but for our tutorial we are going test our own contract on testnet. So first we need to write a contract. We are taking a readymade contract which you can use to deploy to testnet. Example Contract below, credits to @mariaverse for this contract. Check out her post for diving into building a full stack app on Stacks using Clarinet here

;; gm
;; smart contract that posts a GM to the chain for 1 STX

;; constants
(define-constant CONTRACT_OWNER tx-sender)
(define-constant PRICE u1000000)
(define-constant ERR_STX_TRANSFER (err u100))

;; data maps and vars
(define-data-var total-gms uint u0)
(define-map UserPost principal (string-ascii 2))

;; public functions
(define-read-only (get-total-gms)
  (var-get total-gms)
)

(define-read-only (get-gm (user principal))
  (map-get? UserPost user)
)

(define-public (say-gm)
  (begin
    (unwrap! (stx-transfer? PRICE tx-sender CONTRACT_OWNER) ERR_STX_TRANSFER)
    (map-set UserPost tx-sender "gm")
    (var-set total-gms (+ (var-get total-gms) u1))
    (ok "Success")
  )
)

Don’t worry if you don’t know how to write this code yet. For now the only 3 functions we will look into calling is say-gm, get-gm and get-total-gms

1. say-gm: is a public function which transfers funds (STX) from your account to the contract, sets a message gm for your user on the map UserPost and also updates the count of total gms.
2. get-gm: is a read only function so you can read if gm was set for your user to determine whether your said gm.
3. get-total-gms: is a read only function as well which gives you the total number of gms said up till that point.

So copy this code and paste it replacing the existing code, rename your contract if you would like to do that and deploy. It would show a modal on your screen displaying the details of the deployment, the fees and nonce.

Once you confirm the deployment, the transaction would be created and you would have to wait for the transaction to complete. You would be able to verify the deployment through the Hiro Wallet Activity tab.

STEP 4: INTERACT WITH CONTRACTS USING STACKS API

Now, let’s go make some contract calls.

Navigate to Call a Contract and type in the deployer, name of the contract and hit Get Contract


You would now be able to see the contract functions available to call, see the image below. Switch to another Account, because the deployer cannot call the public function, I switched to Account 3 by logging out and logging in again with your new account

The read only functions do not require a transaction because they read the on-chain data directly from the Stacks node and not the chain itself, thereby not charging you anything.

Initial response values of the read only functions would be their initial values none for get-gm as no one has said gm yet and 0 for the total count of gm.

Make a call to the say-gm public function which will show you a modal with the post conditions and fees charged and ask you to confirm the transaction before it is executed.

This would create a transaction on testnet and you would be able to view when the transaction completes and view the results. Now if you go back to call the read only functions again, you should see the updated data after the say-gm function call

Great! You can now interact with any contract on testnet.

Resources:

1. https://www.stacks.co/
2. https://clarity-lang.org/
3. https://docs.stacks.co/docs/intro
4. https://docs.hiro.so/intro

Follow and get latest updates on Clarity Language: https://twitter.com/clarity_lang