units-and-global-variables.rst

.. index:: ! denomination

单位和全局可用变量

.. index:: ! wei, ! finney, ! szabo, ! gwei, ! ether, ! denomination;ether

以太坊（Ether） 单位

一个字面常量可以带一个后缀 wei， gwei 或 ether 来指定一个以太币的数量， 其中没有后缀的以太数字被认为单位是wei。

assert(1 wei == 1);
assert(1 gwei == 1e9);
assert(1 ether == 1e18);

单位后缀的唯一作用是乘以10的幂次方。

Note

0.7.0 版本中删除了 finney 和 szabo 这两个单位。

.. index:: ! seconds, ! minutes, ! hours, ! days, ! weeks, ! years, ! denomination;time

时间单位

诸如 seconds， minutes， hours， days 和 weeks 等 后缀在字面常量后面，可以用来指定时间单位，其中秒是基本单位，单位的考虑方式很直白：

• 1 == 1 seconds
• 1 minutes == 60 seconds
• 1 hours == 60 minutes
• 1 days == 24 hours
• 1 weeks == 7 days

如果您使用这些单位进行日历计算，请注意，由于 闰秒 会造成不是每一年都等于365天，甚至不是每一天都有24小时，而且因为闰秒是无法预测的， 所以需要借助外部的预言机（oracle，是一种链外数据服务，译者注）来对一个确定的日期代码库进行时间矫正。

Note

由于上述原因，在 0.5.0 版本中删除了后缀 years。

这些后缀单位不能应用于变量。例如， 如果您想用时间单位（例如 days）来将输入变量换算为时间，您可以用以下方式：

function f(uint start, uint daysAfter) public {
    if (block.timestamp >= start + daysAfter * 1 days) {
        // ...
    }
}

特殊变量和函数

有一些特殊的变量和函数总是存在于全局命名空间，主要用于提供区块链的信息，或者是通用的工具函数。

.. index:: abi, block, coinbase, difficulty, prevrandao, encode, number, block;number, timestamp, block;timestamp, block;basefee, block;blobbasefee, msg, data, gas, sender, value, gas price, origin

区块和交易属性

• blockhash(uint blockNumber) returns (bytes32)： 给定区块的哈希值 - 只对最近的256个区块有效
• blobhash(uint index) returns (bytes32)： 与当前交易相关联的第 index 个blob。 此带版本的哈希值是由一个表示版本的单字节（当前为 0x01 ）和紧随其后的KZG证明的SHA256哈希的最后31个字节组成。 （ EIP-4844 ）。
• block.basefee (uint)： 当前区块的基本费用 （ EIP-3198 和 EIP-1559 ）
• block.blobbasefee (uint): 当前区块的blob基础费用（ EIP-7516 和 EIP-4844）
• block.chainid (uint)： 当前链的ID
• block.coinbase (address payable)： 当前区块矿工的地址
• block.difficulty (uint)： 当前区块的难度值（ EVM < Paris ）。对于其他EVM版本，它是 block.prevrandao 的一个废弃的别名，将在下一个重大改变版本中被删除。
• block.gaslimit (uint)： 当前区块的燃料上限
• block.number (uint)： 当前区块的区块号
• block.prevrandao (uint)： 由信标链提供的随机数（ EVM >= Paris ）（见 EIP-4399 ）。
• block.timestamp (uint)： 当前区块的时间戳，自Unix epoch以来的秒数
• gasleft() returns (uint256)： 剩余燃料
• msg.data (bytes)： 完整的调用数据
• msg.sender (address)： 消息发送方（当前调用）
• msg.sig (bytes4)： 调用数据的前四个字节（即函数标识符）。
• msg.value (uint)： 随消息发送的 wei 的数量
• tx.gasprice (uint)： 交易的燃料价格
• tx.origin (address)： 交易发送方（完整调用链上的原始发送方）

Note

对于每一个 外部（external） 函数调用， 包括 msg.sender 和 msg.value 在内所有 msg 成员的值都会变化。 这里包括对库函数的调用。

Note

