什么是 ERC-6551

简单来说，6551 是一个为 NFT 创建钱包的标准。这是什么意思呢？

我们考虑一个场景，假设在游戏中，我的地址 A 拥有一个角色 Bob，这个角色它本身是一个 ERC721 的 NFT，同时它的身上也有许多道具，例如帽子，鞋子，武器等，也可能拥有一些资产例如金元宝等。这些资产本身也是 ERC20，ERC721 等类型的 token。这些道具和资产在游戏逻辑中是属于我的角色 Bob 的，但是在实际的底层合约实现中，其实它们都是属于我的地址 A 的。如果我想将我的角色 Bob 出售给别人，我就需要分别将 Bob 还有它所拥有的所有资产都一一转账给买家。这在逻辑和操作上都不是很合理。

6551 标准的目的就是为角色 Bob 创建一个钱包，使得它所拥有的道具都是属于角色 Bob 的，这样看起来就合理多了。我们可以看看官方 EIP 里给到的示例图：

用户账户中拥有两个 NFT，分别是 A#123 和 B#456，其中 A#123 拥有两个账户（ A 和 B），B#456 拥有一个账户（C）。

我们再来看看图中右边这一块是什么意思。6551 协议中提供了一个 Registry 合约，它是用来创建 NFT 钱包的合约，通过调用它的 createAccount 函数就可以对该 NFT 创建一个合约钱包。由于合约钱包的写法可以各式各样，因此该函数需要我们提供一个合约钱包的 Implementation。也就是说我们可以自定义钱包的合约，例如可以是 AA 钱包，可以是 Safe 钱包。图中还有 proxies 关键字，这表示 Registry 在创建钱包的时候是创建了 Implementation 的代理，而不是原模原样将其复制了一份，这样做的目的是为了节省 Gas。这块应用到了 EIP-1167 的知识，对其不熟悉的朋友可以看看我之前的文章。

6551 EIP 中把为 NFT 创建的钱包称为 token bound accounts。它有一个很重要的特性是可以向前兼容 NFT，对于之前链上已经部署的标准 NFT 合约，都可以兼容 6551。

我们平时使用的钱包，不论是 EOA 还是合约钱包，都是钱包本身拥有资产。但在 NFT 账户中，NFT 本身是不拥有资产的，而是它拥有一个合约钱包，该钱包是拥有资产的主体。也就是说 NFT 本身更类似于人的角色。用图说明应该更清晰一点：

代码实现

6551 标准建议 Registry 实现 IERC6551Registry 接口：

interface IERC6551Registry {
    /// @dev The registry SHALL emit the AccountCreated event upon successful account creation
    event AccountCreated(
        address account,
        address implementation,
        uint256 chainId,
        address tokenContract,
        uint256 tokenId,
        uint256 salt
    );

    /// @dev Creates a token bound account for an ERC-721 token.
    ///
    /// If account has already been created, returns the account address without calling create2.
    ///
    /// If initData is not empty and account has not yet been created, calls account with
    /// provided initData after creation.
    ///
    /// Emits AccountCreated event.
    ///
    /// @return the address of the account
    function createAccount(
        address implementation,
        uint256 chainId,
        address tokenContract,
        uint256 tokenId,
        uint256 salt,
        bytes calldata initData
    ) external returns (address);

    /// @dev Returns the computed address of a token bound account
    ///
    /// @return The computed address of the account
    function account(
        address implementation,
        uint256 chainId,
        address tokenContract,
        uint256 tokenId,
        uint256 salt
    ) external view returns (address);
}

createAccount 函数用来为 NFT 创建合约钱包，account 函数用来计算合约钱包地址。它们都利用了 create2 机制，因此可以返回一个确定的地址。对 create2 不了解的朋友可以看我之前的文章。

6551 官方给出了一个已经部署的 Registry 实现可供参考。

其中的 getCreationCode 函数值得留意一下：

function getCreationCode(
    address implementation_,
    uint256 chainId_,
    address tokenContract_,
    uint256 tokenId_,
    uint256 salt_
) internal pure returns (bytes memory) {
    // 将 salt, chainId, tokenContract, tokenId 拼接在 bytecode 后面
    return
        abi.encodePacked(
            hex"3d60ad80600a3d3981f3363d3d373d3d3d363d73",
            implementation_,
            hex"5af43d82803e903d91602b57fd5bf3",
            abi.encode(salt_, chainId_, tokenContract_, tokenId_)
        );
}

它是用来组装 proxy 字节码的函数，可以看到在最后将 salt_、chainId_、tokenContract_、tokenId_ 等数据拼接在了 EIP-1167 的代理字节码后面。这里的目的是为了在创建的合约钱包中可以直接通过字节码读取到这些数据，我们之前学习过的 SudoSwap 代码中也使用了类似的写法，参考这里。

对于创建的 NFT 钱包合约（即 Implementation 合约），6551 也作出了一些要求：

• 应该通过 Registry 创建

• 必须实现 ERC-165 接口

• 必须实现 ERC-1271 接口

• 必须实现下面的 IERC6551Account 接口：

/// @dev the ERC-165 identifier for this interface is `0x400a0398`
interface IERC6551Account {
    /// @dev Token bound accounts MUST implement a `receive` function.
    ///
    /// Token bound accounts MAY perform arbitrary logic to restrict conditions
    /// under which Ether can be received.
    receive() external payable;

    /// @dev Executes `call` on address `to`, with value `value` and calldata
    /// `data`.
    ///
    /// MUST revert and bubble up errors if call fails.
    ///
    /// By default, token bound accounts MUST allow the owner of the ERC-721 token
    /// which owns the account to execute arbitrary calls using `executeCall`.
    ///
    /// Token bound accounts MAY implement additional authorization mechanisms
    /// which limit the ability of the ERC-721 token holder to execute calls.
    ///
    /// Token bound accounts MAY implement additional execution functions which
    /// grant execution permissions to other non-owner accounts.
    ///
    /// @return The result of the call
    function executeCall(
        address to,
        uint256 value,
        bytes calldata data
    ) external payable returns (bytes memory);

    /// @dev Returns identifier of the ERC-721 token which owns the
    /// account
    ///
    /// The return value of this function MUST be constant - it MUST NOT change
    /// over time.
    ///
    /// @return chainId The EIP-155 ID of the chain the ERC-721 token exists on
    /// @return tokenContract The contract address of the ERC-721 token
    /// @return tokenId The ID of the ERC-721 token
    function token()
        external
        view
        returns (
            uint256 chainId,
            address tokenContract,
            uint256 tokenId
        );

    /// @dev Returns the owner of the ERC-721 token which controls the account
    /// if the token exists.
    ///
    /// This is value is obtained by calling `ownerOf` on the ERC-721 contract.
    ///
    /// @return Address of the owner of the ERC-721 token which owns the account
    function owner() external view returns (address);

    /// @dev Returns a nonce value that is updated on every successful transaction
    ///
    /// @return The current account nonce
    function nonce() external view returns (uint256);
}

这里是一个已经实现的合约钱包示例。

应用案例

Sapienz NFT 系列使用了 ERC 6551 标准，我们来看看它是怎样应用 6551 的，代码在此。

我们主要来看其中的 _mintWithTokens 函数，它的作用是，用户需要使用一些白名单的 NFT（例如 PIGEON）来 mint Sapienz NFT。具体逻辑是，函数将用户拥有的这些白名单的 NFT 转入到即将生成的 Sapienz NFT 对应的合约钱包中（即 token bound accounts），然后再为用户 mint Sapienz NFT。也就是说这些转入的白名单 NFT 是归属于生成的 Sapienz NFT 的。

我们来看看主要代码：

function _mintWithTokens(
    address tokenAddress,
    uint256[] memory tokenIds,
    bytes32[][] memory proof,
    address recipient
) internal {
    // ...
    uint256 quantity = tokenIds.length;

    for (uint256 i = 0; i < quantity; i++) {
        uint256 tokenId = tokenIds[i];

        // 计算出 当前 tokenId（是当前 Sapienz 合约的 tokenId，不是传入的 tokenId）所有对应 tba 的地址
        address tba = erc6551Registry.account(
            erc6551AccountImplementation,
            block.chainid,
            address(this),
            startTokenId + i,
            0
        );

        // ....

        // 将白名单 NFT#tokenId 从 msg.sender 转移到 tba 中
        IERC721Upgradeable(tokenAddress).safeTransferFrom(
            msg.sender,
            tba,
            tokenId
        );
    }

    _safeMint(recipient, quantity);
}

我们在前面的 IERC6551Registry 接口中看到，account 函数是用来计算生成的合约钱包地址的，即代码中的 tba 就是合约钱包的地址，然后在后面会通过 tokenAddress 的 safeTransferFrom 函数将白名单 NFT 转入 tba 中。

我们注意到，代码中仅仅是计算出了 tba 的合约地址，但是并没有部署合约这一步操作，也就是说，这里的转入操作的目标地址可能是一个没有实际部署代码的地址，仅仅是一个预留地址而已。例如这个 tba，它是拥有 NFT 的，但是却并没有合约代码（不过在你看到的时候可能已经发生了状态变化）。如果我们希望该地址是有合约代码的话，需要调用 Registry 的 createAccount 函数来创建部署合约。例如这个 tba 就是已经部署的合约地址。

其中字节码的前半部分是 EIP-1167 的拼接字节码，后面的阴影部分是我们前面提到的 getCreationCode 函数中拼接的salt_、chainId_、tokenContract_、tokenId_ 数据。

总结

我们通过原理，代码实现和实际案例学习了 ERC-6551，它本身内容并不复杂，提供了一个创建 NFT 钱包的新思路。我觉得它最友好的一点就是可以向前兼容 NFT，没有侵入性，这样使得 NFT 本身也不用去关心 6551 的逻辑，只要按照自己的业务开发就行。

关于我

欢迎和我交流

参考

ERC-6551: Non-fungible Token Bound Accounts

An interface and registry for smart contract accounts owned by non-fungible tokens

https://eips.ethereum.org

工厂合约

在 Sudoswap 代码中，LSSVMPairFactory 合约是 Pair 的工厂合约，其中可以通过 createPairETH 创建 ETH 的交易对，通过 createPairERC20 创建 ERC20 的交易对。在创建交易对的过程中，调用 LSSVMPairCloner 库合约，其中应用了 EIP-1167 协议。

我们来看看库合约中创建 Pair 的方法：

function cloneETHPair(
    address implementation,
    ILSSVMPairFactoryLike factory,
    ICurve bondingCurve,
    IERC721 nft,
    uint8 poolType
) internal returns (address instance) {
    assembly {
        let ptr := mload(0x40)

        mstore(
            ptr,
            hex"60_72_3d_81_60_09_3d_39_f3_3d_3d_3d_3d_36_3d_3d_37_60_3d_60_35_36_39_36_60_3d_01_3d_73_00_00_00"
        )
        mstore(add(ptr, 0x1d), shl(0x60, implementation))

        mstore(
            add(ptr, 0x31),
            hex"5a_f4_3d_3d_93_80_3e_60_33_57_fd_5b_f3_00_00_00_00_00_00_00_00_00_00_00_00_00_00_00_00_00_00_00"
        )

        mstore(add(ptr, 0x3e), shl(0x60, factory))
        mstore(add(ptr, 0x52), shl(0x60, bondingCurve))
        mstore(add(ptr, 0x66), shl(0x60, nft))
        mstore8(add(ptr, 0x7a), poolType)

        instance := create(0, ptr, 0x7b)
    }
}

其中前三个 mstore 与我们之前的文章介绍的 EIP-1167 的写法类似，但是后面又多了几行 mstore 以及 mstore8，这些都是什么意思呢？

字节码分析

我们先来看看前三个 mstore，这里的具体字节码与之前我们介绍的 1167 写法有些出入，这三行组合出的字节码是（长度为 62 字节）：

分割一下，得到：

1 -> 60723d8160093d39f3
2 -> 3d3d3d3d363d3d37603d6035363936603d013d73bebebebebebebebebebebebebebebebebebebebe5af43d3d93803e603357fd5bf3

其中第一部分的九个字节，反编译得到的结果是：

contract Contract {
    function main() {
        memory[returndata.length:returndata.length + 0x72] = code[0x09:0x7b];
        return memory[returndata.length:returndata.length + 0x72];
    }
}

可以看到，合约初始化时将字节码中从 9 字节到 123（0x7b） 字节的数据返回到 EVM 中，但是我们前面的字节码只有 62 字节，后面还有 61 字节都是什么呢？

此时我们再回看前面的 cloneETHPair 代码，没错，后面的 61 字节就是来自于其最后的几个 mstore，其中 factory、bondingCurve 以及 nft 都是地址类型，分别占据 20 字节，poolType 是 bool 类型，占据 1 个字节。

我们再将上面字节码的第二部分进行反编译：

contract Contract {
    function main() {
        var temp0 = returndata.length;
        var var1 = returndata.length;
        var temp1 = msg.data.length;
        memory[returndata.length:returndata.length + temp1] = msg.data[returndata.length:returndata.length + temp1];
        memory[msg.data.length:msg.data.length + 0x3d] = code[0x35:0x72];
        var temp2;
        temp2, memory[returndata.length:returndata.length + returndata.length] = 
            address(0xbebebebebebebebebebebebebebebebebebebebe)
            .delegatecall.gas(msg.gas)(memory[returndata.length:returndata.length + msg.data.length + 0x3d]);
        var temp3 = returndata.length;
        var var0 = returndata.length;
        memory[temp0:temp0 + temp3] = returndata[temp0:temp0 + temp3];
    
        if (temp2) { return memory[var1:var1 + var0]; }
        else { revert(memory[var1:var1 + var0]); }
    }
}

从上面代码中可以看到，代理合约在调用逻辑合约的时候，总会在最后加上 61 （0x3d）字节的 calldata，正是前面的 factory、bondingCurve 、nft 以及 poolType。那么也就是说，任何通过代理合约转发到逻辑合约的调用，最后都会加上这段 calldata，意味着在逻辑合约的方法中，总是可以获取到这段 calldata。

获取数据

我们来看看 Pair 合约中是如何获取这几个字段值的，以 bondingCurve() 为例：

function bondingCurve() public pure returns (ICurve _bondingCurve) {
    // 这里 ETH Pair 是 61，ERC20 Pair 是 81
    uint256 paramsLength = _immutableParamsLength();
    assembly {
        _bondingCurve := shr(
            0x60,
            calldataload(add(sub(calldatasize(), paramsLength), 20))
        )
    }
}

_immutableParamsLength() 返回常量，ETH Pair 返回 61，ERC20 Pair 返回 81。我们前面参考的方法是 cloneETHPair，因此我们这里默认其值为 61。

接下来的一段汇编代码，首先最里面的 calldatasize() 获取整个 calldata 的长度，其中是包含后面 61 字节的，然后用 calldatasize() 减去 paramsLength，得到的值就是调用合约方法的基础 calldata 长度，再加上 20（这里的 20 是前面 factory 的地址长度），获取到 bondingCurve 地址在整个 calldata 中的偏移量。然后调用 calldataload，将偏移量作为参数，可以获取到 bondingCurve 地址起始的 32 字节数据，其中前 20 字节是 bondingCurve 的地址，后面的 12 （0x60 / 8）字节通过 shr 操作移除，最终得到的就是 bondingCurve 的地址。

我们来看看图示，更加易懂：

其余的 factory 等获取方法同理，只是偏移量不同，最后的 add 数值不同。

看懂这块，我们同理就可以分析 ERC20 Pair 的操作，唯一的区别是在 cloneERC20Pair 方法中，最后还要在 mstore token 地址，因此 calldata 会多 20，即 81。

那么我们思考一下，为什么 Sudoswap 要采用这么复杂的操作，而不是直接将这几个字段直接存储到 Pair 中呢？最重要的就是 gas 的原因，Solidity 中处理 calldata 的操作耗费的 gas 很少，而如果将这些字段存储到 Pair 中，首先 sstore 操作就要耗费大量 gas，其次每次读取 sload 也会耗费大量 gas，与在 calldata 中操作的 gas 消耗可以说不是一个数量级的。

总结

我们看到，Sudoswap 中采取了一个几乎极致的方法来节省 gas，这其中确实是有炫技的成分，不过里面的方法与思想还是值得我们学习的。随着合约开发逐渐卷起来，我觉得这种字节码层级操作的代码以后会越来越多，这块还是值得深入研究的。

关于我

欢迎和我交流

代码分析

在大体业务上来说，Lens 的业务逻辑有些类似于 Twitter，主要包括了下面几个方面：

• Profile，一个地址可以拥有多个 Profile，创建一个 Profile 就可以拥有一个对应 NFT，类似于一个人可以拥有多个账户，可以指定默认 Profile

• Publication，发表内容

• Comment，对内容发表评论，也可以对评论发表评论

• Mirror，类似于转发功能

• Collect，将内容铸造为 NFT

• Follow，关注其他 Profile，关注后可以获得 FollowNFT

相对推特来说，主要就是多了 Collect 功能，接下来我们分功能来看看各自的主要逻辑。

用户的主要操作逻辑入口都是在 LensHub 合约中，其中也包含了许多 setter 方法。主要实现逻辑是在 PublishingLogic 和 InteractionLogic 库合约中。

Profile

创建 Profile

function createProfile(DataTypes.CreateProfileData calldata vars)
    external
    override
    whenNotPaused
    returns (uint256)
{
    // 白名单中的用户才能创建
    if (!_profileCreatorWhitelisted[msg.sender]) 
        revert Errors.ProfileCreatorNotWhitelisted();
    unchecked {
        // ++ 表示从 1 开始
        uint256 profileId = ++_profileCounter;
        _mint(vars.to, profileId);
        PublishingLogic.createProfile(
            vars,
            profileId,
            _profileIdByHandleHash,
            _profileById,
            _followModuleWhitelisted
        );
        return profileId;
    }
}

创建 profile，只有白名单中的地址可以创建，这是为了防止用户名被恶意占领。每次创建一个 profile 会获得一个 NFT。

Profiles can only be minted by addresses that have been whitelisted by governance. This ensures that, given the low-fee environment present on Polygon, the namespace is not reserved by squatters.

我们来看看入参 CreateProfileData 的结构：

struct CreateProfileData {
    // 接收 profile 的地址
    address to;
    // 可以理解为用户名
    string handle;
    // 头像地址
    string imageURI;
    address followModule;
    bytes followModuleInitData;
    string followNFTURI;
}

前面的几个都是一些比较基础的数据字段，后面的几个 follow 字段下文再解释。

下面是创建 profile 的主要逻辑：

function createProfile(
    DataTypes.CreateProfileData calldata vars,
    uint256 profileId,
    mapping(bytes32 => uint256) storage _profileIdByHandleHash,
    mapping(uint256 => DataTypes.ProfileStruct) storage _profileById,
    mapping(address => bool) storage _followModuleWhitelisted
) external {
    // 校验 handle 的内容，只在创建 profile 的时候校验
    _validateHandle(vars.handle);

    // 要求 imageURI 的长度不能大于限制
    if (bytes(vars.imageURI).length > Constants.MAX_PROFILE_IMAGE_URI_LENGTH)
        revert Errors.ProfileImageURILengthInvalid();

    bytes32 handleHash = keccak256(bytes(vars.handle));

    // handle 必须唯一
    if (_profileIdByHandleHash[handleHash] != 0) revert Errors.HandleTaken();

    // handle hash 对应 profileId
    _profileIdByHandleHash[handleHash] = profileId;

    // 存储 profileId 对应的数据，handle，imageURI，followNFTURI
    _profileById[profileId].handle = vars.handle;
    _profileById[profileId].imageURI = vars.imageURI;
    _profileById[profileId].followNFTURI = vars.followNFTURI;

    bytes memory followModuleReturnData;
    if (vars.followModule != address(0)) {
        _profileById[profileId].followModule = vars.followModule;
        followModuleReturnData = _initFollowModule(
            profileId,
            vars.followModule,
            vars.followModuleInitData,
            _followModuleWhitelisted
        );
    }

    _emitProfileCreated(profileId, vars, followModuleReturnData);
}

代码相对也比较好理解，最后的 _initFollowModule 调用我们同样放在后面再讲解，大家记住这里出现过就行。

这里有一个小细节，方法入参中有 mapping 类型，这是只有在 library 库合约中的方法才能实现的，普通的合约方法不能接收 mapping 类型的参数。

Publication

发表内容

function post(DataTypes.PostData calldata vars)
    external
    override
    whenPublishingEnabled
    returns (uint256)
{
    // dispatcher 可以替 owner 为其 post
    _validateCallerIsProfileOwnerOrDispatcher(vars.profileId);
    return
        _createPost(
            vars.profileId,
            vars.contentURI,
            vars.collectModule,
            vars.collectModuleInitData,
            vars.referenceModule,
            vars.referenceModuleInitData
        );
}

_validateCallerIsProfileOwnerOrDispatcher 是校验只有用户本人或者用户的 dispatcher 可以调用，类似于 ERC721 中的 operator 角色：

function _validateCallerIsProfileOwnerOrDispatcher(uint256 profileId) internal view {
    if (msg.sender == ownerOf(profileId) || msg.sender == _dispatcherByProfile[profileId]) {
        return;
    }
    revert Errors.NotProfileOwnerOrDispatcher();
}

我们来看看入参 PostData 的结构：

struct PostData {
    uint256 profileId;
    // 存储内容的 URI
    string contentURI;
    address collectModule;
    bytes collectModuleInitData;
    address referenceModule;
    bytes referenceModuleInitData;
}

后面的几个 collect 和 reference 相关内容我们下文再说。

function _createPost(
    uint256 profileId,
    string memory contentURI,
    address collectModule,
    bytes memory collectModuleData,
    address referenceModule,
    bytes memory referenceModuleData
) internal returns (uint256) {
    unchecked {
        // 更新发布数量
        uint256 pubId = ++_profileById[profileId].pubCount;
        PublishingLogic.createPost(
            profileId,
            contentURI,
            collectModule,
            collectModuleData,
            referenceModule,
            referenceModuleData,
            pubId,
            _pubByIdByProfile,
            _collectModuleWhitelisted,
            _referenceModuleWhitelisted
        );
        return pubId;
    }
}

_createPost 方法仅仅更新了发布数量就进入了库合约中的逻辑：

function createPost(
    uint256 profileId,
    string memory contentURI,
    address collectModule,
    bytes memory collectModuleInitData,
    address referenceModule,
    bytes memory referenceModuleInitData,
    uint256 pubId,
    mapping(uint256 => mapping(uint256 => DataTypes.PublicationStruct))
        storage _pubByIdByProfile,
    mapping(address => bool) storage _collectModuleWhitelisted,
    mapping(address => bool) storage _referenceModuleWhitelisted
) external {
    _pubByIdByProfile[profileId][pubId].contentURI = contentURI;

    // 新建 post 的时候需要初始化 collet module 和 reference module
    // Collect module initialization
    bytes memory collectModuleReturnData = _initPubCollectModule(
        profileId,
        pubId,
        collectModule,
        collectModuleInitData,
        _pubByIdByProfile,
        _collectModuleWhitelisted
    );

    // Reference module initialization
    bytes memory referenceModuleReturnData = _initPubReferenceModule(
        profileId,
        pubId,
        referenceModule,
        referenceModuleInitData,
        _pubByIdByProfile,
        _referenceModuleWhitelisted
    );

    emit Events.PostCreated(
        profileId,
        pubId,
        contentURI,
        collectModule,
        collectModuleReturnData,
        referenceModule,
        referenceModuleReturnData,
        block.timestamp
    );
}

