skills.rest
phpmac
phpmacCOMMUNITY
Explore all skills by this author →
GitHub

upgrade-stellar-contracts

Upgrade Soroban contracts with OpenZeppelin's upgradeable module and Upgrader pattern.

Updated Aug 27, 2026
Search Tags:#migration#upgrade#contract#soroban#stellar#upgradeable#upgrader
One-click install
npx skills add https://github.com/phpmac/foundry --skill upgrade-stellar-contracts-phpmac
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: upgrade-stellar-contracts
Source: https://github.com/phpmac/foundry/tree/main/.agents/skills/upgrade-stellar-contracts
Command: npx skills add https://github.com/phpmac/foundry --skill upgrade-stellar-contracts-phpmac

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Soroban contracts require robust upgrade mechanics to preserve storage layout, support atomic upgrades, and enforce proper authorization. This guide documents how to use OpenZeppelin's upgradeable module and the Upgrader pattern to achieve safe, auditable upgrades with optional migrations.

Core Features & Use Cases

  • Upgradeable contracts via derive macros that embed version metadata and provide upgrade entry points.
  • Atomic upgrade-and-migrate using an Upgrader contract to ensure migration runs after the upgrade.
  • Clear guidance on storage compatibility and rollback considerations for Soroban WASM contracts.

Quick Start

Follow the Upgrader pattern to perform an atomic upgrade and optional migration for a Soroban contract.

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 Soroban contracts without breaking storage layout?▼

Perform atomic Soroban contract upgrades by integrating OpenZeppelin's upgradeable module to use derive macros. This embeds version metadata, provides upgrade entry points, and maintains storage compatibility to prevent data corruption during native WASM contract upgrades.

What is the Upgrader pattern for atomic contract migrations on Stellar?▼

The Upgrader pattern is an atomic contract deployment method that ensures a state migration runs immediately after a Stellar WASM upgrade. It bundles the upgrade and optional migration into a single transaction to guarantee storage consistency.

Does OpenZeppelin's upgradeable module support state migration for Stellar contracts?▼

Yes, OpenZeppelin's upgradeable module supports optional state migration for Stellar contracts. It enables atomic upgrade-and-migrate patterns using an Upgrader contract, applying migration hooks to manage storage compatibility safely during WASM upgrades.

How do I track versions when upgrading Soroban WASM contracts?▼

Track Soroban WASM contract versions by utilizing cargo metadata integrated through OpenZeppelin's upgradeable module. Derive macros automatically embed this version metadata into the contract, providing auditable version tracking across upgrades.

What are the limitations of performing native WASM upgrades on Soroban?▼

Native WASM upgrades on Soroban require explicit authorization checks and careful storage compatibility management. Without using an Upgrader contract for atomic deployment, state migrations may fail or corrupt data if storage layouts are incompatible.

Related Skills

Explore More Software Engineering Skills→
iamcapoteiamcapote

upgrade-stellar-contracts

Automate secure WASM upgrades for Stellar Soroban contracts.

Community
Advanced
baroliverabarolivera

upgrade-stellar-contracts

Implement upgradeable Soroban Stellar contracts with OpenZeppelin tooling.

Community
Advanced
pproencapproenca

python-project

Set up Python projects and manage dependencies with uv.

Community
Intermediate
OpenZeppelinOpenZeppelin
203

upgrade-stellar-contracts

Upgrade Soroban smart contracts with WASM replacement and migration workflows.

Official
Intermediate