ERC-1967 defines fixed storage slots where proxy contracts store the address of their implementation, admin and beacon. Those slots are what make today’s upgradeable contracts — transparent proxies, UUPS proxies and beacon proxies — interoperable with block explorers, tooling and auditors. For tokenization platforms that must fix bugs, add features or respond to new regulation over years, upgradeability is usually a requirement — and ERC-1967 is the foundation.
Key takeaways
- A proxy holds state and balances; it
delegatecalls to an implementation holding the logic. Upgrading swaps the implementation address. - ERC-1967 slots are derived from hashes (e.g.
keccak256("eip1967.proxy.implementation") - 1) to avoid colliding with application storage. - Patterns: Transparent (admin logic in proxy), UUPS (upgrade logic in implementation), Beacon (many proxies share one upgradeable implementation pointer).
- Upgrade powers must be governed: multisig + timelock + disclosure.
How proxies work
- Users call the proxy address — the token address investors know.
- The proxy reads the implementation address from the ERC-1967 slot and
delegatecalls it. - Logic runs in the proxy’s storage context, so balances persist across upgrades.
- An upgrade writes a new implementation address and emits
Upgraded(implementation).
Choosing a pattern
| Pattern | Pros | Cons | Typical use |
|---|---|---|---|
| Transparent | Clear separation of admin and users | Extra gas per call, separate ProxyAdmin | Conservative deployments |
| UUPS | Cheaper calls, upgrade logic can be removed later | Bricking risk if a bad implementation lacks upgrade function | Most new token deployments |
| Beacon | Upgrade many instances at once | Shared blast radius | Factories issuing one token per asset |
| Diamond (ERC-2535) | Modular, beyond size limit | Complexity | Large platforms |
Beacon proxies are well suited to tokenization factories — for example one token contract per property or per bond series sharing one upgradeable logic.
Governance safeguards
Upgradeability means someone can change the rules investors rely on. Regulators, auditors and investors will ask who that is. We recommend:
- Multisig ownership of upgrade rights, with signers across organisations where appropriate.
- Timelocks (e.g. 48–72 hours) so stakeholders can review upgrades before execution, with emergency paths clearly limited.
- Disclosure of upgrade powers in offering documents.
- On-chain governance records — our real estate platform recorded governance actions on-chain and kept contracts open to public verification.
- Upgrade audits — every new implementation is reviewed, including storage layout compatibility.
Common pitfalls
- Storage layout collisions: never reorder or remove state variables; append only, or use namespaced storage (ERC-7201).
- Uninitialised implementations: call
_disableInitializers()in constructors so attackers cannot initialise the logic contract. - Constructors don’t run in proxies: use initialiser functions guarded against re-initialisation.
- Selfdestruct / delegatecall in logic: avoid; they can brick proxies.
- Losing upgrade rights: in UUPS, an implementation without
upgradeToends upgradeability forever.
The standard storage slots
| Slot | Derivation | Stores |
|---|---|---|
| Implementation | bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1) |
Logic contract address |
| Admin | bytes32(uint256(keccak256("eip1967.proxy.admin")) - 1) |
Proxy admin (transparent pattern) |
| Beacon | bytes32(uint256(keccak256("eip1967.proxy.beacon")) - 1) |
Beacon address (beacon pattern) |
Events Upgraded, AdminChanged and BeaconUpgraded record every change, which monitoring systems should alert on.
A governed upgrade workflow
- Propose: engineering prepares the new implementation, tests, storage-layout diff and audit report.
- Review: risk, compliance and (where relevant) the transfer agent approve.
- Queue: multisig submits the upgrade to a timelock; investors and partners are notified.
- Wait: the timelock delay elapses (e.g. 48–72 hours), giving stakeholders time to react.
- Execute: the upgrade is executed; monitoring confirms the new implementation address.
- Verify: source is verified on the explorer; release notes are published.
Upgradeable tokens with immutable guarantees
Some issuers want flexibility without unlimited power. Options:
- Make critical invariants immutable in a non-upgradeable core and keep rules in upgradeable modules.
- Renounce upgrade rights after a stabilisation period.
- Require investor consent for certain upgrades through governance votes.
Frequently asked questions
Usually yes, with strong governance. Immutable contracts are simpler to trust but cannot respond to bugs or regulatory change; some issuers choose immutable tokens with upgradeable compliance modules.
In transparent proxies, upgrade logic lives in the proxy and admin calls are routed separately. In UUPS, the implementation contains the upgrade function, making calls cheaper.
Yes — because ERC-1967 slots are standard, explorers detect proxies and display the implementation’s verified source.
Technically a malicious upgrade could. That is why upgrade rights need multisig control, timelocks and audits.
A beacon proxy asks a separate beacon contract for its implementation, so many proxies can be upgraded together; a transparent proxy stores its own implementation address.
Not in place. You would migrate balances to a new proxied token.
NUVZ is the RWA and Web3 engineering brand of ESS ENN Associates (est. 1993). Our team has designed and shipped tokenization platforms for real estate, education loans, solar PPAs, energy, carbon credits, bank deposits and trade documents. About us · Case studies
This article is for general information only and is not legal, tax or investment advice. Token standards evolve — always confirm the current status of an ERC at eips.ethereum.org and take advice from qualified counsel in each jurisdiction before issuing tokens.
