ERC-3448 — MetaProxy Standard

Back to Infrastructure & Patterns

ERC-3448: MetaProxy

ERC-3448 extends ERC-1167 to support immutable per-clone constructor arguments without runtime initialiser calls. The proxy's runtime bytecode reads the trailing bytes of its own code (an arbitrary ABI-encoded blob) and exposes them via a fixed selector. This eliminates the "deploy then initialize()" two-step that a vanilla ERC-1167 needs when each clone has a different config.

Required Pattern

// MetaProxy runtime: ERC-1167 prefix + delegatecall to impl + appended args
function deployProxy(address impl, bytes memory metadata) internal returns (address proxy) {
    bytes memory creation = abi.encodePacked(
        hex"363d3d373d3d3d3d60368038038091363936013d73",
        impl,
        hex"5af43d3d93803e603457fd5bf3",
        metadata
    );
    assembly { proxy := create(0, add(creation, 0x20), mload(creation)) }
}

// Inside the implementation contract:
function getMetadata() public pure returns (bytes memory data) {
    assembly {
        let pos  := sub(calldatasize(), 0x20)
        let size := calldataload(pos)
        data := mload(0x40)
        mstore(data, size)
        calldatacopy(add(data, 0x20), sub(pos, size), size)
        mstore(0x40, add(add(data, 0x20), size))
    }
}

The proxy's appended bytes are part of its address derivation under CREATE2 — different metadata yields a different deterministic address. This is what makes MetaProxy fully drop-in for ERC-1167 use cases that previously needed a separate factory-side init call.

Neo Equivalent: Constant-slot Manifest Deploy

NeoVM doesn't have appended-runtime-bytes calldata semantics. The equivalent on Neo is to deploy a parameterised contract whose NEF constants are baked at deploy time. Same end-state (per-clone immutable args, deterministic address that includes the args) achieved by a different mechanism.

// The factory builds a per-clone NEF whose constant slots hold `metadata`,
// then deploys via ContractManagement.Deploy. Address determinism comes
// from sender + nonce + manifest name (which can encode the metadata hash).

public static UInt160 DeployMetaProxy(UInt160 impl, ByteString metadata)
{
    var (nef, manifest) = BuildNefWithMetadata(impl, metadata);
    var deployed = (Contract)ContractManagement.Deploy(nef, manifest);
    OnDeployed(deployed.Hash, impl, metadata);
    return deployed.Hash;
}

ERC-3448 (Ethereum)	Neo Equivalent	Notes
MetaProxy.deploy(impl, metadata)	Factory.DeployMetaProxy(impl, metadata) with constants baked into NEF	One-shot deploy; no separate initialize()
Runtime trailing-bytes calldata trick	Constants in NEF reserved slots	Different mechanism, same affordance
Address determinism includes metadata	Manifest name / sender nonce includes metadata hash	Predictable address; different inputs → different address
getMetadata() reads calldatasize() tail	GetMetadata() reads constant slot directly	Simpler; no assembly required
Init-free clone (no follow-up tx)	Init-free clone (constants applied at deploy)	Same UX

When To Use vs Plain ERC-1167

• Plain ERC-1167 (see Pattern A on the ERC-1167 page) when every clone is identical and any per-clone config can be held in storage set by a follow-up initialize() call.
• MetaProxy when each clone has immutable config (vault token address, NFT collection name, multisig threshold) that should be unchangeable post-deploy and visible at the proxy's address.

The Neo factory pattern collapses both into one: the parameterised NEF deploy handles plain clones (no metadata) and meta-proxies (with metadata) the same way. The only difference is whether the factory injects metadata into the constant slots.

Migration Notes

Solidity contracts using OpenZeppelin's Clones.cloneDeterministicWithImmutableArgs or Vectorized's LibClone.deployERC1967WithImmutableArgs map directly to the Neo factory pattern above. The getImmutableArgs() getter on the implementation becomes a simple GetMetadata() returning a constant — no assembly tricks needed.

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