当合约在链下而不是在区块中包含的交易的背景下计算时， 您不应该认为 block.* 和 tx.* 是指任何特定区块或交易的值。 这些值是由执行合约的EVM实现提供的，可以是任意的。

Note

不要依赖 block.timestamp 和 blockhash 产生随机数，除非您知道自己在做什么。

时间戳和区块哈希在一定程度上都可能受到挖矿矿工影响。 例如，挖矿社区中的恶意矿工可以用某个给定的哈希来运行赌场合约的支付函数， 而如果他们没收到任何奖励，例如以太币，还可以用一个不同的哈希重新尝试。

当前区块的时间戳必须严格大于最后一个区块的时间戳， 但这里唯一能确保的只是它会是在权威链上的两个连续区块的时间戳之间的数值。

Note

基于可扩展因素，区块哈希不是对所有区块都有效。 您仅仅可以访问最近 256 个区块的哈希，其余的哈希均为零。

Note

函数 blockhash 以前被称为 block.blockhash， 在 0.4.22 版本中被废弃，在 0.5.0 版本中被删除。

Note

函数 gasleft 的前身是 msg.gas， 在 0.4.21 版本中被弃用，在 0.5.0 版本中被删除。

Note

在 0.7.0 版本中，删除了别名 now （用于 block.timestamp）。

.. index:: abi, encoding, packed

ABI编码和解码函数

• abi.decode(bytes memory encodedData, (...)) returns (...): ABI-解码给定的数据，而类型在括号中作为第二个参数给出。例如： (uint a, uint[2] memory b, bytes memory c) = abi.decode(data, (uint, uint[2], bytes))
• abi.encode(...) returns (bytes memory)： 对给定的参数进行ABI编码
• abi.encodePacked(...) returns (bytes memory)： 对给定参数执行 :ref:`紧打包编码 <abi_packed_mode>`。 请注意，打包编码可能会有歧义!
• abi.encodeWithSelector(bytes4 selector, ...) returns (bytes memory)： ABI-对给定参数进行编码，并以给定的函数选择器作为起始的4字节数据一起返回
• abi.encodeWithSignature(string memory signature, ...) returns (bytes memory)： 相当于 abi.encodeWithSelector(bytes4(keccak256(bytes(signature))), ...)
• abi.encodeCall(function functionPointer, (...)) returns (bytes memory)： 对 函数指针 的调用进行ABI编码，参数在元组中找到。执行全面的类型检查，确保类型与函数签名相符。结果相当于 abi.encodeWithSelector(functionPointer.selector, (...))。

Note

这些编码函数可用于制作外部函数调用的数据，而无需实际调用外部函数。 此外， keccak256(abi.encodePacked(a, b)) 是一种计算结构化数据的哈希值的方法 （但是要注意有可能使用不同的函数参数类型会制作出一个 "哈希碰撞"）。

更多详情请参考 :ref:`ABI <ABI>` 和 :ref:`紧打包编码 <abi_packed_mode>`。

.. index:: bytes members

字节类型的成员

• bytes.concat(...) returns (bytes memory): :ref:`将可变数量的字节和byte1, ..., byte32参数串联成一个字节数组 <bytes-concat>`

.. index:: string members

字符串的成员

• string.concat(...) returns (string memory): :ref:`将可变数量的字符串参数串联成一个字符串数组 <string-concat>`

.. index:: assert, revert, require

错误处理

关于错误处理和何时使用哪个函数的更多细节， 请参见 :ref:`assert 和 require <assert-and-require>` 的专门章节。

assert(bool condition)

如果条件不满足，会导致异常，因此，状态变化会被恢复 - 用于内部错误。

require(bool condition)

如果条件不满足，则恢复状态更改 - 用于输入或外部组件的错误。

require(bool condition, string memory message)

如果条件不满足，则恢复状态更改 - 用于输入或外部组件的错误，可以同时提供一个错误消息。

revert()

终止运行并恢复状态更改。

revert(string memory reason)

终止运行并恢复状态更改，可以同时提供一个解释性的字符串。

.. index:: keccak256, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography,

数学和密码学函数

addmod(uint x, uint y, uint k) returns (uint)

