Proxy Pattern

The Proxy Contract is the permanent, user-facing address that holds the contract's state and storage. It delegates all function calls to the current Implementation Contract using a delegatecall. Users and other contracts interact directly with the Proxy, which remains immutable, ensuring a persistent contract address and data.

The Implementation Contract (or Logic Contract) contains the executable code and business logic. It is a standard smart contract but is never called directly. When the Proxy delegates a call, the logic runs in the Proxy's storage context. This separation allows developers to deploy a new Implementation Contract to upgrade functionality without migrating state.

A crucial component that manages the link between the Proxy and Implementation. It typically involves:

• An Admin or governance contract with permissions to upgrade.
• A function (e.g., upgradeTo(address newImplementation)) that updates the Proxy's reference.
• This mechanism enables non-breaking upgrades, where new features or bug fixes can be deployed while preserving all existing user data and balances.

A strict design constraint in upgradeable contracts. The storage layout (the order and type of state variables) must remain compatible between old and new Implementation Contracts. Incompatible changes can lead to critical data corruption. Common solutions include:

• Using inherited storage contracts.
• Employing EIP-1967 standard storage slots for the implementation address.
• Tools like OpenZeppelin's StorageGap to reserve space for future variables.

A specific proxy variant that prevents function selector clashes between the proxy's admin functions and the implementation's logic. It uses a Proxy Admin contract to separate concerns:

• The admin address calls upgrade functions.
• All other addresses call the delegated logic.
• This prevents a malicious actor from invoking an admin function disguised as a logic function, a security issue in simpler proxies.

Defined by EIP-1822, UUPS is a proxy pattern where the upgrade logic is built into the Implementation Contract itself, not the Proxy. This makes proxies cheaper to deploy but requires each new implementation to contain the upgrade function. It shifts the responsibility (and gas cost) of maintaining upgradeability to the logic contract.

A storage collision occurs when the logic contract's variable layout conflicts with the proxy's storage slots, leading to critical data corruption. This is mitigated by using unstructured storage proxies. Furthermore, initializer functions replace constructors but must be protected from re-initialization attacks using access controls and state checks to prevent contract takeover.

A malicious logic contract can override the proxy's core administrative functions if it defines a function with the same 4-byte selector. For example, a function named admin() in the logic could clash with the proxy's own admin() function, allowing an attacker to hijack upgrade permissions. Proxies must use mechanisms like the EIP-1967 storage slot for admin addresses to prevent this.

If a logic contract's implementation can be made to call selfdestruct, it will destroy the logic contract itself, not the proxy. This bricks the proxy, permanently freezing all assets, as there is no code to delegate calls to. This risk is heightened if the logic contract accepts arbitrary delegate calls or uses external libraries.

The power to upgrade is a centralization risk. A compromised proxy admin private key allows an attacker to deploy malicious logic. Best practices include:

• Using a multi-signature wallet or DAO for upgrade authority.
• Implementing a timelock on upgrades, giving users time to exit if a malicious proposal is made.
• Clearly communicating upgrade processes to users.

The choice between Transparent Proxy and UUPS (EIP-1822) patterns has security trade-offs.

• Transparent Proxies: Admin logic is in the proxy. Safer from accidental clashing but larger gas overhead.
• UUPS Proxies: Upgrade logic is in the implementation. More gas-efficient but requires the implementation to be upgradeable and not self-destruct. A flawed UUPS implementation can permanently lose its upgrade capability.

Transparency is critical for user trust. For every upgrade:

• The new logic contract's source code must be verified on-chain (e.g., Etherscan).
• A comprehensive audit report from a reputable firm should be published.
• A diff report highlighting all code changes from the previous version should be made available to stakeholders.

A proxy implementation where the delegatecall logic is determined by the caller's address (msg.sender). It uses a ProxyAdmin contract to manage upgrades, separating user calls from admin calls. This prevents function selector clashes between the proxy and logic contract.

• Key Feature: Clear separation of user and admin functions.
• Common Use: Early OpenZeppelin upgradeable contract standard.

An upgrade pattern where the upgrade logic is embedded in the implementation contract itself, not the proxy. This makes the proxy contract smaller and cheaper to deploy.

• Key Feature: Upgrade function (upgradeTo) resides in the logic contract.
• Security Note: If the implementation is self-destructed or lacks upgrade function, the proxy becomes permanently frozen.

A pattern where multiple proxy contracts point to a single Beacon contract that stores the current implementation address. Updating the beacon automatically upgrades all dependent proxies.

• Use Case: Efficiently upgrading large numbers of similar contracts (e.g., NFT collections, user wallets).
• Efficiency: Single transaction updates many proxies.

A critical risk in upgradeable contracts where the storage layout of the new implementation contract does not align with the proxy's existing storage. Mismatches can corrupt critical data.

• Mitigation: Inherit from storage gap contracts, use tools like slither for analysis.
• Rule: Never modify the order or type of existing state variables.

A low-level EVM opcode that allows a contract to execute code from another contract while preserving the original contract's context (storage, msg.sender, msg.value). This is the core mechanism enabling all proxy patterns.

• How it works: Code is run from the logic contract, but state is written to the proxy's storage.

Replaces the constructor in upgradeable contracts. Since a proxy's constructor runs only once during its deployment, an initializer function (often initialize) is used to set up the logic contract's initial state.

• Security: Must be protected with an initializer modifier to prevent re-initialization attacks.
• Standard: Part of OpenZeppelin's Initializable contract.