skills.rest
OpenZeppelin
OpenZeppelinOFFICIAL
Explore all skills by this author →
WebsiteGitHub

upgrade-stellar-contracts

Upgrade Soroban smart contracts with WASM replacement and migration workflows.

203|28|Updated Feb 5, 2026
Search Tags:#migration#upgrade#wasm#access-control#soroban#stellar#storage-compatibility
One-click install
npx skills add https://github.com/OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: upgrade-stellar-contracts
Source: https://github.com/OpenZeppelin/openzeppelin-skills/tree/main/skills/upgrade-stellar-contracts
Command: npx skills add https://github.com/OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Helps developers and auditors perform safe upgrades of Soroban (Stellar) smart contracts by guiding WASM binary replacement, storage migration, and access-control checks to avoid accidental state corruption or loss of upgradeability.

Core Features & Use Cases

  • WASM binary upgrades: Use derive macros to replace contract WASM while preserving on-chain storage.
  • Upgrade-and-migrate support: Provide UpgradeableMigratable patterns and an Upgrader wrapper to achieve atomic upgrade-and-migrate flows.
  • Safety guidance and versioning: Explain storage key compatibility rules, authorization requirements, and embedding crate versions into WASM metadata for tracking.
  • Use case: Test deploying V1 locally, write state, upgrade to V2 with migration data, and verify storage and access control on a Soroban testnet.

Quick Start

Upgrade a deployed Soroban contract to a new WASM version on a local testnet, run the required migration with an authorized operator, and verify storage reads after the upgrade.

Frequently Asked Questions about upgrade-stellar-contracts

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I upgrade a Soroban smart contract without losing on-chain state?▼

To upgrade a Soroban smart contract without losing state, replace the WASM binary using derive macros to preserve storage while coordinating migration workflows that maintain storage key compatibility.

What is the best way to run a schema migration when upgrading a Stellar contract?▼

The best way to run a schema migration is using an UpgradeableMigratable pattern with an Upgrader wrapper to achieve atomic upgrade-and-migrate flows guarded by access control.

Does upgrading a Soroban contract WASM binary invoke the constructor?▼

No, upgrading a Soroban contract WASM binary does not invoke the constructor. You must manually test storage consistency because constructors are bypassed during the replacement process.

How do I enforce access control when replacing a Stellar contract WASM?▼

You enforce access control during a Stellar contract WASM replacement by satisfying authorization requirements through an authorized operator before executing the upgrade and migration workflows.

Can I track contract versions when deploying WASM upgrades on Soroban?▼

Yes, you can track contract versions on Soroban by embedding crate metadata versions into the WASM binary metadata, allowing you to monitor deployed contract versions throughout the upgrade lifecycle.

What are the limitations of binary-only upgrades for Soroban contracts?▼

Binary-only upgrades for Soroban contracts require manual storage consistency testing and do not invoke constructors, meaning you must verify storage key compatibility and access control independently.

Related Skills

Explore More Software Engineering Skills→
OpenZeppelinOpenZeppelin
203

setup-stellar-contracts

Set up Soroban/Stellar smart contract projects with OpenZeppelin Rust crate dependencies.

Official
Intermediate
baroliverabarolivera

upgrade-stellar-contracts

Implement upgradeable Soroban Stellar contracts with OpenZeppelin tooling.

Community
Advanced
iamcapoteiamcapote

upgrade-stellar-contracts

Automate secure WASM upgrades for Stellar Soroban contracts.

Community
Advanced
SanctifiedOpsSanctifiedOps
3

upgrade-vs-immutable-decision

Decide upgrade or immutable posture for Solana programs with governance and risk mapping.

Community
Advanced