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

[0xCardiE]

Summary

This PR introduces a Versioned Registry + Router architecture for upgradeable proxy systems in the Swarm storage incentives contracts. The core idea: Bee nodes should not automatically trust new proxy implementations. Instead, they verify (version → implementation) mappings on-chain before interacting with the system.

What changed

• All 4 core contracts (PostageStamp, PriceOracle, StakeRegistry, Redistribution) are now deployed behind OpenZeppelin TransparentUpgradeableProxy with a shared DefaultProxyAdmin, across all networks (local, main, test, tenderly)
• New VersionedRegistryRouter contract (src/VersionedRegistryRouter.sol) — a single contract that combines:
  • Registry: immutable version → implementation mappings with codehash, semver, and deprecation support
  • Router/Guard: verifies proxy implementations are registered and non-deprecated before forwarding calls
  • Multi-proxy management: tracks all 4 proxy addresses, supports verifyAllProxies() batch verification
• Deploy scripts updated across all 4 networks to use proxies + initialize() instead of constructors, deploy the registry router, register all proxies, and register v1.0.0 releases with codehash verification
• 58 tests for VersionedRegistryRouter covering all registry, router, role, invariant, and end-to-end scenarios

How it works

┌──────────┐     ┌──────────────────────────┐     ┌───────────────────┐
│ Bee Node │────▶│ VersionedRegistryRouter   │────▶│ Proxy (e.g.       │
│          │     │                           │     │ PostageStamp)     │
│ "I only  │     │ 1. getProxyImplementation │     │                   │
│  trust   │     │ 2. Check version exists   │     │ ┌───────────────┐│
│  v1.0.0" │     │ 3. Check not deprecated   │     │ │Implementation ││
│          │     │ 4. Verify codehash        │     │ │  (logic)      ││
│          │     │ 5. Forward call           │     │ └───────────────┘│
└──────────┘     └──────────────────────────┘     └───────────────────┘
                          │
                 ┌────────┴─────────┐
                 │ Release Registry  │
                 │ v1.0.0 → 0xABC   │
                 │ v2.0.0 → 0xDEF   │
                 │ (deprecated)      │
                 └──────────────────┘

Security model:

• Proxy can still be upgraded on-chain by the ProxyAdmin owner
• Registry publishes which implementation belongs to which version
• Bee nodes independently decide which versions they accept (local allowlist)
• Unapproved upgrades become effectively unusable by the Bee network

Roles:

• REGISTRAR_ROLE — can register new releases
• DEPRECATOR_ROLE — can deprecate releases
• ROUTER_ADMIN_ROLE — can register proxies and configure selector routing
• DEFAULT_ADMIN_ROLE — can manage all roles

Key invariants:

1. One version → one implementation (immutable once registered)
2. One implementation → one version (no reuse)
3. Deprecated releases remain queryable but fail verification
4. Mappings are permanent — cannot be overwritten even after deprecation

Contract changes

All 4 core Solidity contracts were made proxy-compatible:

• Constructors replaced with initialize() functions (using OZ Initializable)
• immutable state variables converted to regular storage
• _disableInitializers() in constructor to prevent implementation initialization

Deploy pipeline (consistent across all networks)

000 → Token
001 → PostageStamp (proxy + initialize)
002 → PriceOracle (proxy + initialize)
003 → StakeRegistry (proxy + initialize)
004 → Redistribution (proxy + initialize)
005-008 → Role assignments (using keccak256 hashes, proxy-safe)
009 → Local data / env exports
010 → VersionedRegistryRouter + proxy registration + v1.0.0 releases
011 → Etherscan verification
012 → Multisig admin grants

Test improvements

• Witness caching: anchor-aware cache format that auto-detects seed changes and regenerates when needed
• Parallel witness mining: uses worker_threads across all CPU cores (~3 min vs ~16 min per trial)
• Interval mining fix: disabled phantom block mining from 010_deploy_cluster.ts during tests
• 216 tests passing in ~30 seconds (Stats test runs 100 trials from cached witnesses in ~9s)

Cleanup

• Removed isolated deploy/registry/ directory (superseded by integrated pipeline)
• Role scripts use keccak256('ROLE_NAME') instead of read() calls to avoid TransparentUpgradeableProxy: admin cannot fallback to proxy target errors

Test plan

• All 216 tests pass (npx hardhat test)
• Stats test: 100 trials, variance < 0.035, witnesses cached
• VersionedRegistryRouter: 58 tests covering registry, router, roles, invariants, end-to-end lifecycle
• Redistribution: claim-pot witnesses regenerated with anchor-aware caching
• Deploy scripts compile and execute correctly for hardhat network
• Deploy to testnet and verify contracts on Etherscan
• Verify Bee node can read registry and validate implementations