Subscribe to Untitled

<100 subscribers

Subscribe to Untitled

<100 subscribers

老道的学习日志

是什么

众所周知，智能合约部署上链后代码不可改变，但总是会有需要加功能、bug维护、优化gas之类的时候，而且还要减少用户迁移带来的成本。因此有了'可升级'合约，而可升级并不是说修改旧的合约，而是通过将状态与逻辑分离，在保持同一地址对外服务的前提下替换逻辑合约。

怎么搞

代理模式：
- 用户与代理合约进行交互
- 代理在fallback中使用delegatecall将调用委托给逻辑合约
- 逻辑代码在代理的执行上下文里运行，因此状态（存储）保存在代理，而逻辑可替换，实现“状态-逻辑解耦”。设计时要特别注意存储冲突与函数选择器冲突（尤其是管理函数与业务函数的选择器重叠问题）

主流模式

Transparent 透明代理：用户调用都转发给逻辑合约；只有管理员地址调用时，代理自身的管理函数（如 upgradeTo）才会被执行。常与 ProxyAdmin 管理合约配合使用，优点是维护直观、生态成熟，但部署与运行略重。
UUPS（EIP-1822）：升级逻辑下沉到逻辑合约自身（实现 upgradeTo 等），代理更轻；需谨慎实现授权钩子，确保只有预期角色可升级。相较 Transparent，UUPS 部署成本更低，但对实现者规范性要求更高。

一句话总结：新项目优先 UUPS（轻量、直观）；若你需要与现有工具链/审计实践完全对齐，也可选 Transparent。

上手

UUPS 实战项目

项目结构

code/
├── contracts/
│   ├── MyUUPSV1.sol      # V1实现合约
│   ├── MyUUPSV2.sol      # V2实现合约（新功能）
│   └── SimpleProxy.sol   # 简化的代理合约
├── scripts/
│   └── upgrade-demo.ts   # 完整的升级演示脚本
├── test/
│   └── UUPS-Upgrade.test.ts  # 全面的测试套件
└── ignition/modules/
    ├── MyUUPSV1.ts      # V1部署模块
    └── MyUUPSV2.ts      # V2升级模块

核心合约实现

MyUUPSV1.sol - 初始版本

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

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

contract MyUUPSV1 is Initializable, UUPSUpgradeable, OwnableUpgradeable {
    uint256 public value;

    function initialize(uint256 _value) public initializer {
        __Ownable_init(msg.sender);
        __UUPSUpgradeable_init();
        value = _value;
    }

    function setValue(uint256 _value) public {
        value = _value;
    }

    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}
}

MyUUPSV2.sol - 升级版本

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

import "./MyUUPSV1.sol";

contract MyUUPSV2 is MyUUPSV1 {
    // 新增状态变量（注意存储布局）
    string public name;
    uint256 public counter;

    // V2的初始化函数
    function initializeV2(string memory _name) public reinitializer(2) {
        name = _name;
        counter = 0;
    }

    // 新增功能：计数器操作
    function increment() public {
        counter++;
    }

    function decrement() public {
        require(counter > 0, "Counter cannot be negative");
        counter--;
    }

    // 新增功能：设置名称
    function setName(string memory _name) public {
        name = _name;
    }

    // 版本信息
    function getVersion() public pure returns (string memory) {
        return "v2.0.0";
    }
}

关键实现要点

1. 存储布局兼容性

V2继承V1，确保存储槽位置不变
新状态变量添加在原有变量之后
使用reinitializer(2)初始化新变量

2. 升级授权

function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}

只有合约所有者可以执行升级
在V1和V2中都需要实现此函数

3. 代理部署

// 部署实现合约
const MyUUPSV1 = await ethers.getContractFactory("MyUUPSV1");
const v1Implementation = await MyUUPSV1.deploy();

// 编码初始化数据
const initData = v1Implementation.interface.encodeFunctionData("initialize", [100]);

// 部署代理
const SimpleProxy = await ethers.getContractFactory("SimpleProxy");
const proxy = await SimpleProxy.deploy(v1Implementation.target, initData);

4. 升级流程

// 部署V2实现
const MyUUPSV2 = await ethers.getContractFactory("MyUUPSV2");
const v2Implementation = await MyUUPSV2.deploy();

// 编码V2初始化数据
const initV2Data = v2Implementation.interface.encodeFunctionData("initializeV2", ["UUPS Demo Contract"]);

// 执行升级
const v1Proxy = MyUUPSV1.attach(proxy.target);
await v1Proxy.upgradeToAndCall(v2Implementation.target, initV2Data);

测试验证

完整测试套件

describe("UUPS Upgrade Test", function () {
  it("应该成功部署V1合约", async function () {
    // 部署测试
  });

  it("应该能够使用V1功能", async function () {
    // V1功能测试
  });

  it("应该成功升级到V2", async function () {
    // 升级测试
  });

  it("应该能够使用V2的新功能", async function () {
    // V2新功能测试
  });

  it("应该保持V1的原有功能", async function () {
    // 向后兼容性测试
  });

  it("计数器不应该允许负数", async function () {
    // 边界条件测试
  });
});