计算 (x + y) % k，加法会在任意精度下执行，并且加法的结果即使超过 2**256 也不会被截取。从 0.5.0 版本的编译器开始会加入对 k != 0 的校验（assert）。

mulmod(uint x, uint y, uint k) returns (uint)

计算 (x * y) % k，乘法会在任意精度下执行，并且乘法的结果即使超过 2**256 也不会被截取。从 0.5.0 版本的编译器开始会加入对 k != 0 的校验（assert）。

keccak256(bytes memory) returns (bytes32)

计算输入的 Keccak-256 哈希值。

Note

以前 keccak256 的别名叫 sha3 ，在 0.5.0 版本中被删除。

sha256(bytes memory) returns (bytes32)

计算输入的 SHA-256 哈希值。

ripemd160(bytes memory) returns (bytes20)

计算输入的 RIPEMD-160 哈希值。

ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)

利用椭圆曲线签名恢复与公钥相关的地址，错误返回零值。 函数参数对应于签名的 ECDSA 值：

• r = 签名的前32字节
• s = 签名的第二个32字节
• v = 签名的最后1个字节

ecrecover 返回一个 address，而不是 address payable。 参见 :ref:`地址类型 <address>` 进行转换，以备您需要向恢复的地址转移资金。

更多细节，请阅读 使用示例.

Warning

如果您使用 ecrecover，请注意，一个有效的签名可以变成另一个有效的签名，而不需要知道相应的私钥。 在 Homestead 硬分叉中，这个问题对 _transaction_ 签名进行了修复 （见 EIP-2）， 但 ecrecover 函数仍然没有改变。

这通常不是一个问题，除非您要求签名是唯一的，或者用它们来识别个体。 OpenZeppelin 有一个 ECDSA 辅助库， 您可以用它作为 ecrecover 的包装，那样就没有这个问题。

Note

当在 私有区块链 上运行 sha256， ripemd160 或 ecrecover 时，您可能会遇到燃料耗尽（Out-of-Gas）的错误。这是因为这些功能是作为 “预编译合约” 实现的，只有在它们收到第一个消息后才真正存在（尽管它们的合约代码是硬编码的）。向不存在的合约发送消息的成本较高，因此执行时可能会遇到 Out-of-Gas 错误。这个问题的一个变通方法是，在您的实际合约中使用它们之前，先向每个合约发送 Wei（例如1）。这在主网和测试网上都没有问题。

.. index:: balance, codehash, send, transfer, call, callcode, delegatecall, staticcall

地址类型的成员

<address>.balance （ uint256 ）

以 Wei 为单位的 :ref:`address` 的余额。

<address>.code （ bytes memory ）

在 :ref:`address` 的代码（可以是空的）。

<address>.codehash （ bytes32 ）

:ref:`address` 的代码哈希值

<address payable>.transfer(uint256 amount)

向 :ref:`address` 发送数量为 amount 的 Wei，失败时抛出异常，发送2300燃料的矿工费，不可调节。

<address payable>.send(uint256 amount) returns (bool)

向 :ref:`address` 发送数量为 amount 的 Wei，失败时返回 false 2300燃料的矿工费用，不可调节。

<address>.call(bytes memory) returns (bool, bytes memory)

用给定的数据发出低级别的 CALL，返回是否成功的结果和数据，发送所有可用燃料，可调节。

<address>.delegatecall(bytes memory) returns (bool, bytes memory)

用给定的数据发出低级别的 DELEGATECALL，返回是否成功的结果和数据，发送所有可用燃料，可调节。

<address>.staticcall(bytes memory) returns (bool, bytes memory)

用给定的数据发出低级别的 STATICCALL，返回是否成功的结果和数据，发送所有可用燃料，可调节。

更多信息，请参见 :ref:`address` 一节。

Warning

您应该尽可能避免在执行另一个合约函数时使用 .call()，因为它绕过了类型检查、函数存在性检查和参数打包。

Warning

