What is a minimal proxy contract (EIP-1167)?

A minimal proxy contract efficiently forwards calls to an implementation contract using delegatecall, enabling cost-effective deployments and shared logic across multiple instances.

Jul 15, 2025 at 05:00 am

Understanding the Minimal Proxy Contract

A minimal proxy contract is a lightweight smart contract designed to forward all calls to another contract while maintaining minimal overhead. It plays a crucial role in Ethereum-based systems, particularly when deploying multiple instances of a contract with shared logic. The concept was formalized through EIP-1167, which outlines a standard for creating clones of existing contracts using a minimal amount of bytecode.

The core idea behind this mechanism is code reuse. Instead of deploying a new contract with identical logic every time, developers can deploy a proxy that delegates all function calls to a pre-existing implementation contract. This significantly reduces deployment costs and simplifies upgrades.

Key Concept: A minimal proxy contract contains only the necessary code to redirect execution to a target contract.

How Does EIP-1167 Work?

EIP-1167 leverages the delegatecall opcode in Solidity to achieve its functionality. Delegatecall allows one contract to execute code from another contract while preserving the context (such as msg.sender and storage) of the calling contract. In the case of a minimal proxy, this means the proxy forwards all incoming calls to an implementation contract without altering the caller's context.

Here’s how it works:

• The proxy contract contains a single storage slot that holds the address of the implementation contract.
• When a user interacts with the proxy, the fallback function is triggered.
• This fallback function uses delegatecall to forward the call to the stored implementation address.

Because of its simplicity, the proxy contract requires very little gas for deployment—often less than 50,000 gas. This efficiency makes it ideal for scenarios where many similar contracts need to be deployed quickly and cheaply.

Structure of a Minimal Proxy Contract

A minimal proxy contract typically follows a strict structure defined by EIP-1167. Here’s what it includes:

• A constant address variable pointing to the implementation contract.
• A fallback function that performs a delegatecall to that implementation address.
• No constructor or state variables beyond the implementation address.

This design ensures that the proxy does not store any logic itself but simply acts as a conduit for the implementation contract. Below is a simplified version of such a contract written in Solidity:

pragma solidity ^0.8.0;
contract MinimalProxy {
address private immutable implementation;

constructor(address _implementation) {
    implementation = _implementation;
}

fallback() external payable {
    address impl = implementation;
    assembly {
        let ptr := mload(0x40)
        calldatacopy(ptr, 0, calldatasize())
        let result := delegatecall(gas(), impl, ptr, calldatasize(), 0, 0)
        let size := returndatasize()
        returndatacopy(ptr, 0, size)

        switch result
        case 0 { revert(ptr, size) }
        default { return(ptr, size) }
    }
}
}

Important Note: The use of inline assembly in the fallback function is essential for keeping the proxy minimal and efficient.

Use Cases for Minimal Proxy Contracts

Minimal proxy contracts are widely used in various decentralized applications and protocols due to their efficiency and flexibility. Some of the most common use cases include:

• Token Factories: Creating multiple ERC-20 or ERC-721 tokens from a single implementation contract.
• Upgradable Contracts: Serving as a base layer for upgradability patterns like the Transparent Proxy or UUPS.
• Gas-Efficient Deployments: Reducing deployment cost when instantiating hundreds or thousands of contracts.
• Contract Templates: Offering standardized templates for predictable behavior across multiple deployments.

Each of these use cases benefits from the reduced deployment footprint and the ability to maintain consistent logic across multiple proxies.

Differences Between Minimal Proxy and Other Proxy Patterns

There are several proxy patterns in Ethereum, including Transparent Proxies, UUPS (Universal Upgradeable Proxy Standard), and Beacon Proxies. Each has its own trade-offs in terms of complexity, upgradeability, and gas cost.

The key difference between a minimal proxy and other proxy types lies in functionality and extensibility:

• Minimal proxies do not support upgrades unless paired with additional infrastructure.
• Transparent proxies include admin logic and a proxy registry, increasing gas usage and complexity.
• UUPS proxies allow for self-contained upgrades via the implementation contract.

Minimal proxies are best suited for scenarios where the implementation will remain static after deployment or where upgrades are handled externally.

Security Considerations and Best Practices

Although minimal proxy contracts are simple, they are not without risks. Developers should follow best practices to ensure secure usage:

• Ensure Implementation Immutability: Once deployed, the implementation address should not change unless explicitly intended and secured.
• Avoid Storage Conflicts: Since the proxy and implementation share storage context, careful planning is needed if extending the proxy later.
• Verify Bytecode: Always verify the bytecode of both the proxy and the implementation contract to prevent malicious modifications.
• Test Thoroughly: Use tools like Hardhat or Foundry to simulate interactions and test edge cases before mainnet deployment.

Critical Tip: Never assume that a proxy contract inherits security from the implementation—it must be audited separately.

Frequently Asked Questions

Q: Can I upgrade a minimal proxy contract?

While minimal proxies themselves do not include upgrade logic, you can create an upgradable system by combining them with other standards like UUPS or using an external controller to manage implementation addresses.

Q: How much cheaper is deploying a minimal proxy compared to a full contract?

Deploying a minimal proxy typically costs around 20,000–50,000 gas, whereas deploying a full contract may exceed 2 million gas depending on complexity.

Q: Is there a way to retrieve the implementation address from a deployed proxy?

Yes, the implementation address is usually stored at a specific storage slot (often slot 0). You can read it using tools like eth_getStorageAt or by inspecting the contract creation code.

Q: Are minimal proxies compatible with all Solidity versions?

They work well with Solidity 0.5.0 and above. However, for optimal compatibility and gas savings, using Solidity 0.8.x or newer is recommended.