我们来看看 _pubByIdByProfile 的结构：

mapping(uint256 => mapping(uint256 => DataTypes.PublicationStruct)) internal _pubByIdByProfile;

它的结构是 profileId → pubId → PublicationStruct，其中 PublicationStruct 的结构是：

struct PublicationStruct {
    uint256 profileIdPointed;
    uint256 pubIdPointed;

    string contentURI;
    address referenceModule;
    address collectModule;
    address collectNFT;
}

前面两个 pointed 数据代表的是该内容指向的原始内容的 id，只有在当前内容为 Mirror 或者 Comment 类型的时候才有值。

两个 _init 方法我们下文再说。

代码中还有很多的 WithSig 结尾的方法，例如 postWithSig，这是利用 EIP-712 实现的利用签名可以让其他人代替发送交易的方法，不了解的朋友可以看看我的这篇文章。

Comment

发表评论，它的逻辑与 Post 的逻辑很类似，我们主要来看看最核心的部分：

function createComment(
    DataTypes.CommentData memory vars,
    uint256 pubId,
    mapping(uint256 => DataTypes.ProfileStruct) storage _profileById,
    mapping(uint256 => mapping(uint256 => DataTypes.PublicationStruct))
        storage _pubByIdByProfile,
    mapping(address => bool) storage _collectModuleWhitelisted,
    mapping(address => bool) storage _referenceModuleWhitelisted
) external {
    // Validate existence of the pointed publication
    // 校验传入的数据是否正确
    uint256 pubCount = _profileById[vars.profileIdPointed].pubCount;
    if (pubCount < vars.pubIdPointed || vars.pubIdPointed == 0)
        revert Errors.PublicationDoesNotExist();

    // Ensure the pointed publication is not the comment being created
    // 不能指向自己的这条 comment
    if (vars.profileId == vars.profileIdPointed && vars.pubIdPointed == pubId)
        revert Errors.CannotCommentOnSelf();

    _pubByIdByProfile[vars.profileId][pubId].contentURI = vars.contentURI;
    _pubByIdByProfile[vars.profileId][pubId].profileIdPointed = vars.profileIdPointed;
    _pubByIdByProfile[vars.profileId][pubId].pubIdPointed = vars.pubIdPointed;

    // Collect Module Initialization
    bytes memory collectModuleReturnData = _initPubCollectModule(
        vars.profileId,
        pubId,
        vars.collectModule,
        vars.collectModuleInitData,
        _pubByIdByProfile,
        _collectModuleWhitelisted
    );

    // Reference module initialization
    bytes memory referenceModuleReturnData = _initPubReferenceModule(
        vars.profileId,
        pubId,
        vars.referenceModule,
        vars.referenceModuleInitData,
        _pubByIdByProfile,
        _referenceModuleWhitelisted
    );

    // Reference module validation
    address refModule = _pubByIdByProfile[vars.profileIdPointed][vars.pubIdPointed]
        .referenceModule;
    if (refModule != address(0)) {
        IReferenceModule(refModule).processComment(
            vars.profileId,
            vars.profileIdPointed,
            vars.pubIdPointed,
            vars.referenceModuleData
        );
    }

    // Prevents a stack too deep error
    _emitCommentCreated(vars, pubId, collectModuleReturnData, referenceModuleReturnData);
}

与 Post 相比，多了指定 profileIdPointed 和 pubIdPointed 的部分，其指向的就是对应的原始内容 Id。还多了 processComment 的调用，我们下文再讲。

入参 CommentData 的结构：

struct CommentData {
    uint256 profileId;
    string contentURI;
    uint256 profileIdPointed;
    uint256 pubIdPointed;

    bytes referenceModuleData;
    address collectModule;
    bytes collectModuleInitData;
    address referenceModule;
    bytes referenceModuleInitData;
}

Mirror

转发，它的逻辑与前面也是大同小异：

function createMirror(
    DataTypes.MirrorData memory vars,
    uint256 pubId,
    mapping(uint256 => mapping(uint256 => DataTypes.PublicationStruct))
        storage _pubByIdByProfile,
    mapping(address => bool) storage _referenceModuleWhitelisted
) external {
    // 这里是获取最原始的 id，例如 mirror 另外一个 mirror，这里需要获得最原始的数据
    (uint256 rootProfileIdPointed, uint256 rootPubIdPointed, ) = Helpers.getPointedIfMirror(
        vars.profileIdPointed,
        vars.pubIdPointed,
        _pubByIdByProfile
    );

    _pubByIdByProfile[vars.profileId][pubId].profileIdPointed = rootProfileIdPointed;
    _pubByIdByProfile[vars.profileId][pubId].pubIdPointed = rootPubIdPointed;

    // Reference module initialization
    bytes memory referenceModuleReturnData = _initPubReferenceModule(
        vars.profileId,
        pubId,
        vars.referenceModule,
        vars.referenceModuleInitData,
        _pubByIdByProfile,
        _referenceModuleWhitelisted
    );

    // Reference module validation
    address refModule = _pubByIdByProfile[rootProfileIdPointed][rootPubIdPointed]
        .referenceModule;
    if (refModule != address(0)) {
        IReferenceModule(refModule).processMirror(
            vars.profileId,
            rootProfileIdPointed,
            rootPubIdPointed,
            vars.referenceModuleData
        );
    }

    emit Events.MirrorCreated(
        vars.profileId,
        pubId,
        rootProfileIdPointed,
        rootPubIdPointed,
        vars.referenceModuleData,
        vars.referenceModule,
        referenceModuleReturnData,
        block.timestamp
    );
}

多了 getPointedIfMirror 方法，用于获取最原始的 Id，例如 A 文章是原创，B Mirror 了 A，C 又 Mirror 了 B，那么这里不论 Mirror 了多少层，总是获得 A 的 Id。同时后面也多了 processMirror 方法的调用。

入参 MirrorData 的结构：

struct MirrorData {
    // 发表在哪个 profile 的名下
    uint256 profileId;
    // mirror 指向的 profile id
    uint256 profileIdPointed;
    // mirror 指向的 pub id
    uint256 pubIdPointed;
    
    bytes referenceModuleData;
    address referenceModule;
    bytes referenceModuleInitData;
}

Collect

Collect 是将内容铸造为 NFT 的过程，例如用户认为某个内容很好，想将其铸造为 NFT，可以类比为将喜爱的照片装裱的过程。

来看看代码：

function collect(
    address collector,
    uint256 profileId,
    uint256 pubId,
    bytes calldata collectModuleData,
    address collectNFTImpl,
    mapping(uint256 => mapping(uint256 => DataTypes.PublicationStruct))
        storage _pubByIdByProfile,
    mapping(uint256 => DataTypes.ProfileStruct) storage _profileById
) external returns (uint256) {
    // 这里是获取最原始的 pub 数据，包括 profileId， pubId，collectModule
    (uint256 rootProfileId, uint256 rootPubId, address rootCollectModule) = Helpers
        .getPointedIfMirror(profileId, pubId, _pubByIdByProfile);

    uint256 tokenId;
    // Avoids stack too deep
    {
        address collectNFT = _pubByIdByProfile[rootProfileId][rootPubId].collectNFT;
        if (collectNFT == address(0)) {
            // 如果是第一次 collect，则部署一个新的 collect
            collectNFT = _deployCollectNFT(
                rootProfileId,
                rootPubId,
                _profileById[rootProfileId].handle,
                collectNFTImpl
            );
            _pubByIdByProfile[rootProfileId][rootPubId].collectNFT = collectNFT;
        }
        // 第一次 collect 需要部署合约，后面的不需要，直接 mint 就行
        tokenId = ICollectNFT(collectNFT).mint(collector);
    }

    ICollectModule(rootCollectModule).processCollect(
        profileId,
        collector,
        rootProfileId,
        rootPubId,
        collectModuleData
    );
    _emitCollectedEvent(
        collector,
        profileId,
        pubId,
        rootProfileId,
        rootPubId,
        collectModuleData
    );

    return tokenId;
}

既然 collect 会铸造 NFT，那么肯定就有 mint NFT 的过程。我们在上面代码中看到，从 _pubByIdByProfile 中获取 collectNFT 的地址，如果为空，说明该内容是第一次被 collect，此时需要部署一个 collectNFT 的合约，如果不为空，则直接 mint 即可。部署合约这块运用了 EIP-1167 的内容，可以节省 Gas 费用，不了解的朋友可以看看我的这篇文章。

processCollect 是执行 collect 的一些逻辑。我们前面涉及到 collectModule 的部分一直没讲，现在来看看这一块究竟是什么逻辑。实际上 collectModule 就是对 collect 过程的个性化定制模块。例如，内容创造者要求最多只能 collect 100 份，或者是他想要对 collect 进行收费，其他用户必须缴纳一定费用才能进行 collect。collectModule 就是用来实现这些多种多样的功能。目前 Lens 官方配置了下面几种 collect 配置：

• FreeCollectModule，免费 collect

• FeeCollectModule，用户需要支付一定量的费用（Token）才能 collect

• TimedFeeCollectModule，用户只能在内容发布后的一段时间内进行 collect，且需要支付费用

• LimitedFeeCollectModule，用户需要支付费用，并且有数量上限，例如最多只能 collect 500份

• LimitedTimedFeeCollectModule，用户需要支付费用，并且有数量上限，同时也有时间限制

• RevertCollectModule，任何情况下都不能 collect，否则交易失败

上面这几个，除了最后一个 RevertCollectModule，其他的都有一个先决条件是先判断是否只有 follower 才能 collect，这个配置是在用户创建 profile 的时候配置的，也就是说用户可以设置是否只有 follower 才能 collect，这个设置是在 followModule 中。

collectModule 主要有两个模块，init 和 process。init 会初始化一些参数，例如如果用户使用的是 FeeCollectModule，那么 init 就会根据用户传入的参数指定 Token 的类型以及数量等，process 是执行 collect 时进行的逻辑，在这里就会执行转账操作。我们前面看到的 _initPubCollectModule 方法就属于 init 部分，用户会在创建 post 或者 comment 的时候调用 init，在 collect 的时候执行 process。

Follow

Follow 顾名思义就是关注其他 profile，与 collect 相同的是 follow 时也会铸造 NFT，类似于粉丝拥有了一个明星的徽章。

function follow(
    address follower,
    uint256[] calldata profileIds,
    bytes[] calldata followModuleDatas,
    mapping(uint256 => DataTypes.ProfileStruct) storage _profileById,
    mapping(bytes32 => uint256) storage _profileIdByHandleHash
) external returns (uint256[] memory) {
    if (profileIds.length != followModuleDatas.length) revert Errors.ArrayMismatch();
    uint256[] memory tokenIds = new uint256Unsupported embed;
    for (uint256 i = 0; i < profileIds.length; ) {
        string memory handle = _profileById[profileIds[i]].handle;
        if (_profileIdByHandleHash[keccak256(bytes(handle))] != profileIds[i])
            revert Errors.TokenDoesNotExist();

        address followModule = _profileById[profileIds[i]].followModule;
        address followNFT = _profileById[profileIds[i]].followNFT;

        if (followNFT == address(0)) {
            followNFT = _deployFollowNFT(profileIds[i]);
            _profileById[profileIds[i]].followNFT = followNFT;
        }

        tokenIds[i] = IFollowNFT(followNFT).mint(follower);

        if (followModule != address(0)) {
            IFollowModule(followModule).processFollow(
                follower,
                profileIds[i],
                followModuleDatas[i]
            );
        }
        unchecked {
            ++i;
        }
    }
    emit Events.Followed(follower, profileIds, followModuleDatas, block.timestamp);
    return tokenIds;
}

follow 方法支持批量 follow，因此接收的是一个 profileIds 的数组，遍历这一个数组，逐个进行 follow。同样的，如果是该 profile 第一次被 follow，则需要部署 NFT 合约，否则直接 mint 即可。

follow 与 collect 同样都支持定制化模块，follow 目前支持的模块如下：

• ProfileFollowModule，正常 follow，没有限制

• ApprovalFollowModule，只有授权过的地址可以 follow

• FeeFollowModule，follow 需要付费

• RevertFollowModule，不允许 follow，否则直接失败

followModule 同样包含 init 和 process 两个模块。用户可以在创建 profile 的时候调用 init，即 _initFollowModule，也可以后期修改。在 follow 的时候执行 process。

Reference

其实 reference 不算是一个额外的功能，它指的是 comment 或者 mirror 操作。但是它也有自己对应的 module，所以这里把它单独拿出来讲讲。在用户创建 post，comment，mirror 的时候，可以指定当前创建的这个新 pub 在被 reference 时的要求。目前只支持一个模块：

• FollowerOnlyReferenceModule，只有 follower 可以进行 reference

referenceModule 也是包含 init 和 process 两个模块。在用户创建 post，comment，mirror 的时候，会调用 init，即 _initPubReferenceModule。在用户进行 comment，mirror 的时候会调用 process。注意前后两个 comment，mirror 对应的不是一个对象，init 时是指定当该 pub 被 reference 时的要求，process 时是执行当前 reference 对象的要求。

总结

我们已经将 Lens 的主要逻辑代码看完，整体来说不算难，业务逻辑相对也比较简单，没有特别绕的逻辑。希望能对大家起一个代码导读的作用，接下来看代码会更加容易。

关于我

欢迎和我交流

参考

Lens Chain

Scalable SocialFi on Ethereum. Lens is a high-performance blockchain stack built for SocialFi, combining modular Social Primitives, fast settlement, and decentralized storage. The Lens stack is composed of Lens Chain, Social Protocol, and Storage Nodes. As a layer 2 leveraging ZKsync, Avail, and Ethereum's security, Lens delivers the fastest, most cost-effective, and scalable blockchain for developers.

https://lens.xyz

整个玩法分成两部分，我这里将其区别为：

1. 时间挖矿（claim to mint），也就是在参与时指定时间，时间到期后即可领取对应的 XEN，唯一付出的成本就是 gas 费用和等待的时间

2. stake 挖矿，通过质押 XEN 来挖矿

时间挖矿

先来看第一部分，时间挖矿。用户通过调用 claimRank(uint256 term) 来参与，term 代表用户想要挖矿的天数，在这个时间到期之后才能领取 XEN 奖励。

function claimRank(uint256 term) external {
    // SECONDS_IN_DAY = 3_600 * 24;
    // 将天数转化为秒数
    uint256 termSec = term * SECONDS_IN_DAY;
    // 最短挖一天
    // MIN_TERM = 1 * SECONDS_IN_DAY - 1;
    require(termSec > MIN_TERM, "CRank: Term less than min");
    // 最长可参与的天数需要根据参与人数实时计算
    require(termSec < _calculateMaxTerm() + 1, "CRank: Term more than current max term");
    require(userMints[_msgSender()].rank == 0, "CRank: Mint already in progress");

    // create and store new MintInfo
    MintInfo memory mintInfo = MintInfo({
        user: _msgSender(),
        term: term,
        maturityTs: block.timestamp + termSec,
        rank: globalRank,
        amplifier: _calculateRewardAmplifier(),
        eaaRate: _calculateEAARate()
    });
    userMints[_msgSender()] = mintInfo;
    activeMinters++;
    emit RankClaimed(_msgSender(), term, globalRank++);
}

其中全局变量 globalRank 代表的是全局参与的总人数，只增不减。activeMinters 代表正在参与挖矿的人数，当用户参与时间挖矿时增加 1，到期领取奖励后减少 1。userMints 代表用户的挖矿参数。我们看到，这里最短需要参与一天，最多参与的天数是通过 _calculateMaxTerm() 实时计算出来的。

function _calculateMaxTerm() private view returns (uint256) {
    // TERM_AMPLIFIER_THRESHOLD = 5_000;
    // TERM_AMPLIFIER = 15;
    // MAX_TERM_START = 100 * SECONDS_IN_DAY;
    // MAX_TERM_END = 1_000 * SECONDS_IN_DAY;
    if (globalRank > TERM_AMPLIFIER_THRESHOLD) {
        // 如果参与的人数大于 5000
        // globalRank.fromUInt()，先将 globalRank 转换为 int128 类型
        // 然后再对其进行对数 log_2() 计算
        // 即 log_2_globalRank * 15
        uint256 delta = globalRank.fromUInt().log_2().mul(TERM_AMPLIFIER.fromUInt()).toUInt();
        // newMax = 100 天 + delta 天
        uint256 newMax = MAX_TERM_START + delta * SECONDS_IN_DAY;
        // 取 1000 天 和 newMax 的最小值，也就是最多只能挖 1000 天
        return Math.min(newMax, MAX_TERM_END);
    }
    // 如果参与的人数没有超过 5000，则最大只能挖 100 天
    return MAX_TERM_START;
}

首先如果全部参与人数没有超过 5000，那么最多只能挖 100 天。如果达到了 5000，通过对参与人数进行对数运算，计算出对应的最大天数。对应于文档中的：

代码中的 fromUInt() 和 log_2() 都来自于 ABDKMath64x64 库（代码）。其中 fromUInt() 的代码：

function fromUInt (uint256 x) internal pure returns (int128) {
    unchecked {
        require (x <= 0x7FFFFFFFFFFFFFFF);
        return int128 (int256 (x << 64));
    }
}

入参 x 有限制，这个最大值转换为 10 进制是 9223372036854775807，全部参与人数不可能超过这个数，所有可以安全使用。

在构造的挖矿系数 mintInfo 中，_calculateRewardAmplifier() 和 _calculateEAARate() 也是实时计算的。

function _calculateRewardAmplifier() private view returns (uint256) {
    // genesisTs 是合约部署时间，也就是初始时间
    // 这里是计算出距离开始时间过去了多少天
    uint256 amplifierDecrease = (block.timestamp - genesisTs) / SECONDS_IN_DAY;
    // REWARD_AMPLIFIER_START = 3000
    // REWARD_AMPLIFIER_END = 1;
    if (amplifierDecrease < REWARD_AMPLIFIER_START) {
        // 如果是在 3000 天以内
        return Math.max(REWARD_AMPLIFIER_START - amplifierDecrease, REWARD_AMPLIFIER_END);
    } else {
        // 如果超过 3000 天，则使用 1
        return REWARD_AMPLIFIER_END;
    }
}

可以看到，越早参与，可以获得到的 AMP 就越多，最开始一天是 3000，每过一天会减少 1，最终超过 3000 天就会恒定为 1。

对应于文档中 AMP 的计算方式：

function _calculateEAARate() private view returns (uint256) {
    // EAA_PM_STEP = 1
    // EAA_RANK_STEP = 100000
    uint256 decrease = (EAA_PM_STEP * globalRank) / EAA_RANK_STEP;
    // EAA_PM_START = 100
    // 也就是说，如果参与人数大于 1000 万，返回 0
    if (decrease > EAA_PM_START) return 0;
    // 否则返回 100 - 人数 / 100000
    return EAA_PM_START - decrease;
}

从 100 开始，每当有 十万人 参与时，下降 1，最终若达到 一千万人 参与，则恒定为 0。同样也是越早参与越好。对应于文档：

由于 Solidity 中没有小数，因此在代码中将其放大了 1000 倍，后面在 getGrossReward 方法中会再缩小 1000 倍。

到这里，我们可以看到，在用户参与时间挖矿时，已经确定的数据有

1. 用户在全局中的位置（rank）

2. 参与时长（term），由用户在参与时指定

3. AMP，越早参与越大

4. EAA，越早参与越大

接下来我们来看用户领取奖励时的方法 claimMintReward()：

function claimMintReward() external {
    // 获取用户的挖矿系数
    MintInfo memory mintInfo = userMints[_msgSender()];
    require(mintInfo.rank > 0, "CRank: No mint exists");
    // 要求满足时间限制
    require(block.timestamp > mintInfo.maturityTs, "CRank: Mint maturity not reached");

    // calculate reward and mint tokens
    uint256 rewardAmount = _calculateMintReward(
        mintInfo.rank,
        mintInfo.term,
        mintInfo.maturityTs,
        mintInfo.amplifier,
        mintInfo.eaaRate
    ) * 1 ether;
    _mint(_msgSender(), rewardAmount);

    // 清除掉用户的挖矿数据
    _cleanUpUserMint();
    emit MintClaimed(_msgSender(), rewardAmount);
}

校验限制后，计算可得奖励数量，然后 _mint 给用户，计算奖励数量的主要计算逻辑在 _calculateMintReward() 中：

function _calculateMintReward(
    uint256 cRank,
    uint256 term,
    uint256 maturityTs,
    uint256 amplifier,
    uint256 eeaRate
) private view returns (uint256) {
    // 计算当前时间与到期时间的差值
    uint256 secsLate = block.timestamp - maturityTs;
    // 根据时间差值计算需要扣除的数量
    uint256 penalty = _penalty(secsLate);
    // 计算用户后面还有多少人参与游戏
    uint256 rankDelta = Math.max(globalRank - cRank, 2);
    uint256 EAA = (1_000 + eeaRate);
    uint256 reward = getGrossReward(rankDelta, amplifier, term, EAA);
    return (reward * (100 - penalty)) / 100;
}

function getGrossReward(
    uint256 rankDelta,
    uint256 amplifier,
    uint256 term,
    uint256 eaa
) public pure returns (uint256) {
    // log_2_rankDelta
    int128 log128 = rankDelta.fromUInt().log_2();
    int128 reward128 = log128.mul(amplifier.fromUInt()).mul(term.fromUInt()).mul(eaa.fromUInt());
    return reward128.div(uint256(1_000).fromUInt()).toUInt();
}

这里我们先忽略 penalty 这一块，其他部分的计算正好对应于文档中的：

在计算最终奖励数量的时候，自己参与的位置越靠前，后面的人越多，那么

cRG - cRu

就会越大，同样说明越早参与越好。

我们再来看 penalty 这部分，这块其实就是系统限制用户必须在到期后一定时间内领取走，如果没有领取则会随着时间越来越少，最终归零。

function _penalty(uint256 secsLate) private pure returns (uint256) {
    // =MIN(2^(daysLate+3)/window-1,99)
    // 计算这个差值有多少天
    uint256 daysLate = secsLate / SECONDS_IN_DAY;
    // WITHDRAWAL_WINDOW_DAYS = 7
    // 如果这个差值在七天及以上，返回 99
    if (daysLate > WITHDRAWAL_WINDOW_DAYS - 1) return MAX_PENALTY_PCT;
    // 也就是 2 ^ (daysLate + 3) / 7 - 1
    uint256 penalty = (uint256(1) << (daysLate + 3)) / WITHDRAWAL_WINDOW_DAYS - 1;
    return Math.min(penalty, MAX_PENALTY_PCT);
}

对应于文档中的扣除比例：

文档中显示超过七天就全部不能领取，但是代码中显示最多只会扣除 99%。

到这里，我们就介绍完了时间挖矿的代码部分，接下来我们来看看 stake 挖矿的部分。

stake 挖矿

