1. 核心模块

• Contracts（合约库）
  • ERC 标准
    • ERC20
    • ERC721
    • ERC1155
    • ERC777
    • ERC1967Upgrade
  • Governance（治理模块）
    • Governor
    • Timelock
  • Access Control（访问控制）
    • Ownable
    • AccessControl
  • Pausability（暂停功能）
    • Pausable
  • Utility Contracts（实用合约）
    • SafeMath
    • Counters
    • Strings
    • Address
  • Token 相关模块
    • ERC20Votes
    • TokenTimelock
    • TokenVesting
  • Upgradeability（可升级合约）
    • TransparentUpgradeableProxy
    • UUPSUpgradeable
• Security（安全模块）
  • ReentrancyGuard
  • PullPayment
  • Escrow
• Cryptography（加密工具）
  • ECDSA
  • MerkleProof
  • SignatureChecker

2. Subgraphs（子图模块）

• ERC 标准相关
  • ERC20 子图
  • ERC721 子图
  • ERC1155 子图
• Governance（治理相关）
  • Governor 模块子图
  • Timelock 模块子图
• Access Control（访问控制相关）
  • AccessControl 子图
  • Ownable 子图

3. 工具库

• Math
  • SafeMath
  • SignedMath
• Strings（字符串处理）
  • Base64 编码
  • 字符串转换工具
• Context（上下文工具）
• EnumerableSet（枚举集合）
• EnumerableMap（枚举映射）
• DoubleEndedQueue（双端队列）

4. 测试工具

• Test Helpers
  • Address
  • Balance
  • Token
  • Time

5. 部署工具

• Contracts Wizard（合约向导工具）
  • 模板化生成合约
• OpenZeppelin Upgrades
  • 可升级合约工具
  • Proxy 管理

6. 文档与学习资源

• 官方文档
• OpenZeppelin 学习指南
• GitHub 示例项目

TimelockController 示例及讲解

我们来创建一个带有 TimelockController 的智能合约，展示如何使用它来确保关键操作需要经过延迟执行。我们会结合 ERC20 代币合约，并通过 TimelockController 来控制谁有权提议和执行代币的铸造和销毁操作。

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

import "@openzeppelin/contracts/governance/TimelockController.sol";
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/access/AccessControl.sol";

contract TimelockControlledToken is ERC20, AccessControl {
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
    bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");

    // 使用 TimelockController 进行控制
    TimelockController public timelock;

    constructor(
        address timelockAddress, 
        address initialMinter, 
        address initialBurner
    ) ERC20("MyToken", "MTK") {
        // 设置 TimelockController 地址
        timelock = TimelockController(timelockAddress);

        // 将合约的 MINTER_ROLE 和 BURNER_ROLE 分配给 TimelockController 进行管理
        _grantRole(MINTER_ROLE, initialMinter);
        _grantRole(BURNER_ROLE, initialBurner);
    }

    // 只有具有 MINTER_ROLE 的账户才能铸造代币
    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
        _mint(to, amount);
    }

    // 只有具有 BURNER_ROLE 的账户才能销毁代币
    function burn(address from, uint256 amount) public onlyRole(BURNER_ROLE) {
        _burn(from, amount);
    }
}

contract MyTimelockController is TimelockController {
    constructor(
        uint256 minDelay,        // 最小延迟时间（秒）
        address[] memory proposers, // 提议者账户
        address[] memory executors  // 执行者账户
    ) TimelockController(minDelay, proposers, executors) {}
}

代码讲解

运行流程示例：

1. 部署 MyTimelockController：
   • 你可以设置一个最小延迟时间（例如7天），并指定哪些账户是提议者，哪些账户是执行者。

   // 部署 TimelockController，延迟时间为7天
   address[] memory proposers = [address(0x123)];
   address[] memory executors = [address(0x456)];
   MyTimelockController timelock = new MyTimelockController(7 days, proposers, executors);

