ERC-5202 — Blueprint Contract Format

Back to Infrastructure & Patterns

ERC-5202: Blueprint Contract Format

ERC-5202 standardises a container format for storing initcode (or any contract bytecode) inside another contract's runtime, with a 0xFE71 magic prefix that ensures the blueprint can never be executed directly. The pattern lets you "ship" deployable code as a regular contract — factory contracts read the blueprint via EXTCODECOPY, then deploy clones via CREATE / CREATE2. Vyper popularised it; Solidity toolchains added support for blueprint-aware factories soon after.

Container Format

0xFE71<version_bits><len_bits><preamble_data><initcode>

• 0xFE71 — magic bytes; the leading 0xFE is a guaranteed-invalid EVM opcode, so the runtime is uncallable.
• <version_bits> — 2 bits, currently 00.
• <len_bits> — 2 bits, encodes the preamble length width.
• <preamble_data> — optional metadata (compiler version, source hash, etc.).
• <initcode> — the actual contract code to deploy.

A factory reads EXTCODECOPY(blueprint_address, 0, size), parses the header, extracts the initcode, then CREATE2(0, initcode, salt) to deploy a fresh contract from it. The blueprint itself just holds bytes — it can be referenced by many factories or used as a template for clone swarms.

Why It Exists

Pre-5202, "deploy code from data" patterns were ad-hoc:

• Factories embedded the initcode as a bytes constant in their own runtime.
• Some used EXTCODECOPY against arbitrary contract addresses (fragile; the source contract might be self-destructed or callable in unexpected ways).
• ERC-1167 minimal proxies stored only a fixed forwarding stub, which doesn't help when each clone needs distinct initcode.

ERC-5202 normalises the "blueprint as data container" pattern with a guaranteed-invalid runtime so blueprints can't be confused with callable contracts.

Neo Equivalent: NEF Blob Storage + ContractManagement.Deploy

