{
  "$schema": "https://degreesofsatoshi.com/encyclopedia/schemas/article-v1.json",
  "schemaVersion": "1.0.0",
  "id": "contract-proxies",
  "canonical": "https://degreesofsatoshi.com/encyclopedia/contract-proxies/",
  "collection": "ethereum",
  "title": "Contract proxies: one address, replaceable implementation",
  "description": "Understand Ethereum proxy contracts, implementation addresses and upgrade authority without assuming that a stable address means stable application logic.",
  "aliases": [],
  "dates": {
    "published": "2026-10-02",
    "modified": "2026-10-02",
    "verified": "2026-10-02T18:12:41.505Z",
    "dataAsOf": "2026-10-02"
  },
  "authorship": {
    "publisher": "Degrees of Satoshi editorial project",
    "process": "AI-assisted research and drafting with a separate automated source-verification pass; no external expert or named human review is implied."
  },
  "quickAnswer": {
    "text": "A proxy contract forwards execution to implementation code, commonly using delegatecall while keeping state at the proxy address. Some proxies let an authorized party change the implementation. A permanent user-facing address therefore does not by itself mean that the application’s rules cannot change.",
    "claimId": "contract-proxies-quick-answer",
    "sourceIds": [
      "oz-proxy",
      "solidity-delegatecall"
    ]
  },
  "keyFacts": [
    {
      "label": "State",
      "value": "Delegated execution uses the calling contract’s storage context.",
      "sourceIds": [
        "solidity-delegatecall"
      ],
      "id": "state",
      "claimId": "contract-proxies-fact-state"
    },
    {
      "label": "Implementation",
      "value": "Proxy designs track which code address handles delegated calls.",
      "sourceIds": [
        "oz-proxy"
      ],
      "id": "implementation",
      "claimId": "contract-proxies-fact-implementation"
    },
    {
      "label": "Authority",
      "value": "Transparent and UUPS patterns place upgrade checks in different parts of the design.",
      "sourceIds": [
        "oz-proxy"
      ],
      "id": "authority",
      "claimId": "contract-proxies-fact-authority"
    }
  ],
  "prerequisites": [
    "ethereum-smart-contracts"
  ],
  "sections": [
    {
      "id": "two-addresses",
      "heading": "Separate where assets live from which code runs",
      "sourceIds": [
        "oz-proxy",
        "solidity-delegatecall"
      ],
      "paragraphs": [
        "A reader may interact with one proxy address while the logic comes from another implementation address. The proxy’s storage holds the application’s state in the delegated execution model.",
        "Looking only at the implementation’s own storage or balance can therefore be misleading. Inspect the proxy context as well as the current code."
      ]
    },
    {
      "id": "upgrades",
      "heading": "Find who can change the implementation",
      "sourceIds": [
        "oz-proxy"
      ],
      "paragraphs": [
        "An upgrade path may be controlled by a multisig, governance system or another role. Some designs restrict or remove upgrading; others retain broad authority. The word “proxy” alone does not answer which case applies.",
        "Trace the actual authorization function and any delay. A public governance discussion is not equivalent to an enforced on-chain timelock."
      ]
    },
    {
      "id": "compatibility",
      "heading": "New code must understand old storage",
      "sourceIds": [
        "oz-proxy",
        "solidity-layout"
      ],
      "paragraphs": [
        "Delegated implementations share the proxy’s existing storage. An incompatible layout can make new code interpret old values incorrectly even if both versions compile.",
        "Initialization also matters: setup functions can assign critical roles and must be protected appropriately. Source verification of two contracts does not prove their combined deployment is configured correctly."
      ]
    }
  ],
  "faq": [
    {
      "question": "Does every proxy mean someone can upgrade the contract?",
      "answer": "No. Proxy mechanisms and upgrade authority vary. Inspect the actual implementation-selection and authorization paths instead of inferring them from the label alone.",
      "sourceIds": [
        "oz-proxy"
      ]
    }
  ],
  "claims": [
    {
      "id": "contract-proxies-quick-answer",
      "articleSlug": "contract-proxies",
      "statement": "A proxy contract forwards execution to implementation code, commonly using delegatecall while keeping state at the proxy address. Some proxies let an authorized party change the implementation. A permanent user-facing address therefore does not by itself mean that the application’s rules cannot change.",
      "sourceIds": [
        "source-16bb921e662a5173",
        "source-7399ee01181109d4"
      ],
      "sourceLocators": [
        {
          "sourceId": "source-16bb921e662a5173",
          "locator": "TransparentUpgradeableProxy; UUPSUpgradeable; ERC1967Proxy"
        },
        {
          "sourceId": "source-7399ee01181109d4",
          "locator": "Delegatecall and Libraries; Storage, Memory and the Stack; Logs; Message Calls"
        }
      ],
      "scope": {
        "collection": "ethereum",
        "dataAsOf": "2026-10-02",
        "blockHeight": null
      },
      "qualification": "",
      "evidenceStatus": "documented",
      "verification": {
        "status": "verified",
        "method": "independent automated source review",
        "checkedAt": "2026-10-02T18:12:41.505Z",
        "reviewer": "Codex independent automated reviewer /root/verify_ethereum_100",
        "notes": [
          "Checked OpenZeppelin ERC1967, Transparent vs UUPS, minimal clones and initialization/access-control requirements against Solidity delegatecall context.",
          "The article correctly allows non-upgradeable proxies. Storage compatibility concern follows from documented shared proxy state and Solidity packing/layout rules."
        ]
      }
    },
    {
      "id": "contract-proxies-fact-state",
      "articleSlug": "contract-proxies",
      "statement": "State: Delegated execution uses the calling contract’s storage context.",
      "sourceIds": [
        "source-7399ee01181109d4"
      ],
      "sourceLocators": [
        {
          "sourceId": "source-7399ee01181109d4",
          "locator": "Delegatecall and Libraries; Storage, Memory and the Stack; Logs; Message Calls"
        }
      ],
      "scope": {
        "collection": "ethereum",
        "dataAsOf": "2026-10-02",
        "blockHeight": null
      },
      "qualification": "",
      "evidenceStatus": "documented",
      "verification": {
        "status": "verified",
        "method": "independent automated source review",
        "checkedAt": "2026-10-02T18:12:41.505Z",
        "reviewer": "Codex independent automated reviewer /root/verify_ethereum_100",
        "notes": [
          "Checked OpenZeppelin ERC1967, Transparent vs UUPS, minimal clones and initialization/access-control requirements against Solidity delegatecall context.",
          "The article correctly allows non-upgradeable proxies. Storage compatibility concern follows from documented shared proxy state and Solidity packing/layout rules."
        ]
      }
    },
    {
      "id": "contract-proxies-fact-implementation",
      "articleSlug": "contract-proxies",
      "statement": "Implementation: Proxy designs track which code address handles delegated calls.",
      "sourceIds": [
        "source-16bb921e662a5173"
      ],
      "sourceLocators": [
        {
          "sourceId": "source-16bb921e662a5173",
          "locator": "TransparentUpgradeableProxy; UUPSUpgradeable; ERC1967Proxy"
        }
      ],
      "scope": {
        "collection": "ethereum",
        "dataAsOf": "2026-10-02",
        "blockHeight": null
      },
      "qualification": "",
      "evidenceStatus": "documented",
      "verification": {
        "status": "verified",
        "method": "independent automated source review",
        "checkedAt": "2026-10-02T18:12:41.505Z",
        "reviewer": "Codex independent automated reviewer /root/verify_ethereum_100",
        "notes": [
          "Checked OpenZeppelin ERC1967, Transparent vs UUPS, minimal clones and initialization/access-control requirements against Solidity delegatecall context.",
          "The article correctly allows non-upgradeable proxies. Storage compatibility concern follows from documented shared proxy state and Solidity packing/layout rules."
        ]
      }
    },
    {
      "id": "contract-proxies-fact-authority",
      "articleSlug": "contract-proxies",
      "statement": "Authority: Transparent and UUPS patterns place upgrade checks in different parts of the design.",
      "sourceIds": [
        "source-16bb921e662a5173"
      ],
      "sourceLocators": [
        {
          "sourceId": "source-16bb921e662a5173",
          "locator": "TransparentUpgradeableProxy; UUPSUpgradeable; ERC1967Proxy"
        }
      ],
      "scope": {
        "collection": "ethereum",
        "dataAsOf": "2026-10-02",
        "blockHeight": null
      },
      "qualification": "",
      "evidenceStatus": "documented",
      "verification": {
        "status": "verified",
        "method": "independent automated source review",
        "checkedAt": "2026-10-02T18:12:41.505Z",
        "reviewer": "Codex independent automated reviewer /root/verify_ethereum_100",
        "notes": [
          "Checked OpenZeppelin ERC1967, Transparent vs UUPS, minimal clones and initialization/access-control requirements against Solidity delegatecall context.",
          "The article correctly allows non-upgradeable proxies. Storage compatibility concern follows from documented shared proxy state and Solidity packing/layout rules."
        ]
      }
    }
  ],
  "sources": [
    {
      "id": "oz-proxy",
      "label": "Proxy contracts",
      "publisher": "OpenZeppelin",
      "url": "https://docs.openzeppelin.com/contracts/5.x/api/proxy",
      "locator": "TransparentUpgradeableProxy; UUPSUpgradeable; ERC1967Proxy",
      "note": "Proxy implementation slots, delegated execution and upgrade authority.",
      "version": "OpenZeppelin Contracts 5.x",
      "checkedAt": "2026-10-02T17:03:43.024Z",
      "contentSha256": "58fe40b9eaa6d3cf92e48caed2d8db247a790b1a3055948095a48c7f8eb77854",
      "recordId": "source-16bb921e662a5173"
    },
    {
      "id": "solidity-delegatecall",
      "label": "Solidity: Delegatecall and Libraries",
      "publisher": "Solidity contributors",
      "url": "https://docs.soliditylang.org/en/v0.8.30/introduction-to-smart-contracts.html",
      "locator": "Delegatecall and Libraries; Storage, Memory and the Stack; Logs; Message Calls",
      "note": "Execution uses another contract’s code in the caller’s context and storage.",
      "version": "Solidity 0.8.30 documentation",
      "checkedAt": "2026-10-02T17:03:42.822Z",
      "contentSha256": "9fde27b9eb16bcd47d5e9fb73a80d2d3b288ae7b74ac56b29956267028fe7a55",
      "recordId": "source-7399ee01181109d4"
    },
    {
      "id": "solidity-layout",
      "label": "Layout of State Variables in Storage and Transient Storage",
      "publisher": "Solidity contributors",
      "url": "https://docs.soliditylang.org/en/v0.8.30/internals/layout_in_storage.html",
      "locator": "Layout of State Variables; Mappings and Dynamic Arrays",
      "note": "Persistent storage slots, packing and mappings.",
      "version": "Solidity 0.8.30 documentation",
      "checkedAt": "2026-10-02T17:03:42.820Z",
      "contentSha256": "de5fd67613e71fdb6b46e30bcb1c7e63380ea40d9521e757cfba947a5ee8d738",
      "recordId": "source-2b10f2b55ba1af87"
    }
  ],
  "related": {
    "articles": [
      "delegatecall-explained",
      "protocol-upgrades-and-admin-powers",
      "verified-contract-source"
    ],
    "dossiers": [],
    "wallets": []
  },
  "revisionHistory": [
    {
      "date": "2026-10-02",
      "kind": "published",
      "summary": "First publication after primary-source research and independent automated verification."
    }
  ],
  "citation": "Degrees of Satoshi editorial project. “Contract proxies: one address, replaceable implementation.” Published 2026-10-02; updated 2026-10-02. https://degreesofsatoshi.com/encyclopedia/contract-proxies/"
}