Upgrade Stellar Contracts

This helps you implement native WASM upgrades for Stellar Soroban contracts using OpenZeppelin's upgradeable module. You get two derive macros: Upgradeable for simple bytecode replacement and UpgradeableMigratable when you need to modify storage during the upgrade. The atomic upgrade-and-migrate pattern using an Upgrader contract is clever since Soroban's protocol-level upgrade mechanism only applies the new implementation after the current call completes. One thing to watch: there's no automatic storage compatibility checking, so you can easily corrupt state if you rename keys or change value types. The module handles the upgrade flow but deliberately leaves access control to you, which means you need to wire in Ownable or similar yourself.

skills.sh installs: 271
GitHub stars: 222
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add openzeppelin/openzeppelin-skills --skill upgrade-stellar-contracts --agent claude-code

Installs into .claude/skills of the current project.

Files

Stellar Upgrades

Soroban Upgrade Model
Using the OpenZeppelin Upgradeable Module
Access Control
Upgrade Safety

Soroban Upgrade Model

Soroban contracts are mutable by default. Mutability refers to the ability of a smart contract to modify its own WASM bytecode, altering its function interface, execution logic, or metadata. Soroban provides a built-in, protocol-level mechanism for contract upgrades — no proxy pattern is needed.

A contract can upgrade itself if it is explicitly designed to do so. Conversely, a contract becomes immutable simply by not provisioning any upgrade function. This is fundamentally different from EVM proxy patterns:

SKILL.md on GitHub