这里的 stake 其实比常见的挖矿计算逻辑要简单。常见的挖矿 APY 是根据用户质押数量占比以及参与时间来计算的，属于随挖随走类型的。而这里的 stake 挖矿的 APY 在参与时就已经固定了，且需要在参与时就指定参与时间，在时间到期后才能领取奖励，如果没有到期就领取，只能取回本金，没有任何的奖励。

用户可以在前面时间挖矿到期时调用 claimMintRewardAndStake 同时领取奖励并进行 stake，或者单独调用 stake(uint256 amount, uint256 term) 进行 stake 挖矿：

function stake(uint256 amount, uint256 term) external {
    require(balanceOf(_msgSender()) >= amount, "XEN: not enough balance");
    // XEN_MIN_STAKE = 0
    require(amount > XEN_MIN_STAKE, "XEN: Below min stake");
    // 最少 stake 1 天，最多 stake 1000 天
    require(term * SECONDS_IN_DAY > MIN_TERM, "XEN: Below min stake term");
    require(term * SECONDS_IN_DAY < MAX_TERM_END + 1, "XEN: Above max stake term");
    require(userStakes[_msgSender()].amount == 0, "XEN: stake exists");

    // burn staked XEN
    // 直接 burn，而不是从用户手里转账
    _burn(_msgSender(), amount);
    // create XEN Stake
    _createStake(amount, term);
    emit Staked(_msgSender(), amount, term);
}

function _createStake(uint256 amount, uint256 term) private {
    userStakes[_msgSender()] = StakeInfo({
        term: term,
        maturityTs: block.timestamp + term * SECONDS_IN_DAY,
        amount: amount,
        apy: _calculateAPY()
    });
    activeStakes++;
    totalXenStaked += amount;
}

整体的逻辑也比较简单，参与的时候需要指定时间 term。有一个小细节是在 stake 的时候直接 burn 掉了用户的 token，而不是通过转账的方法，这样可以少一步授权操作。由于合约本身既包含了挖矿操作，同时也是 ERC20，因此可以实现这个逻辑。

接下来我们看看计算 APY 的方法 _calculateAPY()：

function _calculateAPY() private view returns (uint256) {
    // 这里 genesisTs 是合约部署时间
    // (SECONDS_IN_DAY * XEN_APY_DAYS_STEP) -> 86400 * 90，也就是 90 天
    // 也就是计算，当前时间距离最开始的合约部署时间有多少个 90 天的差距
    uint256 decrease = (block.timestamp - genesisTs) / (SECONDS_IN_DAY * XEN_APY_DAYS_STEP);
    // XEN_APY_START = 20
    // XEN_APY_END = 2
    // 如果 decrease 差值大于 (20 - 2)，也就是上面的时间差值大于 18 * 90 = 1620 天
    // 则返回 2
    if (XEN_APY_START - XEN_APY_END < decrease) return XEN_APY_END;
    // 否则返回 20 - decrease
    return XEN_APY_START - decrease;
}

基本逻辑也是类似于上面计算 EAA 的方法，一次函数递减，参与的时间越早，相对应的 APY 就越大。初始值为 20，每过 90 天，减少 1。最终在 1620 天后，恒定为 2。对应于文档：

最终在 stake 到期后，可以调用 withdraw() 取出本金和奖励：

function withdraw() external {
    StakeInfo memory userStake = userStakes[_msgSender()];
    require(userStake.amount > 0, "XEN: no stake exists");

    uint256 xenReward = _calculateStakeReward(
        userStake.amount,
        userStake.term,
        userStake.maturityTs,
        userStake.apy
    );
    activeStakes--;
    totalXenStaked -= userStake.amount;

    // mint staked XEN (+ reward)
    _mint(_msgSender(), userStake.amount + xenReward);
    emit Withdrawn(_msgSender(), userStake.amount, xenReward);
    delete userStakes[_msgSender()];
}

其中计算奖励数量的方法 _calculateStakeReward()：

function _calculateStakeReward(
    uint256 amount,
    uint256 term,
    uint256 maturityTs,
    uint256 apy
) private view returns (uint256) {
    if (block.timestamp > maturityTs) {
        // DAYS_IN_YEAR = 365
        uint256 rate = (apy * term * 1_000_000) / DAYS_IN_YEAR;
        return (amount * rate) / 100_000_000;
    }
    return 0;
}

对应于文档中的：

对于 stake 挖矿而言，没有领取的限制，奖励数量不会变化。

总结

到这里我们就看完了主要的逻辑代码。这个玩法有意思的地方在于越早参与获得的奖励越多，相当于普通的挖头矿，但是同时也取决于总体的参与人数，如果后面没有人参与，那么也没啥意义。必须是参与的早且后面还有更多人参与的情况下，奖励才会更多。目前时刻总参与人数已经快达到 50 万了，热度确实很高。

同时，前面的时间挖矿和后面的 stake 挖矿也存在博弈关系，如果前面选择的时间越长，获得的奖励就越多，但是来到后面的 stake 挖矿的 APY 就会降低，需要大家自行抉择。

合约本身代码没啥难度，但是整体机制比较有趣，值得花点时间了解。

关于我

欢迎和我交流

流动性挖矿简介

首先我们先从用户的角度来理解一下流动性挖矿是什么，实际上就是用户通过在合约中质押一个 token 从而赚取另一个 token 的过程。例如，SushiSwap 最初推出的 DEX 流动性挖矿，用户可以通过将 SushiSwap 的 LP token 质押到合约中赚取 Sushi token。那么这个奖励具体是怎么发放以及如何实现的呢？我们今天就来研究一下这部分内容。

先来看几个例子：

一：假设有一个流动性挖矿的合约，可以质押 A token 赚取 B token。它在 0 秒时开始活动，每秒奖励 R 个 B token。此时有用户 Alice 在第 3 秒时质押了 2 个 A token，并且之后没有其他人参与，在第 8 秒时取出 token，图示：

那么他在此时获得的收益就是：

5R = (2 / 2) * (8 - 3) * R

其中，第一个 2 是用户 A 质押的数量，第二个 2 是合约中质押的总量，(8-3)是用户 Alice 质押的时间，R 是每秒发放的奖励。

二：同样是上面的合约，用户 Alice 在第 3 秒时质押了 2 个 A token，在第 6 秒时，用户 Bob 也质押了 2 个 A token。Alice 在第 8 秒时离场，Bob 在第 10 秒时离场。图示：

那么此时 Alice 可以获得的奖励是：

4R = (2 / 2) * (6 - 3) * R + (2 / 4) * (8 - 6) * R

Bob 可以获得的奖励是：

3R = (2 / 4) * (8 - 6) * R + (2 / 2) * (10 - 8) * R

对于 Alice，3～6 秒独占所有奖励，6～8 由于有 Bob 参与，因此需要计算自己在整个池子中的占比，再去计算奖励总额。

Bob 同理，6～8 秒与 Alice 分享，8～10 秒独享奖励。

同时，两个人的奖励总和是 7R，是这 7 秒时间的奖励发放总量。

我们思考一下这部分计算逻辑在代码中如何实现。首先，用户自己的本金数量在一段时间内（下次增加，减少质押数量之前）是不会变化的，但是由于有其它用户的参与，池子中质押的总数量是一直在变化的，而我们计算最终奖励的时候是需要用到池子总数量的，因此需要在代码中一直维护这个变量。

在上面的例子中，我们可以看到，3～6 秒中总量是 2，6～8 秒中总量是 4。这个简单的例子中，由于总量变化了一次，因此可以分解为两部分，但是如果说在 Alice 质押的这段时间，有一万个用户参与。那么总量变化次数将难以估计，这种情况下，如果我们要计算 Alice 可以获得的奖励，就需要知道每一个小区间的质押总量，然后再计算 Alice 的质押占比，再乘上各个小区间的时间长度，最后加起来，便是 Alice 的可以获得的奖励数量。这个计算量在普通的后端计算中也许可以实现，但是在合约中是不可能的，仅仅在 gas 消耗这方面就否定了这个方案。

注：这里的区间是指时间轴上每两个最近的时间点组成的时间段

那么有没有办法在合约中计算出奖励数量呢？答案是可以的。

优化数学原理

我们换一个思路，对于用户来说，他把 token 质押进来这段时间内（下次增加，减少质押数量之前），他所占的份额可能会发生变化，但是数量是没有变的。如果我们知道了每一单位质押 token 在每个区间内可以获得的奖励数量，那么把这些区间内的所有单位奖励都加起来，最后再乘上用户质押的数量，就是最终的奖励，即：

其中，k 是用户质押的数量，At 是每一单位在整个池子中的占比，Tt 是每个区间的时间长度，R * At * Tt 是每个区间每单位质押 token 可以获得的奖励。我们以区间将时间轴进行划分，假设用户在第 a 个区间存入，在第 b 个区间后取出，因此上面公式的跨度是从 a 到 b。

这个公式对于我们在合约中实现似乎没有什么帮助，因为需要计算该用户在每个区间内的质押占比，仍然是一笔不小的工作量。不过我们可以将上面公式稍微转化一下：

可以消去常量，即：

对于 0~b 与 0~(a-1)这部分，由于它们是从 0 区间开始累加的，因此是一个不断递增的变量。我们思考一下，对于用户在任何时刻的操作，此时的时间轴都是由 N 个区间构成的，且当前时刻是最后一个区间的右端点（因为区间就是这么定义的）。对于任何用户的操作，我们可以记录下以当前时刻点为右端点的区间的 At，并累加。这部分是不难计算的，因为 At 是每一单位在整个池子中的占比，所以容易算出：

At = 1 / Lt

其中 Lt 是当前区间质押总量，这个是已知的。Tt 是当前区间的时间长度，也是已知的。

对于 Alice 单一用户而言，在他对池子有操作的时候（增加，减少质押数量），在用户个人维度上记录一下当前的单位数量奖励累加值，再在用户下一次操作的时候，用最新的累加值减去上一次用户个人维度记录的累加值，就是这段时间内用户个人单位数量可以获得的单位奖励，再乘上之前的 kR，就可以算出这段时间内用户获得奖励数量。

实践

我们再来看看前面的例子验证一下：

第 3 秒时，Alice 入场，此刻左边的区间，总质押量为 0，因此单位数量获得的单位奖励为

s = 0

同时将 Alice 的单位累加值记为 0

第 6 秒时，Bob 入场，此刻左边的区间，总质押量为 2，因此单位数量获得的奖励为：

s = s + 1 / 2 * (6 - 3) = 1.5

同时将 Bob 的单位累加值记为 1.5

第 9 秒时，Alice 离场，此刻之前的区间，总质押量为 4，因此单位数量获得的奖励为：

s = s + 1 / 4 * (8 - 6) = 2

同时将 Alice 的单位累加值记为 2，此时 Alice 可以获得的奖励为：

4R = (2 - 0) * 2 * R

其中，第一个 2 是最新累加值，0 是 Alice 的上次累加值，第二个2是 Alice 的质押数量。

第 10 秒时，Bob 离场，此刻之前的区间，总质押量为 2，因此单位数量获得的奖励为：

s = s + 1 / 2 * (10 - 8) = 3

同时将 Bob 的单位累加值记为 3，此时 Bob 可以获得的奖励为：

3R = (3 - 1.5) * 2 * R

与我们上面最原始的方法得出的答案相同，验证成功。

代码实现

接下来我们看看代码怎么写。

首先定义几个变量：

// 质押奖励的发放速率
uint256 public rewardRate = 0;

// 每次有用户操作时，更新为当前时间
uint256 public lastUpdateTime;

// 我们前面说到的每单位数量获得奖励的累加值，这里是乘上奖励发放速率后的值
uint256 public rewardPerTokenStored;

// 在单个用户维度上，为每个用户记录每次操作的累加值，同样也是乘上奖励发放速率后的值
mapping(address => uint256) public userRewardPerTokenPaid;

// 用户到当前时刻可领取的奖励数量
mapping(address => uint256) public rewards;

// 池子中质押总量
uint256 private _totalSupply;

// 用户的余额
mapping(address => uint256) private _balances;

接着按照前面讲解的数学原理实现代码：

// 计算当前时刻的累加值
function rewardPerToken() public view returns (uint256) {
    // 如果池子里的数量为0，说明上一个区间内没有必要发放奖励，因此累加值不变
    if (_totalSupply == 0) {
        return rewardPerTokenStored;
    }
    // 计算累加值，上一个累加值加上最近一个区间的单位数量可获得的奖励数量
    return
        rewardPerTokenStored.add(
            lastTimeRewardApplicable().sub(lastUpdateTime).mul(rewardRate)
                .mul(1e18).div(_totalSupply)
        );
}

// 获取当前有效时间，如果活动结束了，就用结束时间，否则就用当前时间
function lastTimeRewardApplicable() public view returns (uint256) {
    return block.timestamp < periodFinish ? block.timestamp : periodFinish;
}

// 计算用户可以领取的奖励数量
// 质押数量 * （当前累加值 - 用户上次操作时的累加值）+ 上次更新的奖励数量
function earned(address account) public view returns (uint256) {
    return
        _balances[account].mul(rewardPerToken().sub(userRewardPerTokenPaid[account]))
            .div(1e18).add(rewards[account]);
}

modifier updateReward(address account) {
    // 更新累加值
    rewardPerTokenStored = rewardPerToken();
    // 更新最新有效时间戳
    lastUpdateTime = lastTimeRewardApplicable();
    if (account != address(0)) {
        // 更新奖励数量
        rewards[account] = earned(account);
        // 更新用户的累加值
        userRewardPerTokenPaid[account] = rewardPerTokenStored;
    }
    _;
}

上面的代码，实现了我们前面讲过的原理，同时将所有逻辑包装成了一个 modifier，这样与最基本的 stake，withdraw 逻辑抽离，使整个合约逻辑代码更清晰。

最后，实现 stake，withdraw 的逻辑，并用 updateReward 修饰：

function stake(uint256 amount) external nonReentrant notPaused updateReward(msg.sender) {
    require(amount > 0, "Cannot stake 0");
    _totalSupply = _totalSupply.add(amount);
    _balances[msg.sender] = _balances[msg.sender].add(amount);
    stakingToken.safeTransferFrom(msg.sender, address(this), amount);
    emit Staked(msg.sender, amount);
}

function withdraw(uint256 amount) public nonReentrant updateReward(msg.sender) {
    require(amount > 0, "Cannot withdraw 0");
    _totalSupply = _totalSupply.sub(amount);
    _balances[msg.sender] = _balances[msg.sender].sub(amount);
    stakingToken.safeTransfer(msg.sender, amount);
    emit Withdrawn(msg.sender, amount);
}

这段代码来自 Synthetic 的 StakingRewards 的合约（代码地址），我们这里只截取了最核心的逻辑部分，建议大家在理解了上面代码之后去看看完整的代码。

总结

今天我们简单聊了聊流动性挖矿的原理，其实它本身是运用了一个很巧妙的数学原理来实现的。目前 DeFi 中比较流行的两个流动性挖矿合约 StakingRewards 和 MasterChef 都是运用了这个原理。建议大家好好理解一下这一块，看懂之后再看市面上的其他流动性挖矿就会发现基本上大同小异了。英语好的朋友建议也看看下面的视频，讲解得也很透彻。

关于我

欢迎和我交流

参考

synthetix/contracts/StakingRewards.sol at develop · Synthetixio/synthetix

Synthetix Solidity smart contracts. Contribute to Synthetixio/synthetix development by creating an account on GitHub.

https://github.com

SushiSwap: MasterChef LP Staking Pool | Address: 0xc2edad66...7dca888cd | Etherscan

Contract: Verified | Balance: $23,021,510.77 across 3 Chains | Transactions: 464,780 | As at Oct-24-2025 10:42:54 PM (UTC)

https://etherscan.io

EIP-1167，又称 Minimal Proxy Contract，提供了一种低成本复制合约的方法。它有什么意义呢？我们先来看个例子：

function createPair(address tokenA, address tokenB) external returns (address pair) {
    require(tokenA != tokenB, 'UniswapV2: IDENTICAL_ADDRESSES');
    (address token0, address token1) = tokenA < tokenB ? (tokenA, tokenB) : (tokenB, tokenA);
    require(token0 != address(0), 'UniswapV2: ZERO_ADDRESS');
    require(getPair[token0][token1] == address(0), 'UniswapV2: PAIR_EXISTS'); // single check is sufficient
    bytes memory bytecode = type(UniswapV2Pair).creationCode;
    bytes32 salt = keccak256(abi.encodePacked(token0, token1));
    // 通过原始 bytecode 创建合约
    assembly {
        pair := create2(0, add(bytecode, 32), mload(bytecode), salt)
    }
    IUniswapV2Pair(pair).initialize(token0, token1);
    getPair[token0][token1] = pair;
    getPair[token1][token0] = pair; // populate mapping in the reverse direction
    allPairs.push(pair);
    emit PairCreated(token0, token1, pair, allPairs.length);
}

在 Uniswap v2 的工厂合约中，需要创建交易对合约，这里的方法是直接使用交易对合约，即 UniswapV2Pair 合约的 creationCode 进行创建。由于是创建原始的合约内容，因此有一个缺点就是耗费的 gas 取决于 Pair 合约的大小，Pair 合约的内容越多，耗费的 gas 越多。

那么有没有什么改进方法呢？答案是有的，就是通过代理合约来转发调用。从创建原始合约变为创建代理合约，而代理合约只需要负责将调用转发给原始合约就行了，实际执行的逻辑仍然使用最原始的合约。接下来的内容需要大家了解内存布局和 delegatecall 相关的内容，不了解的朋友可以看看这里和这里。

原理

提到代理，可能大家想到的第一反应就是合约升级，但是我们今天说的代理并不涉及合约升级，它仅仅负责合约调用的转发。

我们先来看看可升级合约的代理合约架构：

整个架构中存在一个代理合约和 N 个逻辑合约，只有一套数据，需要升级时则替换逻辑合约，同一时间只能存在一个逻辑合约。

再来看看今天提到的 Minimal Proxy Contract 架构：

整个架构中存在 N 个代理合约和一个逻辑合约，有多套数据分别存储在不同的代理合约中，所有代理合约共享逻辑合约的执行逻辑，同一时间存在多个代理合约。Minimal Proxy Contract 的原理就是将代理合约作为逻辑合约的复制品，各个代理合约存储各自的数据，需要多少份复制品就创建多少个代理合约即可。而代理合约本身只负责请求转发，因此其内容很少，从而耗费更少的 gas。

我们来看一个例子（注意这里是为了简单起见直接使用了构造函数，实际应用中不应该使用构造函数，因为这部分不会在代理合约中运行，即不会被初始化。因此如果有初始化逻辑，需要放在 initialize 函数中额外调用）：

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.15;

contract Demo {
    uint256 public a;

    constructor() {
        a = 1000;
    }

    function setA(uint256 _a) external {
        a = _a;
    }
}

现在我们要对这个 Demo 合约进行复制，可以借助 OZ 的 Clones 合约来完成：

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts v4.4.1 (proxy/Clones.sol)

pragma solidity ^0.8.0;
library Clones {
    /**
     * @dev Deploys and returns the address of a clone that mimics the behaviour of `implementation`.
     *
     * This function uses the create opcode, which should never revert.
     */
    function clone(address implementation) internal returns (address instance) {
        assembly {
            let ptr := mload(0x40)
            mstore(ptr, 0x3d602d80600a3d3981f3363d3d373d3d3d363d73000000000000000000000000)
            mstore(add(ptr, 0x14), shl(0x60, implementation))
            mstore(add(ptr, 0x28), 0x5af43d82803e903d91602b57fd5bf30000000000000000000000000000000000)
            instance := create(0, ptr, 0x37)
        }
        require(instance != address(0), "ERC1167: create failed");
    }
    ///....
}

clone 方法需要接受一个原始逻辑合约的地址，然后返回新生成的克隆合约（也就是我们上面说的代理合约）地址。

我们来看看上面代码是什么意思，首先 let ptr := mload(0x40) 获取内存中空闲内存指针的位置，下一行的 mstore(ptr, 0x3d602d80600a3d3981f33…)，将该数据存入内存中，接下来的 shl(0x60, implementation) 将地址左移 0x60，即 96 位。由于 address 类型实际只占用 20 个字节，而传入的参数是通过 0 补齐到 32 字节的。假设传入的地址是

0xbebebebebebebebebebebebebebebebebebebebe，则补齐的内容为：

0x000000000000000000000000bebebebebebebebebebebebebebebebebebebebe

左移 96 位之后恰好获得原始的地址数据。

接下来将地址数据 mstore 储存到内存中，内存位置为 0x14，即 20。这个数据恰好是上面一行 0x3d602d80600a3d39 中截断后面零值的长度。

第三个 mstore 再将 0x5af43d82803e903d… 拼接到前面的数据所在内存位置后面。三个 mstore 操作下来，此时内存中的数据为：

即三部分数据拼接到一起的结果。但是在合约地址前后拼接的这两部分是什么意思呢？

首先我们将前 10 个字节 3d602d80600a3d3981f3 反编译一下得到：

contract Contract {
    function main() {
        var var0 = returndata.length;
        memory[returndata.length:returndata.length + 0x2d] = code[0x0a:0x37];
        return memory[var0:var0 + 0x2d];
    }
}

即克隆合约的构造方法，内容是将整个克隆合约的字节码返回给 EVM。

再将后面的 45 字节数据 363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3 反编译：

contract Contract {
    function main() {
        var temp0 = msg.data.length;
        memory[returndata.length:returndata.length + temp0] = msg.data[returndata.length:returndata.length + temp0];
        var temp1 = returndata.length;
        var temp2;
        temp2, memory[returndata.length:returndata.length + returndata.length] = address(0xbebebebebebebebebebebebebebebebebebebebe).delegatecall.gas(msg.gas)(memory[returndata.length:returndata.length + msg.data.length]);
        var temp3 = returndata.length;
        memory[temp1:temp1 + temp3] = returndata[temp1:temp1 + temp3];
        var var1 = temp1;
        var var0 = returndata.length;
    
        if (temp2) { return memory[var1:var1 + var0]; }
        else { revert(memory[var1:var1 + var0]); }
    }
}

这部分内容是利用 delegatecall 将调用进行转发的逻辑。

clone 方法的最后一行使用了 create 方法创建克隆合约，长度 0x37 即 55 是内存中克隆合约字节码的长度。

实践

现在我们来实际操作一下，首先编写克隆工厂合约:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.0;

import "./Clones.sol";

contract MyClonesFactory {
    using Clones for address;

    event ProxyGenerated(address proxy);

    function clone(address implementation) external {
        address proxy = implementation.clone();
        emit ProxyGenerated(proxy);
    }
}

接下来先部署原始 Demo 合约，然后部署 MyClonesFactory 合约，随后调用 clone 方法，传入 Demo 合约地址，即可创建克隆合约。

创建原始 Demo 合约时耗费了 14 万 gas：

而 clone 方法创建克隆合约只花费了 6 万 gas：

注意克隆合约是通过内部交易创建的：

Etherscan 也已经支持了 EIP-1167 的合约验证，只要原始合约代码已经验证，那么克隆合约代码自动验证。

原始合约验证代码之前的克隆合约：

