A comprehensive guide to building smart contracts on Stellar with Soroban
- Project Overview and Goals
- Quick Start
- Installation
- Repository Structure
- Examples
- Guides
- Documentation
- Web Application
- Contributing
- Community & Integration
- Additional Resources
- License
The Soroban Cookbook is a comprehensive, production-grade learning resource and pattern library for developers building smart contracts on the Stellar network using Soroban. Designed to complement the official Stellar Developer Documentation, it provides clear, well-tested, and documented code recipes for smart contract development at every level — from absolute beginners writing their first "Hello World" contract to senior engineers deploying complex DeFi protocols.
- Education: Provide clear, production-ready, and secure code patterns that teach safe Soroban and Rust development.
- Acceleration: Drastically speed up the onboarding process for developers entering the Stellar/Soroban ecosystem.
- Standardization: Establish, document, and promote best practices and design patterns for smart contract architecture on Stellar.
- Ecosystem Quality: Maintain a high standard of quality through complete automated test coverage, Clippy verification, and security audits for every example.
Every example in this cookbook:
- Compiles successfully using the latest stable Soroban SDK.
- Contains comprehensive unit and integration tests verifying all critical code paths.
- Enforces strict security boundaries and adheres to standard Rust/Soroban best practices.
- Features detailed, inline explanations of architectural design and storage decisions.
- Passes all CI/CD pipelines including formatting, clippy lints, and test suites.
# 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- Rust (stable, 1.74+)
- Soroban / Stellar CLI
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustc --versionSoroban contracts compile to WebAssembly:
rustup target add wasm32-unknown-unknowncargo install --locked stellar-cli --version 22.1.0
stellar --versiongit clone https://github.com/Soroban-Cookbook/Soroban-Cookbook-.git
cd Soroban-Cookbook-
cargo test --workspaceSoroban-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
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 |
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
Complex systems for experienced developers.
| Example | Concepts |
|---|---|
| 01-multi-party-auth | Threshold signatures, multi-party authorization |
| 02-timelock | Time-delayed execution, queue/cancel/execute |
| 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 |
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 |
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.
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 devContributions 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 --releaseThe Soroban Cookbook is integrated into the official Stellar Developer ecosystem as a featured community resource. We work in tandem with the Stellar Development Foundation (SDF) and community developers to ensure our examples and guides align with the official documentation and best practices.
- Stellar Developer Docs: The cookbook is featured in the official Stellar Smart Contract Documentation under community-driven developer resources.
- Stellar Community Discord: Find us in the
#sorobanchannels. We coordinate examples and help troubleshoot issues with fellow developers.
We maintain an active Roadmap detailing planned expansions, DeFi templates, governance structures, and security validation procedures. Contributions to the cookbook are recognized through the Stellar Developer community incentives, and all submissions undergo a thorough review process detailed in our Contributing Guidelines.
This project is licensed under the MIT License — see the LICENSE file for details.
Built by the community · Powered by Stellar · Written in Rust.