2. 部署 TimelockControlledToken：
   • 将 timelock 作为代币的管理者，同时指定初始的铸币者和销毁者。

   TimelockControlledToken token = new TimelockControlledToken(address(timelock), minterAddress, burnerAddress);

3. 提交操作：
   • 提议者可以通过 TimelockController 提出铸造或销毁代币的操作。
   • 执行者在延迟结束后，可以执行提议的操作。

总结：

• TimelockController 的作用：它引入了一种延迟机制，确保系统的关键操作不会立即执行，给用户足够的时间去审查和退出系统，防止管理员恶意操作。
• 提议者和执行者：TimelockController 通过提议者和执行者的角色分离来管理操作的执行（通过写合约来实现），并允许用户对操作进行提前审查。

AccessManager 基于“角色”和“目标函数”的概念设计：

角色：多个账户可以拥有相同的角色，一个账户也可以拥有多个角色。每个角色通过数值（uint64）来标识，而不是像 AccessControl 那样使用 bytes32 类型。 目标函数：目标函数是合约中受限制的函数，只有具有特定角色的账户才能调用。 在 AccessManager 中，只有被授予角色的账户才能调用与角色相关的目标函数。调用者必须具备与目标函数相匹配的角色才能被授权执行该操作。

await manager.setTargetFunctionRole(
    tokenContractAddress,   // 目标合约地址（如 AccessManagedERC20Mint 的合约地址）
    ['0x40c10f19'],         // 函数选择器：mint(address,uint256)
    MINTER                  // 角色：MINTER_ROLE
);

函数选择器这个概念需要另起说明。

固定供应

假设我们想要创建一个具有固定供应量的代币，比如 1000 个代币，初始供应量分配给部署合约的账户。

早期的合约（如Contracts v1）可能会直接修改 totalSupply 和 balances 变量来创建固定供应量：

contract ERC20FixedSupply is ERC20 {
    constructor() {
        totalSupply += 1000;
        balances[msg.sender] += 1000;
    }
}

但从OpenZeppelin Contracts v2开始，totalSupply 和 balances 被设为私有，不能直接修改。代替的方法是使用 _mint 函数，它可以安全地创建供应并同步更新。

contract ERC20FixedSupply is ERC20 {
    constructor() ERC20("Fixed", "FIX") {
        _mint(msg.sender, 1000);
    }
}

这种方式更安全，因为 _mint 会自动处理 totalSupply 和 balances 的同步更新，并触发标准要求的 Transfer 事件，防止忘记这些操作。

ERC1155 的特点

• 多代币标准：ERC1155 的一个显著特征是，它通过一个合约管理多个代币类型。每个代币有唯一的 ID，你可以通过 balanceOf 查询某个地址持有的某个代币 ID 的余额。
• 代币可替代性：不同于 ERC721，ERC1155 可以同时表示可替代和不可替代的代币。可替代代币通过数量实现（如游戏金币），而不可替代代币只铸造一个（如唯一的物品）。
• 批量操作（Batch Operations）：ERC1155 允许在一个交易中批量操作多个代币，这大大减少了交易中的 Gas 费用。批量查询余额和批量转移代币通过 balanceOfBatch 和 safeBatchTransferFrom 实现。

// contracts/GameItems.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {ERC1155} from "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";

contract GameItems is ERC1155 {
    uint256 public constant GOLD = 0;
    uint256 public constant SILVER = 1;
    uint256 public constant THORS_HAMMER = 2;
    uint256 public constant SWORD = 3;
    uint256 public constant SHIELD = 4;

    constructor() ERC1155("https://game.example/api/item/{id}.json") {
        _mint(msg.sender, GOLD, 1018, "");
        _mint(msg.sender, SILVER, 1027, "");
        _mint(msg.sender, THORS_HAMMER, 1, "");
        _mint(msg.sender, SWORD, 109, "");
        _mint(msg.sender, SHIELD, 109, "");
    }
}

