合約的元數據——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。有效的建議咱們會收納並及時改進，同時將送一份小禮物給您以示感謝。

如下是咱們的社區介紹，歡迎各類合做、交流、學習：）