从foundry工程化的角度详细解读Openzeppelin中的Address库及对应测试。
从foundry工程化的角度详细解读Openzeppelin中的StorageSlot库及对应测试。
从foundry工程化的角度详细解读Openzeppelin中的Arrays库及对应测试。
从foundry工程化的角度详细解读Openzeppelin中的Base64库及对应测试。
从foundry工程化的角度详细解读Openzeppelin中的Counters库及对应测试。
从foundry工程化的角度详细解读Openzeppelin中的Strings库及对应测试。
从foundry工程化的角度详细解读Openzeppelin中的Timers库及对应测试。
Context库是合约开发中最常见的库,同时也是最让人迷惑的库。合约代码里面只将msg.sender和msg.data封装成了函数,感觉多此一举。实际上,本库不提供任何context环境切换的细节功能,而是需要目标合约中重写这两个函数起到了可编辑msg.sender和msg.data的目的。
Multicall库提供了一个`multicall(bytes[] calldata data)`方法,通过该方法可以由调用者在一笔交易中自由组合调用本合约的各个可外部调用的方法。
Create2库本质就是对EVM opcode CREATE2进行的一个封装,可以让开发者在非内联汇编环境下直接使用该opcode。 CREATE2是一种可提前计算合约部署地址的合约部署opcode。而传统的合约部署是通过opcode CREATE完成的。
Math库为合约开发提供了solidity内置的uint256运算以外的其他整形运算方法。solidity内置的整形运算,每一步都会做overflow revert(除非unchecked{}),而Math库会在不影响结果准确性的前提下利用位溢出进行更加tricky的操作。
SafeCast库提供了solidity的基础整数类型uintX和intX之间的类型安全转换的库方法。在不同的类型转换之间都加入溢出检查,如果一旦在转换过程中出现类型的溢出会立刻revert。
Checkpoints库定义了History、Trace224和Trace160结构体。这些结构体中包含了在各个不同的区块高度或自定义key上记录的数值并可以查询出对应区块高度或key上的记录值。Checkpoints库提供了标准的添加记录、查询记录的库方法。
SafeMath库是对solidity中uint256的加、减、乘、除和取模运算的一层封装。由于solidity 0.8之前的uint256运算是不做溢出检查,许多基于0.8版本之前的项目都会使用该库。0.8版本之后solidity编译器内置了整形数溢出检查,所以SafeMath库也不再被广泛使用。
SignedMath库提供了solidity中尚未内置的标准有符号数的数学运算方法。
SignedSafeMath库就是直接对solidity内置的int256类型的加减乘除运算的函数封装。
BitMaps库开发了一种存储更紧凑且高效的mapping(uint256=>bool)。传统的mapping(uint256=>bool)中一个slot只能存储一个键值对的bool值信息,而改用了BitMaps.BitMap数据结构后,一个slot理论上最多可以存256个键值对的bool值信息。
DoubleEndedQueue库提供了双向队列的数据结构及对应操作库函数,提供了队头或队尾插入及弹出元素值等逻辑功能。本库采用优化过的storage存储且所有操作的时间复杂度都是O(1)。特别要注意的是库中的clear操作仅仅将队头和队尾指针清零,而之前队列中的元素值依然留存在storage中
EnumerableSet库提供了Bytes32Set、AddressSet和UintSet三种类型的set,分别适用于bytes32、address和uint256类型的元素。 每种set都提供了对应的增添元素、删除元素、查询当前set中元素个数等操作。几乎所有操作的时间复杂度均为O(1)。
EnumerableMap库提供了Bytes32ToBytes32Map、UintToUintMap、UintToAddressMap、AddressToUintMap和Bytes32ToUintMap五种可迭代的map。每种map都提供了增添/更新键值及查询等操作且所有操作的时间复杂度为O(1)。
ERC165合约是IERC165的标准实现。ERC165提供了本合约是否实现了IERC165接口的查询。如果需要额外支持其他interface,可在目标合约内重写supportsInterface(bytes4)方法。
内联汇编中,Instruction "staticcall"的功能及使用方法与Instruction "call"类似。唯一不同的是在"staticcall"的过程中不允许发生storage的修改。
ERC165Checker库是用来查询已实现IERC165的目标合约自身实现了哪些interface的工具库。在使用时需要注意:利用ERC165Checker提供的查询方法进行查询的过程不会因为目标合约没有实现待查询interface而发生revert。
ERC165Storage合约是ERC165的一种拓展。IERC165的supportsInterface(bytes4)函数的标准实现方式是静态地将已实现接口的interface id硬编码到bytecode中,而ERC165Storage则可在合约部署后动态地添加支持的interface id。
IERC1820Registry.sol是global ERC1820 Registry的接口文件。ERC1820 Registry旨在创建一个全网唯一的interface与对应implementer的查询中心。所有地址都可以在其中注册interface与对应implementer的关联关系。
ERC1820Implementer合约是对IERC1820Implementer interface的实现。该合约往往与ERC1820Registry合约配合使用。如果想要合约成为ERC1820Registry记录在案的implementer,需要目标合约继承ERC1820Implementer。
Escrow合约是Openzeppelin中所有escrow拓展库的基础合约,用于为指定地址锁存eth和提取eth的托管场景。该合约中存入和取出eth的方法都被virtual修饰,开发者可以通过继承重写的方式来做相关修改。
ConditionalEscrow合约继承了Escrow合约,是其的一种功能拓展。ConditionalEscrow的框架中提供设置可withdraw条件,并且只有在满足该条件时才允许owner为对应payee提取eth。
RefundEscrow合约继承了ConditionalEscrow合约,是ConditionalEscrow合约的一种功能拓展。RefundEscrow合约提供了基础的存取eth功能,同时合约owner可以将合约切换到Refunding或Closed状态。
ECDSA(Elliptic Curve Digital Signature Algorithm)是椭圆曲线数字签名算法的简称。ECDSA库十分重要且使用广泛,其作用是在链上验证某message是否由给定的地址的私钥持有者进行签名的。简而言之,ECDSA库是一个验证地址真实身份的工具库。
IERC1271是合约地址作为signer的签名验证标准。EOA地址可以通过其私钥对msg进行签名,而合约地址理论上是没有私钥的。当合约地址作为msg.sender时,可以通过IERC1271标准进行相关的签名验证工作。
SignatureChecker库是一个用于链上签名验证的helper库。该库提供的验签函数既支持EOA账户地址的签名验证也支持IERC1271标准合约地址的签名验证。
EIP-712是一个专门用于对结构化数据求hash值以及签名的标准,大大解决了数据“链下签名+链上验证”的问题并提高了链上消息签名的可用性。EIP712合约提供了EIP 712 domain separator的定义与获取——是结构化数据完整编码的一部分。
MerkleProof库提供了用于验证merkle树proof的工具函数。在生成merkle树和对应proof时应当避免使用64字节长度的leaf(进行hash之前)或避免使用非keccak256的哈希函数(进行leaf的hash计算)。这是因为树中经排序的内部节点的拼接可以被重新解释为leaf值。
Ownable库提供了一种基本的访问控制机制——设置一个owner具有对某些函数特殊的访问权限。通常owner就是本合约的deployer。合约部署后可通过函数transferOwnership()进行owner的修改。本库还提供了modifier onlyOwner,用于为函数限定访问权限。
Ownable2Step库是Ownable库的拓展版本。其提供的访问权限机制同Ownable完全一致,只是owner的更换机制从由原owner直接指定(一次交互)变成原owner指定 + 新owner确认(两次交互)。Ownable2Step库具有Ownable库所有的功能函数。
AccessControl库用于管理函数的调用权限,所有继承了AccessControl的子合约均可为自己的业务函数设置调用权限。AccessControl是一个轻量级的基础库且各个role不支持在编成员的迭代导出,所以授权和撤销role成员的操作会抛出event。
AccessControlEnumerable库用于管理函数的调用权限,是AccessControl库的拓展版。与AccessControl库相比,AccessControlEnumerable支持在编成员的迭代导出,这大大方便了各个角色权限的统计查询。
Openzeppelin中的ERC20库只提供了mint接口,而具体的发行逻辑需要开发者在其子合约中使用`_mint()`自行编写。该库同样遵循了OpenZeppelin的合约设计思路:当函数因产生错误返回false时,直接revert掉。这种设计思路与ERC20的期望标准并不冲突。
ERC20Burnable库是ERC20的拓展。该库允许用户销毁自己和给自己授权的人名下的token。
ERC20Capped库是ERC20的拓展。该库设置了ERC20发行量的上限。
ERC20Permit库是ERC20的拓展。本库通过permit方法允许调用者携带owner的链下签名来进行token的授权。这样,ERC20 token的owner不再需要自己调用approve方法进行授权,进而实现了owner的EOA账户无eth也可完成授权操作。
Pausable库实现了功能函数紧急关停机制,可以继承该合约并使管理员账户来调控合约的开关。合约内有两个修饰器`whenNotPaused`和`whenPaused`,可以根据业务需求将其修饰在对应的函数上来进行开放或关停状态下的访问限制。
ERC20Pausable库是ERC20的拓展。该库提供了可暂停的transfer、mint及burn功能。需要注意的是:ERC20Pausable库并没有提供切换暂停状态的函数,需要开发人员自行开发——同时需要注意切换暂停状态的权限问题。
ERC20FlashMint库是ERC20的拓展。本库在ERC20的基础上实现了IERC3156FlashLender接口,在token层面上支持了闪电贷功能。但是该库默认没有闪电贷手续费,开发者可以通过重写`flashFee()`方法来自定义手续费计算逻辑。
ERC20Snapshot库是ERC20的拓展,增加了各账户余额及总流通量的快照机制。如果涉及到根据账户ERC20余额进行分红、投票等业务可以使用该库,其可有效防御在不同地址间转账进行“一币多用”的攻击。在一个快照横截面数据上进行分红、投票甚至是ERC20分叉都是最有效的解决方案。
SafeERC20库封装了ERC20的操作,使各操作执行失败时触发revert。因为标准IERC20的转账和授权等需通过一个bool返回值来表示操作是否成功,可能实现合约内部没有设置revert机制。有的ERC20合约的授权或转账的实现并无返回值(以太坊上的USDT合约),此时可通过本库与其交互。
TokenTimelock库是是一个锁币合约。它允许指定地址在某一时间点及之后取出全部锁存的代币,实现了一个代币时间锁的功能。
ERC20Wrapper库是一种对某ERC20 token作为标的资产进行包装的wrapped ERC20 token。用户可以质押或赎回标的token,同时获得或销毁相同数量的wrapped token。
ERC20Votes库是一个具备类Compound委托投票功能的ERC20拓展库。本库的发行量上限是2^224-1,比Compound更通用。合约内部使用快照结构Checkpoint来记录每个投票目标地址的总票数,每个token持有者可以采用直接或者离线签名两种方式委托投票给任何地址。
ERC20VotesComp库是专门适配Compound投票和委托的ERC20拓展库。本库可对接Compound的接口,同时也存在缺点(总发行量上限为2^96 - 1)。如果业务上确定需要兼容Compound,那必须弄清楚总发行量上限是否符合业务需求。否则可使用`ERC20Votes`库。
ERC4626库本身是一种有底层ERC20资产质押的shares且本身同样满足ERC20标准。用户可以通过deposit或mint方法来质押底层资产并增发shares,也可使用burn或redeem方法来销毁shares并赎回底层资产。
ERC20PresetFixedSupply库是一种带预铸造功能的ERC20实现,即在合约部署时直接将全部流通量都铸造给某一地址且部署后无法增发。该库同时继承了ERC20Burnable库,支持销毁和委托销毁功能。
ERC20PresetMinterPauser库是一种带mint和pause权限管理的ERC20实现,同时支持销毁和委托销毁的功能。当合约进入paused状态后,全部token的转移功能都将被停止。权限管理功能是直接继承AccessControlEnumerable库。
PaymentSplitter库可以在一组领取地址无感知的情况下,将定量eth或某ERC20 token按照shares占比释放给该组中的某地址。当eth或ERC20 token被转入该合约后,在册的领取地址就可以来领取属于自己占比的那部分。各领取人的shares数量只能在该合约部署时被设置。
VestingWallet库可给指定的受益人按时间线性释放锁在合约内的Eth或Erc20 token。任何转移至本合约的token都必须遵循释放模型。开发者可通过重写`vestedAmount(uint64)`或`vestedAmount(address,uint64)`来自定义token释放模型。
ReentrancyGuard库是一个用来防御函数重入的工具库。函数被修饰器`nonReentrant`修饰可确保其无法被嵌套(重入)调用。本库的代码逻辑上只实现了一个重入锁,所以被`nonReentrant`修饰的函数之间也是无法相互调用的。
PullPayment库是对Openzeppelin中Escrow库的一种封装。从安全角度看,PullPayment是一对多发送eth的最佳解决方案。它可以防止收款人阻塞发送eth的行为并消除重入问题。
Proxy库对外只暴露了fallback和receive函数,是代理合约的基础实现。所有对Proxy合约的call都将被delegatecall到implement合约且delegatecall的执行结果会原封不动地返还给Proxy合约的调用方。通常称implement合约为代理合约背后的逻辑合约。
Clones库是最小代理合约的工厂合约实现,也称之为克隆工厂。ERC1167指定了一种将全部调用都delegatecall到一个已知固定地址的最小字节码实现,它可以以一种不可变且成本极低的方式克隆目标合约。
ERC1967Upgrade库实现了基于ERC1967标准(代理合约的slot分布)的slots读写函数,并在对应slot更新时emit出标准中相应的event。对于各种可升级合约和代理合约的实现而言,本库的作用举足轻重。
ERC1967Proxy库实现了一个基于ERC1967标准的代理合约。通过改变存储于ERC1967标准规定的_IMPLEMENTATION_SLOT号slot中的代理合约地址,代理合约便实现了合约逻辑可升级的功能。
Initializable库用于开发可升级合约或代理合约背后的逻辑合约。由于代理合约无法执行`constructor`函数,通常是将该函数逻辑放到一个external函数中(称为initialize函数)。本库可确保initializer函数全局只能被调用一次。
UUPSUpgradeable库是专为UUPS代理设计的一种合约升级机制的实现。当本合约被设置为ERC1967Proxy代理合约背后的逻辑合约后,可以对其进行合约升级操作。作为逻辑合约的父合约,本库的安全机制可保证不会因某次错误的升级而打破合约的可升级性。
TransparentUpgradeableProxy库是一个透明代理合约的实现,其背后的逻辑合约可由admin来升级。一般的代理合约本身需要管理函数,当这些函数同其背后的逻辑合约的函数产生selector冲突时可能会暴露潜在的漏洞。透明代理模式解决了以上问题。
ProxyAdmin库是指定用于做透明代理TransparentUpgradeableProxy库admin的管理员合约。
BeaconProxy库是信标代理合约的实现。与ERC1967Proxy和TransparentUpgradeableProxy两种代理合约不同,信标代理合约背后的逻辑合约地址并不是存储在代理合约内,而是存储于信标合约中。信标代理合约自身只存储信标合约的地址。
UpgradeableBeacon库是信标代理模式中的信标合约的实现,与一个或多个`BeaconProxy`库实例配合使用。所有到`BeaconProxy`的调用都会被委托到本库指向的逻辑合约上。本库的owner具有更换逻辑合约地址的权限,从而实现信标代理合约的升级功能。
Openzeppelin是一个平台,它具有可用来编写、部署和管理去中心化应用程序的工具。 Openzeppelin也是一款开源工具,它通过提供的产品来提供可靠性和安全性。
本专栏将从Foundry工程化的角度详细解读Openzeppelin中的各合约库源码逻辑及对应单元测试与使用方式。
[openzeppelin]:v4.8.3,[forge-std]:v1.5.6
v4.8.3
v1.5.6
样例代码repo:https://github.com/RevelationOfTuring/foundry-openzeppelin-contracts