• 代币类型：该合约定义了多个代币，如 GOLD（可替代）、THORS_HAMMER（非同质化）等。通过 uint256 常量为每个代币分配一个唯一的 ID。
• 元数据：ERC1155 的构造函数中定义了代币的 tokenURI 模板，代币的具体元数据（如图像、描述等）可以通过替换 {id} 来获取。
• 铸造代币：在合约的构造函数中，初始代币被铸造并分配给合约的部署者。每种代币都有各自的数量。

关键操作

1. 查询余额：你可以通过 balanceOf 查询某个地址持有的某个代币 ID 的余额：

> gameItems.balanceOf(deployerAddress,3) // 查询持有 SWORD 代币的数量
1000000000

2. 转移代币：通过 safeTransferFrom 转移代币，指定代币 ID 和数量：

> gameItems.safeTransferFrom(deployerAddress, playerAddress, 2, 1, "0x0") // 转移 1 个 THORS_HAMMER

3. 批量转移：通过 safeBatchTransferFrom 可以批量转移多个代币

> gameItems.safeBatchTransferFrom(deployerAddress, playerAddress, [0,1,3,4], [50,100,1,1], "0x0") // 批量转移多个代币

4. 查询批量余额：通过 balanceOfBatch 批量查询多个地址、多个代币的余额：

> gameItems.balanceOfBatch([playerAddress,playerAddress,playerAddress,playerAddress,playerAddress], [0,1,2,3,4])
[50,100,1,1,1]

5. 元数据查询：通过 uri 函数获取代币的元数据 URI。{id} 会被替换为代币的 ID（以 64 位的十六进制形式表示），指向代币的具体元数据文件。

> gameItems.uri(2) // 获取 Thor's Hammer 的元数据 URI
"https://game.example/api/item/0000000000000000000000000000000000000000000000000000000000000002.json"

由于 ERC1155 允许通过一个合约管理多个代币类型，并且提供了批量操作功能，因此在处理多个代币时，ERC1155 可以极大地减少 Gas 消耗。例如，批量转移多个代币只需发起一笔交易，相比于单独调用每个代币的转移操作，大幅降低了交易成本。

代币的可替代性由其供应量和用途决定，供应量为1且独特的代币是 NFT。供应量大于1且每个代币相同的则是 虚拟货币。

通胀攻击问题

通胀攻击（Inflation Attack）是 ERC4626 金库面临的潜在安全问题之一。它利用了舍入误差和金库中股份与资产的兑换率变化，攻击者可以通过操纵资产与股份的比率，使其他用户的存款无法得到应有的股份，从而导致用户损失资产。

1. 攻击者存入少量资产：攻击者首先存入一小部分资产，这使得他们成为金库中的唯一持有人。
2. 攻击者直接捐赠大量资产：随后，攻击者直接将大量资产捐赠给金库，而不铸造新的股份。这导致金库的资产与股份的比率严重失衡（即资产数量激增但股份数量不变），使得新的存款无法获得足够的股份。
3. 用户存款受损：当其他用户存入少量资产时，由于股份的比率被攻击者的操作扭曲，用户可能得到的股份非常少甚至为零，从而造成他们的资产损失。

防御机制：虚拟偏移

为防止通胀攻击，ERC4626 可以使用虚拟偏移（Virtual Offset）的策略。这种方法通过在计算股份与资产比率时引入虚拟的资产和股份来增加安全性。

防御机制的两部分： - 精度偏移：在表示股份和资产时，使用更高的精度来减少计算时的舍入误差。 - 虚拟资产和股份：在金库刚开始为空时，使用虚拟的资产和股份来维护转换率，避免因为攻击者操控比率造成的影响。 通过这种方式，攻击者即使进行了大量捐赠，仍然无法通过操纵比率来导致用户存款的损失。

1. ERC20: 可替代代币标准

