ERC-1167 — Minimal Proxy Contract

Back to Infrastructure & Patterns

ERC-1167: Minimal Proxy Contract (Clones)

ERC-1167 standardises a 45-byte runtime bytecode that does nothing but DELEGATECALL to a fixed implementation address. Combined with CREATE2 (ERC-1014) it gives you cheap, deterministic clones of an implementation — the substrate behind every "factory" pattern: TBA registries, multisig factories, NFT collection deployers, AMM pool contracts, etc. OpenZeppelin's Clones.sol is the de-facto helper.

Bytecode Layout

0x363d3d373d3d3d363d73<implementation_20_bytes>5af43d82803e903d91602b57fd5bf3

The runtime forwards calldata, executes DELEGATECALL, and returns the result. Storage is the proxy's own; the implementation contract supplies only logic.

Required Use Pattern

import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";

contract Factory {
    address public immutable implementation;

    function clone(bytes32 salt) external returns (address proxy) {
        proxy = Clones.cloneDeterministic(implementation, salt);
        IInitializable(proxy).initialize(msg.sender);
    }

    function predict(bytes32 salt) external view returns (address) {
        return Clones.predictDeterministicAddress(implementation, salt, address(this));
    }
}

Neo Equivalent: Parameterised Deploy via ContractManagement

NeoVM doesn't have DELEGATECALL. Two patterns reproduce the ERC-1167 use case:

A. Parameterised manifest deploy — the factory ships a small NEF + a manifest template. On Clone(salt), the factory inlines the implementation's contract hash into a constant slot and calls ContractManagement.Deploy(nef, manifest). The "proxy" is a real contract whose every method does Contract.Call(implementation, method, args) and re-returns. Storage stays in the proxy. The deterministic address comes from ContractManagement.GetContractById post-deploy.

B. Single shared dispatcher, scoped storage — one shared "proxy" contract holds N tenants' state in (salt) -> KV namespaces. Cheap (no per-clone deploy fee) but loses per-clone address distinctness. Most factory patterns favour pattern A.

ERC-1167 (Ethereum)	Neo Equivalent	Notes
Clones.clone(impl)	ContractManagement.Deploy(nef, manifest) with impl baked in	Each clone is a real Neo contract; not a runtime DELEGATECALL
Clones.cloneDeterministic(impl, salt)	Sender-scoped nonce + salt → deploy → Contract.Hash	Determinism comes from sender + nonce, not CREATE2 address algebra
Clones.predictDeterministicAddress(impl, salt, deployer)	Off-chain compute via Helper.GetContractHash(deployer, nef.checksum, manifest.name)	Same predict-before-deploy capability
45-byte runtime cost	One full Neo contract per clone (kilobytes)	Higher per-clone cost; offset by lower per-call overhead (no DELEGATECALL frame)
Storage in the proxy, logic in implementation	Storage in the proxy, logic looked up via Contract.Call(impl, ...)	Same separation; explicit instead of implicit

Why The Cost Profile Is Different

ERC-1167 is cheap to deploy (45 bytes) but every call pays a full DELEGATECALL frame. On Neo, deploying a parameterised proxy costs more GAS upfront but every method call is a normal Contract.Call — no extra frame. For factories minting many clones with high call rates the Neo profile usually wins; for one-shot identity-clones it loses. Pattern B (shared dispatcher) is the answer when many cheap clones matter.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IImplementation {
    function initialize(address owner) external;
    function doWork() external returns (uint256);
}

contract Factory {
    address public immutable implementation;
    event Cloned(address indexed clone, address indexed deployer, bytes32 indexed salt);

    constructor(address impl) { implementation = impl; }

    /// Cheapest possible deterministic clone (~45 byte runtime).
    function cloneDeterministic(bytes32 salt) external returns (address proxy) {
        bytes20 implBytes = bytes20(implementation);
        assembly {
            let ptr := mload(0x40)
            mstore(ptr, 0x3d602d80600a3d3981f3363d3d373d3d3d363d73000000000000000000000000)
            mstore(add(ptr, 0x14), implBytes)
            mstore(add(ptr, 0x28), 0x5af43d82803e903d91602b57fd5bf30000000000000000000000000000000000)
            proxy := create2(0, ptr, 0x37, salt)
        }
        require(proxy != address(0), "create2 failed");
        IImplementation(proxy).initialize(msg.sender);
        emit Cloned(proxy, msg.sender, salt);
    }
}

