# upgrade-stellar-contracts

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 281 installs · ★ 225 repo stars
- Author: OpenZeppelin
- License: AGPL-3.0-only · policy=link-only · description only; the file stays with the author
- Source: https://github.com/OpenZeppelin/openzeppelin-skills/tree/HEAD/skills/upgrade-stellar-contracts/SKILL.md
- Updated: 2026-10-19
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/upgrade-stellar-contracts

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/upgrade-stellar-contracts/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/upgrade-stellar-contracts/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/upgrade-stellar-contracts/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/upgrade-stellar-contracts/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install OpenZeppelin/openzeppelin-skills skills/upgrade-stellar-contracts
```

2. **Manually: put the files in place**
- File: `.github/skills/upgrade-stellar-contracts/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/OpenZeppelin/openzeppelin-skills --path skills/upgrade-stellar-contracts
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/upgrade-stellar-contracts/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/OpenZeppelin/openzeppelin-skills/tree/HEAD/skills/upgrade-stellar-contracts/SKILL.md

## When to use it
- 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
- 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

## Similar
- [OpenZeppelin Stellar Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-stellar-contracts.md) — MCP server
- [Xahau MCP](https://affpapa.org/en/nevibecode/mcp/xahau-mcp.md) — MCP server · ★ 6 repo stars
- [m11-ecosystem](https://affpapa.org/en/nevibecode/skills/m11-ecosystem.md) — skill · 3700 installs
- [turso-db](https://affpapa.org/en/nevibecode/skills/turso-db.md) — skill · 554 installs
- [genlayer-intelligent-contracts](https://affpapa.org/en/nevibecode/skills/genlayer-intelligent-contracts.md) — skill · ★ 7165 repo stars
- [cloudflare-workers-multi-lang](https://affpapa.org/en/nevibecode/skills/cloudflare-workers-multi-lang.md) — skill · 317 installs

From the same set: [openzeppelin/openzeppelin-skills](https://affpapa.org/en/nevibecode/by/openzeppelin/openzeppelin-skills.md) — 5 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