可以看到克隆合约的字节码就是去除构造方法字节码之后其余的部分，然后我们验证一下原始合约的代码，这时克隆合约就已经自动验证了，并且标注了 Minimal Proxy Contract：

注意需要直接验证原始逻辑合约，如果验证克隆合约会失败。

总结

EIP-1167 提供了一种低成本克隆合约的方法，并且 Etherscan 也已经提供了支持，在需要创建多个合约的场景下，不失为一种好方法。

关于我

欢迎和我交流

参考

https://medium.com/coinmonks/diving-into-smart-contracts-minimal-proxy-eip-1167-3c4e7f1a41b8

💎🎉 OpenZeppelin Clones 解説 🎉💎

OpenZeppelinのUpgradeable Contractsに関するドキュメントを読んでいて、Clonesの存在を知りました。 ClonesはUpgradable Contractsの仕組みの一部であるProxyの一種で、Implementation Contractの更新機能を省いたProxyだと言えます。（つまり、Implementation ...

https://zenn.dev

EIP- 1167, Minimal Proxy Contract on Etherscan

EIP- 1167, Minimal Proxy Contract on Etherscan Etherscan now supports Minimal Proxy Contract in EIP-1167. EIP-1167 define a standard where a minimal proxy contract forwards all calls and 100% of the ...

https://medium.com

代码分析

我们先看一下 Audius 的合约架构，它采用了可升级合约的架构：

我们知道，可升级合约架构中，代理合约存储了数据，逻辑合约中只是执行逻辑而已，执行过程中涉及到的内存变量会反向修改代理合约中的数据。我们来看看 Audius 的合约是怎么写的：

AudiusAdminUpgradeabilityProxy（代理合约，节选）

contract AudiusAdminUpgradeabilityProxy is UpgradeabilityProxy {
    address private proxyAdmin;
    string private constant ERROR_ONLY_ADMIN = (
        "AudiusAdminUpgradeabilityProxy: Caller must be current proxy admin"
    );
}

在代理合约中，slot 0 的位置是 proxyAdmin，这与我们之前讲过的合约升级不同。我们前面说过为了避免内存槽位冲突，EIP-1967 标准应运而生。它将 implementation 和 admin 这两个字段放在了两个特殊的插槽中：

# bytes32(uint256(keccak256('eip1967.proxy.implementation')) - 1)
0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc

# bytes32(uint256(keccak256('eip1967.proxy.admin')) - 1)
0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103

这样做的目的就是为了最大限度保证这两个保留数据不会和逻辑合约中的数据槽位冲突，而 Audius 这种写法正是造成这次 bug 的原因。

我们再来看看逻辑合约的内容：

Governance（逻辑合约，节选）

contract Initializable {
    /**
     * @dev Indicates that the contract has been initialized.
     */
    bool private initialized;

    /**
     * @dev Indicates that the contract is in the process of being initialized.
     */
    bool private initializing;

    /**
     * @dev Modifier to use in the initializer function of a contract.
     */
    modifier initializer() {
        require(
            initializing || isConstructor() || !initialized,
            "Contract instance has already been initialized"
        );

        bool isTopLevelCall = !initializing;
        if (isTopLevelCall) {
            initializing = true;
            initialized = true;
        }

        _;

        if (isTopLevelCall) {
            initializing = false;
        }
    }

    ///....

    // Reserved storage space to allow for layout changes in the future.
    uint256[50] private ______gap;
}

contract InitializableV2 is Initializable {
    /// ....
}

contract Governance is InitializableV2 {
    /// ....
}

按照合约继承的内存分布规则，Initializable 合约中的 initialized 和 initializing 这两个变量分别位于逻辑合约 Governance 的 slot 0 和 slot 1 中。

看到这里，大家是不是已经发现了问题。如果按照这种写法，那么代理合约和逻辑合约的内存槽位不是冲突了吗？没错，但还有一点要注意的是，由于 initialized 和 initializing 都是 bool 类型变量，因此他们各自都只占据一字节（注意，是 1 byte，不是 1 bit），所以说它们俩实际上是被打包放在了 slot 0 中。也就是说，slot 0 的结构是：

上图是逻辑合约的 slot 0 内存分布。由于与代理合约的 ProxyAdmin 冲突，且 ProxyAdmin 的值为：

0x4DEcA517D6817B6510798b7328F2314d3003AbAC

因此，对应的 slot 0 槽位图示为：

这说明 initialized 和 initializing 这两个变量的值使用了 ProxyAdmin 实际值的最后两个字节！而恰好最后两个字节（0xAB, 0xAC）都是非零值，这也就造成在实际可升级合约的数据读取中，initialized 和 initializing 的值总是 true。而这个巧合其实也取决于 ProxyAdmin 的最后两个字节是什么，如果它的地址最后两字节都是零： 0x4DEcA517D6817B6510798b7328F2314d30030000，那么 initialized 和 initializing 便都是 false 了。

冲突原因已经找到了，我们来看看这个冲突会造成什么。再次看看逻辑合约：

contract Initializable {
    ///....
    modifier initializer() {
        require(
            initializing || isConstructor() || !initialized,
            "Contract instance has already been initialized"
        );

        bool isTopLevelCall = !initializing;
        if (isTopLevelCall) {
            initializing = true;
            initialized = true;
        }

        _;

        if (isTopLevelCall) {
            initializing = false;
        }
    }

    ///....

    // Reserved storage space to allow for layout changes in the future.
    uint256[50] private ______gap;
}

对于 initializer 修饰符，由于 initializing 为 true，因此可以通过 require 校验。而下面的 isTopLevelCall 会被赋值为 false，造成 if 语句无法执行，那么 initializing 将永远为 true，也就是说 initializer 已经起不到限制作用了。

黑客就是利用了这个 bug，从而可以调用各种被 initializer 修饰的方法。这些方法中包含一些特权方法，本来只能被管理员调用一次，这下被黑客调用，损失惨重。

解决办法

解决这个 bug 的中心思想就是去除代理合约和逻辑合约的内存冲突，我们来看看官方的新版逻辑合约：

contract Initializable {
    address private proxyAdmin;

    uint256 private filler1;
    uint256 private filler2;

    /**
     * @dev Indicates that the contract has been initialized.
     */
    bool private initialized;

    /**
     * @dev Indicates that the contract is in the process of being initialized.
     */
    bool private initializing;

    /**
     * @dev Modifier to use in the initializer function of a contract.
     */
    modifier initializer() {
        require(msg.sender == proxyAdmin, "Only proxy admin can initialize");
        require(
            initializing || isConstructor() || !initialized,
            "Contract instance has already been initialized"
        );

        bool isTopLevelCall = !initializing;
        if (isTopLevelCall) {
            initializing = true;
            initialized = true;
        }

        _;

        if (isTopLevelCall) {
            initializing = false;
        }
    }

    /// @dev Returns true if and only if the function is running in the constructor
    function isConstructor() private view returns (bool) {
        // extcodesize checks the size of the code stored in an address, and
        // address returns the current address. Since the code is still not
        // deployed when running a constructor, any checks on its code size will
        // yield zero, making it an effective way to detect if a contract is
        // under construction or not.
        address self = address(this);
        uint256 cs;
        assembly {
            cs := extcodesize(self)
        }
        return cs == 0;
    }

    // Reserved storage space to allow for layout changes in the future.
    uint256[47] private ______gap;
}

1. 将 initialized 和 initializing 变量后移，预留出空间解决内存冲突

2. initializer 修饰符中同时添加只能 proxyAdmin 调用的限制，双重保险

3. 由于前面添加了三个变量，因此最后的 ______gap 预留位置要减少，由之前的 50 个减少为 47 个，这样做是为了兼容之前的数据。避免更新后老数据又冲突了。

总结

一个内存插槽冲突引发的血案，警示我们在编写可升级合约时一定要注意这方面问题。

关于我

欢迎和我交流

参考

Audius Governance Takeover Post-Mortem 7/23/22 | Audius Blog

Your hub for the latest happenings, feature releases, and important notices from Audius.

https://blog.audius.co

Daniel Von Fange

@danielvf

The Audius hack this week involved two contracts that overlapped the same storage slot (for three different variables).

The end of the admin address on the proxy was used by the implementation contract as value of the initializing and initialized variables. 1/6

340

2:49 PM • Jul 29, 2022

编译合约

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.15;

contract Demo {
    constructor() {}

    function func1() public {}

    function func2() public {}
}

该合约中一共有两个方法，分别是 func1 与 func2。我们这里着重于理解方法调用的过程，因此简单起见就将方法内容置为空。

使用 solc 进行编译：

solc Demo.sol --bin

得到的字节码为：

利用 0xfe 操作符分割后，得到的各部分分别为：

6080604052348015600f57600080fd5b5060818061001e6000396000f3（init bytecode）

6080604052348015600f57600080fd5b506004361060325760003560e01c806374135154146037578063b1ade4db14603f575b600080fd5b603d6047565b005b60456049565b005b565b56（runtime bytecode）

a264697066735822122069532a763e3f61abcfbb422ae7dc4587126c8f8b2264e73bb837a5924ebb1d4964736f6c634300080f0033（metadata hash）

init bytecode 是合约部署部分，我们在上篇文章中已经介绍过了。调用合约方法是与 runtime bytecode 这部分进行交互，我们主要来研究这一块。

我们知道，调用合约方法交易的 data 域就是合约签名与参数的拼接内容。具体来说，就是合约签名的 keccak256 哈希值的前 4 个字节再加上参数内容就构成了 data 部分。

在上面例子中，func1 与 func2 的哈希值前 4 个字节分别是 0x74135154 与 0xb1ade4db，同时由于这两个方法都没有参数，因此不用在后面拼接参数。如果 fun1 的方法签名为：

function func1(uint _a) public {}

那么就需要添加参数，并且补齐 32 字节：

其中 0x254e43db 是 func1(uint256) 的哈希值前 4 个字节。

接下来我们就来看看在调用合约方法的过程中，在 EVM 字节码层面会发生什么。我们以调用 func1 方法为例，那么此时交易的 data 域内容就为 0x74135154。

我们先将 runtime bytecode 部分的字节码与其 opcodes 一一对应起来：

0 -> 60 PUSH1
1 -> 80 0x80
2 -> 60 PUSH1
3 -> 40 0x40
4 -> 52 MSTORE
5 -> 34 CALLVALUE
6 -> 80 DUP1
7 -> 15 ISZERO
8 -> 60 PUSH1
9 -> 0f 0xF
10 -> 57 JUMPI
11 -> 60 PUSH1
12 -> 00 0x0
13 -> 80 DUP1
14 -> fd REVERT
15 -> 5b JUMPDEST
16 -> 50 POP
17 -> 60 PUSH1
18 -> 04 0x4
19 -> 36 CALLDATASIZE
20 -> 10 LT
21 -> 60 PUSH1
22 -> 32 0x32
23 -> 57 JUMPI
24 -> 60 PUSH1
25 -> 00 0x0
26 -> 35 CALLDATALOAD
27 -> 60 PUSH1
28 -> e0 0xE0
29 -> 1c SHR
30 -> 80 DUP1
31 -> 63 PUSH4
(32 ~ 35) -> 74135154 func1 方法签名哈希前四字节
36 -> 14 EQ
37 -> 60 PUSH1
38 -> 37 0x37
39 -> 57 JUMPI
40 -> 80 DUP1
41 -> 63 PUSH4
(42 ~ 45) -> b1ade4db func2 方法签名哈希前四字节
46 -> 14 EQ
47 -> 60 PUSH1
48 -> 3f 0x3F
49 -> 57 JUMPI
50 -> 5b JUMPDEST
51 -> 60 PUSH1
52 -> 00 0x0
53 -> 80 DUP1
54 -> fd REVERT
55 -> 5b JUMPDEST
56 -> 60 PUSH1
57 -> 3d 0x3D
58 -> 60 PUSH1
59 -> 47 0x47
60 -> 56 JUMP
61 -> 5b JUMPDEST
62 -> 00 STOP
63 -> 5b JUMPDEST
64 -> 60 PUSH1
65 -> 45 0x45
66 -> 60 PUSH1
67 -> 49 0x49
68 -> 56 JUMP
69 -> 5b JUMPDEST
70 -> 00 STOP
71 -> 5b JUMPDEST
72 -> 56 JUMP
73 -> 5b JUMPDEST
74 -> 56 JUMP

来看看这部分字节码都干了些什么。

调用合约方法流程

0 - 4 行我们已经非常熟悉了，加载空闲内存指针。

5 - 14 行是校验 msg.value 必须为零，我们在上篇文章已经看到过这部分了。由于合约中没有 payable 方法，因此要求所有的合约调用的 callvalue 都要为零，否则会在 14 行REVERT 失败。

如果传入的 value 为零，则进入正常流程 15 行，在 16 行将栈中无用数据 pop 出。

17 - 18 行将 0x4 放入栈中，它代表正常的方法调用签名长度。此时栈为：

| 4

19 行获取到 data 域的长度并放入栈中，0x74135154 的长度为 4 个字节。此时栈为：

| 4 | 4

20 行从栈中获取两个数据，并判断第一个数字是否小于第二个数字，小于返回 1，否则返回 0。这里由于 4 = 4，因此返回 0。这部分是什么意思呢？上面我们说到第一次放入栈中的 4 代表正常的方法调用签名长度，也就是方法签名前四个字节的意思。无论我们调用了哪个方法，有没有参数，data 域的长度都至少应该是 4。如果某个交易的 data 域的长度小于 4，说明它并不是正常的方法调用，那么在接下来的流程中肯定就走不到正常的方法名匹配部分，要么交易失败，要么进入到 fallback 的调用流程中。我们这个例子中没有声明 fallback 方法，因此如果这时 LT 操作符返回 1（即 TRUE），交易就会失败。

在这里正常情况下，此时栈中为：

| 0

21 - 22 行将 0x32 放入栈中：

| 0 | 0x32

23 行 JUMPI(0x32, 0) 操作符根据栈中数据判断是否跳转。由于第二个参数是 0，因此不跳转，继续向下执行。这里假设第二个参数是 1，也就是上一步中的 data 域长度小于 4 字节，流程会跳转到 0x32，也就是 50 行，并最终在 54 行 REVERT 交易失败，验证了我们上面的说法。

24 - 25 行将 0x0 放入栈中：

| 0

26 行加载 32 字节长度的 data 域放入栈中，开始位置从栈中获取，这里即为 calldata[0]，当前的 data 域内容为 0x74135154，不够 32 字节因此需要用 0 补齐。此时栈中为：

| 7413515400000000000000000000000000000000000000000000000000000000

27 - 28 行将 0xE0，即 224 放入栈中：

| 0x7413515400000000000000000000000000000000000000000000000000000000 | 0xE0

29 行 SHR 取出栈中数据，将 7413515400000000000000000000000000000000000000000000000000000000 右移 224 位，前者的长度是 256（即 64 * 4） 位，右移之后变成 0x74135154，刚好是四个字节，这四个字节恰好是方法签名哈希值的前四个字节，是用来匹配合约中的方法的。此时栈为：

| 0x74135154

30 行复制一份栈顶数据：

| 0x74135154 | 0x74135154

31 - 35 将 func1 的方法签名哈希前四个字节放入栈中：

| 0x74135154 | 0x74135154 | 0x74135154

36 行 EQ 判断栈顶两个元素是否相等，这里相等，因此返回 1:

| 0x74135154 | 1

37 - 38 将 0x37 放入栈中：

| 0x74135154 | 1 ｜ 0x37

39 行 JUMPI(0x37, 1) 判断是否跳转，此时会跳转到 0x37，即 55 行。栈为：

| 0x74135154

这里如果第二个参数，也就是 EQ 的结果为 0，说明调用的方法与当前的方法不匹配，则不跳转，继续向下运行，寻找下一个方法签名进行匹配。

此时，我们已经找到了相匹配的合约方法，也就是说已经完成了匹配方法名的过程。接下来就是执行方法体内容了。

跳转到 55 行，56 - 59 将 0x3D 与 0x47 放入栈中：

| 0x74135154 | 0x3D | 0x47

其中，0x47，即 71 是 func1 方法体所在的字节码开始位置。

60 行 JUMP 跳转到 71 行执行 func1 方法体，此时栈为：

| 0x74135154 | 0x3D

由于 func1 内容为空，因此不需要执行什么操作。

72 行获取栈顶元素 0x3D，即 61，并跳转。

61 - 62 行这里会进行方法调用的结尾工作，通过 STOP 结束。

小结

这篇文章我们学习了合约方法调用在字节码层面的实现。我们通过一个简单的合约，了解了合约方法调用过程中，用户的请求是如何匹配到具体的方法的。其实内容也比较简单，就是在栈中与所有的方法签名哈希值一个一个进行比对，如果相同，则跳转到相应的部分执行对应方法内容。这里还是建议大家都亲手去 evm.codes 这个网站去实际操作一下，感受整个流程中内存与栈内容的变化，会加深对整个流程的理解。

关于我

欢迎和我交流

参考

A deep-dive into Solidity - function selectors, encoding and state variables

In the last post, we have seen how the Solidity compiler creates code - the init bytecode - to prepare and deploy the actual bytecode executed at runtime. Today, we will look at a few standard patterns that we find when looking at this runtime bytecode.

http://leftasexercise.com

EVM Deep Dives: The Path to Shadowy Super Coder 🥷 💻 - Part 1

Digging deep into the EVM mechanics during contract function calls

https://noxx.substack.com

编译合约

我们来看一个例子：

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.15;

contract Demo {
    constructor() {}
}

这个合约比上篇文章的还要简单，它什么内容都没有，仅仅有一个合约的框架而已，这样我们就可以不用关心一些额外内容比如变量赋值等，只需关心合约部署的最核心步骤。

先使用 solc 进行编译：

solc Demo.sol --bin

编译后的字节码为：

6080604052348015600f57600080fd5b50603f80601d6000396000f3fe6080604052600080fdfea2646970667358221220c6a9021ede10c2befd51f04c8bcd9294ea47f79868b9ad6d81af3e41d3b2c2bf64736f6c634300080f0033

按照 0xfe 操作符分割后的结果为：

6080604052348015600f57600080fd5b50603f80601d6000396000f3（init bytecode）

6080604052600080fd（runtime bytecode）

a2646970667358221220c6a9021ede10c2befd51f04c8bcd9294ea47f79868b9ad6d81af3e41d3b2c2bf64736f6c634300080f0033（metadata hash）

其中 init bytecode 部分就是合约的部署流程，我们主要着重于这部分。

我们前面说过，这些字节码对应的其实都是 opcodes，也就是操作符和操作数，我们可以通过

solc Demo.sol --opcodes

来得到对应的 opcodes：

PUSH1 0x80 PUSH1 0x40 MSTORE CALLVALUE DUP1 ISZERO PUSH1 0xF JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST POP PUSH1 0x3F DUP1 PUSH1 0x1D PUSH1 0x0 CODECOPY PUSH1 0x0 RETURN INVALID PUSH1 0x80 PUSH1 0x40 MSTORE PUSH1 0x0 DUP1 REVERT INVALID LOG2 PUSH5 0x6970667358 0x22 SLT KECCAK256 0xC6 0xA9 MUL 0x1E 0xDE LT 0xC2 0xBE REVERT MLOAD CREATE 0x4C DUP12 0xCD SWAP3 SWAP5 0xEA SELFBALANCE 0xF7 SWAP9 PUSH9 0xB9AD6D81AF3E41D3B2 0xC2 0xBF PUSH5 0x736F6C6343 STOP ADDMOD 0xF STOP CALLER

我们将 init bytecode 部分的 16 进制字节码与其 opcodes 一一对应起来：

0  -> 60 PUSH1
1  -> 80 0x80
2  -> 60 PUSH1
3  -> 40 0x40
4  -> 52 MSTORE
5  -> 34 CALLVALUE
6  -> 80 DUP1
7  -> 15 ISZERO
8  -> 60 PUSH1
9  -> 0f 0xF
10 -> 57 JUMPI
11 -> 60 PUSH1
12 -> 00 0x0
13 -> 80 DUP1
14 -> fd REVERT
15 -> 5b JUMPDEST
16 -> 50 POP
17 -> 60 PUSH1
18 -> 3f 0x3F
19 -> 80 DUP1
20 -> 60 PUSH1
21 -> 1d 0x1D
22 -> 60 PUSH1
23 -> 00 0x0
24 -> 39 CODECOPY
25 -> 60 PUSH1
26 -> 00 0x0
27 -> f3 RETURN

我们今天的目标就是把这些字节码搞懂，看看它都干了些什么。

合约部署流程

开头的 0 → 4 是我们前面讲过的加载空闲内存指针的过程，即 MSTORE(0x40, 0x80)，此时内存中的数据为（第三行的最后为 80）：

每一行的长度是 64，即 32 个字节。我们前面说过 0x40 - 0x5f 内存区域是用来存储空闲内存指针的，对照上面结果，确实如此。

接下来，第 5 行的 CALLVALUE，获取创建合约时发送的 ETH 数量，并存入栈中。我们创建该合约并不需要同时发送 ETH，因此值为 0。此时的栈中数据为（左边是栈底，右边是栈顶，下同）：

| 0

第 6 行的 DUP1，会取栈顶第一个元素，也就是 0，并且复制一份，再放入栈中。此时，栈中数据为：

| 0 | 0

第 7 行 ISZERO，取出栈顶元素，判断是否为 0，若为 0，返回 1，否则返回 0，最后将结果放入栈中。此时，栈为：

| 0 | 1

第 8、9 行，将 0xF 放入栈中。此时，栈为：

| 0 | 1 | F

第 10 行，JUMPI 会取出栈顶的两个元素，并将其作为参数，即 JUMPI(F, 1)，如果第二个参数是 1，则跳转到第一个参数，也就是 F 位置，如果不是 1，则不跳转。这里需要跳转，F 是 16 进制中的 15，因此需要跳转到 15 行。这个 15 行，也就是从 0 开始第 15 个字节处。每个操作符都消耗一个字节，操作数也同样消耗字节。此时，栈为：

| 0

第 15 行是 JUMPDEST，是跳转的目标位，也就是说，凡是 JUMPI 指令进行跳转，跳转的目标必须是它，它本身并没有什么实际作用，仅仅用做标记位。如果跳转至此，没有该操作符，则流程失败。

第 16 行，POP 会弹出栈顶的元素，即弹出 0。此时栈为空：

|

第 17、18 行，PUSH1 3F，即将 0x3F 放入栈中。此时，栈为：

| 3F

第 19 行，DUP1 复制栈顶元素。此时，栈为：

| 3F | 3F

第 20 到 23 行，连续将两个元素 0x1D、0x0 放入栈中。此时，栈为：

| 3F | 3F | 1D | 0

第 24 行，CODECOPY，将当前运行环境中的字节码复制到内存中，接收 3 个参数，分别是目标内存位置、要复制数据的起始位置、复制长度。这里是 CODECOPY(0, 1D, 3F)，即从字节码中的 1D 起始，复制长度为 3F 的字节码到内存位置 0 处。

