序言
本文是 Solidity 文档(以太坊官方 Solidity 开发手册)中文版连载的第六部分。这个连载的前五部分是智能合约概述、安装 Solidity 编译器、结合实例学习 Solidity、源文件结构和类型。
这份文档的英文原文可以在以太坊官网的最下方 Solidity 链接中找到。官方的英文版本文档中有中译版链接,即是本连载内容的出处。这个连载将按照英文文档的先后顺序进行。
Solidity 是以太坊官方的智能合约开发高级语言。这份中文译本是由 Hiblock 社区组织贡献的,官方 Github:https://github.com/etherchina/solidity-doc-cn。
我本人于 3 月初加入本项目,目前作为管理员、贡献者和校订人利用业余时间参与日常工作;截至到 5 月底,翻译工作已接近完成。有兴趣的朋友请直接在以太坊官网的链接中查看最新中文版本状态,或者关注上述中文译本的 Github repository。
出于单独阅读的需要,我在连载中会删除原文里的 rst 控制标签、部分外部链接和文内链接。
本文是对 Solidity 中的单位和全局变量的完整介绍。
单位和全局变量
以太币单位
以太币单位之间的换算就是在数字后边加上 wei
、 finney
、 szabo
或 ether
来实现的,如果后面没有单位,缺省为 Wei。例如 2 ether == 2000 finney
的逻辑判断值为 true
。
时间单位
秒是缺省时间单位,在时间单位之间,数字后面带有 seconds
、 minutes
、 hours
、 days
、 weeks
和 years
的可以进行换算,基本换算关系如下:
1 == 1 seconds
1 minutes == 60 seconds
1 hours == 60 minutes
1 days == 24 hours
1 weeks == 7 days
1 years == 365 days
由于闰秒造成的每年不都是 365 天、每天不都是 24 小时,所以如果你要使用这些单位计算日期和时间,请注意这个问题。因为闰秒是无法预测的,所以需要借助外部的预言机(oracle,是一种链外数据服务,译者注)来对一个精确的日期库进行更新。
注意:
基于上述原因years
前缀已经不推荐使用了。
这些后缀不能直接用在变量后边。如果想用时间单位(例如 days)来将输入变量换算为时间,你可以用如下方式来完成:
function f(uint start, uint daysAfter) public {
if (now >= start + daysAfter * 1 days) {
// ...
}
}
特殊变量和函数
在全局命名空间中已经存在了(预设了)一些特殊的变量和函数,他们主要用来提供关于区块链的信息。
区块和交易属性
-
block.blockhash(uint blockNumber) returns (bytes32)
: 给定区块的哈希—仅对最近的 256 个区块有效而不包括当前区块 -
block.coinbase
(address
): 挖出当前区块的矿工地址 -
block.difficulty
(uint
): 当前区块难度 -
block.gaslimit
(uint
): 当前区块 gas 限额 -
block.number
(uint
): 当前区块号 -
block.timestamp
(uint
): 自 unix epoch 起始当前区块以秒计的时间戳 -
gasleft() returns (uint256)
:剩余的 gas -
msg.data
(bytes
): 完整的 calldata -
msg.gas
(uint
): 剩余 gas -
msg.sender
(address
): 消息发送者(当前调用) -
msg.sig
(bytes4
): calldata 的前 4 字节(也就是函数标识符) -
msg.value
(uint
): 随消息发送的 wei 的数量 -
now
(uint
): 目前区块时间戳(block.timestamp
) -
tx.gasprice
(uint
): 交易的 gas 价格 -
tx.origin
(address
): 交易发起者(完全的调用链)
注意:
对于每一个外部函数调用,包括msg.sender
和msg.value
在内所有msg
成员的值都会变化。这里包括对库函数的调用。
注意:
不要依赖block.timestamp
、now
和block.blockhash
产生随机数,除非你知道自己在做什么。时间戳和区块哈希在一定程度上都可能受到挖矿矿工影响。例如,挖矿社区中的恶意矿工可以用某个给定的哈希来运行赌场合约的 payout 函数,而如果他们没收到钱,还可以用一个不同的哈希重新尝试。
当前区块的时间戳必须严格大于最后一个区块的时间戳,但这里唯一能确保的只是它会是在权威链上的两个连续区块的时间戳之间的数值。
注意:
基于可扩展因素,区块哈希不是对所有区块都有效。你仅仅可以访问最近 256 个区块的哈希,其余的哈希均为零。
ABI 编码函数
-
abi.encode(...) returns (bytes)
:返回给定参数的 ABI 编码 -
abi.encodePacked(...) returns (bytes)
:对给定参数进行打包的编码 -
abi.encodeWithSelector(bytes4 selector, ...) returns (bytes)
:对从第二个参数开始的给定参数进行 ABI 编码,并以第一个参数作为返回结果的前 4 字节——即用第一个参数作为函数选择器(function selector),仅对其余参数进行 ABI 编码 -
abi.encodeWithSignature(string signature, ...) returns (bytes)
:等价于 ``abi.encodeWithSelector(bytes4(keccak256(signature), ...)```
注意:
这些编码函数可以用来基于函数调用的数据来产生 ABI 编码,而不会实际调用一个函数。此外,keccak256(abi.encodePacked(a, b))
是计算keccak256(a, b)
的更明确的方式,后者在未来的版本中不再推荐使用。
关于 ABI 编码的详情请参考后续的“应用二进制编码(ABI)说明”一章。
错误处理
-
assert(bool condition)
:如果条件不满足则是交易不产生实际效果——用于内部错误。 -
require(bool condition)
:如果条件不满足则恢复(revert)——用于输入或者外部组件引起的错误。 -
require(bool condition, string message)
:如果条件不满足则恢复(revert)——用于输入或者外部组件引起的错误,同时提供一个错误消息。 -
revert()
:终止运行并恢复(revert)状态(state)变动。 -
revert(string reason)
:终止运行并恢复(revert)状态(state)变动,并提供一个字符串信息来解释原因。
数学和密码学函数
-
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(...) returns (bytes32)
:计算“紧打包”参数(需要参考后续的“应用二进制编码说明”一章)的 Ethereum-SHA-3 (Keccak-256)哈希。 -
sha256(...) returns (bytes32)
:计算“紧打包”参数(需要参考后续的“应用二进制编码说明”一章)的 SHA-256 哈希。 -
sha3(...) returns (bytes32)
:等价于 keccak256。 -
ripemd160(...) returns (bytes20)
:计算“紧打包”参数(需要参考后续的“应用二进制编码说明”一章)的 RIPEMD-160 哈希。 -
ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)
:利用椭圆曲线签名恢复与公钥相关的地址,错误返回零值。参考示例。
上文中的“紧打包(tightly packed)”是指不会对参数值进行 padding 处理(就是说所有参数值的字节码是连续存放的,中间不保留为把长度补充为一个“字”,即 32 字节,而追加的若干 0 值字节数据,译者注),这意味着下边这些调用都是等价的:
keccak256("ab", "c")
keccak256("abc")
keccak256(0x616263)
keccak256(6382179)
keccak256(97, 98, 99)
如果需要 padding,可以使用显式类型转换:keccak256("\x00\x12")
和 keccak256(uint16(0x12))
是一样的。
请注意,常量值会使用存储它们所需要的最少字节数进行打包。例如:keccak256(0) == keccak256(uint8(0))
,keccak256(0x12345678) == keccak256(uint32(0x12345678))
。
在一个私链上,你很有可能碰到由于 sha256
、ripemd160
或者 ecrecover
引起的 gas 用尽(Out-of-Gas)问题。这个原因就是他们被当做所谓的预编译合约而执行,并且在第一次收到消息后这些合约才真正存在(尽管合约代码是硬编码)。发送到不存在的合约的消息非常昂贵,所以实际的执行会导致 Out-of-Gas 错误。在你的合约中实际使用它们之前,给每个合约发送一点儿以太币,比如 1 Wei。这在官方网络或测试网络上都不是问题。
地址相关
-
<address>.balance
(uint256
):以 Wei 为单位的某个地址(address
)的余额。 -
<address>.transfer(uint256 amount)
:向某个地址(address
)发送数量为 amount 的 Wei,失败时抛出异常,且将额外发送 2300 gas 的矿工费,不可调整。 -
<address>.send(uint256 amount) returns (bool)
:向某个地址(address
)发送数量为 amount 的 Wei,失败时返回false
,且将额外发送 2300 gas 的矿工费用,不可调整。 -
<address>.call(...) returns (bool)
:执行低级函数CALL
,失败时返回false
,会发送所有可用 gas,不可调整。 -
<address>.callcode(...) returns (bool)
:执行低级函数CALLCODE
,失败时返回false
,会发送所有可用 gas,不可调整。 -
<address>.delegatecall(...) returns (bool)
:执行低级函数DELEGATECALL
,失败时返回false
,会发送所有可用 gas,不可调整。
更多信息,请参考上一章中介绍的“地址”部分。
警告:
使用 send 有很多危险:如果调用栈深度已经达到 1024(这总是可以由调用者所强制指定),转账会失败;并且如果接收者用光了 gas,转账同样会失败。为了保证以太币转账安全,总是检查send
的返回值,利用transfer
或者后文中的更好的方式:
使用一种由接收者取回资金的模式。
注意:
如果通过一个低级函数 delegatecall 来访问一个存储(storage)变量,两个合约存储中的数据布局(位置)必须一致,以保证可以在被调用的合约中通过变量名正确地访问到调用合约中的存储变量。这当然不是在高级的库中通过函数参数传递存储指针的那种情况。
注意:不鼓励使用
callcode
,并且将来它会被移除。
合约相关
-
this
(current contract's type):当前合约,可以明确转换为某个地址(address
)。 -
selfdestruct(address recipient)
:销毁合约,并把余额发送到指定的地址(address
)。 -
suicide(address recipient)
:等价于 selfdestruct。
此外,当前合约内的所有函数都可以被直接调用,包括当前函数。