Soroban Cookbook

A comprehensive guide to building smart contracts on Stellar with Soroban

Table of Contents

• About
• Quick Start
• Installation
• Repository Structure
• Examples
• Guides
• Documentation
• Contributing
• Additional Resources
• License

About

The Soroban Cookbook is a community-driven developer resource for building smart contracts on the Stellar network using Soroban. It provides clear, well-documented examples and practical patterns for developers at every level — from a first "Hello World" contract to production-grade DeFi protocols.

Every example in this cookbook:

• Compiles with the latest stable Soroban SDK
• Includes comprehensive unit and integration tests
• Features inline documentation explaining key concepts
• Follows Rust and Soroban best practices
• Passes all automated CI/CD checks

Quick Start

# Clone the repository
git clone https://github.com/Soroban-Cookbook/Soroban-Cookbook-.git
cd Soroban-Cookbook

# Run a basic example
cd examples/basics/01-hello-world
cargo test

# Build the contract as WASM
cargo build --target wasm32-unknown-unknown --release

Installation

Prerequisites

• Rust (stable, 1.74+)
• Soroban / Stellar CLI

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustc --version

2. Add the WASM target

Soroban contracts compile to WebAssembly:

rustup target add wasm32-unknown-unknown

3. Install Stellar CLI

cargo install --locked stellar-cli --version 22.1.0
stellar --version

4. Clone and verify

git clone https://github.com/Soroban-Cookbook/Soroban-Cookbook.git
cd Soroban-Cookbook
cargo test --workspace

Repository Structure

Soroban-Cookbook/
├── examples/               # Smart contract examples
│   ├── basics/             # Beginner-friendly fundamentals
│   ├── intermediate/       # Common patterns and use cases
│   ├── advanced/           # Complex systems and protocols
│   ├── defi/               # DeFi-specific examples
│   ├── nfts/               # NFT implementations
│   ├── governance/         # DAO and voting systems
│   └── tokens/             # Token standards and patterns
├── book/                   # mdBook documentation source
│   └── src/
│       ├── guides/         # Step-by-step tutorials
│       ├── examples/       # Example write-ups
│       └── docs/           # Reference documentation
├── docs/                   # Supplementary reference docs
└── .github/                # CI/CD workflows and templates

Examples

By Difficulty

Basics

Core Soroban concepts, one at a time.

Example	Concepts
01-hello-world	Contract struct, #[contract] / #[contractimpl], unit tests
02-storage-patterns	persistent, instance, temporary storage, TTL
03-authentication	require_auth(), admin roles, balances
03-custom-errors	#[contracterror], error codes, rate limiting
04-events	env.events().publish(), topic design
05-auth-context	Cross-contract execution context
05-error-handling	Error enums, validation, propagation
06-soroban-types	Address, Symbol, Bytes, Map, Vec
06-validation-patterns	Precondition checks, overflow-safe arithmetic
07-enum-types	#[contracttype] enums, role dispatch
08-custom-structs	#[contracttype] structs, nested types
09-primitive-types	u32, u64, i128, arithmetic safety

Intermediate

Common patterns and real-world use cases.

• Token interactions and wrappers
• Cross-contract patterns (factory, proxy, registry)
• Access control: multi-sig patterns, RBAC, timelocks
• Data structures: iterables, queues, priority queues

Advanced

Complex systems for experienced developers.

Example	Concepts
01-multi-party-auth	Threshold signatures, multi-party authorization
02-timelock	Time-delayed execution, queue/cancel/execute

By Use Case

Category	Description
DeFi	AMMs, lending pools, vaults, escrow, yield protocols
NFTs	Minting, marketplaces, metadata standards
Governance	DAOs, voting systems, proposals
Tokens	SEP-41 tokens, wrappers, vesting, airdrops

Guides

Step-by-step tutorials in the book:

Guide	Description
Getting Started	Set up your development environment
Testing	Unit tests, integration tests, best practices
Deployment	Deploy to testnet and mainnet
Ethereum to Soroban	Solidity → Rust pattern translation

Documentation

Reference docs in docs/:

• Best Practices — Security, storage, and code quality guidelines
• Quick Reference — Cheat sheet for common patterns
• Glossary — Key terms and concepts

The full documentation site is built with mdBook and deployed to GitHub Pages on every push to main.

Contributing

Contributions are welcome. Whether you're fixing a typo, improving docs, or adding a new example — see CONTRIBUTING.md for guidelines. Please also read our Code of Conduct.

Ways to contribute:

• Add new contract examples or patterns
• Improve documentation and guides
• Report bugs or suggest improvements
• Review pull requests

Before submitting a PR, make sure your changes pass the local checks:

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo build --workspace --target wasm32-unknown-unknown --release

Additional Resources

• Soroban Documentation
• Stellar Developer Portal
• Soroban Rust SDK
• Stellar Community Discord
• Project Roadmap - Planned phases, milestones, and KPIs

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built by the community · Powered by Stellar · Written in Rust