Development of Smart Contracts in Clarity (Stacks)
Stacks is a blockchain that runs on top of Bitcoin and uses Bitcoin as a settlement layer. Smart contracts on Stacks execute through Proof of Transfer (PoX) consensus, finality is ensured by Bitcoin blocks. This is a unique position: Turing-complete smart contracts with Bitcoin finality, without needing to bridge BTC.
The Clarity language is intentionally designed unlike Solidity. It is interpreted (not compiled to bytecode — code is read and executed directly), decidable (behavior is fully predictable without execution), and intentionally not Turing-complete in recursion (no recursive calls between contracts in a single transaction).
What Decidable Means — and Why It Matters for Audits
In Solidity an auditor must simulate code execution to understand what will happen on a given call. In Clarity syntax is written so function behavior can be derived statically, without execution. No dynamic calls via pointer, no arbitrary recursion, no self-destruct.
In practice this means: reentrancy attacks in the classical sense are impossible. Contract A calls contract B — B cannot call A back in the same transaction. This is a fundamental language limitation, not just a lint rule. An entire class of vulnerabilities that cost hundreds of millions on EVM simply doesn't exist here.
But this has a price: patterns familiar from Solidity don't work directly.
Clarity Syntax and Type System
Clarity is written in Lisp-like syntax (S-expressions). For developers experienced with Solidity/JavaScript this is unfamiliar. Example of a simple function:
(define-public (transfer (amount uint) (sender principal) (recipient principal))
(begin
(asserts! (is-eq tx-sender sender) err-not-authorized)
(try! (ft-transfer? my-token amount sender recipient))
(ok true)
)
)
principal — type for addresses (Stacks address or contract principal). uint — unsigned integer. No implicit type conversions. try! unwraps Result, reverts on error.
Data Types
| Type | Solidity Analogue | Features |
|---|---|---|
uint |
uint256 |
Unsigned only |
principal |
address |
Includes contract principals |
(buff N) |
bytes |
Fixed length |
(string-ascii N) |
string |
ASCII, fixed length |
(list N T) |
T[] |
Fixed maximum length |
(optional T) |
no direct analogue | Explicit handling of absence |
Fixed lengths are important. Clarity has no dynamic arrays of arbitrary length. (list 200 uint) is a list of at most 200 elements. This is intentional: gas model in Stacks is calculated statically based on maximum data sizes.
SIP-009 and SIP-010 — Token Standards
SIP-010 — Fungible Token standard (analogous to ERC-20). Required functions: transfer, get-balance, get-total-supply, get-decimals, get-name, get-symbol, get-token-uri.
SIP-009 — Non-Fungible Token (analogous to ERC-721). Includes: get-last-token-id, get-token-uri, get-owner, transfer.
Unlike ERC-20, SIP-010 requires transfer to take sender as explicit parameter and verify tx-sender == sender. This prevents one classic vector: calling transferFrom on behalf of another address without verification.
Trait System
Clarity has no interfaces like Solidity. Instead — traits: named sets of functions that a contract commits to implementing. When a function is called with a parameter of type <trait>, the runtime checks that the passed contract implements all trait functions. This enables building composable systems — for example, a marketplace accepting any SIP-009-compatible NFT contract.
In Depth: Working with Bitcoin in Clarity
This is the main unique capability of Stacks. Via Clarity Bitcoin library, a contract can read Bitcoin transactions directly (without bridge). get-burn-block-info? function returns data about a Bitcoin block. verify-merkle-proof allows on-chain verification of transaction inclusion in a Bitcoin block.
This opens a pattern: user sends BTC to Bitcoin address, Clarity contract verifies transaction via Merkle proof and mints tokens on Stacks. No trust assumptions, no wrapped BTC, no bridge — pure cryptographic verification.
Implementing this pattern is non-trivial: need to understand Bitcoin transaction structure (segwit vs. legacy), Merkle tree of Bitcoin blocks, and correctly parse (buff 1024) as UTXO data. But this is first-class language functionality, not a hack.
Development Tools
- Clarinet — CLI for developing and testing Clarity contracts (Hardhat/Foundry analogue for Stacks)
-
clarinet new— project initialization -
clarinet test— run tests via Deno/TypeScript -
clarinet console— REPL for interactive interaction with contracts -
clarinet integrate— local network with Bitcoin block simulation - Hiro Explorer — block explorer for Stacks (mainnet + testnet)
- stacks.js — JavaScript library for contract interaction (ethers.js analogue)
Tests are written in TypeScript using Vitest or Jest. Clarinet provides simnet — in-memory network simulator, allowing testing multiple blocks, advancing time, simulating Bitcoin transactions.
Typical Development Challenges
No msg.value/Payable functions. STX payments are handled via stx-transfer?. If contract should accept STX, must explicitly handle transfer in function logic. No automatic "ETH attached to call".
Post-conditions on client side. stacks.js and wallets (Leather, Xverse) support post-conditions: user signs transaction with explicit maximum balance change. If contract tries to change balance more than specified — transaction is rejected. This protects against drain attacks, but requires proper SDK configuration.
Read-only functions and their limitations. define-read-only functions cannot change state, but can read state of other contracts via contract-call?. With complex read-only computations, hits cost limit for read-only calls (significantly lower than for normal transactions).
Development Process
Design. Define data structures (maps, vars), functions with access rights, token standards. Draw call graph between contracts — important for analyzing reentrancy (which doesn't exist) and deployment order.
Development in Clarinet. Iterative development with tests. Clarinet console for checking logic. Test coverage via simnet.callPublicFn, simnet.callReadOnlyFn.
Audit before deployment. Clarity allows formal analysis — check all execution paths, verify correctness of post-conditions on client.
Deployment. clarinet deployments generate --testnet → clarinet deployments apply. Contracts deploy in dependency order automatically.
Timeline
Standard SIP-010 token with custom logic — 3-5 working days. Complex protocol (DEX, lending, NFT marketplace with SIP-009) — 2 to 4 weeks. Contracts with Bitcoin verification via Clarity Bitcoin — from 2 weeks, depends on UTXO logic complexity.
Cost is calculated individually after analyzing requirements.