{"skill":{"slug":"setup-stellar-contracts","displayName":"Setup Stellar Contracts","summary":"Set up a Stellar/Soroban smart contract project with OpenZeppelin Contracts for Stellar. Use when users need to: (1) install Stellar CLI and Rust toolchain f...","description":"---\nname: setup-stellar-contracts\ndescription: \"Set up a Stellar/Soroban smart contract project with OpenZeppelin Contracts for Stellar. Use when users need to: (1) install Stellar CLI and Rust toolchain for Soroban, (2) create a new Soroban project, (3) add OpenZeppelin Stellar dependencies to Cargo.toml, or (4) understand Soroban import conventions and contract patterns for OpenZeppelin.\"\nlicense: AGPL-3.0-only\nmetadata:\n  author: OpenZeppelin\n---\n\n# Stellar Setup\n\n## Soroban/Stellar Development Setup\n\nInstall the Rust toolchain (v1.84.0+) and the Soroban WASM target:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nrustup target add wasm32v1-none\n```\n\nInstall the Stellar CLI:\n\n```bash\ncurl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh\n```\n\nCreate a new Soroban project:\n\n```bash\nstellar contract init my_project\n```\n\nThis creates a Cargo workspace with contracts in `contracts/*/`.\n\n## OpenZeppelin Dependencies\n\nLook up the current version from the [stellar-contracts repo](https://github.com/OpenZeppelin/stellar-contracts) before adding. Pin exact versions with `=` as the library is under active development.\n\nAdd OpenZeppelin crates to the **root** `Cargo.toml` under `[workspace.dependencies]`:\n\n```toml\n[workspace.dependencies]\nstellar-tokens = \"=<VERSION>\"\nstellar-access = \"=<VERSION>\"\nstellar-contract-utils = \"=<VERSION>\"\nstellar-macros = \"=<VERSION>\"\n```\n\nThen reference them in the **per-contract** `contracts/*/Cargo.toml`:\n\n```toml\n[dependencies]\nsoroban-sdk = { workspace = true }\nstellar-tokens = { workspace = true }\nstellar-access = { workspace = true }\nstellar-contract-utils = { workspace = true }\nstellar-macros = { workspace = true }\n```\n\nAvailable crates: `stellar-access`, `stellar-accounts`, `stellar-contract-utils`, `stellar-fee-abstraction`, `stellar-governance`, `stellar-macros`, `stellar-tokens`.\n\n> Only add the crates the contract actually uses. `stellar-macros` provides proc-macro attributes (for example, `#[when_not_paused]`, `#[only_owner]`, `#[derive(Upgradeable)]`) and is needed in most contracts.\n\n## Code Patterns\n\nImports use underscores as the crate root (Rust convention):\n\n```rust\nuse stellar_tokens::fungible::{Base, FungibleToken};\nuse stellar_tokens::fungible::burnable::FungibleBurnable;\nuse stellar_access::ownable::Ownable;\nuse stellar_contract_utils::pausable::Pausable;\nuse stellar_macros::when_not_paused;\n```\n\nContracts use `#[contract]` on the struct and `#[contractimpl]` on the impl block (from `soroban_sdk`):\n\n```rust\nuse soroban_sdk::{contract, contractimpl, Env};\n\n#[contract]\npub struct MyToken;\n\n#[contractimpl]\nimpl MyToken {\n    // Implement trait methods here\n}\n```\n\nTrait implementations are separate `impl` blocks per trait (e.g., `FungibleToken`, `Pausable`). Guard macros like `#[when_not_paused]` and `#[only_owner]` decorate individual functions.\n\n## Platform Notes\n\n- **Read operations are free in Stellar.** Optimize for minimizing writes; reads and computation are cheap. Prefer clean, readable code over micro-optimizations.\n- **Instance storage TTL extension is the developer's responsibility.** The OpenZeppelin library handles TTL extension for other storage entries, but contracts must extend their own `instance` storage entries to prevent expiration.\n\n## Build & Test\n\nBuild the contract to WASM:\n\n```bash\nstellar contract build\n```\n\nThis is a shortcut for `cargo build --target wasm32v1-none --release`. Output appears in `target/wasm32v1-none/release/`.\n\nRun tests:\n\n```bash\ncargo test\n```\n\n> `soroban-sdk` testutils are automatically enabled for in-crate unit tests.\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":675,"installsAllTime":25,"installsCurrent":1,"stars":0,"versions":3},"createdAt":1773554341033,"updatedAt":1779000017737},"latestVersion":{"version":"1.0.1","createdAt":1773929751433,"changelog":"Fix display name from probe to proper title","license":"MIT-0"},"metadata":null,"owner":{"handle":"samledger67-dotcom","userId":"s17e6161jqcyaq82bkvewk1rz583ndyf","displayName":"samledger67-dotcom","image":"https://avatars.githubusercontent.com/u/261800271?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089985549}}