Soroban Cookbook

A comprehensive guide to building smart contracts on Stellar with Soroban

Table of Contents

• Project Overview and Goals
• Quick Start
• Installation
• Repository Structure
• Examples
• Guides
• Documentation
• Web Application
• Contributing
• Additional Resources
• License

Project Overview and Goals

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

Project Goals

• Make Soroban contract development easier by providing concrete, real-world examples to the problems
• Teach safe Soroban and Rust patterns through documentation and tests
• Support beginners and advanced developers with clearly organized examples
• Keep repository examples current with Stellar and Soroban tooling
• Maintain high-quality CI, build, and test coverage for every contribution

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

Project Goals:

• Education: Provide clear, production-ready, and secure examples for Soroban developers.
• Acceleration: Speed up the onboarding process for the Stellar/Soroban ecosystem.
• Standardization: Establish and document best practices for smart contract architecture on Stellar.
• Community: Foster a collaborative environment for developers to share patterns and solutions.

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
├── webapp/                 # Next.js web application for interactive examples
├── scripts/                # Build and deployment scripts
└── .github/                # CI/CD workflows and templates

Examples

By Difficulty

Basics

Core Soroban concepts, one at a time.

Example	Concepts
hello-world	Minimal contract struct, #[contractimpl], returning vectors
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-validation-patterns	Precondition checks, overflow-safe arithmetic
07-type-conversions	TryFromVal, IntoVal, safe narrowing
08-soroban-types	Address, Symbol, Bytes, Map, Vec
09-enum-types	#[contracttype] enums, role dispatch
10-custom-structs	#[contracttype] structs, nested types
11-primitive-types	u32, u64, i128, arithmetic safety
12-data-types	Full type system reference
13-collection-types	Vec, Map collection patterns
14-event-filtering	Indexer-friendly event topics

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: iterable mappings, 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

• Style Guide — Naming, documentation, and testing standards

• Performance Benchmarks — Resource usage comparison and optimization tips

• Quick Reference — Cheat sheet for common patterns

• Glossary — Key terms and concepts

• Troubleshooting — Common build, test, and deployment issues with solutions

• Wallet Ecosystem Survey — Research, features comparison, and integration priority list for Soroban-compatible wallets

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

Web Application

An interactive web application built with Next.js to explore and run Soroban contract examples directly in your browser.

• Located in webapp/
• Built with Next.js, React, and TypeScript
• Provides a playground for testing contracts

To run the webapp locally:

cd webapp
npm install
npm run dev

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

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.