Feat/postage decoupled

[0xCardiE]

PostageStamp Storage Decoupling Architecture

Overview

Separates PostageStamp into two contracts:

• PostageStampStorage - Immutable contract holding all BZZ tokens and batch data (deployed once, never upgraded)
• PostageStamp - Upgradeable logic contract containing business rules (versioned, can be replaced)

How It Works

Layer	Component	Description
Storage	PostageStampStorage	Permanent, holds tokens & batch data
Logic	PostageStamp v1, v2, v3...	Upgradeable business logic
Client	Bee v1.0, v1.1, v2.0...	Each version uses specific logic contract

Key Points

• Storage uses WRITER_ROLE (OpenZeppelin AccessControl) - multisig grants this to logic contracts
• Multiple logic contracts can have write access simultaneously (enables gradual network migration)
• Bee nodes are hardcoded to use a specific logic contract address
• Upgrades require only: deploy new logic → multisig grants WRITER_ROLE → release new Bee version

Benefits

• ✅ Zero token migration on upgrades
• ✅ Zero batch data migration on upgrades
• ✅ Old and new Bee versions can coexist during transition
• ✅ Rollback capability (revoke new version, keep old)
• ✅ Simple governance (only role management needed)

Upgrade Process

1. Deploy new PostageStamp logic (points to existing storage)
2. Multisig calls storage.grantRole(WRITER_ROLE, newLogicAddress)
3. Release new Bee version with new logic address
4. (Optional) Revoke old logic after full migration

[0xCardiE]

ROUND_LENGTH Parameter Change Verification

Context

ROUND_LENGTH changed from hardcoded 152 (Gnosis, 5s blocks) to configurable immutable set at deployment. Base uses 380 (2s blocks).

Goal: Maintain identical wall-clock timing across networks.

• Gnosis: 152 blocks × 5s = 760s per round
• Base: 380 blocks × 2s = 760s per round ✅

---

Checklist for Reviewers

1. Round Calculation

Files: PriceOracle.sol:197, Redistribution.sol:814

Same number of rounds per day on both networks:

• Gnosis: 86400s ÷ 760s = ~113 rounds/day
• Base: 86400s ÷ 760s = ~113 rounds/day ✅

2. Phase Durations

File: Redistribution.sol:821, 907, 935

Phase	Blocks	Gnosis Time	Base Time
Commit	0 → ROUND_LENGTH/4	38 × 5s = 190s	95 × 2s = 190s ✅
Reveal	ROUND_LENGTH/4 → ROUND_LENGTH/2	38 × 5s = 190s	95 × 2s = 190s ✅
Claim	ROUND_LENGTH/2 → end	76 × 5s = 380s	190 × 2s = 380s ✅

All phases have identical wall-clock duration.

3. Staking Wait Period (2 Rounds)

File: Redistribution.sol:305, 844

• Gnosis: 2 × 152 × 5s = 1520s (~25 min)
• Base: 2 × 380 × 2s = 1520s (~25 min) ✅

Same minimum staking wait time before participating.

4. Freeze Penalties

File: Redistribution.sol:560, 570

Freeze duration in blocks converted to time:

Depth	Gnosis Freeze	Base Freeze
16	152 × 65536 × 5s = 576 days	380 × 65536 × 2s = 576 days ✅
17	152 × 131072 × 5s = 1152 days	380 × 131072 × 2s = 1152 days ✅

Freeze penalties result in same wall-clock duration.

5. Last Block Prevention

File: Redistribution.sol:321

Still prevents commits on last block of commit phase (works with any ROUND_LENGTH value).

---

Configuration Values

Network	Chain ID	ROUND_LENGTH	minimumValidityBlocks	Block Time
Gnosis	100	152	17280 (24h)	5s
Base	8453	380	43200 (24h)	2s

Verification formula:

• ROUND_LENGTH_base = ROUND_LENGTH_gnosis × (gnosis_block_time / base_block_time)
• 380 = 152 × (5 / 2) = 152 × 2.5 ✅

---

Files Modified

• src/PriceOracle.sol - ROUND_LENGTH constant → immutable
• src/Redistribution.sol - ROUND_LENGTH constant → immutable
• src/PostageStamp.sol - minimumValidityBlocks now constructor param
• helper-hardhat-config.ts - Network-specific values added