Decision records · ADR-016
ADR-016: UUPS upgradeability with ERC-7201 storage and a per-file optimizer setting
The reference token is a UUPS proxy with ERC-7201 namespaced storage, compiled with optimizer.runs = 1 so that it fits EIP-170 at 24,136 bytes.
- Document ID
- ADR-016
- Date
- 2026-09-21
- Source
- docs/adr/ADR-016.md
| Field | Value |
|---|---|
| ID | ADR-016 |
| Subject area | Implementation |
| Status | Accepted |
| Date | 2026-09-21 |
| Owners | A-REX Contributors |
| Related requirements | NFR-07, NFR-08 (SDD §3) |
| Supersedes / superseded by | — |
Context
During the alpha the reference token must be upgradeable, because production feedback will change it. It must also fit the EIP-170 limit, and it must not repeat the earlier code base's storage-layout comments that did not match the actual layout.
Issue
How should the reference token be made upgradeable, safe to upgrade and small enough to deploy?
Assumptions
- OpenZeppelin 5 uses ERC-7201 namespaced storage throughout.
- Upgrades go through governance with a timelock.
Constraints
- EIP-170 (24,576 bytes).
- Solidity 0.8.22, EVM
paris, OpenZeppelin 5.3.0 (C-05).
Alternatives considered
| Alternative | For | Against | Outcome |
|---|---|---|---|
| Transparent proxy | Well known | Extra admin contract; more gas per call | Rejected |
| Immutable token | Simplest trust model | No fixes during the alpha | Deferred (fine for third-party implementations) |
UUPS + ERC-7201 + optimizer.runs = 1 for ARexToken only | Safe layout, small proxy, fits the limit | Slightly higher runtime gas from the low optimizer setting | Accepted |
Decision
ARexToken is UUPS-upgradeable; _authorizeUpgrade requires UPGRADER_ROLE; state lives in the ERC-7201 namespace arex.storage.token; hardhat.config.js compiles this one file with optimizer.runs = 1.
Argument
UUPS keeps the upgrade logic in the implementation and the proxy minimal; ERC-7201 makes layout collisions structurally unlikely; a per-file optimizer setting fits the limit without changing the rest of the build.
Consequences
Positive
- Upgrades validated by the OpenZeppelin plugin.
- The token deploys on every EVM chain.
Negative
UPGRADER_ROLEis total power over the token.
Obligations it creates
UPGRADER_ROLEsits behind a multisig and a timelock.TokenStorageis append-only; validate before every upgrade.
Implementation and evidence
| What | Where |
|---|---|
| Implementation | contracts/reference/core/ARexToken.sol, hardhat.config.js |
| Upgrade authorization | test/standard/ARexToken.test.js: is upgradeable through UUPS by UPGRADER_ROLE only |
| Validated upgrade | test/standard/ImplementationGuide.test.js, step 15 |