feat: Versioned Registry Router + Upgradeable Proxies for All Core Contracts

[0xCardiE]

Summary

This PR introduces a versioned registry + router for Swarm storage-incentive contracts deployed behind upgradeable proxies. The registry publishes immutable version → implementation mappings (address + codehash + semver + deprecation). Clients (e.g. Bee) must not blindly trust “whatever sits behind this proxy today”; they pin a trusted version and verify chain state before (or during) protocol calls.

New since the original PR text:

• verifyImplementation(address implementation) on VersionedRegistryRouter — same implementation-level checks as inside verifyProxy, without requiring a registered proxyId (useful for tooling and pure reads).
• RegistryGuardedTransparentUpgradeableProxy — extends OZ TransparentUpgradeableProxy: on every non-admin fallback / receive, runs verifyProxy(registryProxyId) then delegates ( msg.sender unchanged ).
• pinnedExecute(address expectedImpl, bytes calldata data) on that guarded proxy — atomic path for Bee: verifies registry + requires address(this)’s current implementation equal to expectedImpl, then **delegatecall**s into the live implementation with data. If an operator upgrades the proxy to another registered build, a node still pinned to the old implementation reverts in the same transaction (PinMismatch).

---

Architecture (high level)

Registrar / deploy
    → registerRelease(versionId, semver, implementation, codehash)
    → ProxyAdmin upgrades proxy to that implementation (when adopted)
    → registerProxy(proxyId, proxyAddress) on router

Bee (policy)
    → locally: trusted versionId(s) / semver (from release, governance, or image config)
    → on-chain: read getRelease(versionId) → expected implementation + deprecations
    → optionally compare with live pointer (getProxyImplementation(proxyId) or EIP-1967 slot on proxy)

Bee (execution — recommended with guarded proxy)
    → tx to proxy: pinnedExecute(expectedImpl, abi.encodeCall(...))
    → expectedImpl := getRelease(trustedVersionId).implementation (cached / refreshed)

VersionedRegistryRouter.forward remains an optional path: selector-gated verifyProxy + call to the proxy. Implementations invoked via forward see msg.sender == router, so it is not a universal replacement for direct node calls.

---

On-chain API changes (VersionedRegistryRouter)

All view unless noted.

Function	Purpose
registerRelease(versionId, semver, implementation, codehash)	Registrar-only; immutable mapping (cannot overwrite version or reuse implementation).
deprecateRelease(versionId)	Deprecator-only; release stays readable but fails verification.
getRelease(versionId)	Returns ReleaseInfo: implementation, exists, deprecated, codehash, semver.
getVersionForImplementation(implementation)	Reverse lookup (bytes32 version id or zero).
verifyImplementation(implementation)	Reverts unless impl is registered, not deprecated, and extcodehash(implementation) matches stored codehash. Returns versionId on success.
registerProxy(proxyId, proxy)	Router-admin; proxy must use the same ProxyAdmin instance the router was constructed with.
deprecateProxy(proxyId)	Deprecator-only; verifyProxy / guarded fallback revert for this proxy id.
getProxyImplementation(proxyId)	Current implementation address behind the registered TransparentUpgradeableProxy.
verifyProxy(proxyId)	Reverts if proxy entry missing/deprecated, or current implementation fails verifyImplementation rules. Returns implementation on success.
verifyAllProxies()	Batch view; skips deprecated proxy entries.
forward(proxyId, data) / forwardUnchecked(proxyId, data)	Optional; see msg.sender caveat above.

---

On-chain API — RegistryGuardedTransparentUpgradeableProxy

Deploy args (in addition to OZ transparent proxy): VersionedRegistryRouter registry, bytes32 registryProxyId (must match registerProxy).

Path	Behaviour
Normal ABI call (fallback)	_beforeFallback: verifyProxy(registryProxyId) → delegate to _implementation().
pinnedExecute(expectedImpl, data)	verifyProxy → require(_implementation() == expectedImpl) → delegatecall(implementation, data). msg.sender in the implementation is the EOA / contract that called pinnedExecute. Payable; ETH forwards to implementation via delegate context rules.
Admin (upgradeTo, etc.)	OZ ifAdmin path — does not run pinnedExecute / pin checks on those admin functions. pinnedExecute reverts for msg.sender == proxy admin (AdminCannotPin).

