OpenZeppelin Upgrades

To be upgrade safe, a contract must follow specific rules to ensure compatibility with the proxy pattern:

1. No Constructors: Contracts cannot use constructor. Instead, use an initialize function. It is highly recommended to use the Initializable base contract from @openzeppelin/contracts-upgradeable and the initializer modifier to ensure the function can only be called once.
2. Avoid Dangerous Operations: For security and compatibility, contracts should avoid using selfdestruct or delegatecall unless they are specifically guarded.
3. Storage Layout Compatibility: When upgrading, you can change the code but cannot modify existing state variables. You may only append new state variables after the existing ones to maintain a compatible storage layout.

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract MyContract is Initializable {
  uint256 value;

  function initialize(uint256 initialValue) public initializer {
    value = initialValue;
  }
}

The plugins automate the management of upgradeable deployments through high-level functions.

deployProxy workflow:

1. Validation: Checks that the implementation contract is upgrade safe.
2. Implementation Deployment: Deploys the implementation contract. The Hardhat plugin optimizes this by checking if a contract with the same bytecode is already deployed to avoid redundant deployments.
3. Proxy Setup: Creates the proxy contract and initializes it, deploying a proxy admin if required.

upgradeProxy workflow:

1. Validation: Ensures the new implementation is upgrade safe and compatible with the existing implementation.
2. Implementation Deployment: Deploys the new implementation contract (skipping if bytecode already exists in Hardhat).
3. Proxy Upgrade: Updates the proxy to point to the new implementation.

A common issue in proxy patterns is a function clash, where a function in the logic contract has the same name and signature as a function in the proxy (e.g., both have upgradeTo(address)).

OpenZeppelin Upgrades uses the Transparent Proxy pattern to resolve this. The proxy decides which contract to call based on the msg.sender:

1. If the caller is the Admin (the address with rights to upgrade the proxy): The proxy only responds to its own administrative functions and does not delegate calls to the logic contract. This prevents the admin from accidentally triggering logic functions that clash with proxy functions.
2. If the caller is any other address: The proxy always delegates the call to the logic contract, regardless of whether the function name matches a proxy function.

Note for Developers: When using OpenZeppelin Upgrades, the ProxyAdmin contract is automatically used as the admin. This means you can interact with the proxy from your standard accounts without being blocked by the transparent proxy logic.

OpenZeppelin Upgrades operates on a Fail-Closed principle for all critical operations. This means that if any part of the upgrade-safety validation process is compromised, the operation must fail loudly and immediately rather than proceeding with potentially unsafe defaults.

Critical Operations Subject to Validation

• deploy* (e.g., deployProxy)
• upgrade* (e.g., upgradeProxy)
• validateImplementation
• validateUpgrade
• forceImport

When Validation Fails

The system will trigger a hard failure if validation data is:

• Missing or incomplete.
• Outdated.
• Unable to be matched to the contract (e.g., due to a missing or malformed build-info companion file or absent storageLayout output).
• Mismatched in name or encoding.

Bypassing Validation

Validation can only be bypassed through explicit, documented, and user-facing opt-out mechanisms. Examples include:

• unsafeAllow* methods
• unsafeSkipStorageCheck
• unsafeAllowRenames
• Specific NatSpec annotations

Note: A silent skip of validation is considered a critical failure of the tool's safety guarantees.

The UnsafeUpgrades library is a lightweight alternative to Upgrades designed for Forge tests and coverage. It skips all safety validations.

When to use:

• When running forge coverage.
• When you have already instantiated implementation contracts and want to avoid the overhead of validation.
• When you do not require --ffi or clean compilations between runs.

Warnings:

• NOT recommended for Forge scripts.
• Does not validate upgrade safety or implementation compatibility.
• Not supported for OpenZeppelin Defender deployments.

Key Differences:

• Upgrades uses contractName (string) to find and validate contracts.
• UnsafeUpgrades uses impl (address) for the implementation, assuming it is already deployed.

import { UnsafeUpgrades } from "openzeppelin-foundry-upgrades/Upgrades.sol";

// Example: Deploying without validation
address proxy = UnsafeUpgrades.deployUUPSProxy(implAddress, initializerData);