我们来看看这几个参数是什么意思，首先第一个参数是说将结果都放在 0 开始的内存处，这个好理解。第二个参数 1D，换成 10 进制是 29，我们前面看的 init bytecode 部分一共有 27 行（算上 0 行有 28 行），由于我们是按照 0xfe 来将其分割的，因此按照全部字节码来说，0xfe 是位于第 28 行的，而第 29 行开始的部分就是 runtime bytecode 了。也就是说，我们需要从 runtime bytecode 处开始复制代码，长度是 0x3F，即 10 进制的 63。我们再来看整体的字节码，从 runtime bytecode 处的 6080604052… 开始的字节码，一直到最后，长度是 126，恰好是 63 个字节。

也就是说，我们将除了 init bytecode 部分的 runtime bytecode 与 metadata hash 复制到了内存中。此时，内存中数据为：

6080604052600080fdfea2646970667358221220c6a9021ede10c2befd51f04c
8bcd9294ea47f79868b9ad6d81af3e41d3b2c2bf64736f6c634300080f003300
0000000000000000000000000000000000000000000000000000000000000080
0000000000000000000000000000000000000000000000000000000000000000

同时，栈中数据为：

| 3F

接下来，第 25、26 行，PUSH1 0x0 将 0 放入了栈中。此时，栈为：

| 3F | 0

最后，第 27 行，RETURN 从内存中读取数据并返回给 EVM，并结束流程。它接收两个参数，分别是起始位置以及长度，即 RETURN(0, 3F)。前面我们说了 0x3F 是 runtime bytecode 与 metadata hash 的长度，也就说从内存中读取了这两部分的数据，并返回。即返回值为：

6080604052600080fdfea2646970667358221220c6a9021ede10c2befd51f04c
8bcd9294ea47f79868b9ad6d81af3e41d3b2c2bf64736f6c634300080f0033

此时，栈中数据已经清空。

现在，我们已经走完了部署的整个流程，可以看到，整个部署的流程主要就是简单的两步：

1. 运行构造函数的逻辑

2. 获取 runtime bytecode 与 metadata hash 的内容并返回给 EVM

接下来我们回到第 5 行，这里我们获取了 CALLVALUE，前面的流程中值为 0。现在我们假设在创建合约的同时也发送了 ETH，那么这里得到的就是非零值，这里我们假设是在创建合约时同时发送了 1 wei（只要是非零值结果都一样），那么栈中为：

| 1

第 6 行 DUP1，复制后栈为：

| 1 | 1

第 7 行 ISZERO，由于栈顶非零，因此结果为 0，此时栈中为：

| 1 | 0

第 8、9 行，将 0xF 放入栈中。此时，栈为：

| 1 | 0 | F

第 10 行，JUMPI(F, 0)，由于第二个参数是 0，因此不跳转，继续向下执行。

第 11、12 行，PUSH1 0x0 将 0 放入栈中：

| 1 | 0

第 13 行 DUP1，此时栈为：

| 1 | 0 | 0

第 14 行 REVERT，抛出错误，流程以失败结束。

那么我们说的这个 CALLVALUE 0 或者非 0，到底是什么意思呢？

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.15;

contract Demo {
    constructor() {}
}

看看代码，其实就是因为合约中的构造函数没有 payable 关键字，禁止向合约中发送 ETH。因此在字节码中需要对此进行判断。那么我们就会想到，如果加上了 payable 之后，字节码会怎样呢？

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.15;

contract Demo {
    constructor() payable {}
}

编译后的字节码：

6080604052603f8060116000396000f3（init bytecode）

6080604052600080fd（runtime bytecode）

a26469706673582212208c516264e3e6785d014f2db856266d96d155fdd72ef5e53ecc896b5837f13cc664736f6c634300080f0033（metadata hash）

这时我们看到 init bytecode 部分短了很多，其实就是去掉了判断 CALLVALUE 的部分。我们再将其与 opcodes 一一对应：

0  -> 60 PUSH1
1  -> 80 0x80
2  -> 60 PUSH1
3  -> 40 0x40
4  -> 52 MSTORE
5  -> 60 PUSH1
6  -> 3f 0x3F
7  -> 80 DUP1
8  -> 60 PUSH1
9  -> 11 0x11
10 -> 60 PUSH1
11 -> 00 0x0
12 -> 39 CODECOPY
13 -> 60 PUSH1
14 -> 00 0x0
15 -> f3 RETURN

我们再简单过一下流程。

0 → 4: MSTORE(0x40, 0x80)，内存为：

5 → 6: PUSH1 0x3F

| 3F

7: DUP1

| 3F | 3F

8 → 9: PUSH1 0x11

| 3F | 3F | 11

10 → 11: PUSH1 0x0

| 3F | 3F | 11 | 0

12: CODECOPY(0, 11, 3F)，此时内存为：

13 → 14: PUSH1 0x0

| 3F | 0

15: RETURN(0, 3F)，内存中前 3F 个字节，即

我们看到，由于构造函数中有 payable 关键字，也就是发不发送 ETH 都可以，对应于字节码的整个流程中确实没有了对于 CALLVALUE 的判断。

实际部署合约

我们从字节码方面走完了整个部署流程，那么我们来实际部署一个合约，来看看具体交易的细节。仍然使用最开始的合约：

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.15;

contract Demo {
    constructor() {}
}

通过 Remix 或者其它工具进行部署。我在 Rinkeby 上部署了合约，部署的交易哈希是：

利用 Ethersjs 读取交易详情：

从图中注意到两点，一个是 to 字段为空，一个是 data 字段恰好就是我们前面编译合约之后得到的字节码，这也正是部署合约交易的两个特点。

小结

这篇文章我们学习了字节码层面的合约部署流程，我们以最简单的合约为例，逐一走过了整个流程。对于有更复杂操作的合约，原理都一样，只不过是多了一些变量赋值等操作。这里强烈推荐 evm.codes 这个网站，将字节码放进去，我们就可以一步一步观察到实际的内存与栈中的数据，分析字节码会更加直观。

下篇文章我们来聊聊合约方法调用的过程，仍然是从字节码层面分析，相对会更加复杂一点，不过也更加有趣。

关于我

欢迎和我交流

参考

A deep-dive into Solidity - contract creation and the init code

In some of the previous posts in this series, we have already touched upon contract creation and referred to the fact that during contract creation, an init bytecode is sent as part of a transaction which is supposed to return the actual bytecode of the smart contract.

http://leftasexercise.com

合约编译

我们用一个简单的图示来解释这个过程：

我们从一个很简单的例子开始（文件命名为 Demo.sol）：

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.15;

contract Demo {
    uint256 a;
    constructor() {
      a = 1;
    }
}

我们平时开发项目用的都是 hardhat，forge 这种框架，他们的底层都是通过 solc 来进行编译。这次我们就直接使用编译工具 solc 来进行编译，可以参考这里进行安装。这里列出 Mac 的安装方法：

brew update
brew upgrade
brew tap ethereum/ethereum
brew install solidity

安装完成后，我们来编译试试，使用下面的命令：

solc Demo.sol --bin

输出以下内容：

======= Demo.sol:Demo ======= Binary: 6080604052348015600f57600080fd5b506001600081905550603f8060256000396000f3fe6080604052600080fdfea26469706673582212204ca38d4a605f03f1487b9cb337c0853cca3c62a6c42f942ecb021fb7357002b564736f6c634300080f0033

我们看到在结果中输出了一串 16 进制字符，这就是上面的合约经过编译过后的字节码。我们前面说过，字节码是一串二进制的字符，这里显示为 16 进制方便阅读。注意到我们在命令中指定了 --bin 参数，因此输出的是 16 进制。

第一眼看见这串字符是不是已经懵了，别慌，我们慢慢来研究。首先，我们需要知道，EVM 的核心实际上是一个 stack machine（栈机器），它会接受操作符和操作数，学过数据结构的朋友应该都了解栈的原理。其次，上面这些字符都是由操作符和操作数组成的。例如开头的 60 代表的是 PUSH1，也就是将后面的一个字节（这里是 80）压入栈中。后面又是一个 60，接着是 40，即代表将 40 压入栈中。后面是 52，代表 MSTORE，它需要消耗两个操作数，需要从栈中获取。也就是说，上面的 6080604052，就代表着：

MSTORE 的两个操作数分别为 0x40、0x80，即 MSTORE(0x40, 0x80)，也就是在内存中地址 0x40 处存储了数据 0x80。（这一句不明白没关系，我们先往下看）

现在我们已经明白了字节码的基本逻辑，它就是由操作符和操作数组成的。其中两个字符代表一个字节，操作符都是一个字节，但是操作数可能有多个字节。像我们前面看到的 PUSH1，是将后面的一个字节压入栈中，如果是 PUSH4，就是将后面的四个字节压入栈中。一般将操作符称为 Opcodes，这里可以看到所有的 Opcodes。需要注意的是操作符和操作数有可能重复，例如判断 60 是操作符还是操作数，取决于它在字节码中的位置，并不是绝对的。例如 6060，前面的 60 是操作符，后面的就是操作数，代表 PUSH1 60。

字节码构造

接下来我们看看字节码的构造，我们在上面的字节码中搜索 fe，可以看到其中有两个 fe，同时查询 Opcodes 对照表，可知 fe 是无效操作符（INVALID）。它的作用其实是分隔符，它将字节码分成了三部分：

1. init bytecode（初始化字节码）

2. runtime bytecode （运行时字节码）

3. metadata hash（合约的一些 meta 信息哈希）

那么我们前面编译的字节码就被分成了三部分：

6080604052348015600f57600080fd5b506001600081905550603f8060256000396000f3（init bytecode）

6080604052600080fd（runtime bytecode）

a26469706673582212204ca38d4a605f03f1487b9cb337c0853cca3c62a6c42f942ecb021fb7357002b564736f6c634300080f0033（metadata hash）

我们先来看看最后这里的 metadata hash，它默认是合约 metadata 文件的 IPFS 哈希值，我们可以使用：

solc Demo.sol --metadata

来获取到其 metadata：

{
    "compiler": {
        "version": "0.8.15+commit.e14f2714"
    },
    "language": "Solidity",
    "output": {
        "abi": [
            {
                "inputs": [],
                "stateMutability": "nonpayable",
                "type": "constructor"
            }
        ],
        "devdoc": {
            "kind": "dev",
            "methods": {},
            "version": 1
        },
        "userdoc": {
            "kind": "user",
            "methods": {},
            "version": 1
        }
    },
    "settings": {
        "compilationTarget": {
            "Demo.sol": "Demo"
        },
        "evmVersion": "london",
        "libraries": {},
        "metadata": {
            "bytecodeHash": "ipfs"
        },
        "optimizer": {
            "enabled": false,
            "runs": 200
        },
        "remappings": []
    },
    "sources": {
        "Demo.sol": {
            "keccak256": "0xf6e99f20fac61b16466088a9996227f35c4ca82119a846ba19a83698e8e126b1",
            "license": "UNLICENSED",
            "urls": [
                "bzz-raw://3fda90691cfa365f68a59d5b6bb76f8a0189153cebf93143879521ea309751b8",
                "dweb:/ipfs/QmP2dVkfPWy3tAriX17tar9phGzC8gqYzutmhEur6dwdiw"
            ]
        }
    },
    "version": 1
}

可以看到其中主要包含了编译器版本，ABI，IPFS 等信息。这部分了解即可，我们平时也用不到这些，详细内容可以查看文档。

我们前面提到了一些操作数，例如 0x40、0x80，这些数字是什么意思呢。要了解这些，我们就得先明白 EVM 中的内存布局。前面的文章中，我们讲解过内存布局，但是当时讲的实际上是 Storage Layout，也就是状态变量的布局结构。而我们现在要讲的是 Memory Layout。区别在于 Storage 的数据是永久存在于区块链上的，类似于计算机的硬盘数据。而 Memory 的数据只有在发起交易的时候才有，交易完毕，数据全部消失，类似于计算机的内存数据。

合约内存

Memory 的数据结构就是一个简单的字节数组，数据可以以 1 字节（8 位）或者 32 字节（256 位）为单位进行存储，读取时只能以 32 字节为单位读取，但是读取时可以从任意字节处开始读取，不限定于 32 的倍数字节。图示：

用于操作内存的一共有 3 个操作符：

• MSTORE (x, y) - 在内存 x 处开始存储 32 字节的数据 y

• MLOAD (x) - 将内存 x 处开始的 32 字节数据加载到栈中

• MSTORE8 (x, y) - 在内存 x 处存储 1 字节数据 y（32字节栈值中的最低有效字节）

Solidity 中预留了 4 个 32 字节的插槽（slot），分别是：

• 0x00 - 0x3f (64 字节): 哈希方法的暂存空间

• 0x40 - 0x5f (32 字节): 当前已分配内存大小 (也称为空闲内存指针)

• 0x60 - 0x7f (32 字节): 零槽，用作动态内存数组的初始值，永远不能写入值

这里面最重要的就是中间这一项，也就是空闲指针。它会指向空闲空间的开始位置，也就是说，要将一个新变量写入内存，给它分配的位置就是空闲指针所指向的位置。需要注意的是，Solidity 中的内存是不会被释放（free）的。

对于空闲指针，它的更新遵守了很简单的原则：

新的空闲指针位置 = 旧的空闲指针位置 + 分配的数据大小

上图中我们看到，Solidity 的预留空间已经占据了 128 个字节，因此空闲指针的起始位置就只能从 0x80（128字节） 开始。空闲指针本身是存在于 0x40 位置的。由于我们在函数中的操作均需要在内存中进行，因此首要任务就是要通过空闲指针分配内存，所以我们前面才需要使用 6080604052，也就是 MSTORE(0x40, 0x80)，来加载空闲指针。此时是不是已经有些明白为什么所有的合约都是以 6080604052 开头了（有些老版本合约以 6060604052 开头）。

小结

这篇文章我们就先介绍到这里，我们学习了合约的编译过程，字节码的构造，以及合约的内存分布。可以多看几遍消化消化。下篇文章我们将介绍合约的部署，也就是 init bytecode 部分，了解 EVM 在合约部署时的运行逻辑。

关于我

欢迎和我交流

参考

A deep-dive into Solidity - function selectors, encoding and state variables

In the last post, we have seen how the Solidity compiler creates code - the init bytecode - to prepare and deploy the actual bytecode executed at runtime. Today, we will look at a few standard patterns that we find when looking at this runtime bytecode.

http://leftasexercise.com

EVM Deep Dives: The Path to Shadowy Super Coder 🥷 💻 - Part 2

Let's take a trip down memory lane

https://noxx.substack.com

这次攻击事件的原理是，用户在将 NFT 从协议中取出后，仍然可以借出 token。黑客利用这个 bug，不断新建合约，将其作为抵押人，抵押 NFT 并取出，然后再去借出 token，从而实现无本套利。

代码分析

XCarnival 的核心在于三个合约：

• XNFT，用户抵押 NFT 入口

• XToken，用户借款入口

• P2Controller，校验用户的权限，例如订单是否可借出，用户是否可赎回等

这次的 bug 在于，用户可以将 NFT 抵押到协议之后，再取出 NFT，而由于合约借贷逻辑中，没有订单的状态进行判断，因此仍然可以调用借出方法进行借贷，造成资产流失。

我们先来看看抵押的代码：

注意到抵押方法的 xToken 地址是作为参数传进去的，指定要借哪个 token。

再来看看取出 NFT 的方法（由于这段代码太长，我们只截取最重要的部分）：

我们看到，在取出 NFT 的最后，将订单的 isWithdraw 置为了 true，指明订单已经被取出。

接下来我们看看借出 xToken 的部分：

xToken 中会调用 controller 的各种 allow，verify 方法等来判断该 token 是否可借出。那么我们再看看 controller 中是如何实现的：

注意到没有，这里并没有对订单中的 NFT 是否取出，也就是上面的 isWithdraw 进行检查。如果我们先去抵押 NFT，这时已经生成了订单，然后再取出。此时再去调用 xToken 的 borrow 方法，那么就可以借款，而此时是没有任何抵押的。此次黑客事件就是利用了这个 bug。

攻击步骤

我们来看看黑客的几笔交易都在干什么：

1. 从 OpenSea 中购买 BAYC （tokenId：5110）作为抵押物

2. 创建攻击合约

3. 将 BAYC 转到攻击合约中

4. 新建内部合约并将其作为抵押人，抵押 NFT 后取出

5. 内部合约行使借贷权利，从协议中借出 token

其中第四步的详细逻辑为：

这样在一笔交易中就可以构建多个抵押人（即新建的合约）。在实际的攻击中每一笔交易新建了四个内部合约，然后多次调用该方法，就可以构建出许多的抵押人。并且这些抵押人在协议中已经没有了抵押，但是仍然有借出 token 的权利。

接下来第五步，利用内部合约抵押人的身份，在没有任何抵押的情况下，直接从协议中借出 token，完成套利。

注意黑客在调用抵押方法 pledgeAndBorrow 的时候，传入了自定义的 xToken 地址。由于在这一步只需要实现抵押，不需要借贷，因此传入自定义的 xToken，可以避免 xToken 自带的一堆校验。

整体的逻辑还是比较简单的，我们也来尝试写写攻击合约。

攻击重现

要重现攻击，就需要模拟主网的各种状态，这时我们可以利用 hardhat 的 fork 功能，不熟悉的朋友可以看看我之前写的一篇文章，对其用法有详细的解释。

黑客的第一笔交易发生在区块 15028718 中，是购买 BAYC 的交易，那么我们就 fork 区块 15028720，并且使用 hardhat_impersonateAccount 模拟黑客的地址，那么此时在本地我们就拥有了 BAYC（5110），只需要关注攻击逻辑本身即可。

根绝我们前面的分析，在第四步中，需要新建内部的辅助合约，并具有抵押、取出、转移 NFT 的功能，最重要的，需要有借出 xToken 的功能。同时，在外部的攻击合约中，需要维护一个内部合约的地址列表，方便后续集中调用借款方法。

综上，我们最终实现的内部辅助合约为：

外部攻击合约为：

感兴趣的朋友可以多看几遍，结合注释好好理解一下，我们不再详细解释。

接着我们在本地自测，调用两次 prepare 之后调用 attack，测试结果为：

balance before hack is 27.69746933937151467 balance after hack is 315.51434111624879089

差值恰好是 36 * 4 * 2 = 288，说明我们模拟成功。

总结

这次的 bug 原因在于在一个很小的细节，也就是 NFT 取出后没有修改状态。这种小问题，审计人员也没有查出来，说明细节真的很重要。我们在编写合约的时候，对各个状态的变更都要仔细考虑几遍。

关于我

欢迎和我交流

参考

熊市新考验 -- XCarnival NFT 借贷协议漏洞分析

慢雾安全团队建议在进行借款操作时应做好订单状态中是否已经提走抵押品的判断，避免再次出现此类问题。

https://mp.weixin.qq.com

门有锁，但钥匙在锁孔上 - 详解 XCarnival 攻击

这个安全检查，一言难尽

https://mp.weixin.qq.com

源码解读

TransferSelectorNFT

上篇文章的最后，我们谈到了 NFT 的转账操作：

可以看到，需要先根据 NFT 地址获取相应的转账管理器，然后采用对应的管理器来进行转账。其内部的实现为：

这段代码中先查询该 NFT 有没有特定的转账管理器。如果没有，则利用 ERC165 规范，查询 NFT 合约实现了哪种规范（ERC721 或 ERC1155），然后使用对应的通用管理器。转账管理器本身的合约代码很简单，例如 ERC721 的转账代码为：

TransferManagerERC721

Manager

CurrencyManager，ExecutionManager 这两个管理器合约内容比较简单，包含基本的 add，remove，view 等方法，我们这里不再介绍。

RoyaltyFeeRegistry

该合约用于存储版税的相关信息，包括设置，读取等方法。

其中设置方法只能由 owner，即 RoyaltyFeeSetter 合约调用。

RoyaltyFeeSetter

设置版税信息，可以理解为将上面的 RoyaltyFeeRegistry 合约包装了一层，这里是设置的入口。包含下面几个主要方法：

• updateRoyaltyInfoForCollectionIfAdmin

• updateRoyaltyInfoForCollectionIfOwner

• updateRoyaltyInfoForCollectionIfSetter

• updateRoyaltyInfoForCollection

• _updateRoyaltyInfoForCollectionIfOwnerOrAdmin（内部方法，被上面的 IfAdmin 和 IfOwner 方法调用）

前四个方法均为设置版税功能，区别在于，前两个是由 NFT 的管理员设置，由于每个 NFT 合约的写法都不同，因此会区分 admin，owner 等角色。第三个方法是由前面设置版税时的 setter 设置。第四个是由 RoyaltyFeeSetter 合约本身的 owner 调用。最后一个内部方法调用上面的 registry 合约，进行设置操作。

我对这几个方法的理解是，如果 NFT 合约本身实现了 owner 或者 admin 方法，那么就有自主设置版税的权利。如果没有实现，可以找到系统管理员协助设置，此时同时会设置一个 setter 角色，以后 NFT 的版税就可以通过 setter 地址调用 updateRoyaltyInfoForCollectionIfSetter 来管理。系统更加推荐使用 setter 角色来管理版税。

我们来看看其中一个设置方法：

updateRoyaltyInfoForCollectionIfAdmin

逻辑比较简单。要求只有 NFT 的 admin 可以调用。我们看到第一步要求 NFT 不能实现 ERC2981，奇怪了，ERC2981 不就是版税的标准呢，为什么不能实现这个接口呢，我们后面会解答这个问题。

_updateRoyaltyInfoForCollectionIfOwnerOrAdmin

RoyaltyFeeManager

该合约是最外层的接口，主合约在这里获取版税信息，只有一个主要方法：

calculateRoyaltyFeeAndGetRecipient

我们看到，首先要检查系统中是否设置了该 NFT 的版税信息，如果没有设置，再去检查 NFT 本身是否包含版税信息。反过来想，如果合约本身就已经包含了版税信息，那么我们就没有必要在系统中设置。这也就解答了我们前面提出的问题：在 RoyaltyFeeSetter 合约中设置版税时，要求 NFT 合约本身不能实现 ERC2981。因为实现了 ERC2981 的合约，我们直接使用其自身的版税信息即可，不必再次设置。

接下来我们看看交易策略，LooksRare 合约库中一共包含 5 个交易策略，分别是：

• StrategyStandardSaleForFixedPrice，标准固定价格交易

• StrategyPrivateSale，卖家指定的买家才能购买

• StrategyDutchAuction，荷兰拍卖

• StrategyAnyItemFromCollectionForFixedPrice，买家出价购买一个 NFT 合集中任意一项。例如，买家想购买 BAYC，任意一个都可以

• StrategyAnyItemInASetForFixedPrice，买家出价购买一个 NFT 合集中某些特定 tokenId 中任意一项。例如，买家只想购买蓝色背景的 BAYC

我们回想一下，在上篇文章中我们看到每个 match 成单方法都会调用策略的方法来校验该交易是否有效。例如：

我们先提前了解一点，每个策略中都有两个主要方法：

• canExecuteTakerAsk，校验 taker 卖单与 maker 买单能否有效匹配

• canExecuteTakerBid，校验 taker 买单与 maker 卖单能否有效匹配

接下来我们分别来介绍每个策略的代码，看看他们的具体实现。

StrategyStandardSaleForFixedPrice