Neo's deployment model already separates "the bytes that will be deployed" (the NEF + manifest) from "the act of deploying them" (ContractManagement.Deploy(nef, manifest)). Storing those bytes in a contract's Storage and looking them up at deploy time is the direct equivalent of ERC-5202's pattern — and it's been usable since day one, without needing an EVM opcode hack to render the storage uncallable (because Storage isn't callable to begin with).

public static void StoreBlueprint(ByteString name, ByteString nef, ByteString manifestJson)
{
    if (!Runtime.CheckWitness(GetAdmin())) throw new Exception("admin only");
    var ctx = Storage.CurrentContext;
    Storage.Put(ctx, NefKey(name),      nef);
    Storage.Put(ctx, ManifestKey(name), manifestJson);
}

public static UInt160 DeployFromBlueprint(ByteString name, object data)
{
    var ctx = Storage.CurrentContext;
    var nef         = Storage.Get(ctx, NefKey(name));
    var manifestStr = Storage.Get(ctx, ManifestKey(name));
    var contract    = (Contract)ContractManagement.Deploy(nef, manifestStr, data);
    return contract.Hash;
}

ERC-5202 (Ethereum)	Neo Equivalent	Notes
Blueprint stored as a contract's runtime, prefixed with 0xFE71	Blueprint stored as raw bytes in another contract's Storage	Storage isn't callable; no magic-prefix hack needed
EXTCODECOPY(blueprint, 0, size) to extract	Storage.Get(ctx, key) to extract	Direct read, no opcode quirks
CREATE / CREATE2(salt, initcode) to deploy	ContractManagement.Deploy(nef, manifest, data)	Native deploy primitive
Per-blueprint version/preamble bits in header	NEF version + checksum in the NEF header itself	Already structured; no need for parallel preamble
Factory must validate magic prefix	No validation needed; if it's not a valid NEF, Deploy reverts	Cleaner failure mode

Why Neo Doesn't Need The ERC

ERC-5202 exists because Ethereum entangles "is this address a deployable template?" with "can I call this address?". The 0xFE prefix is a hack to ensure blueprints are uncallable. On Neo, deployable blobs live in storage, not in a contract's runtime — the entanglement doesn't exist, so the hack isn't needed.

The mirror page exists to make the equivalent pattern explicit: "blueprint contracts" on Neo are just contracts with Storage slots holding NEFs, plus a Deploy method that consumes them. The shape is the same as ERC-5202; the implementation is simpler.

Migration Notes

For Solidity factories using ERC-5202 blueprints:

1. Store the NEF + manifest in your factory's storage instead of storing the runtime of a blueprint contract. Use a name → bytes map.
2. Replace EXTCODECOPY with Storage.Get in your deploy method.
3. Replace CREATE2(salt, initcode) with ContractManagement.Deploy(nef, manifest, data). Salt becomes part of data or part of the manifest name (for address uniqueness).
4. Drop the magic-prefix validation — Neo's deploy primitive validates the NEF format itself.

For storing multiple blueprints (e.g. a factory that ships V1, V2, V3 versions of a contract), namespace storage keys by version: (blueprint, "v1") -> nef_bytes etc.

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

library Blueprint {
    bytes2 constant MAGIC = 0xFE71;

    /// Extract the initcode from a blueprint contract.
    function extractInitcode(address blueprint) internal view returns (bytes memory initcode) {
        uint256 size;
        assembly { size := extcodesize(blueprint) }
        require(size > 2, "blueprint too small");
        bytes memory full = new bytes(size);
        assembly { extcodecopy(blueprint, add(full, 0x20), 0, size) }
        require(uint16(bytes2(full)) == 0xFE71, "bad magic");

        // Skip header (variable; spec details elided).
        uint256 offset = 2;
        initcode = new bytes(size - offset);
        for (uint256 i = 0; i < initcode.length; ++i) initcode[i] = full[i + offset];
    }
}

contract BlueprintFactory {
    function deployFrom(address blueprint, bytes32 salt) external returns (address deployed) {
        bytes memory initcode = Blueprint.extractInitcode(blueprint);
        assembly { deployed := create2(0, add(initcode, 0x20), mload(initcode), salt) }
        require(deployed != address(0), "deploy failed");
    }
}

When compiled with neo-solc, both extcodecopy and create2 fault. Replace with the Neo blueprint-storage pattern (see C# tab) — the result is shorter and cleaner.

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("BlueprintRegistry")]
[ContractPermission("*", "deploy")]
public class BlueprintRegistry : SmartContract
{
    private const byte Prefix_Nef       = 0x01;
    private const byte Prefix_Manifest  = 0x02;
    private const byte Prefix_Admin     = 0xff;

    [DisplayName("_deploy")]
    public static void Deploy(object data, bool update)
    {
        if (update) return;
        Storage.Put(Storage.CurrentContext, new byte[] { Prefix_Admin }, (UInt160)data);
    }

    private static UInt160 Admin()
        => (UInt160)Storage.Get(Storage.CurrentContext, new byte[] { Prefix_Admin });

    public static void StoreBlueprint(ByteString name, ByteString nef, string manifestJson)
    {
        if (!Runtime.CheckWitness(Admin())) throw new Exception("admin only");
        var ctx = Storage.CurrentContext;
        Storage.Put(ctx, NefKey(name),      nef);
        Storage.Put(ctx, ManifestKey(name), manifestJson);
    }

    public static UInt160 DeployFromBlueprint(ByteString name, object data)
    {
        var ctx = Storage.CurrentContext;
        var nef         = (ByteString)Storage.Get(ctx, NefKey(name));
        var manifestStr = (string)Storage.Get(ctx, ManifestKey(name));
        if (nef is null) throw new Exception("blueprint not found");

        var contract = (Contract)ContractManagement.Deploy((NefFile)nef, manifestStr, data);
        return contract.Hash;
    }

    public static UInt160 PredictAddress(ByteString name)
    {
        var ctx = Storage.CurrentContext;
        var nef         = (NefFile)(ByteString)Storage.Get(ctx, NefKey(name));
        var manifestStr = (string)Storage.Get(ctx, ManifestKey(name));
        if (nef is null) throw new Exception("blueprint not found");
        var manifest = ContractManifest.FromJson(manifestStr);
        return Helper.GetContractHash(Runtime.ExecutingScriptHash, nef.CheckSum, manifest.Name);
    }

    public static (ByteString, string) GetBlueprint(ByteString name)
    {
        var ctx = Storage.CurrentContext;
        return ((ByteString)Storage.Get(ctx, NefKey(name)),
                (string)    Storage.Get(ctx, ManifestKey(name)));
    }

    private static byte[] NefKey(ByteString name)      => new byte[] { Prefix_Nef }.Concat(name);
    private static byte[] ManifestKey(ByteString name) => new byte[] { Prefix_Manifest }.Concat(name);
}

Use With ERC-1167 / ERC-3448 / ERC-7656 Family

This blueprint registry composes with the proxy/factory mirrors:

• ERC-1167 — the implementation NEF lives in a blueprint registry; clone factories DeployFromBlueprint(implName, …).
• ERC-3448 — same with per-instance metadata baked at deploy time.
• ERC-7656 — service registries consume blueprints to spin up per-(linked, serviceId) services.

Together they cover the full "deploy from data" pattern. The blueprint registry is the storage layer; the proxy/registry contracts are the deployment layer that consume blueprints to mint instances.

Pattern Summary

You want to …	Use
Deploy many identical clones cheaply	ERC-1167 + Blueprint
Deploy clones with immutable per-instance config	ERC-3448 + Blueprint
Deploy services bound to NFTs / contracts	ERC-7656 + Blueprint
Just hold deployable bytes for later	This page (Blueprint Registry) standalone