Clarity language

Clarity language guide for Scaffold Stacks developers — syntax essentials, learning resources, and daily patterns for Stacks smart contract development.

Scaffold Stacks handles deploy, bindings, and frontend — you still write Clarity in contracts/contracts/*.clar. For language depth, use official Stacks docs. This page routes you there and lists syntax you will use daily.

Contents

• Learning resources
• Scaffold workflow
• Syntax essentials
• Responses and errors
• Built-in context
• Maps and lists
• Tokens

Learning resources

Need	Resource
First-time Clarity	Clarity Crash Course
Structured book	Clarity Book
Interactive course	Clarity Universe
Browser REPL	Clarity Playground
Function/type reference	Clarity Reference
Language spec (SIP-002)	SIP-002 Smart Contract Language

Scaffold workflow

# edit contracts/contracts/my-contract.clar
stacksdapp check          # Clarinet type-check + check_checker
stacksdapp test           # Vitest + simnet in contracts/tests/
stacksdapp generate       # refresh frontend hooks
stacksdapp deploy --network testnet --yes

Contract tests live in contracts/tests/*.test.ts — no Docker. See Testing.

Default new projects use Clarity 6 (epoch 4.0). See Clarity versions.

Syntax essentials

Clarity is LISP-like: expressions in parentheses.

Data variables

(define-data-var counter uint u0)
(var-get counter)
(var-set counter (+ (var-get counter) u1))

Functions

Form	Who can call	Mutates state
define-read-only	Anyone	No
define-public	Anyone	Yes (via ok path)
define-private	Same contract only	Yes

(define-read-only (get-count)
  (ok (var-get counter)))

(define-public (increment)
  (begin
    (var-set counter (+ (var-get counter) u1))
    (ok (var-get counter))))

Responses and errors

Public functions return (response T uint) — success (ok value) or error (err uint):

(define-constant ERR_UNAUTHORIZED (err u401))

(define-public (admin-only)
  (begin
    (asserts! (is-eq tx-sender CONTRACT_OWNER) ERR_UNAUTHORIZED)
    (ok true)))

• asserts! — aborts with err if condition is false
• try! — unwraps ok or propagates err

Built-in context

Name	Meaning
tx-sender	Principal that signed the transaction
contract-caller	Immediate caller (may differ with contract calls)
block-height	Stacks block height
burn-block-height	Bitcoin block height
current-contract	This contract’s principal

Use tx-sender vs contract-caller carefully for access control. See Contracts.

Maps and lists

(define-map balances principal uint)

(map-set balances tx-sender u100)
(map-get? balances tx-sender)

(define-data-var ids (list 10 uint) (list))

Tokens

For SIP-010 fungible tokens and SIP-009 NFTs, use scaffold templates instead of writing from scratch:

stacksdapp add my-token --template sip010
stacksdapp add my-nft --template sip009

Full trait tables and impl-trait rules: SIP standards

Low-level token primitives:

(define-fungible-token my-token)
(ft-mint? my-token amount recipient)
(ft-transfer? my-token amount sender recipient)

(define-non-fungible-token my-nft uint)
(nft-mint? my-nft token-id recipient)
(nft-transfer? my-nft token-id sender recipient)

Next steps

• Contracts — add and test contracts
• Clarity versions — C4/C5/C6 epoch mapping
• SIP standards — token and NFT templates
• Workflows — common development patterns