应用场景： - 虚拟货币：ERC20 是目前最常用的可替代代币标准，适用于表示像 ETH、USDT、DAI 这样的虚拟货币。这些代币可以互相替代，且每个单位都具有相同的价值。 - 去中心化金融（DeFi）：ERC20 代币被广泛用于 DeFi 应用中，包括借贷平台、流动性挖矿、收益聚合器等。用户可以用 ERC20 代币进行交易、抵押、借贷和流动性提供。 - 支付系统：ERC20 代币可以作为支付手段，用于商品或服务的购买。这些代币是可替代的，因此非常适合支付场景。

典型应用： - 虚拟货币：USDT、DAI、UNI、LINK 等。 - DeFi 平台：Aave、Compound、Uniswap 等平台都使用 ERC20 代币进行流动性提供和交易。

2. ERC721: 非同质化代币（NFT）标准

应用场景： - 数字收藏品和艺术品：ERC721 标准用于表示每个代币都是独一无二的，如 CryptoKitties、数字艺术品（如 Beeple 的作品）等。每个代币都有其独特的属性和价值。 - 虚拟地产：在 Decentraland、The Sandbox 等元宇宙平台中，虚拟土地使用 ERC721 标准，因为每块土地都是独特的、不可替代的。 - 游戏道具：在区块链游戏中，ERC721 代币可以表示独特的游戏道具，如角色、装备等，这些物品不可互换。

典型应用： - NFT 项目：CryptoPunks、Bored Ape Yacht Club、Art Blocks 等。 - 元宇宙项目：Decentraland、The Sandbox 等。

3. ERC1155: 多代币标准

应用场景： - 游戏道具和资产：ERC1155 允许同时管理可替代和不可替代的代币，非常适合区块链游戏。在游戏中，像金币（可替代的）和独特武器（不可替代的）可以通过一个合约来管理，极大节省了 Gas 费用。 - 批量交易和管理：ERC1155 支持批量转移多个代币，因此特别适合那些需要一次性处理多个代币交易的场景，如游戏内奖励发放或批量交易收藏品。 - 数字收藏品：ERC1155 可以用于管理同一系列中的多个收藏品，每个代币可以是独一无二的（NFT），也可以是相同的（如游戏代币）。

典型应用： - 区块链游戏：Gods Unchained、Enjin、Axie Infinity 等。 - 批量交易收藏品：支持批量发行和交易的数字收藏品平台。

4. ERC4626: 金库代币标准

应用场景： - 收益聚合器和金库：ERC4626 是专门为代币化金库设计的标准，它允许用户将资产存入金库并获得相应的股份，股份代表了金库中的资产份额。它适用于收益聚合器（如 Yearn Finance）等场景，用户可以存入资产赚取利息或其他收益。 - 借贷平台：ERC4626 可以用于借贷市场，允许用户存入抵押资产并获得股份，股份的价值会随金库中资产的变化而变化。 - 自动化收益策略：用户可以通过存入资产参与 DeFi 策略，金库会自动执行收益最大化的策略，并按比例分发给所有股份持有人。

典型应用： - Yearn Finance：用户存入 ERC20 代币，金库会自动将资金分配给各种收益策略并返还股份。 - 借贷市场：Compound、Aave 等平台可以基于 ERC4626 来管理用户的存款和利息分配。

总结表格：

通过这些标准，你可以根据不同的应用场景选择合适的代币标准进行开发。

OpenZeppelin Governance 模块的主要功能和组件

1. 提案与投票机制（Proposals and Voting）：
   • 提案（Proposal）：持有治理代币的用户可以发起提案，建议对项目进行某些更改，比如修改某个合约的参数，或者分配资金。每个提案包含执行这些更改的具体步骤。
   • 投票（Voting）：项目中的代币持有者可以对提案进行投票。通常，投票权与用户所持有的治理代币数量成正比，也就是说持有更多代币的用户有更大的投票权。
   • 投票方式：OpenZeppelin 提供了多种投票方式，包括简单多数制投票、加权投票、时间锁投票等，确保治理过程的灵活性和透明度。