使用 send 有很多危险：如果调用栈深度已经达到 1024（这总是可以由调用者所强制指定）， 转账会失败；并且如果接收者用光了以太燃料，转账同样会失败。为了保证以太币转账安全， 总是检查 send 的返回值，使用 transfer 或者下面更好的方式： 使用接收者可以提取以太的模式。

Warning

由于 EVM 认为对一个不存在的合约的调用总是成功的， Solidity 在执行外部调用时使用 extcodesize 操作码进行额外的检查。 这确保了即将被调用的合约要么实际存在（它包含代码），要么就会产生一个异常。

对地址而不是合约实例进行低级调用 （即 .call(), .delegatecall(), .staticcall(), .send() 和 .transfer()） 不包括 这种检查，这使得它们在燃料方面更便宜，但也更不安全。

Note

在 0.5.0 版本之前，Solidity 允许地址成员被合约实例访问，例如 this.balance。 现在这被禁止了，必须做一个明确的地址转换。 address(this).balance。

Note

如果状态变量是通过低级别的委托调用来访问的，那么两个合约的存储布局必须一致， 以便被调用的合约能够正确地通过名称来访问调用合约的存储变量。 当然，如果存储指针作为函数参数被传递的话，情况就不是这样了，就像高层库的情况一样。

Note

在 0.5.0 版本之前， .call, .delegatecall 和 .staticcall 只返回成功状况， 不返回数据。

Note

在 0.5.0 版本之前，有一个名为 callcode 的成员，其语义与 delegatecall 相似但略有不同。

.. index:: this, selfdestruct, super

合约相关

this （当前合约类型）

当前合约，可以显式转换为 :ref:`address`

super

继承层次结构中上一级的合约

selfdestruct(address payable recipient)

销毁当前合约，将其资金发送到给定的 :ref:`address` 并结束执行。 注意， selfdestruct 有一些从EVM继承的特殊性：

• 接收合约的接收函数不会被执行。
• 合约只有在交易结束时才真正被销毁， 任何一个 revert 可能会 "恢复" 销毁。

此外，当前合约的所有函数都可以直接调用，包括当前函数。

Warning

从 0.8.18 及以上版本开始，在 Solidity 和 Yul 中使用 selfdestruct 将触发一个已废弃警告， 因为 SELFDESTRUCT 操作码最终会发生如 EIP-6049 中所述的行为上的重大变化。

Note

在 0.5.0 版本之前，有一个叫做 suicide 的函数，其语义与 selfdestruct 相同。

.. index:: type, creationCode, runtimeCode

类型信息

表达式 type(X) 可以用来检索关于 X 类型的信息。 目前，对这一功能的支持是有限的（ X 可以是合约类型或整数型），但在未来可能会扩展。

以下是合约类型 C 的可用属性：

type(C).name

合约的名称。

type(C).creationCode

内存字节数组，包含合约的创建字节码。 可以在内联程序中用来建立自定义的创建程序， 特别是通过使用 create2 操作码。 这个属性 不能 在合约本身或任何派生合约中被访问。 它会导致字节码被包含在调用站点的字节码中，因此像这样的循环引用是不可能的。

type(C).runtimeCode

内存字节数组，包含合约运行时的字节码。 通常是由 C 的构造函数部署的代码。 如果 C 有一个使用内联汇编的构造函数，这可能与实际部署的字节码不同。 还要注意的是，库合约在部署时修改其运行时字节码，以防止常规调用。 与 .creationCode 相同的限制也适用于这个属性。

除了上述属性外，以下属性对接口类型 I 可用：

type(I).interfaceId

一个 bytes4 值，是包含给定接口 I 的 EIP-165 接口标识符。 这个标识符被定义为接口本身定义的所有函数选择器的 XOR，不包括所有继承的函数。

以下属性可用于整数类型 T：

type(T).min

类型 T 所能代表的最小值。

type(T).max

类型 T 所能代表的最大值。

保留关键词

这些关键字在 Solidity 中是保留的。它们在将来可能成为语法的一部分：

after， alias， apply， auto， byte， case， copyof， default， define， final， implements， in， inline， let， macro， match， mutable， null， of， partial， promise， reference， relocatable， sealed， sizeof， static， supports， switch， typedef， typeof， var。