Upgrade Stylus smart contracts using OpenZeppelin proxy patterns on Arbitrum. Use when users need to: (1) make Stylus Rust contracts upgradeable with UUPS or Beacon proxies, (2) understand Stylus-specific proxy mechanics (logic_flag, WASM reactivation), (3) integrate UUPSUpgradeable with access control, (4) ensure storage compatibility across upgrades, or (5) test upgrade paths for Stylus contracts.
Stylus contracts run on Arbitrum as WebAssembly (WASM) programs alongside the EVM. They share the same state trie, storage model, and account system as Solidity contracts. Because of this, EVM proxy patterns work identically for Stylus — a Solidity proxy can delegate to a Stylus implementation and vice versa.
| Stylus | Solidity | |
|---|---|---|
| Proxy mechanism | Same — delegatecall to implementation contract | delegatecall to implementation contract |
| Storage layout | #[storage] fields map to the same EVM slots as equivalent Solidity structs | Sequential slot allocation per Solidity rules |
| EIP standards | ERC-1967 storage slots, ERC-1822 proxiable UUID | Same |
| Context detection | logic_flag boolean in a unique storage slot (no immutable support) | address(this) stored as immutable |
| Initialization | Two-step: constructor sets logic_flag, then set_version() via proxy | Constructor + initializer via proxy |
| Reactivation | WASM contracts must be reactivated every 365 days or after a Stylus protocol upgrade | Not applicable |
Existing Solidity contracts can upgrade to a Stylus (Rust) implementation via proxy patterns. The #[storage] macro lays out fields in the EVM state trie identically to Solidity, so storage slots line up when type definitions match.
OpenZeppelin Contracts for Stylus provides three proxy patterns:
| Pattern | Key types | Best for |
|---|---|---|
| UUPS | UUPSUpgradeable, IErc1822Proxiable, Erc1967Proxy | Most projects — upgrade logic in the implementation, lighter proxy |
| Beacon | BeaconProxy, UpgradeableBeacon | Multiple proxies sharing one implementation — updating the beacon upgrades all proxies atomically |
| Basic Proxy | Erc1967Proxy, Erc1967Utils | Low-level building block for custom proxy patterns |
The implementation contract composes UUPSUpgradeable in its #[storage] struct alongside access control (e.g., Ownable). Integration requires:
UUPSUpgradeable (and access control) as fields in the #[storage] structself.uups.constructor() and initialize access control in the constructorinitialize calling self.uups.set_version() — invoked via proxy after deploymentIUUPSUpgradeable — upgrade_to_and_call guarded by access control, upgrade_interface_version delegating to self.uupsIErc1822Proxiable — proxiable_uuid delegating to self.uupsThe proxy contract is a thin Erc1967Proxy with a constructor that takes the implementation address and initialization data, and a #[fallback] handler that delegates all calls.
Deploy the proxy with set_version as the initialization call data. Use cargo stylus deploy or a deployer contract. The initialization data is the ABI-encoded setVersion call:
let data = MyContractAbi::setVersionCall {}.abi_encode();
// Pass `data` as the proxy constructor's second argument at deployment time.
Multiple BeaconProxy contracts point to a single UpgradeableBeacon that stores the current implementation address. Updating the beacon upgrades all proxies in one transaction.
Stylus does not support the immutable keyword. Instead of storing __self = address(this), UUPSUpgradeable uses a logic_flag boolean in a unique storage slot:
logic_flag = true in its own storage.delegatecall), the proxy's storage does not contain this flag, so it reads as false.only_proxy() checks this flag to ensure upgrade functions can only be called through the proxy, not directly on the implementation.only_proxy() also verifies that the ERC-1967 implementation slot is non-zero and that the proxy-stored version matches the implementation's VERSION_NUMBER.
Examples: See the
examples/directory of the rust-contracts-stylus repository for full working integration examples of UUPS, Beacon, and related patterns.
Upgrade functions must be guarded with access control. OpenZeppelin's Stylus contracts do not embed access control into the upgrade logic itself — you must add it in upgrade_to_and_call:
fn upgrade_to_and_call(&mut self, new_implementation: Address, data: Bytes) -> Result<(), Vec<u8>> {
self.ownable.only_owner()?; // or any access control check
self.uups.upgrade_to_and_call(new_implementation, data)?;
Ok(())
}
Common options:
Stylus #[storage] fields are laid out in the EVM state trie identically to Solidity. The same storage layout rules apply when upgrading:
One difference from Solidity: nested structs in Stylus #[storage] (e.g., composing Erc20, Ownable, UUPSUpgradeable as fields) are laid out with each nested struct starting at its own deterministic slot. This is consistent with regular struct nesting in Solidity, but not with Solidity's inheritance-based flat layout where all inherited variables share a single sequential slot range.
logic_flag and any implementation-only state. It runs once at implementation deployment.set_version() must be called via the proxy (during deployment or via upgrade_to_and_call) to write the VERSION_NUMBER into the proxy's storage.set_version() in it.The UUPS implementation enforces three safety checks:
upgrade_to_and_call (e.g., self.ownable.only_owner())only_proxy() reverts if the call is not via delegatecallproxiable_uuid() must return the ERC-1967 implementation slot, confirming UUPS compatibilityStylus WASM contracts must be reactivated once per year (365 days) or after any Stylus protocol upgrade. Reactivation can be done using cargo-stylus or the ArbWasm precompile. If a contract is not reactivated, it becomes uncallable. This is orthogonal to proxy upgrades but must be factored into maintenance planning.
Before upgrading a production contract:
upgrade_to_and_call, and verify that all existing state reads correctlyupgrade_to_and_callVERSION_NUMBER is incremented in the new implementation