2. 执行决策（Execution of Decisions）：
   • 一旦提案通过，系统会执行提案中规定的动作。OpenZeppelin Governance 模块允许用户将投票结果自动转化为链上操作，如调用合约函数、转移代币等。这种自动化执行的功能是区块链治理的重要特性，避免了中心化机构的干预。
3. 治理代币（Governance Tokens）：
   • 治理代币是治理机制的核心，持有这些代币的用户可以参与项目的管理决策。通过持有代币，用户可以获得提案权和投票权。这些代币通常是ERC20标准的代币。
   • 有时，代币的投票权还会根据锁仓时间等因素进行调整，持有时间越长，投票权越大。
4. 时间锁（Timelocks）：
   • 时间锁 是治理中的一个关键机制，用于确保在某个决策被批准后，执行操作前有一定的延迟时间。这段时间允许社区成员审查和讨论即将执行的提案，确保安全性，防止突然的恶意更改。
   • 时间锁还可以为治理提供透明度，允许所有利益相关者在提案生效前看到结果。
5. 代理投票（Delegation）：
   • OpenZeppelin 的治理模块允许代币持有者将他们的投票权委托给其他人。这个功能对于那些不想频繁参与日常治理活动的用户非常重要，因为他们可以将自己的投票权转移给他们信任的人。
6. 治理模块的扩展性：
   • OpenZeppelin 的治理模块是可扩展的，你可以根据项目的需求调整治理逻辑、投票规则、时间锁设置等。开发者可以使用OpenZeppelin的合约基础，创建符合项目需求的治理机制。

使用场景

OpenZeppelin 的治理模块通常用于去中心化自治组织（DAO），DeFi 项目，和其他依赖社区决策的区块链项目。以下是一些典型的使用场景： - 去中心化金融（DeFi）项目：比如在一个DeFi协议中，治理代币持有者可以通过提案决定协议的参数修改，流动性奖励分配，或者资金池的管理。 - 协议升级：当区块链协议需要升级时，治理模块允许社区投票决定是否接受新的合约部署。 - 资金管理：DAO项目中，社区成员可以通过提案和投票决定如何使用项目的资金，或者如何激励开发者。

总结：

OpenZeppelin 的 Governance 模块提供了一种可靠和灵活的机制，使项目能够通过去中心化的方式管理自身。它通过提案、投票、时间锁等方式，确保了治理过程的透明性和社区参与度。治理代币持有者可以对项目的未来进行表决，并通过智能合约直接执行这些决策，使治理过程公开、公平且高效。

这个治理模块非常适合任何希望实施去中心化管理的项目，尤其是DAO或去中心化金融（DeFi）协议。

Cryptography（密码学）

1. 签名验证（Checking Signatures On-Chain）： - ECDSA 用于恢复和管理以太坊账户的ECDSA签名。签名通常通过 web3.eth.sign 生成，是一个包含65字节数组的签名，结构为 [v, r, s]。 - 通过 ECDSA.recover 可以恢复签名者的地址并与目标地址进行对比，验证签名的合法性。签名验证时，需要使用 toEthSignedMessageHash 方法处理带有以太坊前缀的签名数据。

using ECDSA for bytes32;
using MessageHashUtils for bytes32;

function _verify(bytes32 data, bytes memory signature, address account) internal pure returns (bool) {
    return data
        .toEthSignedMessageHash()
        .recover(signature) == account;
}

Verifying Merkle Proofs（验证Merkle证明）

• MerkleProof 提供以下方法：
  • verify：证明某个值属于Merkle树的一部分。
  • multiProofVerify：证明多个值属于Merkle树的一部分。

Introspection（接口检测）

