Beacon Proxy

OpenZeppelin-based beacon and beacon proxy contracts with optional versioning and opt-in upgrades.

Contracts

Classic (single implementation)

• UpgradeableBeaconExtended – Extends OZ UpgradeableBeacon with implementationVersion and ImplementationUpgraded(..., newVersion) event.
• BeaconProxyExtended – Extends OZ BeaconProxy with beaconAddress() and implementationAddress() view functions.

Versioned / opt-in (Safe-like)

Proxies pin a version and resolve implementation as beacon.implementation(version). The beacon publishes new versions; each proxy opts in via upgradeToVersion(newVersion) (proxy owner only).

• VersionedUpgradeableBeacon

  • Stores one Version record per version: mapping(uint64 => Version) where Version { address implementation; bool isBreakingChange; bool deprecated; bytes32 storageLayoutHash; }. The constructor validates version 1 the same way addVersion validates later versions: non-zero implementation with deployed code, and a non-zero storage-layout hash.
  • Views: latestVersion(), implementation(version), isVersionAvailable(version), getVersion(version) (full Version record), getVersions(), getVersionsCompatibility(fromVersion, toVersion).
  • Admin: addVersion(version, implementation, storageLayoutHash, isBreakingChange) (version must be strictly greater than latestVersion; implementation must be a deployed contract — reverts with ImplementationNotContract otherwise; storageLayoutHash must be non-zero; reverts with StorageLayoutUnchanged if isBreakingChange is true but storageLayoutHash equals the current latest version's — an unchanged layout can't be a breaking change), deprecateVersion(version) (reverts with VersionAlreadyDeprecated if already deprecated — a no-op call that would otherwise re-emit VersionDeprecated).
  • Upgrade: upgradeProxyToVersion(proxy, version, safeUpgrade) (proxy owner only). Reverts with SameVersion if version equals the proxy's current version — a same-value write that would otherwise re-emit ProxyUpgraded. When safeUpgrade is true, the call also reverts (UnsafeUpgrade) unless getVersionsCompatibility(currentVersion, version) is true.
  • Ownership: transferProxyOwnership(proxy, newOwner) (proxy owner only) reverts with SameOwner if newOwner is already the current owner — a same-value write that would otherwise re-emit ProxyOwnerChanged.
  • Compatibility: getVersionsCompatibility(fromVersion, toVersion) only inspects the boundary version being moved onto — the target when upgrading (toVersion > fromVersion), the source when downgrading (toVersion < fromVersion) — not every version in between. A version's isBreakingChange flag already captures its diff against its own predecessor, so this is sufficient without walking the range.
  • Events: VersionAdded(version, implementation, storageLayoutHash, isBreakingChange), VersionDeprecated(version).

• VersionedBeaconProxy

  • Storage: beacon (ERC-1967 slot), pinned uint64 version, proxy owner.
  • Views: beacon(), version(), proxyOwner().
  • Actions: upgradeToVersion(newVersion) (only proxy owner), transferProxyOwnership(newOwner).
  • Events: ProxyUpgraded(oldVersion, newVersion, newImplementation), ProxyOwnerChanged(oldOwner, newOwner).

Versioned flow

1. Beacon admin publishes a new implementation: beacon.addVersion(v, impl, storageLayoutHash, isBreakingChange).
2. Proxies see beacon.latestVersion() and beacon.implementation(version).
3. Proxy owner chooses when to upgrade: beacon.upgradeProxyToVersion(proxy, targetVersion, safeUpgrade).

This allows staged rollouts, per-tenant governance, and adoption only after verification.

Usage

// Deploy versioned beacon with initial implementation (version 1) and its storage-layout hash
VersionedUpgradeableBeacon beacon = new VersionedUpgradeableBeacon(owner, implV1, hashV1);

// Add versions (beacon owner): storage-layout hash + whether the version is a breaking change
beacon.addVersion(2, implV2, hashV2, false); // non-breaking
beacon.addVersion(3, implV3, hashV3, true);  // breaking storage change

// Deploy proxy (pins the latest version at registration), with init data and owner
bytes memory initData = abi.encodeWithSelector(MockImplementation.initialize.selector, "MyName");
VersionedBeaconProxy proxy = new VersionedBeaconProxy(address(beacon), initData, proxyOwner);

// Later: proxy owner opts in to a new version. safeUpgrade=true reverts if the boundary version
// being moved onto (target when upgrading, source when downgrading) is flagged as breaking.
beacon.upgradeProxyToVersion(address(proxy), 2, true);

Tests

• pnpm test – runs tests/versioned-beacon-proxy.spec.ts (VersionedUpgradeableBeacon / VersionedBeaconProxy). The classic contracts (UpgradeableBeaconExtended, BeaconProxyExtended) have no tests yet.