Solidity在全局命名空间中已经存在了(预设了)一些特殊的变量和函数,他们主要用来提供关于区块链的信息或一些通用的工具函数。
为了方便理解,可以把这些变量和函数理解为Solidity 语言层面的(原生) API 。
区块和交易
-
blockhash(uint blockNumber) returns (bytes32)
:指定区块的区块哈希——仅可用于最新的 256 个区块且不包括当前区块 -
block.chainid(uint)
: 当前链 id -
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.sender(address)
: 消息发送者(当前调用) -
msg.sig(bytes4)
: calldata 的前 4 字节(也就是函数标识符) -
msg.value(uint)
: 随消息发送的 wei 的数量 -
tx.gasprice(uint)
: 交易的 gas 价格 -
tx.origin(address payable)
: 交易发起者(完全的调用链)
注意:对于每一个外部函数调用,包括
msg.sender
和msg.value
在内所有msg
成员的值都会变化。这里包括对库函数的调用。
注意:不要依赖
block.timestamp
和blockhash
产生随机数,除非你知道自己在做什么。时间戳和区块哈希在一定程度上都可能受到挖矿矿工影响。例如,挖矿社区中的恶意矿工可以用某个给定的哈希来运行赌场合约的 payout 函数,而如果他们没收到钱,还可以用一个不同的哈希重新尝试。
当前区块的时间戳必须严格大于最后一个区块的时间戳,但这里能确保也需要它是在权威链上的两个连续区块。
注意:基于可扩展因素,区块哈希不是对所有区块都有效。你仅仅可以访问最近 256 个区块的哈希,其余的哈希均为零。
注意:
blockhash
函数之前是使用block.blockhash
,block.blockhash
在v0.4.22
开始不推荐使用,在v0.5.0
已经移除了。
注意:
gasleft
函数之前是使用msg.gas, msg.gas
在v0.4.21
开始不推荐使用,在v0.5.0
已经移除了。
注意:在
v0.7.0
,now
(block.timestamp
的别名) 被移除了。
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)
: ABI - 对给定参数进行编码 -
abi.encodePacked(...) returns (bytes)
:对给定参数执行打包编码(packed encoding)
,注意,打包编码的方式可能是不明确的(注:这里翻译总是觉得怪怪的)。 -
abi.encodeWithSelector(bytes4 selector, ...) returns (bytes)
:
ABI - 从第二个参数开始对给定参数进行编码,并在给定的四字节选择器前面加上前缀 -
abi.encodeWithSignature(string signature, ...) returns (bytes)
:
等价于:
abi.encodeWithSelector(bytes4(keccak256(signature), ...)
注意:这些编码函数可以用来构造函数调用数据,而不用实际进行调用。此外,
keccak256(abi.encodePacked(a, b))
是一种计算结构化数据的哈希值(尽管我们也应该关注到:使用不同的函数参数类型也有可能会引起“哈希冲突” )。
字节成员
-
bytes.concat(...) returns (bytes memory)
:将可变数量的字节和 bytes1, ..., bytes32 参数连接到一个字节数组
字符串成员
-
string.concat(...) returns (string memory)
:将可变数量的字符串参数连接到一个字符串数组
bytes.concat
和string.concat
您可以使用 string.concat
连接任意数量的string
值。该函数返回一个string memory
(字符串内存)数组,该数组包含参数的内容,没有填充。如果希望使用其他类型的参数,而这些参数不能隐式转换为string
,则需要首先将它们转换为string
。
类似地,该 bytes.concat
函数可以连接任意数量的 bytes
或 bytes1 ... bytes32
值。该函数返回一 bytes memory
(字节内容) 数组 ,该数组包含参数的内容,不带填充。如果希望使用字符串参数或其他不能隐式转换为 bytes
的类型,则需要首先将它们转换为 bytes
或 bytes1/…/bytes32
。
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.12;
contract C {
string s = "Storage";
function f(bytes calldata bc, string memory sm, bytes16 b) public view {
string memory concatString = string.concat(s, string(bc), "Literal", sm);
assert((bytes(s).length + bc.length + 7 + bytes(sm).length) == bytes(concatString).length);
bytes memory concatBytes = bytes.concat(bytes(s), bc, bc[:2], "Literal", bytes(sm), b);
assert((bytes(s).length + bc.length + 2 + 7 + bytes(sm).length + b.length) == concatBytes.length);
}
}
如果您调用string.concat
或bytes.concat
不使用参数,它们将返回一个空数组。
错误处理
可以参阅错误处理及异常
assert(bool condition)
如果不满足条件,则会导致 Panic
错误,则撤销状态更改 - 用于检查内部错误。
require(bool condition)
如果条件不满足则撤销状态更改 - 用于检查由输入或者外部组件引起的错误。
require(bool condition, string memory message)
如果条件不满足则撤销状态更改 - 用于检查由输入或者外部组件引起的错误,可以同时提供一个错误消息。
revert()
终止运行并撤销状态更改。
revert(string memory reason)
终止运行并撤销状态更改,可以同时提供一个解释性的字符串。
数学和密码学函数
addmod(uint x, uint y, uint k) returns (uint)
计算 (x + y) % k
,加法会在任意精度下执行,并且加法的结果即使超过 2**256
也不会被截取。从 v0.5.0
版本的编译器开始会加入对 k != 0
的校验(assert)。
mulmod(uint x, uint y, uint k) returns (uint)
计算 (x * y) % k
,乘法会在任意精度下执行,并且乘法的结果即使超过 2**256
也不会被截取。从 v0.5.0
版本的编译器开始会加入对 k != 0
的校验(assert)。
keccak256((bytes memory) returns (bytes32)
计算 Keccak-256
哈希。
注意:之前
keccak256
的别名函数sha3
在v0.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)
利用椭圆曲线签名恢复与公钥相关的地址,错误返回 0
值。
函数参数对应于 ECDSA
签名的值:
-
r
= 签名的前 32 字节 -
s
= 签名的第2个32 字节 -
v
= 签名的最后一个字节
ecrecover
返回一个 address
, 而不是 address payable
。
警告
:如果你使用ecrecover
,需要了解,在不需要知道相应的私钥下,签名也可以转换为另一个有效签名(可能是另外一个数据的签名)。在 Homestead 硬分叉,这个问题对于_transaction_
签名已经解决了(查阅 EIP-2)。 不过ecrecover
没有更改。除非需要签名是唯一的,否则这通常不是问题,或者是用它们来识别物品。 OpenZeppelin有一个 ECDSA助手库 ,可以将其用作ecrecover
的”包装“,而不会出现此问题。
注意:在一个私链上,你很有可能碰到由于
sha256
、ripemd160
或者ecrecover
引起的Out-of-Gas
。这个原因就是他们被当做所谓的预编译合约而执行,并且在第一次收到消息后这些合约才真正存在(尽管合约代码是硬代码)。发送到不存在的合约的消息非常昂贵,所以实际的执行会导致Out-of-Gas
错误。在你的合约中实际使用它们之前,给每个合约发送一点儿以太币,比如1 Wei
。这在官方网络或测试网络上不是问题。
地址成员
<address>.balance (uint256)
以 Wei 为单位的 地址类型 Address 的余额。<address>.code (bytes memory)
在 地址类型Address
上的代码(可以为空)<address>.codehash (bytes32)
地址的代码哈希<address payable>.transfer(uint256 amount)
向 地址类型Address
发送数量为amount
的Wei
,失败时抛出异常,使用固定(不可调节)的2300 gas
的矿工费。<address payable>.send(uint256 amount) returns (bool)
向 地址类型Address
发送数量为amount 的 Wei
,失败时返回false
,发送2300 gas
的矿工费用,不可调节。<address>.call(bytes memory) returns (bool, bytes memory)
用给定的有效载荷(payload
)发出底层CALL
调用,返回成功状态及返回数据,发送所有可用gas
,也可以调节gas
。<address>.delegatecall(bytes memory) returns (bool, bytes memory)
用给定的有效载荷 发出底层DELEGATECALL
调用 ,返回成功状态并返回数据,发送所有可用gas
,也可以调节gas
。 发出底层函数DELEGATECALL
,失败时返回false
,发送所有可用gas
,可调节。<address>.staticcall(bytes memory) returns (bool, bytes memory)
用给定的有效载荷 发出底层STATICCALL
调用 ,返回成功状态并返回数据,发送所有可用gas
,也可以调节gas
警告
:在执行另一个合约函数时,应该尽可能避免使用.call()
,因为它绕过了类型检查,函数存在检查和参数打包。
警告
:使用send
有很多危险:如果调用栈深度已经达到1024
(这总是可以由调用者所强制指定),转账会失败;并且如果接收者用光了gas
,转账同样会失败。为了保证以太币转账安全,总是检查send
的返回值,利用transfer
或者下面更好的方式: 用这种接收者取回钱的模式。
注意:在版本
v0.5.0
之前,Solidity允许通过合约实例来访问地址的成员,例如this.balance
,不过现在禁止这样做,必须显式转换为地址后访问,如:address(this).balance
。
注意:如果在通过底层函数
delegatecall
发起调用时需要访问存储中的变量,那么这两个合约的存储布局需要一致,以便被调用的合约代码可以正确地通过变量名访问合约的存储变量。 这不是指在库函数调用(高级的调用方式)时所传递的存储变量指针需要满足那样情况。
注意:在
v0.5.0
版本以前,.call
,.delegatecall
和.staticcall
仅仅返回成功状态,没有返回值。
注意:在
v0.5.0
版本以前, 还有一个callcode
函数,现在已经去除。
合约相关
this
(当前的合约类型)
当前合约,可以显示转换为 地址类型Address
。-
selfdestruct(address payable recipient)
销毁合约,并把余额发送到指定 地址类型Address
。
请注意,selfdestruct
具有从EVM继承
的一些特性:- 接收合约的
receive
函数 不会执行。 - 合约仅在交易结束时才真正被销毁,并且
revert
可能会“撤消”销毁。
- 接收合约的
此外,当前合约内的所有函数都可以被直接调用,包括当前函数。
注意:在
v0.5.0
之前, 还有一个suicide
,它和selfdestruct
语义是一样的。
类型信息
表达式 type(X)
可用于检索参数 X
的类型信息。
目前,此功能还比较有限( X
仅能是合约和整型),但是未来应该会扩展。
用于合约类型 C
支持以下属性:
type(C).name
:
获得合约名type(C).creationCode
:
获得包含创建合同字节码的内存字节数组。它可以在内联汇编中构建自定义创建例程,尤其是使用create2
操作码。 不能在合同本身或派生的合同访问此属性。 因为会引起循环引用。type(C).runtimeCode
获得合同的运行时字节码的内存字节数组。这是通常由C
的构造函数部署的代码。 如果C
有一个使用内联汇编的构造函数,那么可能与实际部署的字节码不同。 还要注意库在部署时修改其运行时字节码以防范定期调用(guard against regular calls
)。 与.creationCode
有相同的限制,不能在合同本身或派生的合同访问此属性。 因为会引起循环引用。
除上面的属性, 下面的属性在接口类型I
下可使用:
-
type(I).interfaceId
:
返回接口I
的bytes4
类型的接口ID
,接口ID
参考:EIP-165
定义的, 接口 ID 被定义为XOR
(异或) 接口内所有的函数的函数选择器(不包括所有继承的函数)。
对于整型 T
有下面的属性可访问:
type(T).min
T
的最小值。type(T).max
T
的最大值。