Skip to main content
skill CX Codex

upgrade-stellar-contracts — Claude Code skill

upgrade-stellar-contracts — a skill for upgrading Stellar/Soroban smart contracts with OpenZeppelin's upgradeable module. Use it to make contracts updatable, migrate storage data, or ensure compatibility across bytecode replacements.

AGPL-3.0-only 281 installs ★ 225 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a claude-code
Open on GitHub

What upgrade-stellar-contracts does

Soroban lets contracts upgrade their own WASM code through a protocol-level mechanism—no proxy contracts needed. The skill provides two patterns: Upgradeable for code-only updates and UpgradeableMigratable when storage must change too. Derive macros automatically set the version from Cargo.toml into WASM metadata per SEP-49.

For atomic upgrade-and-migrate in a single call, wrap both operations in an auxiliary Upgrader contract. When bytecode is replaced, the new contract's constructor does not run; initialization must happen via migration. Storage keys must remain stable—removing, renaming, or changing their types will corrupt state.

Authorization lives in your _require_auth implementation. Skipping this check exposes the contract to unauthorized code replacement. Leverage Ownable for single-owner access or AccessControl from the access package for role-based control.

What it helps with

  • make a Soroban contract updatable without a proxy pattern
  • migrate storage data during a contract upgrade
  • perform code upgrade and storage migration in one atomic transaction
  • maintain storage key compatibility across versions
  • test upgrade scenarios for Soroban contracts

Example prompts for the agent

  • Add #[derive(Upgradeable)] to your contract struct and implement authorization in _require_auth
  • Use UpgradeableMigratable to transform data during upgrade via the _migrate method
  • Wrap upgrade and migration in an Upgrader contract to execute them atomically

How to install upgrade-stellar-contracts

1Skills CLI (Vercel)

npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a claude-code

2Manually: put the files in place

~/.claude/skills/upgrade-stellar-contracts/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/upgrade-stellar-contracts/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about upgrade-stellar-contracts

How do I install upgrade-stellar-contracts in Claude Code?

Run npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a claude-code, then open ~/.claude/skills/upgrade-stellar-contracts/SKILL.md.

What does the upgrade-stellar-contracts skill do?

It simplifies Soroban contract updates. It provides derive macros for code-only upgrades, storage migration, and atomic upgrade-with-migration patterns in a single invocation.

When should I use Upgradeable vs. UpgradeableMigratable?

Use Upgradeable if you only need to replace the bytecode. Use UpgradeableMigratable if you must also transform data stored in the contract during the upgrade.

Similar skills

All skills for Backend and APIs →

From the same set5

Project sponsors

Companies that keep this analytics open