演示结果

成功的升级流程

🚀 开始UUPS可升级合约演示...
📦 部署V1实现合约... ✅
📦 部署代理合约... ✅
🔍 测试V1功能: 初始值: 100, 设置新值后: 200 ✅
📦 部署V2实现合约... ✅
⬆️  升级到V2... ✅
🔧 初始化V2新功能... ✅
🔍 验证升级后的状态:
   升级后的值 (应该保持不变): 200 ✅
   版本信息: v2.0.0 ✅
   合约名称: UUPS Demo Contract ✅
   计数器初始值: 0 ✅
🆕 测试V2新功能:
   增加计数器后: 2 ✅
   减少计数器后: 1 ✅
   更新后的名称: 升级成功的UUPS合约 ✅
🔄 验证V1功能仍然可用: 最终值: 500 ✅

测试结果

✅ 6个测试全部通过
✅ 状态完美保持
✅ 新功能正常工作
✅ 向后兼容性良好

核心优势

状态保持 - 升级后V1的状态完全保持
新功能添加 - V2成功添加了计数器和名称功能
向后兼容 - V1的所有功能在升级后依然可用
安全升级 - 只有合约所有者可以执行升级
完整测试 - 覆盖了所有升级场景和边界条件

最佳实践

存储布局 - 新版本只能在末尾添加状态变量
初始化器 - 使用reinitializer为新版本初始化新变量
权限控制 - 严格控制升级权限，通常限制为合约所有者
测试覆盖 - 全面测试升级前后的功能和状态保持
渐进升级 - 分步骤验证每个升级环节

💡 实战总结：UUPS模式通过将升级逻辑下沉到实现合约，实现了轻量级的可升级方案。关键在于正确处理存储布局、权限控制和状态迁移。
一句话总结：UUPS + 多签 + Timelock 是当前最实用的可升级治理组合：代码上用初始化器替代构造器、架构上用代理解耦状态与逻辑、流程上用多签与延时把风险“物理隔离”。

参考文献

老道的学习日志

是什么

怎么搞

代理模式：
- 用户与代理合约进行交互
- 代理在fallback中使用delegatecall将调用委托给逻辑合约
- 逻辑代码在代理的执行上下文里运行，因此状态（存储）保存在代理，而逻辑可替换，实现“状态-逻辑解耦”。设计时要特别注意存储冲突与函数选择器冲突（尤其是管理函数与业务函数的选择器重叠问题）

主流模式

Transparent 透明代理：用户调用都转发给逻辑合约；只有管理员地址调用时，代理自身的管理函数（如 upgradeTo）才会被执行。常与 ProxyAdmin 管理合约配合使用，优点是维护直观、生态成熟，但部署与运行略重。
UUPS（EIP-1822）：升级逻辑下沉到逻辑合约自身（实现 upgradeTo 等），代理更轻；需谨慎实现授权钩子，确保只有预期角色可升级。相较 Transparent，UUPS 部署成本更低，但对实现者规范性要求更高。

一句话总结：新项目优先 UUPS（轻量、直观）；若你需要与现有工具链/审计实践完全对齐，也可选 Transparent。

上手

UUPS 实战项目

项目结构

code/
├── contracts/
│   ├── MyUUPSV1.sol      # V1实现合约
│   ├── MyUUPSV2.sol      # V2实现合约（新功能）
│   └── SimpleProxy.sol   # 简化的代理合约
├── scripts/
│   └── upgrade-demo.ts   # 完整的升级演示脚本
├── test/
│   └── UUPS-Upgrade.test.ts  # 全面的测试套件
└── ignition/modules/
    ├── MyUUPSV1.ts      # V1部署模块
    └── MyUUPSV2.ts      # V2升级模块

核心合约实现

MyUUPSV1.sol - 初始版本

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

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

contract MyUUPSV1 is Initializable, UUPSUpgradeable, OwnableUpgradeable {
    uint256 public value;

    function initialize(uint256 _value) public initializer {
        __Ownable_init(msg.sender);
        __UUPSUpgradeable_init();
        value = _value;
    }

    function setValue(uint256 _value) public {
        value = _value;
    }

    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}
}

MyUUPSV2.sol - 升级版本

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

import "./MyUUPSV1.sol";

contract MyUUPSV2 is MyUUPSV1 {
    // 新增状态变量（注意存储布局）
    string public name;
    uint256 public counter;

    // V2的初始化函数
    function initializeV2(string memory _name) public reinitializer(2) {
        name = _name;
        counter = 0;
    }

    // 新增功能：计数器操作
    function increment() public {
        counter++;
    }

    function decrement() public {
        require(counter > 0, "Counter cannot be negative");
        counter--;
    }

    // 新增功能：设置名称
    function setName(string memory _name) public {
        name = _name;
    }

    // 版本信息
    function getVersion() public pure returns (string memory) {
        return "v2.0.0";
    }
}

