setup-stellar-contracts

Q: How do I install setup-stellar-contracts?

Run npx skills add https://github.com/openzeppelin/openzeppelin-skills --skill setup-stellar-contracts in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/setup-stellar-contracts/ (personal) or .claude/skills/setup-stellar-contracts/ (project).

by openzeppelinBusiness & Finance

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.

Installs: 281
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/openzeppelin/openzeppelin-skills --skill setup-stellar-contracts

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads setup-stellar-contracts automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Stellar Setup

Soroban/Stellar Development Setup

Install the Rust toolchain (v1.84.0+) and the Soroban WASM target:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32v1-none

Install the Stellar CLI:

curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh

Create a new Soroban project:

stellar contract init my_project

This creates a Cargo workspace with contracts in contracts/*/.

OpenZeppelin Dependencies

Look up the current version from the stellar-contracts repo before adding. Pin exact versions with = as the library is under active development.

Add OpenZeppelin crates to the root Cargo.toml under [workspace.dependencies]:

[workspace.dependencies]
stellar-tokens = "=<VERSION>"
stellar-access = "=<VERSION>"
stellar-contract-utils = "=<VERSION>"
stellar-macros = "=<VERSION>"

Then reference them in the per-contract contracts/*/Cargo.toml:

[dependencies]
soroban-sdk = { workspace = true }
stellar-tokens = { workspace = true }
stellar-access = { workspace = true }
stellar-contract-utils = { workspace = true }
stellar-macros = { workspace = true }

Available crates: stellar-access, stellar-accounts, stellar-contract-utils, stellar-fee-abstraction, stellar-governance, stellar-macros, stellar-tokens.

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.

Code Patterns

Imports use underscores as the crate root (Rust convention):

use stellar_tokens::fungible::{Base, FungibleToken};
use stellar_tokens::fungible::burnable::FungibleBurnable;
use stellar_access::ownable::Ownable;
use stellar_contract_utils::pausable::Pausable;
use stellar_macros::when_not_paused;

Contracts use #[contract] on the struct and #[contractimpl] on the impl block (from soroban_sdk):

use soroban_sdk::{contract, contractimpl, Env};

#[contract]
pub struct MyToken;

#[contractimpl]
impl MyToken {
    // Implement trait methods here
}

Trait implementations are separate impl blocks per trait (e.g., FungibleToken, Pausable). Guard macros like #[when_not_paused] and #[only_owner] decorate individual functions.

Platform Notes

Read operations are free in Stellar. Optimize for minimizing writes; reads and computation are cheap. Prefer clean, readable code over micro-optimizations.
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.

Build & Test

Build the contract to WASM:

stellar contract build

This is a shortcut for cargo build --target wasm32v1-none --release. Output appears in target/wasm32v1-none/release/.

Run tests:

cargo test

soroban-sdk testutils are automatically enabled for in-crate unit tests.

FAQ

What does the setup-stellar-contracts skill do?

How do I install setup-stellar-contracts?

Run npx skills add https://github.com/openzeppelin/openzeppelin-skills --skill setup-stellar-contracts in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/setup-stellar-contracts/ (personal) or .claude/skills/setup-stellar-contracts/ (project).

Which AI agents can use setup-stellar-contracts?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is setup-stellar-contracts safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains setup-stellar-contracts?

It is published by openzeppelin in openzeppelin/openzeppelin-skills. It has 281 recorded installs.