Selector / collision note:
pinnedExecute uses bytes4(keccak256("pinnedExecute(address,bytes)")). Core implementations must not declare a public/external function with the same selector on the same proxy, or calls could be ambiguous (always route Bee traffic through pinnedExecute explicitly in the client).

---

What Bee nodes should do

1. Configuration (local, trusted)

• registryRouter contract address (per chain).
• trustedVersionId (or semver → versionId mapping) per product line — from governance, release notes, or baked into the Bee binary.
• Proxy addresses Bee already uses (PostageStamp, Redistribution, etc.).
• proxyId per core proxy as registered in VersionedRegistryRouter (same id used at deploy for that proxy row).

Pin the implementation Bee trusts:

expectedImpl = getRelease(trustedVersionId).implementation
require release.exists && !release.deprecated
require getVersionForImplementation(expectedImpl) == trustedVersionId   // consistency

Cache expectedImpl and refresh on config change / reconnect (registry rows are immutable, but deprecation can flip; verifyProxy / pinnedExecute still enforce “not deprecated” at call time).

2. Reads (no gas) — health / startup

Use eth_call:

• getRelease(trustedVersionId)
• verifyProxy(proxyId) — fails if proxy deprecated or implementation not registered / bad codehash / release deprecated
• Optionally getProxyImplementation(proxyId) and compare address equality with getRelease(trustedVersionId).implementation (redundant with a strict pin policy but good for diagnostics)

3. Writes (transactions) — recommended with guarded proxy

For each protocol call today you send to the proxy with calldata C, instead send one tx:

to := proxyAddress   // RegistryGuardedTransparentUpgradeableProxy instance
data := abi.encodeWithSelector(
    pinnedExecute.selector,
    expectedImpl,    // from step 1; must match pinned version’s implementation
    C                // same calldata you would have sent to the proxy for the core contract
)

• If ProxyAdmin repointed the proxy to another registered implementation, pinnedExecute reverts (PinMismatch) even though verifyProxy alone would pass for the new impl—because Bee did not update its pin.

4. Writes — legacy / stock TransparentUpgradeableProxy

Bee can keep direct C to the proxy. No on-chain atomic pin; mitigate with maturity, timelocks, and re-reads before sensitive batches, or migrate deploys to RegistryGuardedTransparentUpgradeableProxy.

5. Optional: verifyImplementation

Use when you have an implementation address from getProxyImplementation or an EIP-1967 storage read and want a single call that enforces registration + non-deprecated + codehash without a proxyId.

---

Security notes (short)

• Dual compromise (registrar + proxy admin): attacker can register malicious new versionId and point the proxy there. Pinning trustedVersionId + pinnedExecute(expectedImpl from that row) prevents accepting a different row’s implementation without the node updating config.
• Guarded fallback alone only enforces “current impl is some valid release”; pinnedExecute enforces “current impl is my expected address.”
• forward: convenient but wrong msg.sender for many core methods; use only where semantics allow.

---

Deploy / ops

• Default: deploy RegistryGuardedTransparentUpgradeableProxy for core proxies when Bee should use pinnedExecute.
• Constructor: (_logic, admin, initData, registry, registryProxyId); then registerProxy(registryProxyId, proxy) with the same id.
• Register registerRelease before or when adopting an implementation; upgrade order should avoid long windows where the proxy points at unregistered bytecode (guarded proxy reverts all user calls until registered).

---

Tests

• VersionedRegistryRouter tests cover registry, verifyProxy, verifyImplementation, forward, roles, invariants, RegistryGuardedTransparentUpgradeableProxy fallback paths, and pinnedExecute (success, PinMismatch, registry failure, admin rejection, bubbled revert).
• Full repo: run npx hardhat test after merge (exact counts depend on branch).

---

Test plan (PR checklist)

• Full Hardhat suite green
• Deploy scripts: optional switch to RegistryGuardedTransparentUpgradeableProxy + document proxyId / registerProxy ordering
• Bee: implement pinnedExecute Tx path + config for trustedVersionId / expectedImpl
• Document pinnedExecute selector and no collision rule for new implementation ABIs
• Etherscan / explorer verification for new proxy type