最标准的买卖策略，固定价格，买单与卖单均指定 tokenId。

可以看到标准策略中需要校验 price、tokenId 是否匹配，并检查时间戳是否有效，逻辑比较简单。只要满足这些规则，就是符合标准策略。

StrategyPrivateSale

当卖家指定由某位固定的买家购买时，使用该策略。

卖家指定买家，此时卖单挂单中会指定买家的地址，将其存放在 MakerOrder 的 params 字段。因为这个策略的执行只能由买家触发，所以 canExecuteTakerAsk 方法没有意义，需要返回 false。在下面的 canExecuteTakerBid 中，需要将卖家指定的买家地址从 params 中解析出来，然后进行校验，同时也要校验价格，tokenId，时间戳等信息。

StrategyDutchAuction

荷兰拍卖，价格会不断下降，买家为主动方。

荷兰拍卖同样由买家触发，因此 taker 卖单没有意义，canExecuteTakerAsk 需要返回 false。在 canExecuteTakerBid 方法中，根据开始价格，结束价格，拍卖时常来计算当前实时价格，最后对参数进行校验。

StrategyAnyItemFromCollectionForFixedPrice

买家购买合集中任意一项均可，因此为买家挂单。此时卖家为 taker 主动方，因此 canExecuteTakerBid 没有意义，返回 false。我们看到，在 canExecuteTakerAsk 中仅仅校验了价格与时间，没有 tokenId，这是为何呢？因为买家购买任意一款均可，那么就不用指定 tokenId，只要价格与时间等信息匹配，任意一款 tokenId 都可以，因此这里不用校验。

StrategyAnyItemInASetForFixedPrice

买家指定购买某些特定的 tokenId，此时买家挂单，卖家为 taker 主动方，因此 canExecuteTakerBid 没有意义，返回 false。canExecuteTakerAsk 中利用了 Merkle Tree 的技术，maker 买单中的 params 字段存储所有想要购买 tokenId 合集的 Merkle Root，taker 卖单中的 params 存储了该 tokenId 对应的 Proof。最后通过 verify 校验 taker 卖单中的 tokenId 是否匹配。

总结

现在我们就已经介绍完了 LooksRare 的所有主要合约，是不是感觉还挺简单的。我个人认为 LooksRare 的文档和代码写得都比较简洁易懂，比较适合开发者来学习 NFT 市场的原理。希望大家能够结合代码库和我的文章，多理解几遍，必然会对自己的能力有一些提升。

LooksRare 代码系列文章

1. LooksRare 合约代码解读（一）

2. LooksRare 合约代码解读（二）

关于我

欢迎和我交流

参考

系统架构

名词解释

• ask 代表卖家卖出，bid 代表买家买入。

• maker 代表主动挂单的人，例如卖家主动挂单卖 NFT ，此时卖家为 maker。或者买家对某 NFT 出价，此时买家为 maker。

• taker 代表撮合完成订单的人，例如买家看到某 NFT 的价格合适，对其买入，此时买家为 taker。或者卖家看到某买家的出价合适，对其卖出，此时卖家为 taker。

结合上面的描述，合约中一共有四个角色，分别是：

• makerAsk，挂单的卖家

• makerBid，出价的买家

• takerAsk，撮合完成订单的卖家

• takerBid，撮合完成订单的买家

链下

挂单（出价）行为是在链下完成的，即 maker 操作不上链，只是在链下签名。

链上

成单行为是在链上完成的，即 taker 操作上链。因此代码中只有成单，没有挂单的逻辑。

合约架构

• LooksRareExchange，主合约，用户的所有操作都在这里

• 管理合约

  • CurrencyManager，管理协议支持的支付币种

  • ExecutionManager，管理协议支持的交易策略

  • RoyaltyFeeManager，管理 NFT 对应的版税信息

  • TransferManager，均继承于 ITransferManagerNFT

    • TransferManagerERC721，执行 ERC-721 的转移操作（使用 safeTransferFrom）

    • TransferManagerERC1155，执行 ERC-1155 的转移操作

    • TransferManagerNonCompliantERC721，执行 ERC-721 的转移操作（不使用 safeTransferFrom，而是 transferFrom）

• OrderTypes，包含 MakerOrder 与 TakerOrder 的订单数据结构

• TransferSelectorNFT，管理 NFT 对应的 TransferManager

• 交易策略合约

  • StrategyStandardSaleForFixedPrice，标准固定价格交易

  • StrategyPrivateSale，卖家指定的买家才能购买

  • StrategyDutchAuction，荷兰拍卖

  • StrategyAnyItemFromCollectionForFixedPrice，买家出价购买一个 NFT 合集中任意一项。例如，买家想购买 BAYC，任意一个都可以

  • StrategyAnyItemInASetForFixedPrice，买家出价购买一个 NFT 合集中某些特定 tokenId 中任意一项。例如，买家只想购买蓝色背景的 BAYC

• RoyaltyFeeRegistry，设置 NFT 的版税信息，存储版税信息

• RoyaltyFeeSetter，设置 NFT 的版税信息，该合约为入口，调用上面的合约

看到这么多合约，是不是已经晕了。不用怕，我们要关心的只有 LooksRareExchange 合约，其他的合约都是为了它服务的。

源码解读

注：由于 Mirror 的排版原因，长代码的阅读性很差，因此为了统一起见，所有代码将会截图展示。同时，只着重于主要业务逻辑，对于例如 setter 等比较简单的部分，不再介绍。

OrderTypes

包含 MakerOrder 与 TakerOrder，分别为：

LooksRareExchange

我们知道，挂单是在通过签名在链下进行的，每个挂单都包含 nonce。但是如果要取消订单，必须要上链，为什么呢？因为在成单的时候，要用到挂单的签名信息，而一旦签名了，签名信息是一直存在的。即使链下再怎么操作，链上也可以把这份签名拿过来用。因此 maker 需要在链上将这个 nonce 的订单取消，让其在链上失效。这样即使有人拿着签名信息来用，那么在链上这个 nonce 的订单已经失效了。

对于上面两个函数，cancelAllOrdersForSender 属于一刀切，传入一个 nonce，该 nonce 以下的订单就全部失效。cancelMultipleMakerOrders 则是传入特定的 nonce 列表，只有这些 nonce 的订单失效。

matchAskWithTakerBidUsingETHAndWETH

买家发起撮合，使用 WETH 购买

matchAskWithTakerBid

买家发起撮合，使用指定币种（makerAsk.currency）购买

可以看到上面两个函数的逻辑大同小异，区别比较大的地方就是使用 WETH 购买的函数中，需要对 msg.value 以及 ETH 的转换进行处理。

matchBidWithTakerAsk

卖家发起撮合

可以看到，与上一个方法也是大同小异，只是方向不同。

用户所有的操作就是这些，我们再来小结一下：

• cancelAllOrdersForSender → 取消指定 nonce 以下所有订单

• cancelMultipleMakerOrders → 批量取消指定订单

• matchAskWithTakerBidUsingETHAndWETH → 买家发起撮合，使用 WETH 购买

• matchAskWithTakerBid → 买家发起撮合，使用指定币种(makerAsk.currency)购买

• matchBidWithTakerAsk → 卖家发起撮合

读懂这些逻辑，我们就已经掌握了 LooksRare 合约的核心内容。

接下来，我们看看几个重要的内部函数。

_transferFeesAndFunds

分发买家的款项（非 ETH 支付）

_transferFeesAndFundsWithWETH

分发买家的款项（WETH 支付）

我们可以看到，上面两个函数的内容基本相同，主要逻辑都是对买家的款项进行了分发，计算了协议费用和版税费用，最后将剩余款项转给卖家。

还记得我们前面看到的 MakerOrder 中的 minPercentageToAsk 字段吗，当时看是不是有点迷茫，这个字段是什么意思？因为有版税和协议费用的存在，且它俩都是变量，可能卖家在挂单之后，各种费用的值被管理员修改了，那么在挂单的时候就需要设置一个最小可接受的值，如果最后盈利的数量小于该值，那么就不交易了，类似于 DEX 中滑点的概念。

注意到两个函数最大的区别就是转账这块，在非 ETH 函数中，使用的是 safeTransferFrom，而在 ETH 函数中，使用的是 safeTransfer。因为一个是 ERC20，一个是原生货币，后者在调用函数的同时就已经转入款项了。同时这也是为什么我们前面的入口函数那里，ETH 支付的函数需要对 msg.value 进行处理，而 ERC20 不需要这一步。

_transferNonFungibleToken

转账 NFT

由于目前 NFT 流行的标准有 ERC-721 和 ERC-1155，两者的转账方法略有不同。因此，这里会根据 NFT 合集对应的标准，选取相应的转账管理器来进行转账。转账管理器的内部逻辑其实很简单，我们后面再介绍，这里先着重于主逻辑。

_validateOrder

校验订单信息

这里，先校验订单的 nonce 是否有效，我们最开始看到的两个关于 nonce 的数据结构可以用来验证。然后再根据 maker 的签名和 makerOrder 的哈希值来判断其是否为正确的订单信息，这里利用了 EIP-712 的相关内容，不熟悉的朋友可以看看我之前的写的这篇文章。

小结

到这里，所有的主逻辑我们就已经看完了，是不是还算比较简单。

我们先休息一下，没有完全看懂的朋友可以再多看两遍消化一下。这篇文章就先介绍到这里，看完这篇我们基本上就已经对 LooksRare 的主要逻辑了解了个大概了。剩下的合约基本上都是辅助合约了，例如各种管理器合约，我们放在下篇文章介绍。

LooksRare 代码系列文章

1. LooksRare 合约代码解读（一）

2. LooksRare 合约代码解读（二）

关于我

欢迎和我交流

参考

代码示例

先来看一段简单的代码：

pragma solidity 0.8.10;

contract EventsDemo {
    // 定义 Events
    event Transfer(
        address indexed from, 
        address indexed to, 
        uint256 amount
    );

    function transfer(address to, uint256 amount) external {
        // 发送 Events
        emit Transfer(msg.sender, to, amount);
    }
}

在上述代码中，我们通过 event 关键字定义事件，通过 emit 关键字发送事件。这样，在调用 transfer 函数的时候，就会发送 Transfer 事件，将其数据记录在链上。

接下来我们实际部署一下，并调用 transfer 看看会发生什么。

调用 transfer 时的参数我们分别设为：

• to → 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4

• amount → 123

调用成功后，查看 Etherscan 的 Logs 页面：

我们可以看到页面中有三部分，分别是：

• Address

• Topics

• Data

其中 Address 是合约地址，这个很容易理解，那么剩下的两个字段分别代表什么呢？

基本数据结构

Events 打印出的日志中包含两种数据结构，分别是 topic 和 data。每个日志中最多可以包含 4 个 topic，data 则没有限制。topic 的第一个字段默认是事件签名，在上例中，Topics[0] 中的 0xddf25…b3ef 哈希值就是 Transfer 事件的签名：

keccak256(bytes("Transfer(address,address,uint256)"))

图示即为（图片来自于这里）：

我们注意到，前面定义的 Transfer 事件中，from 和 to 字段都带有一个 indexed 关键字，它的作用就是将该字段列为 topic。由于最多限制 4 个 topic，且第一个 topic 默认是事件签名，因此在合约中定义事件的时候，最多只能有 3 个字段可以使用 indexed。那么 topic 到底有什么用呢？

将字段列为 topic 可以方便检索。例如，我们想要在链下监听 Transfer 事件，但是并不想监听每一笔事件，只想监听 from 是我的地址的事件，那么就必须将 from 设置为 topic，否则 data 类型的日志是没有办法做到的。

在上例中，我们将 from 和 to 设置为 indexed，因此我们可以在上图中看到，有三个 topic，分别是

• 事件签名

• from，这里是调用合约的地址

• to

那么剩下的 data 部分就是 amount 字段的数据了。

data 的内容是将数据经过 abi-encoded 的结果。

我们在 Etherscan 上传代码，刷新页面：

这时 Etherscan 就可以识别出事件的 name，并且可以将 topic 和 data 数据解码。

Topic 的限制

前面我们说到，一个事件日志中，最多只能有 4 个 topic，也就是说最多有 3 个 indexed。同时，topic 本身也有长度限制，每个 topic 只能容纳 32 个字节的数据。那么像 string 或者 bytes 这种非定长的数据能否设置为 topic 呢？

答案是可以的，但是需要对其内容进行哈希。我们来看一段代码：

pragma solidity 0.8.10;

contract EventsDemo {
    event Message(
        address indexed from,
        address indexed to,
        string message
    );

    function sendMessage(address to, string memory message) public {
        emit Message(msg.sender, to, message);
    }
}

首先，我们先将 Message 事件中的 message 字段设置非 indexed，部署并调用，调用的参数分别是：

• to → 0x5b38da6a701c568545dcfcb03fcb875f56beddc4

• message → Hello World

结果为：

message 字段位于 data 中，可以被正常解码。

接下来，我们给 message 加上 indexed：

event Message(
    address indexed from,
    address indexed to,
    string indexed message
);

部署并调用，使用同样的参数，结果为：

此时，data 中内容为空，而 topic[3] 的值就是 message 的哈希值：

keccak256(bytes("Hello World"))

Events 的 Gas 花费

根据以太坊黄皮书的内容，日志的基础费用是 375 Gas。另外每个 topic 同样需要花费 375 Gas，data 中每个字节需要花费 8 Gas。

因此，我们前面的 Transfer 事件花费的 Gas 为：

1756 = 375（基础费用）+ 375 * 3（3 个 topic）+ 32 * 8（data 中共 32 字节）

Low-level log

Solidity 老版本中还存在一种底层调用，例如：

pragma solidity >=0.4.10 <0.7.0;

contract C {
    function f() public payable {
        uint256 _id = 0x420042;
        log2(
            bytes32(msg.value),
            bytes32(uint256(msg.sender)),
            bytes32(_id)
        );
    }
}

包括 log0、log1、log2、log3、log4，不过新版文档中已经去除了这部分内容，因此我们也不再介绍，了解其存在即可，感兴趣的朋友可以查看这里。

监听事件

链下监听事件有很多种方法，几乎所有主流语言都有对应的 web3 库可以实现。我前面写的一篇 ethers 使用教程的文章中包含了这部分内容，感兴趣的朋友可以前往查看，这里就不再赘述了。

总结

Solidity 中 Events 是一个很实用的日志工具，花费 Gas 少，利于链下来监听链上交易。

关于我

欢迎和我交流

参考

Events and Logging in SoliditySolidity Events and Logging [With Examples] | Chainlink

In this technical tutorial, learn all about events and logging in Solidity. This is everything you need to know.

https://blog.chain.link

https://docs.soliditylang.org/en/latest/contracts.html#events

Understanding event logs on the Ethereum blockchain

Understanding event logs on the Ethereum blockchain Most transactions have an event log, but those event logs can be hard to read. Preface: If you haven't read my article on the Ethereum Virtual ...

https://medium.com

基本命令

首先，我们先创建一个 Hardhat 项目，不熟悉的朋友可以看看这里。创建完毕之后，就可以在本地 node 中 fork 区块了。使用命令（替换自己的 key）：

npx hardhat node --fork https://eth-mainnet.alchemyapi.io/v2/

这个命令会将当前最新的一个区块数据 fork 到本地，也就是说现在本地 node 链中存在的就是这个区块的数据。当然也可以指定区块号进行 fork：

npx hardhat node --fork https://eth-mainnet.alchemyapi.io/v2/ --fork-block-number 14913700

每次 fork 都使用命令行指定这一堆参数很麻烦，因此可以将其放在 Hardhat 的配置文件 hardhat.config.js 中：

module.exports = {
  solidity: "0.8.4",

  networks: {
    hardhat: {
      // 添加 forking 内容
      forking: {
        url: "https://eth-mainnet.alchemyapi.io/v2/<key>",
        // 如果不指定区块，则默认 fork 当前最新区块
        blockNumber: 14913700
      }
    }
  }
};

这样配置之后，就可以直接使用

npx hardhat node

此时本地 node 的数据就是 fork 的区块数据。

需要注意的一点是，在执行 npx hardhat test 运行单元测试时，测试内容运行的链不是本地 node，而是沙盒模式。因此如果想要在单元测试的沙盒模式中使用 fork 的数据，需要在配置文件中显式配置 forking 内容。如果希望单元测试在本地 node 中执行，需要指定网络：

npx hardhat test --network localhost

测试 fork 数据

接下来，我们利用单元测试来实际验证一下我们的 fork 是否成功。在 test 文件夹下创建 fork.test.js 文件，编写代码：

const { ethers } = require("hardhat");

describe("Fork", function () {
  it("Testing fork data", async function () {
    console.log((await ethers.provider.getBlockNumber()).toString());
  });
});

执行测试，输出 14913700，说明 fork 成功。

现在我们来试试，实际调用主网的数据。我们以 USDT 合约为例，调用它的数据：

// 需要将 usdt 的 abi 保存在本地
const USDT_ABI = require("./usdt_abi.json");
// usdt 合约的主网地址
const USDT_ADDRESS = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
const { ethers } = require("hardhat");

describe("Fork", function () {
  it("Testing fork data", async function () {
    const provider = ethers.provider;
    // 构造 usdt 合约对象
    const USDT = new ethers.Contract(USDT_ADDRESS, USDT_ABI, provider);
    // 调用 usdt 的 totalSupply
    let totalSupply = await USDT.totalSupply();
    console.log(totalSupply.toString());
  });
});

结果为：

再去查看 USDT 的实际发行量：

验证数据正确。

fork 功能还有一个很有用的功能是，可以本地模拟任意账户，那么就意味着可以在本地拥有该地址的任意资产，这对我们做一些测试很有帮助。在测试文件中编写如下代码：

const mockAddress = "0x4c8CFE078a5B989CeA4B330197246ceD82764c63";

await network.provider.request({
  method: "hardhat_impersonateAccount",
  params: [mockAddress],
});

const signer = await ethers.provider.getSigner(mockAddress);

这样就可以模拟地址 0x4c8CFE078a5B989CeA4B330197246ceD82764c63，此时 signer 就是该地址的信息。先来查看该地址的账户信息：

let ETHBalance = await signer.getBalance();
console.log(`ETH balance is ${ETHBalance.toString() / 1e18}`);

let USDTBalance = await USDT.balanceOf(signer.getAddress()) / 1e6;
console.log(`USDT balance is ${USDTBalance.toString()}`);

执行结果为：

主网查询其资产为：

验证数据正确。我们再来看看如何模拟该账户发送交易，假设需要向其他地址发送一万 USDT，代码为：

// 打印转账前的账户余额
let USDTBalanceA = await USDT.balanceOf(signer.getAddress()) / 1e6;
console.log(`USDT balance before transfer is ${USDTBalanceA.toString()}`);

const recipient = "0x652361ED2a8FB7E9b15Fe073AAb9fE2cFacb0B52";

let USDTBalanceB = await USDT.balanceOf(recipient) / 1e6;
console.log(`USDT balance of recipient before transfer is ${USDTBalanceB.toString()}`);

console.log("========Transfering========");

// 转账操作
await USDT.connect(signer).transfer(
  "0x652361ED2a8FB7E9b15Fe073AAb9fE2cFacb0B52",
  ethers.utils.parseUnits("10000", 6)
);

// 打印转账后的账户余额
USDTBalanceA = await USDT.balanceOf(signer.getAddress()) / 1e6;
console.log(`USDT balance after transfer is ${USDTBalanceA.toString()}`);

USDTBalanceB = await USDT.balanceOf(recipient) / 1e6;
console.log(`USDT balance of recipient after transfer is ${USDTBalanceB.toString()}`);

结果为：

验证转账成功。

拓展

fork 下还有一些功能我们这里没有介绍，例如

// 设置账户余额
await network.provider.send("hardhat_setBalance", [
  "0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B",
  "0x1000",
]);

// 设置账户 nonce
await network.provider.send("hardhat_setNonce", [
  "0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B",
  "0x21",
]);

感兴趣的朋友可以查看文档自行了解。

总结

Hardhat fork 在平时的测试中非常方便，例如我们想要测试闪电贷，套利合约等，如果在主网测试，一是很慢，二是会花费 Gas。不过这个功能也不是 Hardhat 的专属，Ganache 和 Foundry 也有 fork 功能，感兴趣的朋友可以了解一下。

关于我

欢迎和我交流

参考

https://hardhat.org/hardhat-network/guides/mainnet-forking

https://hardhat.org/hardhat-network/reference

https://stackoverflow.com/questions/71106843/check-balance-of-erc20-token-in-hardhat-using-ethers-js

EIP-712 的出现就是为了解决这个问题，利用 EIP-712，我们可以对更大的数据集，例如对结构体进行签名。那么这种签名格式有什么实际的应用场景呢。使用过 Uniswap，PancakeSwap 等 DEX 的朋友应该有印象，在移除 LP 流动性的时候，我们需要先签名，然后再发送一笔交易移除流动性。正常情况下，其实应该我们先调用 LP 代币的授权方法，授权 DEX 合约可以转移我们的 LP，然后再去移除流动性。而这种二合一的实现正是应用了 EIP-712。它帮助我们仅仅签名一次，就可以将两步交易合并为一步交易，从而节省 Gas 费用。这篇文章我们就来看看 EIP-712 到底是怎么使用的。

基本结构

EIP712Domain

顾名思义，是一个与域相关的结构体，总共包含五个字段：

• name，合约或者协议的名称

• version，合约的版本

• chainId，合约部署的链 Id，一般使用 block.chainid，即当前链 Id

• verifyingContract，签名的合约地址，一般使用 address(this)，即当前合约

• salt，随机数盐，一般不常用

DOMAIN_SEPARATOR

EIP712Domain 数据的哈希值，即：

DOMAIN_SEPARATOR = keccak256(
    abi.encode(
        EIP712DOMAIN_TYPEHASH,
        keccak256(name，即合约名称),
        keccak256(version，即合约版本),
        chainId,
        verifyingContract
    )
);

EIP712DOMAIN_TYPEHASH

bytes32 constant EIP712DOMAIN_TYPEHASH = keccak256(
    "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
);

签名对象

这里我们以签名 Mail 对象为例：

struct Mail {
    address from;
    address to;
    string contents;
}

签名对象类型哈希

bytes32 internal constant TYPE_HASH = keccak256(
    "Mail(address from,address to,string contents)"
);

注意对象名要首字母大写，结构体字段按照函数签名编写。这是规范，套用即可。

如果结构体中还包含其他结构体，例如：

struct Transaction {
    Person from;
    Person to;
    Asset tx;
}

struct Asset {
    address token;
    uint256 amount;
}

struct Person {
    address wallet;
    string name;
}

那么需要写成（按照首字母排序，因此 Asset 在 Person 前面）：

Transaction(Person from,Person to,Asset tx)Asset(address token,uint256 amount)Person(address wallet,string name)

签名对象值哈希

计算值哈希的格式为：

keccak256(
    abi.encode(
        TYPE_HASH, 
        mail.from,
        mail.to,
        keccak256(bytes(mail.contents))
    )
);

其中第一个参数为 TYPE_HASH，即签名对象类型的哈希。接下来依次是对象的各个字段，如果是变长类型例如 string，bytes，则需要对其进行哈希。例如，这里的 mail.contents 是 string 类型，因此需要进行哈希。

