Skip to content
Financial Context Wiki

Proxy contract

A proxy contract forwards calls to implementation code while keeping the proxy address and state. Learn how proxy patterns work and where upgrade, storage, and admin risks arise.

Updated

For educational purposes only; not investment advice. Investing may result in loss.

Direct answer

A proxy contract is an intermediary contract that forwards calls to another contract, usually called the implementation or logic contract. In a common EVM design, the proxy uses delegatecall, so the implementation’s code runs in the proxy’s context while state and balances remain at the proxy address.

This indirection lets a system keep a stable user-facing address while changing its implementation. It can also reduce deployment cost when many proxies share code. A proxy is not automatically upgradeable: some minimal proxies point permanently to one implementation, while upgradeable proxies add a controlled way to change the implementation or beacon.

Users must therefore evaluate both the active implementation and the authority that can change it. Verified proxy bytecode alone does not establish what code will execute tomorrow.

How it works

When a call reaches the proxy, its fallback path copies or forwards the call data to an implementation. With delegatecall, address(this) is the proxy, storage reads and writes affect the proxy, and the original msg.sender and msg.value are preserved. The proxy then returns or reverts with the implementation’s returned data.

Because proxy metadata shares the proxy’s storage space with application state, standardized slots help avoid accidental collisions. ERC-1967 defines slots for an implementation address, a beacon address, and an optional admin, and recommends events when those values change. The standard makes proxies easier to inspect; it does not make an upgrade safe by itself.

Common designs place upgrade authority in different locations:

  • Transparent proxy: the proxy distinguishes administrative calls from ordinary user calls, commonly through a separate admin contract.
  • UUPS proxy: upgrade logic lives in the implementation, which must authorize changes and remain compatible with the expected upgrade interface.
  • Beacon proxy: the proxy asks a beacon for its implementation; changing one beacon can affect every proxy that follows it.
  • Minimal clone: many small proxies delegate to shared code, often with no upgrade path at all.

Example

Suppose a vault proxy holds user balances and delegates to implementation A. Users deposit through the proxy address, and implementation A’s code updates balance records in the proxy’s storage.

Governance later changes the ERC-1967 implementation slot to implementation B. The proxy address and recorded balances do not move, but future calls execute implementation B’s code. If B preserves the storage layout and implements the intended rules, users see new behavior at the same address.

If B reorders storage variables, omits an authorization check, or adds a withdrawal path controlled by the upgrader, the same upgrade can corrupt accounting or expose assets. The operational question is therefore not merely whether a contract is a proxy, but who can change its execution path, under what delay, and with what verification.

Risks

  • Upgrade-key compromise: an administrator, multisig, or governance process may install malicious or defective code.
  • Storage-layout incompatibility: changing variable order, types, or inheritance can cause new code to misread or overwrite existing state.
  • Initialization failure: constructors do not initialize proxy storage; missing or replayable initializer protections can let another account claim privileged roles.
  • Call-routing surprises: function-selector clashes, admin-specific routing, or an unexpected beacon can make the executed path differ from the visible interface.
  • Shared upgrade blast radius: one beacon or implementation decision may change many contract instances at once.

Before depositing assets or granting approvals, resolve the current implementation or beacon on-chain, identify upgrade authority and any timelock, review verified source and storage compatibility, and inspect recent Upgraded, BeaconUpgraded, and AdminChanged events where applicable. Monitoring remains necessary after the first review because the execution path can change.

Common misconceptions

  • “The proxy stores no meaningful state.” Under delegatecall, application state and often assets belong to the proxy even though logic comes from another address.
  • “A verified implementation makes the system trustless.” Upgrade keys, governance, beacons, initialization, and future implementations remain part of the trust model.
  • “Every proxy can be upgraded.” Clones and other fixed proxies may delegate permanently; upgradeability depends on the specific design and authorization code.

Sources

Navigation

Search the wiki...