📜 Proxy Contracts

Proxy contracts let you keep the same contract address while changing the code that runs behind it. Users and integrations always call the same address; only the implementation (logic) is swapped. This is the standard way to build upgradeable smart contracts on the EVM.

🎯 Why Proxies

• Bug fixes — Deploy a new implementation and point the proxy to it
• New features — Add functions or change logic without migrating state
• Same address — Integrations, frontends, and users keep using the original contract address

📚 Core Idea

User → Proxy (fixed address) → Implementation (replaceable)
         │
         └── holds state (storage)
         └── delegatecall() to implementation

• Proxy — Holds state (storage layout) and uses delegatecall to run the implementation’s code in its own context
• Implementation — Contains the logic; has no state of its own (storage lives in the proxy)
• Critical — Implementation and upgrades must preserve storage layout  to avoid corruption

📝 Common Patterns

🔧 OpenZeppelin Upgrades (Hardhat)

Install:

npm install --save-dev @openzeppelin/hardhat-upgrades

Config:

// hardhat.config.js
require("@openzeppelin/hardhat-upgrades");

Deploy as upgradeable:

// scripts/deploy.js
const { ethers, upgrades } = require("hardhat");
 
async function main() {
  const MyContract = await ethers.getContractFactory("MyContract");
  const proxy = await upgrades.deployProxy(MyContract, [/* constructor args */], {
    kind: "uups", // or "transparent"
  });
  await proxy.waitForDeployment();
 
  console.log("Proxy at", await proxy.getAddress());
}
 
main().catch(console.error);

Upgrade later:

// scripts/upgrade.js
const { ethers, upgrades } = require("hardhat");
 
async function main() {
  const proxyAddress = "0x...";
  const MyContractV2 = await ethers.getContractFactory("MyContractV2");
  const upgraded = await upgrades.upgradeProxy(proxyAddress, MyContractV2);
  console.log("Upgraded to", await upgraded.getAddress());
}
 
main().catch(console.error);

⚠️ Security Notes

• Storage layout — Never remove or reorder existing storage variables; only append. See OpenZeppelin upgrades docs .
• Initializers — Use initializer instead of constructor for upgradeable contracts so the implementation isn’t constructed twice.
• Access control — Restrict who can upgrade (owner, multisig, timelock).

🔗 Resources

• EIP-1822: UUPS 
• OpenZeppelin: Proxies 
• OpenZeppelin: Upgrades Plugins 
• Writing upgradeable contracts