代码实践

看了这么多概念，是不是已经懵了。我们马上来看看代码：

合约

pragma solidity 0.8.10;

contract EIP712Mail {
    // Mail 是待签名的结构体
    struct Mail {
        address from;
        address to;
        string contents;
    }

    struct EIP712Domain {
        string  name;
        string  version;
        uint256 chainId;
        address verifyingContract;
    }

    bytes32 public immutable DOMAIN_SEPARATOR;

    bytes32 public constant EIP712DOMAIN_TYPEHASH = keccak256(
        "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
    );

    // 签名对象哈希
    bytes32 internal constant TYPE_HASH = keccak256(
        "Mail(address from,address to,string contents)"
    );

    constructor() {
        DOMAIN_SEPARATOR = keccak256(
            // 计算 DOMAIN_SEPARATOR 哈希
            // 这里的 name 为 EIP712Mail，即合约名
            // version 为 1
            abi.encode(
                EIP712DOMAIN_TYPEHASH,
                keccak256("EIP712Mail"),
                keccak256("1"),
                block.chainid,
                address(this)
            )
        );
    }

    // 计算待签名的结构体的哈希
    function hashStruct(Mail memory mail) public pure returns (bytes32) {
        return keccak256(
            abi.encode(
                TYPE_HASH,
                mail.from,
                mail.to,
                keccak256(bytes(mail.contents))
            )
        );
    }
}

这就是基本的代码逻辑，接下来再看看验证签名的代码：

function verify(Mail memory mail, address signer, uint8 v, bytes32 r, bytes32 s) public view returns (bool) {

    // Note: we need to use `encodePacked` here instead of `encode`.
    // 这里是固定格式，套用即可
    bytes32 digest = keccak256(abi.encodePacked(
        "\x19\x01",
        DOMAIN_SEPARATOR,
        hashStruct(mail)
    ));
    
    return ecrecover(digest, v, r, s) == signer;
    
}

verify 函数接收三个参数，分别是待签名结构体，签名地址，v，r，s。其中 v，r，s 是构成签名的三部分，签名一共有 65 个字节，前 32 个字节是 r，接下来 32 个字节是 s，最后一个字节是 v。ecrecover 是 Solidity 内置函数，可以用于验证签名，它会根据 digest 以及签名内容 v，r，s 来计算出签名人的地址。如果结果等于传入的签名地址，则说明验证签名正确。

接下来我们看看在链下如何进行签名：

使用 JavaScript 进行签名：

const {ethers} = require("ethers");
// 将合约部署在 hardhat node 本地链上
const provider = new ethers.providers.JsonRpcProvider();

// 这里我们使用 hardhat node 自带的地址进行签名
const privateKey = `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`
const wallet = new ethers.Wallet(privateKey, provider);

async function sign() {
    // 获取 chainId
    const { chainId } = await provider.getNetwork();

    // 构造 domain 结构体
    // 最后一个地址字段，由于我们在合约中使用了 address(this)
    // 因此需要在部署合约之后，将合约地址粘贴到这里
    const domain = {
        name: 'EIP712Mail',
        version: '1',
        chainId: 4,
        verifyingContract: '0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0',
    };
    // The named list of all type definitions
    // 构造签名结构体类型对象
    const types = {
        Mail: [
            {name: 'from', type: 'address'},
            {name: 'to', type: 'address'},
            {name: 'contents', type: 'string'}
        ]
    };
    // The data to sign
    // 自行构造一个结构体的值
    const value = {
        from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
        contents: 'xyyme'
    };
    const signature = await wallet._signTypedData(
        domain,
        types,
        value
    );

    // 将签名分割成 v r s 的格式
    let signParts = ethers.utils.splitSignature(signature);
    console.log(">>> Signature:", signParts);
    // 打印签名本身
    console.log(signature);
}

sign()

运行脚本，得到的结果如下：

我们将 rsv 签名，vaule 值，以及签名地址传给 verify 函数进行验证，结果为 true，说明验证成功。

使用 Python 进行签名：

也可以使用 Python 进行签名，不过语法稍微有些复杂。我们这里作展示，但是我个人还是推荐使用 JavaScript 进行签名。

# 需要安装 web3, eth-account 依赖
import eth_account
from web3 import Web3
from eth_account.messages import encode_structured_data

web3 = Web3(Web3.HTTPProvider())

private_key = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
account = web3.eth.account.privateKeyToAccount(private_key)

domain = {
    "name": "EIP712Mail",
    "version": "1",
    "chainId": web3.eth.chain_id,
    "verifyingContract": "0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0",
}

value = {
    "from": '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
    "to": '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
    "contents": 'xyyme'
}

// 这里是固定格式，套用即可
msg = {
    "types": {
        "EIP712Domain": [
            {"name": "name", "type": "string"},
            {"name": "version", "type": "string"},
            {"name": "chainId", "type": "uint256"},
            {"name": "verifyingContract", "type": "address"}
        ],
        "Mail": [
            {"name": 'from', "type": 'address'},
            {"name": 'to', "type": 'address'},
            {"name": 'contents', "type": 'string'}
        ]
    },
    "domain": domain,
    "primaryType": 'Mail',
    "message": value
}

// 需要先对结构数据进行编码
encoded_data = encode_structured_data(msg)

// 再进行签名
signed_message = web3.eth.account.sign_message(encoded_data, private_key)

print(signed_message)
r = signed_message['r']
s = signed_message['s']
v = signed_message['v']

print(f'r => {hex(r)}')
print(f's => {hex(s)}')
print(f'v => {hex(v)}')

同样可以打印出 rsv 签名。不过我在使用 Python 的时候遇到了一个问题，就是如果待签名结构体中存在 bytes 字段，需要使用：

bytes("...xxx...", "utf-8")

对内容进行编码，而这种类型无法进行 JSON 序列化，这是当前版本（5.29.1）存在的问题，更新到测试版（6.0.0b2）则可以成功签名，但是签名结果错误。这里我没有深究，也可能是我的使用方法有误。个人还是推荐使用 JavaScript 进行签名，更加简单易用。

应用

最开始我们提到过，Uniswap 中运用了 EIP-712，使得移除流动性的操作由两步变成一步，减少了 Gas 的使用。由于 Uniswap 的操作比较复杂，需要组 LP 等，用于演示的话会占用比较长的篇幅。我们这里使用 Dai 的合约进行演示，Dai 的合约中有一个 permit 函数，用于第三方授权，同样也是应用了 EIP-712 标准。

我们知道在 ERC20 币种中，A 可以调用 approve 来对 B 进行授权，而 Dai 合约中的 permit 函数的目的就是，A 提前在链下对授权对象进行签名，这样第三方就可以拿着 A 的签名去调用 permit 来实现 A 的授权操作，从而使 A 在不发送交易的情况下就能够完成授权操作。

我们来看看 Dai 的核心代码（仅包含了签名相关）：

contract Dai is LibNote {
    // ERC20 信息，name 和 version 用于 domain 签名
    string  public constant name     = "Dai Stablecoin";
    string  public constant symbol   = "DAI";
    string  public constant version  = "1";
    uint8   public constant decimals = 18;
    uint256 public totalSupply;

    mapping (address => uint)                      public balanceOf;
    mapping (address => mapping (address => uint)) public allowance;
    // nonces 用于避免重放攻击
    mapping (address => uint)                      public nonces;

    // --- EIP712 niceties ---
    bytes32 public DOMAIN_SEPARATOR;

    // 计算签名结构体 Permit 的哈希
    // bytes32 public constant PERMIT_TYPEHASH = keccak256("Permit(address holder,address spender,uint256 nonce,uint256 expiry,bool allowed)");

    bytes32 public constant PERMIT_TYPEHASH = 0xea2aa0a1be11a07ed86d755c93467f4f82362b452371d1ba94d1715123511acb;

    constructor(uint256 chainId_) public {
        wards[msg.sender] = 1;
        // 计算 domain 哈希
        DOMAIN_SEPARATOR = keccak256(abi.encode(
            keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
            keccak256(bytes(name)),
            keccak256(bytes(version)),
            chainId_,
            address(this)
        ));
    }

    // 常规授权方法
    function approve(address usr, uint wad) 
        external returns (bool) {
        allowance[msg.sender][usr] = wad;
        emit Approval(msg.sender, usr, wad);
        return true;
    }

    // --- Approve by signature ---
    // 重点是这里的 permit 函数
    function permit(address holder, address spender, uint256 nonce, uint256 expiry,
                    bool allowed, uint8 v, bytes32 r, bytes32 s) external
    {
        bytes32 digest =
            keccak256(abi.encodePacked(
                "\x19\x01",
                DOMAIN_SEPARATOR,
                keccak256(abi.encode(PERMIT_TYPEHASH,
                                     holder,
                                     spender,
                                     nonce,
                                     expiry,
                                     allowed))
        ));

        require(holder != address(0), "Dai/invalid-address-0");
        require(holder == ecrecover(digest, v, r, s), "Dai/invalid-permit");
        require(expiry == 0 || now <= expiry, "Dai/permit-expired");
        // 用于防止重放攻击
        require(nonce == nonces[holder]++, "Dai/invalid-nonce");
        uint wad = allowed ? uint(-1) : 0;
        allowance[holder][spender] = wad;
        emit Approval(holder, spender, wad);
    }
}

可以看到这些代码与我们前面的代码实践大同小异。permit 函数的参数中，holder 地址需要在链下进行签名，spender 即为被授权地址，nonce 用于防止重放攻击，这是什么意思呢？

假设 A 之前有一个对 B 进行授权的签名，后来 A 又取消了授权，也就是将授权额度减为 0。或者说 B 在一段时间内已经耗费完了所有授权。假设没有防止重放攻击，那么在这时，如果 B 是有恶意的，那么 B 就可以再次使用之前 A 的授权签名来进行授权，从而花费 A 的 token。如果加上了 nonce 字段，那么 A 在每次签名的时候，也对 nonce 进行签名，同时合约中对 nonce 进行记录，且是递增的，这样就可以确保每次的签名只能够使用一次，防止发生重放攻击。

接下来，我们来部署 Dai 的代码进行测试，部署时 chainId 使用 31337，这是 hardhat node 本地链的 chainId。然后使用 JavaScript 在链下进行签名：

const {ethers} = require("ethers");
const provider = new ethers.providers.JsonRpcProvider()

const privateKey1 = `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80` // Private key of account 1
const wallet = new ethers.Wallet(privateKey1, provider)

async function sign() {
    const { chainId } = await provider.getNetwork();
    const domain = {
        name: 'Dai Stablecoin',
        version: '1',
        chainId: chainId,
        verifyingContract: '0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9',
    };
    const types = {
        Permit: [
            {name: 'holder', type: 'address'},
            {name: 'spender', type: 'address'},
            {name: 'nonce', type: 'uint256'},
            {name: 'expiry', type: 'uint256'},
            {name: 'allowed', type: 'bool'},
        ]
    };

    // 这里 expiry 需要使用 0 或者比当前时间大的时间戳
    // 由于是初次授权，因此 nonce 为 0，下次递增
    const value = {
        holder: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
        spender: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
        nonce: 0,
        expiry: 2208963661,
        allowed: true
    };
    const signature = await wallet._signTypedData(
        domain,
        types,
        value
    );

    let signParts = ethers.utils.splitSignature(signature);
    console.log(">>> Signature:", signParts);
    console.log(signature);
}

sign()

打印出签名结果，使用第三方地址调用 permit 函数传入对应的参数。接下来我们调用 allowance 函数传入 holder 与 spender，结果非零，为 type(uint).max，说明我们操作成功。

对于 Uniswap 的签名操作，感兴趣的朋友可以自己实践操作一下，我们这里不再演示。

总结

EIP-712 初次看上去比较复杂，其实只要掌握了用法，基本都是套用即可，难度不高。在业界的一些应用也确实能够提高用户的体验。

关于我

欢迎和我交流

参考

https://www.8btc.com/article/6669785

EIP2612: 通过链下签名授权实现更少 Gas 的 ERC20代币

本文介绍了一种通过线下签名的进行授权的方式，来转移 gas 费用。

https://learnblockchain.cn

安装

npm install --save ethers

基本使用方法

// 需要导入 ethers 包
const { ethers } = require("ethers");

// 构建 provider，可以理解为与区块链交互的桥梁
// 1. 可使用最基础的 JsonRpcProvider 进行构建 provider
const INFURA_ID = 'xxx..';
const provider = new ethers.providers.JsonRpcProvider(`https://mainnet.infura.io/v3/${INFURA_ID}`);

// 2. 也可使用封装好的特定 provider，例如 AlchemyProvider，InfuraProvider
// 使用 alchemy 的时候，第一个参数若为 null 则代表主网
const ALCHEMY_ID = `xxx...`;
const provider = new ethers.providers.AlchemyProvider('null', ALCHEMY_ID);

接下来我们看看一些常用的函数：

// 获取当前网络最新的区块号 
let blockNumber = await provider.getBlockNumber(); 

// 获取余额，参数为地址，返回值是 bignumber 格式，单位为 wei
let balance = await provider.getBalance("0x...");

// 将 wei 格式转化为 ether 格式，bignumber 和 toString 格式都可以作为参数
let balance_in_ether = ethers.utils.formatEther(balance);

// 将 ether 转换为 wei 格式，返回值为 bignumber 格式
let result = ethers.utils.parseEther("1.0");

// 获取 gas price，返回值为 bignumber 格式
let gasPrice = await provider.getGasPrice();

// 获取内存 storage slot
// 第一个参数是合约地址，第二个参数是插槽位置
// 插槽位置可以使用十进制或者十六进制，十六进制需要加引号
await provider.getStorageAt("0x...", 3);
await provider.getStorageAt("0x...", "0x121");

// 获取地址的 nonce
await provider.getTransactionCount("0x...");

注意上面返回值为 bignumber 格式的数据，如果要在控制台打印，需要使用 toString() 进行转换。同时，由于 JavaScript 中的语法限制，所有 await 的语句都要放在 async 函数中。也就是说，要执行带有 await 的语句，必须为：

const main = async () => {
    let gasPrice = await provider.getGasPrice();
}

main();

构建钱包信息

// 构建钱包有两种方法
// 1. 直接通过 provider 和 私钥 构建
const privateKey1 = `0x...` // Private key of account 1
const wallet = new ethers.Wallet(privateKey1, provider);

// 2. 先通过 私钥 构建钱包，然后连接 provider
wallet = new ethers.Wallet(privateKey1);
walletSigner = wallet.connect(provider);

// 获取钱包地址
let address = await wallet.getAddress();

发送链上原生货币（例如 ETH，BNB）

// eth 转账
const tx = await wallet.sendTransaction({
    to: wallet2.getAddress(),
    value: ethers.utils.parseEther("100")
});

// 等待交易上链
await tx.wait();
// 打印交易信息
console.log(tx);

构建合约

// 可以直接通过 函数签名 构建 abi
// 需要用到哪个函数就写哪个，不需要写出全部的函数签名
const ERC20_ABI = [
    "function name() public view returns (string)",
    "function symbol() view returns (string)",
    "function totalSupply() view returns (uint256)",
    "function balanceOf(address) view returns (uint)",

    "event Transfer(address indexed from, address indexed to, uint amount)"
];

// 合约地址
const address = '0x...';
// 通过 地址，abi，provider 构建合约对象
const contract = new ethers.Contract(address, ERC20_ABI, provider);

调用合约只读方法

// 读取 name() 的值
const name = await contract.name();
console.log(name.toString());

// 读取 symbol() 的值
const symbol = await contract.symbol();
console.log(symbol);

// 读取 ERC20 合约中 balanceOf 的值
const balance = await contract.balanceOf('0x....');
console.log(balance.toString());

调用合约的写方法

// 获取钱包的 ERC20 余额
const balance = await contract.balanceOf(wallet.getAddress());

// 合约连接钱包对象
const contractWithWallet = contract.connect(wallet);

// 调用合约的 transfer 方法向其他账户转账
// 注意这里是调用 ERC20 合约的 transfer 函数，而不是原生货币转账
// 如果要调用 approve 函数，则为 contractWithWallet.approve
const tx = await contractWithWallet.transfer('0x...', balance);
// 等待交易上链
await tx.wait();

console.log(tx);

实时监听合约事件

// Transfer 事件要在 abi 中声明
// 括号中的参数分别对应 Transfer 事件的参数
contract.on("Transfer", (from, to, amount, event) => {
    console.log(`${from} sent ${ethers.utils.formatEther(amount)} to ${to}`);
});

// 这里是指定参数的监听行为
// 例如，我只想监听接收人是 `0x1234....` 的事件，那么就这样指定地址
// 构造一个 filter，然后通过 filter 筛选
filter = contract.filters.Transfer(null, '0x1234....');

// Receive an event when that filter occurs
contract.on(filter, (from, to, amount, event) => {
    // The to will always be "address"
    console.log(`I got ${ethers.utils.formatEther(amount)} from ${from}.`);
});

设置范围，扫描指定区块范围的事件

// 创建 指定发送人是 myAddress 的 filter
const myAddress = `0x...`;
filterFrom = contract.filters.Transfer(myAddress, null);

// 创建 指定接收人是 myAddress 的 filter
filterTo = contract.filters.Transfer(null, myAddress);
// 扫描指定区块的范围

console.log(await contract.queryFilter(filterFrom, 14692250, 14693250))

// 扫描最近 1000 个区块
console.log(await contract.queryFilter(filterFrom, -1000))

// 扫描所有区块
await daiContract.queryFilter(filterTo)

签名

// 签名 utf-8
const signature = await wallet.signMessage('hello world');
console.log(signature);

// 更常见的 case 是签名 hash，长度为 32 字节
// 注意签名十六进制时，必须要将其转换为数组格式

// This string is 66 characters long
message = "0x4c8f18581c0167eb90a761b4a304e009b924f03b619a0c0e8ea3adfce20aee64";
// This array representation is 32 bytes long
messageBytes = ethers.utils.arrayify(message);

// To sign a hash, you most often want to sign the bytes
const signature2 = await wallet.signMessage(messageBytes);
console.log(signature2);

指定调用合约时的一些参数

// 我们上面在做一些写操作，例如转 ETH，写合约等操作时
// 使用的 gasLimit、gasPrice，都是由链上获取的默认数值
// 如果想要手动指定，需要添加一个额外的参数
// 声明一个对象，填写需要覆盖的字段，例如
let overrides = {
    gasLimit: 230000,
    maxFeePerGas: ethers.utils.parseUnits('12', 'gwei'),
    maxPriorityFeePerGas: ethers.utils.parseUnits('3', 'gwei'),
    nonce: (await provider.getTransactionCount(wallet.getAddress()))
}
// 将 overrides 作为最后一个参数
await walletWithSigner.transfer(wallet2.getAddress(), amount, overrides)

总结

本文列出了一些常用的用法，作为基本的使用基本够用了。查询更多方法可以查询 Ethers.js 的官方文档。总的来说，Ethers.js 还是比较简单的，上手也比较快。

关于我

欢迎和我交流

参考

Documentation

Documentation for ethers, a complete, tiny and simple Ethereum library.

https://docs.ethers.org

初始化

首先执行下面的命令来做一些初始化的工作：

1. mkdir upgradeable_demo && cd upgradeable_demo

2. npm init -y

3. npm install --save-dev hardhat

4. npx hardhat，创建实例项目，并且按照步骤进行

5. npm install --save-dev @openzeppelin/hardhat-upgrades，安装 hardhat 的升级组件

6. npm install --save-dev @nomiclabs/hardhat-ethers ethers，这两个包主要用于合约部署和测试

7. npm install --save @openzeppelin/contracts-upgradeable，安装可升级合约库

接下来我们配置 hardhat 的配置文件：

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

/**
 * @type import('hardhat/config').HardhatUserConfig
 */
module.exports = {
  solidity: "0.8.4",
  networks: {
    rinkeby: {
      url: // 这里填写对应网络的 rpc 地址,
      accounts: [这里填写私钥]
    }
  }
};

然后我们再来编写可升级合约，在 contracts 文件夹下创建 Demo.sol 文件：

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.4;

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

contract Demo is Initializable {
    uint256 public a;

    // 初始化函数，后面的修饰符 initializer 来自 Initializable.sol
    // 用于限制该函数只能调用一次
    function initialize(uint256 _a) public initializer {
        a = _a;
    }

    function increaseA() external {
        ++a;
    }
}

编译合约 npx hardhat compile，没有问题。

Transparent Proxy

接着我们编写部署脚本，在 scripts 文件夹下创建 deploy.js 文件：

async function main() {
    const Demo = await ethers.getContractFactory("Demo");
    console.log("Deploying Demo...");
    // initializer 后面的参数为初始化函数的名字，这里为 initialize
    // 中括号的参数为初始化函数的参数
    const demo = await upgrades.deployProxy(Demo, [101], { initializer: 'initialize' });
    // 这里打印的地址为代理合约的地址
    console.log("Demo deployed to:", demo.address);
}

// 这里也可以简化为 main()，后面的都省略也可以
main()
    .then(() => process.exit(0))
    .catch(error => {
        console.error(error);
        process.exit(1);
    });

我们来运行部署脚本，这里我们使用本地测试网络进行部署：

注意，本地测试网络需要运行 npx hardhat node。本地网络无需在配置文件中配置，如果使用真实网络，需要进行配置，并且在 --network 后面指定网络名称即可。

npx hardhat run scripts/deploy.js --network localhost

可以观察到一共部署了三个合约，对应的部署顺序分别是

1. 逻辑合约

2. ProxyAdmin 合约

3. 代理合约（名为 TransparentUpgradeableProxy）

注意，一个项目中只会有一个 ProxyAdmin 合约，管理着所有的代理合约。也就是说，我们在同一个项目中再去部署另外的合约，那么只会有步骤 1、3，ProxyAdmin 只在部署第一个合约时会部署。

这时，假设由于业务场景变化，需要修改合约，将 increaseA 函数修改为：

function increaseA() external {
    a += 10;
}

再次编译，没有问题。接着编写升级脚本，在 scripts 文件夹下创建 upgrade.js 文件：

async function main() {
    // 这里的地址为前面部署的代理合约地址
    const proxyAddress = '0x...';

    const Demo = await ethers.getContractFactory("Demo");
    console.log("Preparing upgrade...");
    // 升级合约
    await upgrades.upgradeProxy(proxyAddress, Demo);
}

main()
    .then(() => process.exit(0))
    .catch(error => {
        console.error(error);
        process.exit(1);
    });

接着运行

npx hardhat run scripts/upgrade.js --network localhost

升级合约时， upgradeProxy 中一共有两个步骤：

1. 部署新的逻辑合约

2. 调用 ProxyAdmin 合约的 upgrade 函数来更换新合约，两个参数分别是代理合约和新逻辑合约的地址

这样我们就完成了可升级合约的部署与升级，注意到我们的部署过程中有 ProxyAdmin 合约，说明这是 TransparentProxy 的合约升级模式。接下来我们看看 UUPS 的模式如何部署及升级。

UUPS

若要支持 UUPS 的升级模式，需要做以下几点改动：

1. 逻辑合约需继承 UUPSUpgradeable 合约