When compiled with neo-solc, the assembly { create2(...) } block faults — create2 has no NeoVM equivalent. Replace the factory body with a Neo-native parameterised deploy (see the C# tab) or make the Factory itself the shared dispatcher (pattern B).

using System;
using System.ComponentModel;
using System.Numerics;
using Neo;
using Neo.Cryptography;
using Neo.SmartContract.Framework;
using Neo.SmartContract.Framework.Attributes;
using Neo.SmartContract.Framework.Native;
using Neo.SmartContract.Framework.Services;

namespace R3E.Examples;

// Pattern A — parameterised deploy via ContractManagement.
//
// The factory stores the implementation's contract hash and a NEF + manifest
// template. Clone(salt) bakes the implementation hash into a constant slot in
// the proxy's NEF, deploys it, and records the resulting hash by salt.

[DisplayName("CloneFactory")]
[ContractPermission("*", "deploy")]
public class CloneFactory : SmartContract
{
    private const byte Prefix_Clone = 0x01;
    private const byte Prefix_Impl  = 0x02;

    [DisplayName("Cloned")]
    public static event Action<UInt160, UInt160, ByteString> OnCloned;

    public static UInt160 GetImplementation()
        => (UInt160)Storage.Get(Storage.CurrentContext, new byte[] { Prefix_Impl });

    public static UInt160 CloneDeterministic(ByteString salt)
    {
        var key = CloneKey(salt);
        var existing = (UInt160)Storage.Get(Storage.CurrentContext, key);
        if (existing is not null) throw new Exception("salt already used");

        var (nef, manifest) = BuildProxyFor(GetImplementation(), salt);
        var deployed = (Contract)ContractManagement.Deploy(nef, manifest);
        Storage.Put(Storage.CurrentContext, key, deployed.Hash);
        OnCloned(deployed.Hash, Runtime.CallingScriptHash, salt);
        return deployed.Hash;
    }

    public static UInt160 Predict(ByteString salt)
    {
        var (nef, manifest) = BuildProxyFor(GetImplementation(), salt);
        return Helper.GetContractHash(Runtime.ExecutingScriptHash, nef.CheckSum, manifest.Name);
    }

    private static byte[] CloneKey(ByteString salt)
        => new byte[] { Prefix_Clone }.Concat(salt);

    private static (NefFile, ContractManifest) BuildProxyFor(UInt160 impl, ByteString salt)
    {
        // Vendoring elided. The proxy's NEF holds a single dispatcher script
        // that loads `impl` from a constant slot and calls Contract.Call(impl, method, args)
        // for every entry-point in the manifest. Salt is mixed into the manifest name
        // for address uniqueness.
        throw new Exception("vendoring elided for example brevity");
    }
}

// The proxy contract — one instance per clone. All storage is its own; all
// logic is delegated to the implementation contract.
[DisplayName("MinimalProxy")]
[ContractPermission("*", "*")]
public class MinimalProxy : SmartContract
{
    private static readonly UInt160 IMPLEMENTATION =
        (UInt160)"0x0000000000000000000000000000000000000000";

    // Forward any unknown method to the implementation. Neo's manifest must
    // list each forwarded method, so the proxy is generated to mirror the
    // implementation's manifest at deploy time (see CloneFactory.BuildProxyFor).
    public static object Forward(string method, object[] args)
    {
        return Contract.Call(IMPLEMENTATION, method, CallFlags.All, args);
    }
}

Pattern B — Shared Dispatcher (Cheaper for Many Clones)

[DisplayName("SharedDispatcher")]
[ContractPermission("*", "*")]
public class SharedDispatcher : SmartContract
{
    private const byte Prefix_TenantState = 0x01;

    public static object Call(ByteString salt, string method, object[] args)
    {
        // Storage is namespaced by (salt) so every "tenant" gets isolated state.
        var ctx = Storage.CurrentContext;
        var prefix = new byte[] { Prefix_TenantState }.Concat(salt);
        // ... dispatch method against namespaced storage ...
        return null;
    }
}

Pattern B trades address-distinctness for ~zero per-clone deploy cost. Use it when the only thing the clone needs to provide is scoped storage and witness-based authorization.

When To Use Which

• Pattern A (parameterised deploy) — when downstream code needs a distinct contract address per clone (e.g. NFT collections, marketplaces that index by contract hash, TBAs).
• Pattern B (shared dispatcher) — when only logical isolation matters, not address-level. Lower-cost for high clone counts.
• Skip cloning entirely — Neo's Storage.Find + prefix conventions let most factory-pattern designs collapse to "one contract, scoped storage". Use cloning only when a third party needs an address to call.