ERC-7936 Version-selectable proxy interface (Versioned Proxy Contract Interface)

Review · Other · created 2025-04-17

A standard that registers multiple versions of an implementation together in a proxy contract, letting callers directly choose the version they want at call time.

Why it is needed

Smart contracts need upgrades for bug fixes or new features, and this is usually handled through the proxy pattern. However, the current proxy pattern connects all callers only to the latest implementation. If the interface changes in a new version, existing integrations can break, and there is no standard way to migrate to the new version gradually. Trust is an even bigger problem. Even if an admin key or governance is compromised and malicious code is deployed, users have no choice but to use that latest implementation, and they cannot escape a harmful upgrade unless they stop using the contract entirely. In the end, users must trust the administrator or governance forever, with no way to choose and trust only a specific version that has been audited and verified. This standard solves this problem with a proxy interface that keeps previous versions open.

What to implement

In depth

Version registry and required behavior

The proxy MUST maintain a mapping of bytes32 version identifiers to implementation addresses, and MUST also maintain a default version to use for calls that do not specify a version. Appropriate events (VersionRegistered, DefaultVersionChanged) MUST be emitted when a version is registered or the default version is changed. The administrative functions are registerVersion, removeVersion, and setDefaultVersion, and the query functions provided are getImplementation, getDefaultVersion, and getVersions. It is RECOMMENDED (SHOULD) to implement access control for administrative functions such as version registration or setting the default version.

Execution rules for executeAtVersion

When executeAtVersion(bytes32 version, bytes calldata data) is called, the proxy MUST verify that the specified version exists, forward the call to that implementation, and return the data from the implementation unchanged. This function is declared as payable. Version selection is kept as a separate function rather than embedded in the call data, in order to cleanly separate version selection from function calls, avoid modifying existing function signatures, and allow explicit auditing of which version was used.

Fallback function and backwards compatibility

The proxy SHOULD implement a fallback function that forwards calls without a specified version to the default version implementation. This preserves compatibility with the traditional proxy pattern, so existing contracts that interact with the proxy can continue to be used without modification. The original text explains that this standard does not create incompatibility with existing Ethereum standards or implementations, and is in fact designed to strengthen the backwards compatibility of smart contracts. In addition, the EIP-1967 storage slots MAY be implemented for compatibility with existing tooling.

Why the version identifier is defined as bytes32

The version identifier is defined as bytes32 rather than a semantic versioning string. There are four reasons: to give flexibility in choosing a versioning scheme, to reduce the gas cost of storage and comparison, to allow both string-based versions (converted to bytes32) and numeric versions, and to allow Git commit identifiers in SHA-1 or SHA-256 form to be stored as well. As in the comment's example, it is also possible to convert and use a string like "1.0.0".

Why the registry pattern was chosen

Two alternatives were considered during the design process. First, having a separate proxy for each version increases deployment cost and complexity. Second, keeping only a single current version in storage does not allow different callers to use different versions at the same time. Keeping a registry of versions and implementation addresses inside a single proxy avoids both problems, while the default version mechanism also maintains compatibility with the traditional proxy pattern.

Choice against malicious upgrades

In the traditional proxy, even if an upgrade is malicious, all users are exposed to the latest implementation. Under this standard, users can stay on a version they have verified and trust, mitigating the risk of harmful code being deployed due to compromised admin keys or governance issues. The original Security Considerations states that this standard is meant to significantly improve the security of the widely used proxy pattern, and does not list other specific precautions.

Note on proposal status

The status of this document is Review. As this proposal is still under review, the interface and detailed requirements may change in the future.

Original ERC · ← ERCs