2. 覆写 _authorizeUpgrade 函数

3. 部署脚本需要添加 kind: 'uups' 参数

此时，逻辑合约变为：

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.4;

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

// 需要继承 UUPSUpgradeable 合约
contract Demo is Initializable, UUPSUpgradeable {
    uint256 public a;

    function initialize(uint256 _a) public initializer {
        a = _a;
    }

    function increaseA() external {
        a += 10;
    }

    // 覆写 _authorizeUpgrade 函数
    function _authorizeUpgrade(address) internal override {}
}

部署脚本变为：

async function main() {
    const Demo = await ethers.getContractFactory("Demo");
    console.log("Deploying Demo...");
    // 这里添加了参数 => kind: 'uups'
    const demo = await upgrades.deployProxy(Demo, [101], { initializer: 'initialize', kind: 'uups' });
    console.log("Demo deployed to:", demo.address);
}

main()
    .then(() => process.exit(0))
    .catch(error => {
        console.error(error);
        process.exit(1);
    });

编译合约并运行部署脚本（注意，这时最好删除 .openzeppelin 文件夹下的对应网络配置文件，因为其包含了我们上面测试的 TransparentProxy 模式的一些运行配置，可能会有影响），可以观察到一共部署了两个合约，分别是：

1. 逻辑合约

2. 代理合约（名为 ERC1967Proxy）

此时，假设我们需要升级合约，在改动了合约之后，我们可以继续使用上面的 upgrade.js 脚本进行升级，这时的升级步骤是：

1. 部署新的逻辑合约

2. 调用代理合约的 upgradeTo 函数进行升级，参数是新的逻辑合约地址

我们可以看到，两种升级模式有所区别。TransparentProxy 模式在升级的时候，需要调用 ProxyAdmin 的升级函数。而 UUPS 模式在升级时，需要调用代理合约的升级函数。后者相比于前者少部署一个合约。

UUPS 中需要注意的权限管理问题

这里有一个重点是，由于 TransparentProxy 模式是由 ProxyAdmin 进行管理，也就是说只有 ProxyAdmin 有权限进行升级，那么我们只要保证 ProxyAdmin 合约的管理员权限安全即可保证整个可升级架构安全。而对于 UUPS 模式来说，升级合约的逻辑是需要调用代理合约的，这时的权限管理就需要开发者手动处理。具体来说，就是对于我们覆写的 _authorizeUpgrade 函数，需要加上权限管理：

function _authorizeUpgrade(address) internal 
    override onlyOwner {}

这里加上了 onlyOwner 用于限制升级权限，否则任何人都可调用代理合约的 upgradeTo 进行升级。但要注意的是，我们这里只是简单加上了 onlyOwner 做为示例的权限管理，在实际开发中，由于升级的逻辑和业务逻辑都在逻辑合约中，因此需要区分业务场景的 owner 和合约升级架构的 owner。这里可能会对开发者带来困扰，因此需要多加注意。

总结

TransparentProxy 和 UUPS 是目前阶段比较流行的成熟的合约升级解决方案。OZ 建议开发者使用 UUPS，更加轻量级，节省 gas。我个人还是比较倾向于前者，因为我觉得前者架构清晰，权限管理简单。后者将业务逻辑和升级组件都放在逻辑合约中，当需要多次升级合约时，是否节省 gas 仍需探讨。不过建议大家两个都能够熟练掌握，毕竟难度不高，上手也很简单。

合约升级系列文章

1. 深入理解合约升级(1) - 概括

2. 深入理解合约升级(2) - Solidity 内存布局

3. 深入理解合约升级(3) - call 与 delegatecall

4. 深入理解合约升级(4) - 合约升级原理的代码实现

5. 深入理解合约升级(5) - 部署一个可升级合约

关于我

欢迎和我交流

参考

UUPS Proxies: Tutorial (Solidity + JavaScript)

UUPS Proxies: A Tutorial In this tutorial we will deploy an upgradeable contract using the UUPS proxy pattern. We assume some familiarity with Ethereum upgradeable proxies. Introduction to UUPS The original proxies included in OpenZeppelin followed the Transparent Proxy Pattern. While this pattern is still provided, our recommendation is now shifting towards UUPS proxies, which are both lightweight and versatile.

https://forum.openzeppelin.com

OpenZeppelin Upgrades: Step by Step Tutorial for Hardhat

OpenZeppelin Hardhat Upgrades Smart contracts deployed with the OpenZeppelin Upgrades plugins can be upgraded to modify their code, while preserving their address, state, and balance. This allows you to iteratively add new features to your project, or fix any bugs you may find in production.

https://forum.openzeppelin.com

https://www.npmjs.com/package/@openzeppelin/hardhat-upgrades

Using the UUPS proxy pattern to upgrade smart contracts - LogRocket Blog

UUPS is a gas-efficient proxy pattern that allows underlying logic to be upgraded when needed, without losing previous data.

https://blog.logrocket.com

这是我们在第一篇文章中的图例，当我们学习了内存结构以及 delegatecall 之后，我们再来看这幅图，就能够很好地理解了：数据都存放在代理合约的内存插槽中，而由于代理合约使用了 delegatecall，因此函数执行都在逻辑合约中运行，修改的却是代理合约中的数据。这样就可以方便替换逻辑合约，实现合约升级。

合约升级实现过程

简版 Proxy

首先我们考虑，对于代理合约而言，如何将请求转发到逻辑合约。最简单的方法就是对于逻辑合约中的每个函数，都在代理合约中包装一层，然后通过 delegatecall 来分别调用各个函数。这种方法是不可行的，因为既然我们都用到了可升级合约，那就说明我们后期会对合约做改动，我们总不能每添加一个函数，都在代理合约中添加一个包装层。一是这样很冗余，二是这样无法实现，因为代理合约也是区块链上的智能合约，它本身是不可变的。

这时我们想到，能不能够利用 Solidity 中的 fallback 与 receive 函数，它们的作用就是接收并处理一切未实现的函数（两者的区别是，receive 接收所有 msg.data 为空的调用，fallback 接收所有未匹配函数的调用）。如果我们将所有的函数调用都通过 fallback 转发给逻辑合约，那么是否就达到目标了呢？我们来看看代码：

// 注：这个实现有问题（后文有描述），不要直接使用！
contract Proxy {
    address public implementation;
    address public admin;

    constructor() public {
        admin = msg.sender;
    }
    function setImplementation(address newImplementation) external {
        require(msg.sender == admin, "must called by admin");
        implementation = newImplementation;
    }
    function changeAdmin(address newAdmin) external {
        require(msg.sender == admin, "must called by admin");
        admin = newAdmin;
    }

    function _delegate() internal {
        require(msg.sender != admin, "admin cannot fallback to proxy target");
        address _implementation = implementation;
        // 下面代码是利用 delegatecall 把请求转发给 _implementation 所指定地址的合约中去
        assembly {
            calldatacopy(0, 0, calldatasize())
            let result := delegatecall(gas(), _implementation, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())

            switch result
            case 0 { revert(0, returndatasize()) }
            default { return(0, returndatasize()) }
        }
    }

    fallback () payable external {
        _delegate();
    }
    // Will run if call data is empty.
    receive () payable external {
        _delegate();
    }
}

这段代码中，我们将 fallback 和 receive 函数都指向了 _delegate 函数，它会将有请求都转发给逻辑合约。乍一看没有什么问题，但是需要注意：

1. 此合约中有两个字段，implementation 和 admin，分别存储逻辑合约地址和管理员地址（管理员地址用户更换逻辑合约升级）。它们分别占据了插槽 0 和 1 的位置，那么这就有可能和我们的逻辑合约中的内存发生冲突，如果逻辑合约中有对这俩插槽的修改，那就直接把这两个很重要的变量给改掉了，那就乱套了。

2. 还有一个问题就是代理合约本身也存在一些自身的方法，比如 changeAdmin 等，如果逻辑合约中恰好也有这些方法，那么用户的请求就不会转发到逻辑合约。

EIP-1967

该如何解决这个问题呢？EIP-1967 提出了一个解决办法，它把 implementation 和 admin 这两个字段放在了两个特殊的插槽中：

# bytes32(uint256(keccak256('eip1967.proxy.implementation')) - 1)
0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc

# bytes32(uint256(keccak256('eip1967.proxy.admin')) - 1)
0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103

这两个插槽是经过哈希计算出来的值，根据概率来看，不可能与逻辑合约中的其他内存位置发生冲突。此时，我们的代码就变成了：

bytes32 private constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

bytes32 private constant _ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;

注意这里指用了 constant 来保存插槽位置，constant 关键字保存的是常量，并不保存在插槽中。这样我们就解决了前面提到的第一个问题。

我们再来看看第二个问题，这个问题看似很好解决，比如我们给代理合约中的函数都起一些不常用的名字就行。例如，把上面的 changeAdmin 改成 changeAdmin12345。但是问题没有这么简单，我们要知道，智能合约匹配请求是根据函数签名 keccak256 值的前 4 个字节来判断的，如果两个函数的哈希值前 4 位相同，那么它们就被判断为同一个函数，例如：

# keccak256("proxyOwner()") 前 4 字节为 025313a2
proxyOwner()

# keccak256("clash550254402()") 前 4 字节为 025313a2
clash550254402()

这个问题被称为 Proxy selector clashing。这可能会造成一些问题，如果我们的逻辑合约中恰好有函数的哈希值前 4 位与代理合约中的某个函数相同，那就会造成用户的请求实际上是在代理合约中执行的，而执行结果必然是我们不希望发生的。

Transparent Proxy

Transparent Proxy 提出了解决方案，它主要从两方面解决这个问题：

1. 来自普通用户的请求全部转发给逻辑合约，即使代理合约与逻辑合约发生了名称冲突，也要转发

2. 来自管理员 admin 的请求，全部不转发，由代理合约处理

主要的代码如下：

contract Proxy {
    bytes32 private constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
    bytes32 private constant _ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;

    modifier ifAdmin() {
        // 如果调用者是 admin，就执行；否则转发到 Implementation 合约
        if (msg.sender == admin()) {
            _;
        } else {
            _delegate();
        }
    }

    constructor() public {
        address admin = msg.sender;
        bytes32 slot = _ADMIN_SLOT;
        assembly {
            sstore(slot, admin)
        }
    }
    function implementation() public ifAdmin returns (address) {
        return _implementation();
    }

    function _implementation() internal view returns (address impl) {
        bytes32 slot = _IMPLEMENTATION_SLOT;
        assembly {
            impl := sload(slot)
        }
    }

    function setImplementation(address newImplementation) external ifAdmin {
        bytes32 slot = _IMPLEMENTATION_SLOT;
        assembly {
            sstore(slot, newImplementation)
        }
    }
    function admin() public ifAdmin returns (address) {
        return _admin();
    }

    function _admin() internal view returns (address adm) {
        bytes32 slot = _ADMIN_SLOT;
        assembly {
            adm := sload(slot)
        }
    }
    function changeAdmin(address newAdmin) external ifAdmin {
        bytes32 slot = _ADMIN_SLOT;
        assembly {
            sstore(slot, newAdmin)
        }
    }

    function _delegate() internal {
        address _implementation = _implementation();
        // 下面代码是利用 delegatecall 把请求转发给 _implementation 所指定地址的合约中去
        assembly {
            calldatacopy(0, 0, calldatasize())
            let result := delegatecall(gas(), _implementation, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())

            switch result
            case 0 { revert(0, returndatasize()) }
            default { return(0, returndatasize()) }
        }
    }

    fallback () payable external {
        // 来自 admin 的请求不转发
        require(msg.sender != _admin(), "admin cannot fallback to proxy target");
        _delegate();
    }

    // 来自 admin 的请求不转发
    receive () payable external {
        require(msg.sender != _admin(), "admin cannot fallback to proxy target");
        _delegate();
    }
}

可以看到，合约中添加了 ifAdmin 修饰符，用于判断请求的来源。对于代理合约自身的一些函数如 changeAdmin 等，均使用了该修饰符。这样即使出现了签名冲突的情况，只要是来自于普通用户的请求，均直接转发给了逻辑合约执行。这样就解决了前面的第二个问题。

不过，仍然存在一个小问题，就是 admin 用户无法作为普通用户的视角正常调用。这个问题也比较好解决，一般可以准备一个特殊账户作为 admin 用户，仅调用管理员方法即可。也有另一个解决方法，就是使用一个 ProxyAdmin 合约来作为管理员，这样所有的账户都可以正常调用合约了。

ProxyAdmin 的合约代码片段如下：

contract ProxyAdmin is Ownable {
    // 管理员EOA地址通过调用该方法来更换逻辑合约
    function upgrade(IProxy proxy, address newImplementation) public onlyOwner {
        proxy.setImplementation(implementation);
    }
    // ......
}

interface IProxy {
    function setImplementation(address newImplementation);
    // ......
}

此时整个合约的架构为：

Universal Upgradeable Proxy Standard (UUPS)

UUPS 是 OpenZeppelin 在近期推出的一种新的合约升级模式，与上面的 Transparent 代理模式原理相同，都是利用 delegatecall 通过代理合约调用逻辑合约。所不同的是，Transparent 模式是将替换逻辑合约的函数放在代理合约中，而 UUPS 则是将其放在了逻辑合约中。也就是说，前者模式中，每个代理合约中都有一个类似 upgradeTo 这样的函数，用来更换逻辑合约。而在后者模式中，这样的函数是放在了逻辑合约的实现中。

官方文档中对于两者的对比，主要表述了 UUPS 模式更加轻量级，更加节省 gas，并且更推荐使用这种模式。由于代理合约中不用再包含替换逻辑合约的函数，因此节省了 gas。我个人目前对于这种模式持保留意见，因为对于可升级合约来说，代理合约和逻辑合约是一对多的关系。在之前的模式中，把替换逻辑合约的部分放在代理合约中，这也只需要部署一份代理合约。而新模式中，每个逻辑合约都要包含这部分升级组件，这样是否更加耗费 gas。而且将这部分逻辑放在逻辑合约中，是否会造成逻辑合约变得更加臃肿。毕竟在之前的模式中，开发逻辑合约时只需要关注业务逻辑即可。也许是因为目前我对于 UUPS 模式的理解不够深入，暂时先将疑问抛出，待后续继续深入学习。

可升级合约的一些限制

要实现合约升级，有一些限制需要我们注意

第一个就是我们在上篇文章最后提到的，在升级合约，也就是更换逻辑合约的时候，新合约的新增状态变量必须添加在当前所有变量之后，不能在前面的变量中插入，否则会更改内存插槽对应关系。同理，如果合约涉及到继承关系，不能在基类中添加变量（在基类中添加变量就相当于在基类和子类的状态变量之前插入变量）。也不能够更改或删除之前的状态变量。

第二个是不能使用构造函数 constructor，由于合约的构造函数是在合约初始化的时候就被调用，这时它的一些赋值操作会直接影响到自身的内存。合约升级的前提是代理合约通过 delegatecall 调用逻辑合约来影响代理的内存布局，如果逻辑合约自己使用了构造函数去初始化一些变量，那么对于代理合约而言，内存是没有任何变化的。对于该问题，替代方法是使用 initialize 函数来代替构造函数。在合约部署完成后需要手动调用 initialize 函数。同时要记得，逻辑合约中实现的 initialize 函数中要手动实现调用基类的 initialize 方法。例如：

pragma solidity ^0.6.0;

import "@openzeppelin/upgrades/contracts/Initializable.sol";

contract BaseContract is Initializable {
    uint256 public y;

    function initialize() public initializer {
        y = 42;
    }
}

contract MyContract is BaseContract {
    uint256 public x;

    function initialize(uint256 _x) public initializer {
        // 手动调用基类中的初始化方法
        BaseContract.initialize();
        x = _x;
    }
}

第三个是所有状态变量不能在声明时就赋初始值，例如：

contract MyContract {
    uint256 public hasInitialValue = 42;
}

这种行为类似于在构造函数中赋值，不可行。需要改为在 initialize 函数中赋值。

代码

Openzeppelin 库已经实现了完善的可升级合约库，我们在开发过程中可以直接使用现有的合约进行部署，避免重复造轮子出现错误。同时也提供了相应的文档以供参考。

合约升级系列文章

1. 深入理解合约升级(1) - 概括

2. 深入理解合约升级(2) - Solidity 内存布局

3. 深入理解合约升级(3) - call 与 delegatecall

4. 深入理解合约升级(4) - 合约升级原理的代码实现

5. 深入理解合约升级(5) - 部署一个可升级合约

关于我

欢迎和我交流

参考

The transparent proxy pattern - OpenZeppelin blog

Much has been discussed around proxy patterns and how to best achieve upgradeability in Ethereum smart contracts. The underlying idea is quite simple: instead of interacting with your smart contract directly... | Smart Contracts Audit

https://www.openzeppelin.com

What is the receive keyword in solidity?

Solidity has a receive keyword. What is it and how do I use it?

https://ethereum.stackexchange.com

Using with Upgrades

The official documentation for OpenZeppelin Libraries and Tools

https://docs.openzeppelin.com

https://docs.openzeppelin.com/contracts/4.x/api/proxy#transparent-vs-uups

UUPS Proxies: Tutorial (Solidity + JavaScript)

UUPS Proxies: A Tutorial In this tutorial we will deploy an upgradeable contract using the UUPS proxy pattern. We assume some familiarity with Ethereum upgradeable proxies. Introduction to UUPS The original proxies included in OpenZeppelin followed the Transparent Proxy Pattern. While this pattern is still provided, our recommendation is now shifting towards UUPS proxies, which are both lightweight and versatile.

https://forum.openzeppelin.com

call 和 delegatecall 是 Solidity 中调用外部合约的方法，但是它俩却有挺大的区别。假设 A 合约调用 B 合约，当在 A 合约中使用 call 调用 B 合约时，使用的是 B 合约的上下文，修改的是 B 合约的内存插槽值。而在如果在 A 合约中使用 delegatecall 调用 B 合约，那么在 B 合约的函数执行过程中，使用的是 A 合约的上下文，同时修改的也是 A 合约的内存插槽值。这么说有些抽象，我们来看一个简单的示意图：

从上面的图中我们可以看出，在使用 call 调用时，B 合约使用的上下文数据均是 B 本身的。而当使用 delegatecall 调用时，B 合约使用了 A 合约中的上下文数据。我们来写段代码测试一下：

pragma solidity 0.8.13;


contract A {
    address public b;
    constructor(address _b) {
        b = _b;
    }

    function foo() external {
        (bool success, bytes memory data) = 
            b.call(abi.encodeWithSignature("foo()"));
        require(success, "Tx failed");
    }
}

contract B {
    event Log(address sender, address me);
    function foo() external {
        emit Log(msg.sender, address(this));
    }
}

上面代码中，我们在 A 合约中使用 call 调用 B 合约，通过 Log 事件记录一些信息。先部署 B 合约，然后将其地址作为参数部署 A 合约，接着我们调用 foo 函数，可以获取到 Log 事件的内容为：

与我们前面的说的规则一致，使用 call 调用时，使用的是 B 本身的上下文。接下来我们将 call 改成 delegatecall：

function foo() external {
    (bool success, bytes memory data) = 
        b.delegatecall(abi.encodeWithSignature("foo()"));
    require(success, "Tx failed");
}

再来看看执行结果：

可以看到当使用了 delegatecall 调用时，使用了 A 合约的上下文。

上面我们还提到，当使用 delegatecall 时，修改的是调用合约的内存插槽值，这是什么意思呢，我们来看一个例子：

pragma solidity 0.8.13;


contract A {
    uint256 public alice;
    uint256 public bob;

    address public b;
    constructor(address _b) {
        b = _b;
    }

    function foo(uint256 _alice, uint256 _bob) external {
        (bool success, bytes memory data) = 
            b.delegatecall(abi.encodeWithSignature("foo(uint256,uint256)", 
            _alice, _bob));
        require(success, "Tx failed");
    }
}

contract B {
    uint256 public alice;
    uint256 public bob;
    function foo(uint256 _alice, uint256 _bob) external {
        alice = _alice;
        bob = _bob;
    }
}

这段代码中，我们使用 delegatecall 来调用 foo 函数，foo 函数的作用是给 B 合约的两个变量赋值。但是实际调用后的结果是，A 合约的两个变量被赋值，而 B 中的变量仍为空。这就是我们前面说的，delegatecall 会修改调用合约的内存插槽值，我们来看一个图示：

在 A 合约中有三个状态变量，B 合约中有两个状态变量。当 A 合约使用 delegatecall 调用 B 合约时，对 B 合约状态变量的赋值会通过插槽顺序分别影响 A 合约的各个变量。也就是说，对 B 合约插槽 0 的变量 alice 赋值，实际上是把值赋给了 A 合约插槽 0 的变量 alice。同理，对 B 合约的第 n 个插槽赋值，实际上会对 A 合约的第 n 个插槽赋值。注意，这里仅仅和插槽顺序有关，而和变量名无关。如果我们将 B 合约改为：

contract B {
    // 调换了变量声明顺序
    uint256 public bob;
    uint256 public alice;
    function foo(uint256 _alice, uint256 _bob) external {
        // 调换了赋值内容
        bob = _alice;
        alice = _bob;
    }
}

这段代码中，虽然变量声明以及赋值的顺序调换，但是 foo 的内容仍然是将 _alice 赋值给插槽 0 的变量，将 _bob 赋值给插槽 1 的变量，因此 A 合约的结果不变。

delegatecall 在合约升级方面的应用

学习理解 delegatecall 是我们后面学习合约升级的基础，合约升级的原理就是代理合约通过 delegatecall 调用逻辑合约，此时逻辑合约的上下文以及数据都是来自于代理合约，那么即使升级，更换了逻辑合约，所有的数据仍然存在于代理合约中，没有影响。可升级合约还有一个限制是，在升级合约时，不能更改已有的状态变量的顺序，如果需要新添变量，只能放在当前所有变量之后，不能在其中插入，原因就是这会改变插槽对应关系，使变量内容混乱。例如，若升级前的插槽为：

此时，变量 a 和 b 的值分别存储在代理合约的插槽 0，1 中。若添加变量 c，将其放在 a 和 b 中间，那么后续对于 c 的修改实际修改的是 b 的插槽，而对于 b 的修改则是在一个新的插槽上操作，造成数据混乱。

总结

delegatecall 会在被调用合约中使用调用合约的上下文，同时影响的是调用合约的内存插槽，这有时会对合约开发带来一些困扰。在使用时，一定要多考虑各方面的影响。同时，delegatecall 也是代理合约升级模式的基石，要理解合约升级，必须要明白这种调用方式的方方面面。

合约升级系列文章

1. 深入理解合约升级(1) - 概括

2. 深入理解合约升级(2) - Solidity 内存布局

3. 深入理解合约升级(3) - call 与 delegatecall

4. 深入理解合约升级(4) - 合约升级原理的代码实现

5. 深入理解合约升级(5) - 部署一个可升级合约

关于我

欢迎和我交流

参考

DelegateCall() - Blockchain Academy

This topic focuses on the functionality of delegate calls in Solidity.

https://blockchain-academy.hs-mittweida.de

Solidity中的delegatecall杂谈-安全KER - 安全资讯平台

安全KER - 安全资讯平台

https://www.anquanke.com