library MetaProxy {
    function deploy(address impl, bytes memory metadata) internal returns (address proxy) {
        bytes memory creation = abi.encodePacked(
            hex"363d3d373d3d3d3d60368038038091363936013d73",
            impl,
            hex"5af43d3d93803e603457fd5bf3",
            metadata
        );
        assembly { proxy := create(0, add(creation, 0x20), mload(creation)) }
        require(proxy != address(0), "deploy failed");
    }

    function deployDeterministic(address impl, bytes memory metadata, bytes32 salt)
        internal returns (address proxy)
    {
        bytes memory creation = /* same as above */;
        assembly { proxy := create2(0, add(creation, 0x20), mload(creation), salt) }
        require(proxy != address(0), "deploy failed");
    }
}

// Implementation reads its appended metadata.
contract VaultClone {
    function asset() public pure returns (address a) {
        bytes memory meta = _getMetadata();
        assembly { a := mload(add(meta, 0x20)) }
    }

    function _getMetadata() internal pure returns (bytes memory data) {
        assembly {
            let pos  := sub(calldatasize(), 0x20)
            let size := calldataload(pos)
            data := mload(0x40)
            mstore(data, size)
            calldatacopy(add(data, 0x20), sub(pos, size), size)
            mstore(0x40, add(add(data, 0x20), size))
        }
    }
}

The assembly { create(...) } and the calldatasize() trick both fault under neo-solc — neither has a NeoVM equivalent. Replace with the C# factory pattern below; the implementation reads its baked-in constants directly instead of via assembly.

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

namespace R3E.Examples;

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

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

    public static UInt160 Deploy(UInt160 impl, ByteString metadata)
    {
        var key = ProxyKey(impl, metadata);
        var existing = (UInt160)Storage.Get(Storage.CurrentContext, key);
        if (existing is not null) return existing;

        var (nef, manifest) = BuildNefWithMetadata(impl, metadata);
        var deployed = (Contract)ContractManagement.Deploy(nef, manifest);
        Storage.Put(Storage.CurrentContext, key, deployed.Hash);
        OnDeployed(deployed.Hash, impl, metadata);
        return deployed.Hash;
    }

    public static UInt160 Predict(UInt160 impl, ByteString metadata)
    {
        var (nef, manifest) = BuildNefWithMetadata(impl, metadata);
        return Helper.GetContractHash(Runtime.ExecutingScriptHash, nef.CheckSum, manifest.Name);
    }

    private static byte[] ProxyKey(UInt160 impl, ByteString metadata)
        => new byte[] { Prefix_Proxy }.Concat(impl).Concat(metadata);

    private static (NefFile, ContractManifest) BuildNefWithMetadata(UInt160 impl, ByteString metadata)
    {
        // Builds a NEF whose constant slots hold (impl, metadata). Each method
        // forwards via Contract.Call(impl, ...) and exposes GetMetadata() that
        // returns the baked metadata. Manifest.Name suffixed with metadata hash
        // for address uniqueness across (impl, metadata) tuples. Vendoring elided.
        throw new Exception("vendoring elided for example brevity");
    }
}

// The proxy contract — one per (impl, metadata) tuple. Constants baked in.
[DisplayName("MetaProxy")]
[ContractPermission("*", "*")]
public class MetaProxy : SmartContract
{
    private static readonly UInt160 IMPLEMENTATION =
        (UInt160)"0x0000000000000000000000000000000000000000";
    private static readonly ByteString METADATA = "";

    [Safe]
    public static ByteString GetMetadata() => METADATA;

    public static object Forward(string method, object[] args)
        => Contract.Call(IMPLEMENTATION, method, CallFlags.All, args);
}

Concrete Use: Vault Clones

// Each cloned vault is bound to a specific NEP-17 asset, baked at deploy.
[DisplayName("VaultClone")]
public class VaultClone : SmartContract
{
    private static readonly UInt160 ASSET =
        (UInt160)"0x0000000000000000000000000000000000000000";  // baked per-clone

    [Safe]
    public static UInt160 Asset() => ASSET;

    public static void Deposit(BigInteger amount)
    {
        Contract.Call(ASSET, "transfer", CallFlags.All,
            new object[] { Runtime.CallingScriptHash, Runtime.ExecutingScriptHash, amount, null });
        // ... credit vault shares ...
    }
}

// Factory side:
//   factory.Deploy(vaultImpl, asset.ToByteArray())
//   → vault contract whose ASSET constant is the supplied hash
//   → no Initialize() call needed; address depends on (impl, asset)

This is the same pattern that ERC-3448 enables on Ethereum, with a cleaner expression: constants are just constants in the Neo manifest, no assembly tricks required.