• ERC165 是一个标准，用于在运行时检测合约是否支持某个接口。
  • IERC165 定义了 supportsInterface 方法。
  • ERC165 可以继承该合约实现接口检测功能。
  • ERC165Checker 简化了检查合约是否支持特定接口的过程。

using ERC165Checker for address;

myAddress._supportsInterface(bytes4)
myAddress._supportsAllInterfaces(bytes4[])

contract MyContract {
    using ERC165Checker for address;
    bytes4 private InterfaceId_ERC721 = 0x80ac58cd;

    function transferERC721(
        address token,
        address to,
        uint256 tokenId
    ) public {
        require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN");
        IERC721(token).transferFrom(address(this), to, tokenId);
    }
}

Math（数学操作）

• OpenZeppelin 提供了 Math 和 SignedMath 库，用于处理额外的数学运算，如求平均值。它还支持有符号整数的运算。

contract MyContract {
    using Math for uint256;
    using SignedMath for int256;

    function tryOperations(uint256 a, uint256 b) internal pure {
        (bool overflowsAdd, uint256 resultAdd) = x.tryAdd(y);
        (bool overflowsSub, uint256 resultSub) = x.trySub(y);
        (bool overflowsMul, uint256 resultMul) = x.tryMul(y);
        (bool overflowsDiv, uint256 resultDiv) = x.tryDiv(y);
    }

    function unsignedAverage(int256 a, int256 b) {
        int256 avg = a.average(b);
    }
}

Structures（数据结构）

OpenZeppelin 提供增强的数据结构： - BitMaps：用于存储布尔值。 - Checkpoints：记录并查找检查点的值。 - DoubleEndedQueue：支持队列操作的双端队列。 - EnumerableSet/EnumerableMap：支持枚举操作的集合和映射，可以轻松查询链上和链下的存储内容。

Misc（杂项）

Base64： - 将 bytes32 数据转为 Base64 字符串，适用于ERC721或ERC1155中生成URL安全的 tokenURI。

import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
import {Base64} from "@openzeppelin/contracts/utils/Base64.sol";

contract My721Token is ERC721 {
    using Strings for uint256;

    constructor() ERC721("My721Token", "MTK") {}

    function tokenURI(uint256 tokenId) public pure override returns (string memory) {
        bytes memory dataURI = abi.encodePacked(
            '{',
            '"name": "My721Token #', tokenId.toString(), '"',
            '}'
        );
        return string(
            abi.encodePacked(
                "data:application/json;base64,",
                Base64.encode(dataURI)
            )
        );
    }
}

Multicall（多重调用）

• Multicall 合约允许将多个调用打包成一个外部调用，方便外部账户在一次交易中进行多个操作。

import "@openzeppelin/contracts/utils/Multicall.sol";

contract Box is Multicall {
    function foo() public {}
    function bar() public {}
}

使用 multicall 函数进行批量调用的示例：

const Box = artifacts.require('Box');
const instance = await Box.new();

await instance.multicall([
    instance.contract.methods.foo().encodeABI(),
    instance.contract.methods.bar().encodeABI()
]);

总结：

OpenZeppelin 提供了大量的实用工具和库，包括加密、数学操作、接口检测、数据结构以及多重调用等。这些工具帮助开发者快速、安全地开发区块链应用，减少代码冗余并提升效率。

实际用途：

• 区块链项目监控：如果你开发了一个基于区块链的项目（比如发行代币、部署智能合约等），你可能想实时了解项目上的合约运行情况，比如查询所有的代币转移记录、智能合约执行情况等，Subgraph 可以自动帮你把这些活动整理成数据，并提供接口让你轻松查询。

• 去中心化应用（DApp）数据查询：你可以使用 Subgraph 记录和查询你 DApp 的用户行为、代币余额变化等操作，方便在前端展示信息。

简而言之，Subgraph 就是一个自动化工具，帮助你记录和查询区块链合约活动的数据，让你能够轻松访问和分析这些数据，而不必自己编写复杂的监听和处理代码。