关键实现要点

1. 存储布局兼容性

V2继承V1，确保存储槽位置不变
新状态变量添加在原有变量之后
使用reinitializer(2)初始化新变量

2. 升级授权

function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}

只有合约所有者可以执行升级
在V1和V2中都需要实现此函数

3. 代理部署

// 部署实现合约
const MyUUPSV1 = await ethers.getContractFactory("MyUUPSV1");
const v1Implementation = await MyUUPSV1.deploy();

// 编码初始化数据
const initData = v1Implementation.interface.encodeFunctionData("initialize", [100]);

// 部署代理
const SimpleProxy = await ethers.getContractFactory("SimpleProxy");
const proxy = await SimpleProxy.deploy(v1Implementation.target, initData);

4. 升级流程

// 部署V2实现
const MyUUPSV2 = await ethers.getContractFactory("MyUUPSV2");
const v2Implementation = await MyUUPSV2.deploy();

// 编码V2初始化数据
const initV2Data = v2Implementation.interface.encodeFunctionData("initializeV2", ["UUPS Demo Contract"]);

// 执行升级
const v1Proxy = MyUUPSV1.attach(proxy.target);
await v1Proxy.upgradeToAndCall(v2Implementation.target, initV2Data);

测试验证

完整测试套件

describe("UUPS Upgrade Test", function () {
  it("应该成功部署V1合约", async function () {
    // 部署测试
  });

  it("应该能够使用V1功能", async function () {
    // V1功能测试
  });

  it("应该成功升级到V2", async function () {
    // 升级测试
  });

  it("应该能够使用V2的新功能", async function () {
    // V2新功能测试
  });

  it("应该保持V1的原有功能", async function () {
    // 向后兼容性测试
  });

  it("计数器不应该允许负数", async function () {
    // 边界条件测试
  });
});

演示结果

成功的升级流程

🚀 开始UUPS可升级合约演示...
📦 部署V1实现合约... ✅
📦 部署代理合约... ✅
🔍 测试V1功能: 初始值: 100, 设置新值后: 200 ✅
📦 部署V2实现合约... ✅
⬆️  升级到V2... ✅
🔧 初始化V2新功能... ✅
🔍 验证升级后的状态:
   升级后的值 (应该保持不变): 200 ✅
   版本信息: v2.0.0 ✅
   合约名称: UUPS Demo Contract ✅
   计数器初始值: 0 ✅
🆕 测试V2新功能:
   增加计数器后: 2 ✅
   减少计数器后: 1 ✅
   更新后的名称: 升级成功的UUPS合约 ✅
🔄 验证V1功能仍然可用: 最终值: 500 ✅

测试结果

✅ 6个测试全部通过
✅ 状态完美保持
✅ 新功能正常工作
✅ 向后兼容性良好

核心优势

状态保持 - 升级后V1的状态完全保持
新功能添加 - V2成功添加了计数器和名称功能
向后兼容 - V1的所有功能在升级后依然可用
安全升级 - 只有合约所有者可以执行升级
完整测试 - 覆盖了所有升级场景和边界条件

最佳实践

存储布局 - 新版本只能在末尾添加状态变量
初始化器 - 使用reinitializer为新版本初始化新变量
权限控制 - 严格控制升级权限，通常限制为合约所有者
测试覆盖 - 全面测试升级前后的功能和状态保持
渐进升级 - 分步骤验证每个升级环节

💡 实战总结：UUPS模式通过将升级逻辑下沉到实现合约，实现了轻量级的可升级方案。关键在于正确处理存储布局、权限控制和状态迁移。
一句话总结：UUPS + 多签 + Timelock 是当前最实用的可升级治理组合：代码上用初始化器替代构造器、架构上用代理解耦状态与逻辑、流程上用多签与延时把风险“物理隔离”。

No activity yet

Untitled

No activity yet

可升级合约从入门到上线：UUPS + 多签 + Timelock 一把梭

可升级合约从入门到上线：UUPS + 多签 + Timelock 一把梭

是什么

怎么搞

主流模式

上手

UUPS 实战项目

项目结构

核心合约实现

MyUUPSV1.sol - 初始版本

MyUUPSV2.sol - 升级版本

关键实现要点

1. 存储布局兼容性

2. 升级授权

3. 代理部署

4. 升级流程

测试验证

完整测试套件

演示结果

成功的升级流程

测试结果

核心优势

最佳实践

参考文献

是什么

怎么搞

主流模式

上手

UUPS 实战项目

项目结构

核心合约实现

MyUUPSV1.sol - 初始版本

MyUUPSV2.sol - 升级版本

关键实现要点

1. 存储布局兼容性

2. 升级授权

3. 代理部署

4. 升级流程

测试验证

完整测试套件

演示结果

成功的升级流程

测试结果

核心优势

最佳实践

参考文献

No activity yet

No activity yet