ERC-1967 — Standard Proxy Storage Slots

Back to Infrastructure & Patterns

ERC-1967: Standard Proxy Storage Slots

Ethereum bytecode is immutable: once deployed, you cannot change the runtime code. Upgradeable contracts work around this with a proxy pattern: a small, intentionally-stable proxy contract delegatecalls into a separate "implementation" contract whose address it stores. ERC-1967 standardises where the proxy stores the implementation address so explorers can find it.

Costs of the Proxy Pattern

• Per-call overhead: every external call routes through delegatecall.
• Storage layout fragility: implementation upgrades must preserve storage layout exactly.
• selfdestruct traps: implementation calling selfdestruct destroys the proxy.
• Initializer races: first call must initialize before adversary does.
• Audit complexity: two contracts to audit; storage-collision audits required.

Neo Equivalent: NEP-22 Native Update (No Proxy)

Neo contracts upgrade in place via ContractManagement.Update(nef, manifest, data). Replaces bytecode and manifest atomically, preserves all storage, runs _deploy(data, update: true) for migrations, requires owner witness. The contract hash never changes — every reference, every NEP-17 holder, every NFT, every approval continues to work.

Live on Neo TestNet

Both implementations deployed on Neo N3 TestNet.

Implementation	TestNet Address	Contract Hash
Solidity (neo-solc)	NRiL2gKGW5L8YgRcudr8mFNjrDUkkWZHR3	0x48f6d58a…bfdbd245
Neo C# (nccs)	NTgmiKbdcnknygAtt2ssWEjfPsJUM9hWGV	0x096f01e4…481be976

Verified: initial version is 1, owner is the deployer. The Neo C# contract uses NEP-22's Update method for in-place upgrades — calling it bumps the version counter via _deploy(data, update: true), the standard Neo lifecycle hook. docs/standards-mirror/deployments/erc-1967/.

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

contract ERC1967Proxy {
    bytes32 internal constant _IMPLEMENTATION_SLOT =
        0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
    bytes32 internal constant _ADMIN_SLOT =
        0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;

    constructor(address impl, bytes memory data) payable {
        _setImplementation(impl);
        _setAdmin(msg.sender);
        if (data.length > 0) {
            (bool ok, ) = impl.delegatecall(data);
            require(ok, "init failed");
        }
    }

    fallback() external payable { _delegate(_implementation()); }
    receive() external payable  { _delegate(_implementation()); }

    function _delegate(address impl) internal {
        assembly {
            calldatacopy(0, 0, calldatasize())
            let result := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())
            switch result
            case 0 { revert(0, returndatasize()) }
            default { return(0, returndatasize()) }
        }
    }

    function _implementation() internal view returns (address impl) {
        assembly { impl := sload(_IMPLEMENTATION_SLOT) }
    }

    function _setImplementation(address impl) internal {
        assembly { sstore(_IMPLEMENTATION_SLOT, impl) }
    }

    function _setAdmin(address admin) internal {
        assembly { sstore(_ADMIN_SLOT, admin) }
    }
}

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("UpgradeableContract")]
[ContractPermission("*", "*")]
public class UpgradeableContract : SmartContract
{
    private static readonly byte[] OwnerKey   = { 0xff };
    private static readonly byte[] VersionKey = { 0xfe };

    [DisplayName("Updated")]
    public static event Action<int> OnUpdated;

    /// <summary>NEP-22: standard contract update entrypoint.</summary>
    public static void Update(ByteString nefFile, string manifest, object data)
    {
        var owner = (UInt160)Storage.Get(Storage.CurrentContext, OwnerKey);
        if (!Runtime.CheckWitness(owner)) throw new Exception("owner only");
        ContractManagement.Update(nefFile, manifest, data);
    }

    /// <summary>NEP-29: deploy/update lifecycle callback.</summary>
    public static void _deploy(object data, bool update)
    {
        if (update)
        {
            var oldVersion = (int)(BigInteger)(Storage.Get(Storage.CurrentContext, VersionKey)
                                               ?? new byte[] { 0 });
            var newVersion = oldVersion + 1;
            Storage.Put(Storage.CurrentContext, VersionKey, newVersion);
            OnUpdated(newVersion);
            return;
        }
        Storage.Put(Storage.CurrentContext, OwnerKey, (UInt160)data);
        Storage.Put(Storage.CurrentContext, VersionKey, 1);
    }

    /// <summary>NEP-31: optional destroy method.</summary>
    public static void Destroy()
    {
        var owner = (UInt160)Storage.Get(Storage.CurrentContext, OwnerKey);
        if (!Runtime.CheckWitness(owner)) throw new Exception("owner only");
        ContractManagement.Destroy();
    }
}

Side-By-Side: What Goes Away

Proxy Concern	Neo Result
Implementation slot	None — contract bytecode lives at the script hash
Admin slot	None — owner is just a storage key
delegatecall indirection	None — calls hit the contract directly
Storage layout fragility	Storage layout is just storage; you control it
Per-call gas overhead	Zero — no proxy hop
Initializer race	_deploy(update: false) runs once at deploy
Selfdestruct trap	ContractManagement.Destroy() is explicit and gated