合约的元数据——Solidity中文文档（6）

写在前面：HiBlock区块链社区成立了翻译小组，翻译区块链相关的技术文档及资料，本文为Solidity文档翻译的第六部分《合约的元数据》，特发布出来邀请solidity爱好者、开发者作公开的审校，您能够添加微信baobaotalk_com，验证输入“solidity”，而后将您的意见和建议发送给咱们，也能够在文末“留言”区留言，有效的建议咱们会采纳及合并进下一版本，同时将送一份小礼物给您以示感谢。

Solidity编译器自动生成JSON文件，即合约的元数据，其中包含了当前合约的相关信息。 它能够用于查询编译器版本，所使用的源代码，应用二进制接口-Application Binary Interface(ABI) 和 以太坊标准说明格式-Ethereum Nature Specification Format(natspec) 文档，以便更安全地与合约进行交互并验证其源代码。

编译器会将元数据文件的 Swarm 哈希值附加到每一个合约的字节码末尾（详情请参阅下文）， 以便你能够以认证的方式获取该文件，而没必要求助于中心化的数据提供者。

固然，你必须将元数据文件发布到 Swarm （或其余服务），以便其余人能够访问它。 该文件能够经过使用 solc --metadata 来生成，并被命名为 ContractName_meta.json 。 它将包含源代码的在 Swarm 上的引用，所以你必须上传全部源文件和元数据文件。

元数据文件具备如下格式。 下面的例子将以人类可读的方式呈现。 正确格式化的元数据应正确使用引号，将空白减小到最小，并对全部对象的键值进行排序以获得惟一的格式。 代码注释固然也是不容许的，这里仅用于解释目的。

{
 // 必选：元数据格式的版本
 version: "1",
 // 必选：源代码的编程语言，通常会选择规范的“子版本”
 language: "Solidity",
 // 必选：编译器的细节，内容视语言而定。
 compiler: {
   // 对 Solidity 来讲是必须的：编译器的版本
   version: "0.4.6+commit.2dabbdf0.Emscripten.clang",
   // 可选： 生成此输出的编译器二进制文件的哈希值
   keccak256: "0x123..."
 },
 // 必选：编译的源文件／源单位，键值为文件名
 sources:
 {
   "myFile.sol": {
     // 必选：源文件的 keccak256 哈希值
     "keccak256": "0x123...",
     // 必选（除非定义了“content”，详见下文）：
     // 已排序的源文件的URL，URL的协议能够是任意的，但建议使用 Swarm 的URL
     "urls": [ "bzzr://56ab..." ]
   },
   "mortal": {
     // 必选：源文件的 keccak256 哈希值
     "keccak256": "0x234...",
     // 必选（除非定义了“urls”）： 源文件的字面内容
     "content": "contract mortal is owned { function kill() { if (msg.sender == owner) selfdestruct(owner); } }"
   }
 },
 // 必选：编译器的设置
 settings:
 {
   // 对 Solidity 来讲是必须的： 已排序的重定向列表
   remappings: [ ":g/dir" ],
   // 可选： 优化器的设置（ enabled 默认设为 false ）
   optimizer: {
     enabled: true,
     runs: 500
   },
   // 对 Solidity 来讲是必须的：用以生成该元数据的文件名和合约名或库名
   compilationTarget: {
     "myFile.sol": "MyContract"
   },
   // 对 Solidity 来讲是必须的：所使用的库的地址
   libraries: {
     "MyLib": "0x123123..."
   }
 },
 // 必选：合约的生成信息
 output:
 {
   // 必选：合约的 ABI 定义
   abi: [ ... ],
   // 必选：合约的 NatSpec 用户文档
   userdoc: [ ... ],
   // 必选：合约的 NatSpec 开发者文档
   devdoc: [ ... ],
 }
}

2

元数据哈希字节码的编码

因为在未来咱们可能会支持其余方式来获取元数据文件， 相似 {"bzzr0"：<Swarm hash>} 的键值对，将会以 CBOR 编码来存储。 因为这种编码的起始位不容易找到，所以添加两个字节来表述其长度，以大端方式编码。 因此，当前版本的Solidity编译器，将如下内容添加到部署的字节码的末尾:

0xa1 0x65 'b' 'z' 'z' 'r' '0' 0x58 0x20 <32 **bytes**swarm hash> 0x00 0x29

所以，为了获取数据，能够检查部署的字节码的末尾以匹配该模式，并使用 Swarm 哈希来获取元数据文件。

3

自动化接口生成和以太坊标准说明格式 的使用方法

元数据如下列方式被使用：想要与合约交互的组件（例如，Mist）读取合约的字节码， 从中获取元数据文件的 Swarm 哈希，而后从 Swarm 获取该文件。该文件被解码为上面的 JSON 结构。

而后该组件能够使用ABI自动生成合约的基本用户接口。

此外，Mist能够使用 userdoc 在用户与合约进行交互时向用户显示确认消息。

有关 以太坊标准说明格式-Ethereum Nature Specification Format(natspec) 的其余信息能够在 这里 （https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format）找到。

4

源代码验证的使用方法

为了验证编译，能够经过元数据文件中的连接从 Swarm 中获取源代码。 获取到的源码，会根据元数据中指定的设置，被正确版本的编译器（应该为“官方”编译器之一）所处理。 处理获得的字节码会与建立交易的数据或者 CREATE 操做码使用的数据进行比较。 这会自动验证元数据，由于它的哈希值是字节码的一部分。 而额外的数据，则是与基于接口进行编码并展现给用户的构造输入数据相符的。

延伸阅读：智能合约-Solidity官方文档（1）

安装Solidity编译器-Solidity官方文档（2）

根据例子学习Solidity-Solidity官方文档（3）

深刻理解Solidity之源文件及合约结构——Solidity中文文档（4）

安全考量——Solidity中文文档（5）

本文内容来源于HiBlock区块链社区翻译小组，感谢全体译者的辛苦工做。

注：本文为solidity翻译的第六部分《合约的元数据》，特发布出来邀请solidity爱好者、开发者作公开的审校，您能够添加微信baobaotalk_com，验证输入“solidity”，而后将您的意见和建议发送给咱们，也可在文末“留言”区留言，或经过原文连接访问咱们的Github。有效的建议咱们会收纳并及时改进，同时将送一份小礼物给您以示感谢。

如下是咱们的社区介绍，欢迎各类合做、交流、学习：）