Exercises

Hands-on practice exercises for mastering Citizen smart contract development. Each exercise builds on concepts from the guides and introduces progressively more complex patterns.

How to use these exercises

Each exercise page follows the same structure:

1. Problem statement — What you're building and the requirements
2. Starter code — A template to fill in
3. Hints — Step-by-step guidance (try without them first!)
4. Complete solution — Full working implementation with explanation
5. Test cases — Verify your contract works correctly

Setup

Before starting, make sure you have:

• Rust toolchain with wasm32-unknown-unknown target (Installation)
• Read the Hello World tutorial
• Local node running (bash scripts/start-local-stack.sh)
• A deployment script ready (see Deployment)

Workflow

# 1. Create a new contract crate
cargo new --lib exercise-counter
cd exercise-counter

# 2. Set up Cargo.toml (see each exercise)

# 3. Write your solution in src/lib.rs

# 4. Build to WASM
RUSTFLAGS="-C link-arg=--allow-undefined" cargo build --release --target wasm32-unknown-unknown

# 5. Deploy and test (use the deployment script from each exercise)

Exercise list

#	Exercise	Concepts practiced	Difficulty
1	Counter	Basic storage, events, responses
2	Token	Maps, arithmetic, transfer logic
3	Access Control	Authorization, roles, owner pattern
4	Voting	State machines, time-based logic, enumeration
5	Multi-Contract	Cross-contract calls, composition
6	Auction	Complex state, deadlines, refunds

Learning path

Beginner ────────────────────────────────────────── Advanced

Counter ──► Token ──► Access Control ──► Voting ──► Multi-Contract ──► Auction
   │           │            │                │             │               │
   │           │            │                │             │               │
storage    maps         signatures     state machine  cross-contract   deadlines
events     arithmetic   roles          enumeration    composition      refunds
responses  validation   owner pattern  time logic     integration      edge cases

Skills checklist

By completing all exercises, you will have practiced:

• Creating and building WASM contracts
• Using Item<T> and Map<K,V> storage patterns
• Extracting parameters with ctx.param(), ctx.param_or(), ctx.param_opt()
• Verifying Ed25519 signatures
• Checking governance approval
• Implementing role-based access control
• Emitting structured events
• Building complex response objects
• Implementing state machines
• Working with block-height-based deadlines
• Maintaining enumeration indexes
• Making cross-contract calls
• Handling edge cases and error paths
• Writing integration tests

Reference contracts

The repository includes several real-world contracts you can study:

Contract	Location	Demonstrates
admin-registry-v2	modules/admin-registry-v2/	Full admin management with SDK
voting-trust	modules/voting-trust/	Complete governance voting system
ctzn-token	modules/ctzn-token/	Soulbound token with tiers and access control
admin-registry	modules/admin-registry/	Raw WASM (no SDK) for comparison