upgrade-stylus-contracts

Name: upgrade-stylus-contracts
Availability: InStock
Author: OpenZeppelin

Apply EVM proxy patterns to upgrade Stylus smart contracts on Arbitrum.

203|28|Updated Feb 5, 2026

Search Tags:#proxy #upgrades #beacon #arbitrum #stylus #storage-compatibility #uups

Ready to run

npx skills add https://github.com/OpenZeppelin/openzeppelin-skills --skill upgrade-stylus-contracts

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: upgrade-stylus-contracts
Source: https://github.com/OpenZeppelin/openzeppelin-skills/tree/main/skills/upgrade-stylus-contracts
Command: npx skills add https://github.com/OpenZeppelin/openzeppelin-skills --skill upgrade-stylus-contracts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Provides actionable guidance to make Stylus (Rust) smart contracts upgradeable using established EVM proxy patterns so teams can perform implementation swaps without corrupting on-chain state or losing control of upgrades.

Core Features & Use Cases

Proxy Patterns: Explains UUPS, Beacon, and Erc1967 proxy models and when to apply each pattern for Stylus contracts.
Storage Compatibility: Details Stylus #[storage] layout rules, migration precautions, and the rule to only append fields to avoid slot collisions.
Access Control & Safety: Describes how to integrate Ownable or RBAC with upgrade_to_and_call, enforce proxy-context via logic_flag and VERSION_NUMBER, and validate proxiable UUIDs.
Operational Requirements: Covers initialization via set_version, testing upgrade paths on a devnet, and yearly WASM reactivation planning.
Use Case: Migrate an existing Solidity implementation to a Stylus implementation behind an Erc1967 proxy, verify storage alignment, and perform controlled upgrades with access control.

Quick Start

Upgrade a Stylus contract to a new UUPS implementation with access control and verify storage compatibility on a local Arbitrum devnet.

Frequently Asked Questions about upgrade-stylus-contracts

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

FAQPage Schema

How do I upgrade Stylus contracts on Arbitrum using proxy patterns?▼

To upgrade Stylus contracts on Arbitrum, apply EVM proxy patterns like UUPS, Beacon, or Erc1967 to safely swap implementation logic without corrupting on-chain state. You enforce proxy-context via logic_flag and VERSION_NUMBER, guard upgrade functions with access control, and verify storage layout compatibility before swapping implementations.

What is storage compatibility verification for Stylus Rust contracts?▼

Stylus storage compatibility verification checks that #[storage] layout rules are followed during contract upgrades to prevent slot collisions. The primary rule is to only append new fields to existing storage structs, ensuring that implementation swaps do not overwrite or misalign previously stored on-chain state.

When should I use UUPS versus Beacon proxies for Stylus contract upgrades?▼

Use UUPS proxies for Stylus upgrades when you want upgrade logic contained within the implementation contract itself, minimizing proxy size. Choose Beacon proxies when multiple Stylus contracts need to be upgraded simultaneously to the same new implementation through a single beacon contract.

Can I migrate an existing Solidity implementation to Stylus behind an Erc1967 proxy?▼

Yes, you can migrate a Solidity implementation to Stylus behind an Erc1967 proxy. This requires verifying storage alignment between EVM and Stylus layouts, enforcing proxy-context via logic_flag, and performing controlled upgrades using access control to manage the implementation swap safely.

Do I need to reactivate WASM for Stylus contracts annually?▼

Yes, Stylus contracts require annual WASM reactivation procedures to maintain operational status on Arbitrum. Planning for yearly WASM reactivation is a necessary operational requirement when managing upgradeable Stylus contracts to ensure the implementation logic remains active and callable on-chain.

How do I test Stylus contract upgrade paths safely?▼

Test Stylus contract upgrade paths safely by deploying to a local Arbitrum devnet first. Verify storage compatibility, validate proxiable UUIDs, enforce proxy-context via logic_flag and VERSION_NUMBER, and check access control on upgrade_to_and_call functions before executing upgrades on mainnet.