date:20170801
基本設計
在以太坊生態(tài)系統(tǒng)中，應用二進制接口是跟合約交互的標準途徑。從區(qū)塊鏈外部或者合約之間的交互都可以通過這個方式。數據根據它的類型編碼，我們將在這個文章中詳細論述。編碼不是自我描述的，所以如果要解碼就需要模式（schema）。
我們假設合約的接口函數是強類型的，在編譯的時候推斷，且是靜態(tài)的。沒有提供反省機制。我們假設所有的合約都定義這樣的接口，使得任何合約都可以在編譯的時候調用。
該描述文檔不描述接口是動態(tài)的合約或者另一種情況--在運行的時候才知道。這些情況是很重要的，因為他們可以構建以太坊生態(tài)系統(tǒng)的豐富的內建設施。（？This specification does not address contracts whose interface is dynamic or otherwise known only at run-time. Should these cases become important they can be adequately handled as facilities built within the Ethereum ecosystem.）
函數選擇器
函數調用的調用數據的前四個字節(jié)指出了所調用的函數。它是函數簽名的keccak（SHA-3）的前四個字節(jié)（左邊，高位，大端存儲）。簽名被定義為基本原型的權威表達式。例如，函數名稱和用括號括起來的參數類型。參數類型通過一個逗號隔開-沒有使用空格。
參數編碼
從第五個字節(jié)開始，就是參數的編碼。這個編碼除了用在前四個字節(jié)指定函數外，也用在了其他地方。例如，返回值和時間參數也是用同樣的方式。
類型
有下面幾種基礎類型：
- uint<M>：M位的無符號類型的整形，0 < M <= 256,M % 8 == 0,例如，uint32，uint8，uint256。
- int<M>：M位的有符號整形，0 < M <= 256,M % 8 == 0。
- address：等價于uint160，except for the assumed interpretation and language typing.
- uint，int：各自是uint256,int256的同義詞（不是用來計算函數選擇器）
- bool：等價于 uint8，值被限制為0和1。
- fixed<M>x<N>：M位的有符號，固定點的小數，0 < M <= 256,M % 8 == 0,且0 < N <= 80, 意味著值v為v/(10 ** N).（？signed fixed-point decimal number of M bits, 0 < M <= 256, M % 8 ==0, and 0 < N <= 80, which denotes the value v as v / (10 ** N).）
- ufixed<M>x<N>：fixed<M>x<N>的無符號變量
- fixed，ufixed：各自等價于fiexed128x19，ufixed128x19（不是用來計算函數選擇器）
- bytes<M>：M位的二進制類型，0 < M <= 32.
- function：等價于bytes24，一個地址，加函數選擇器
下面是（固定大小的）數組類型：
- <type>[M]：給定類型的固定長度的數組
下面是非固定大小的類型：
- bytes: 動態(tài)大小的字符串
- string:動態(tài)大小的unicode字符串，假設是UTF-8編碼
- <type>[]:給定類型的動態(tài)長度的數組
類型可以結合為匿名結構體，通過把有限數量的參數用圓括號包圍，通過逗號隔開：
- (T1,T2,...,Tn)：匿名結構體（有序元組），由類型T1，...，Tn，n >= 0
可以組合成結構體有結構體，結構體數組等結構。
編碼的正式描述(?該章節(jié)尚未理解，翻譯出錯的概率很大，讀者可以直接查看原文)
我們現在開始正式描述編碼，它遵循下面的準則。如果參數中有嵌套數組，它們非常有用：
屬性：
1. 為了獲取一個值而讀取的次數，差不多是值在參數數組結構里的深度。例如，如果要獲取a_i[k][l][r]，就要讀取4次。在之前版本的ABI中，最壞的情況下，讀取次數和動態(tài)參數的總數線性相關。
2.變量的值或者數組元素不會插入其他值，而且可以重新定位。例如，它只使用相關的“addresses”。
我們區(qū)分了靜態(tài)和動態(tài)類型。靜態(tài)類型編碼在當前位置。而動態(tài)類型編碼在當前區(qū)塊之后的單獨分配的位置，
定義：以下的類型被稱為是“動態(tài)的”：* bytes* string* 對于任意類型T的數組T[] 任意動態(tài)類型T的數組T[k]，且K > 0* (T1,....,Tk),對于1 <= i <= k,如果Ti都是動態(tài)的。
所有其他的類型稱為“靜態(tài)”。
定義:len(a)是任意字符串 a 的字節(jié)數。len(a)的類型假設為uint256。
我們定義enc，真實的編碼，作為ABI類型的映射值到二進制字符串，所以len(enc(X))，當且僅當X是動態(tài)的時候，依賴于X的值。
定義：對于任意的ABI的值X，我們遞歸定義enc(X)依賴于X的類型
- 對于任意k>=0，任意類型的T1,...Tk
enc(X) = head(X(1)) ... head(X(k-1)) tail(X(0)) .... tail(X(k-1))
其中X(i)是組件的第i個值，head和tail定義為Ti的靜態(tài)類型，為
head(X(i)) = enc(X(i)) and tail(X(i)) = “” (空字符串)
并且
head(X(i)) = enc(len(head(X(0)) ... head(X(k-1)) tail(X(0)) ... tail(X(i-1)))) tail(X(i)) = enc(X(i))
另外一種情況，例如 如果Ti是一個動態(tài)類型。
注意，在動態(tài)的情況下，head(X(i))是很清晰，因為頭部的長度只依賴于類型而不是值。值是tail(X(i))起始的偏移相對于enc(X)的起始。 - 對于任意的T和k，T[k]
enc(X) = enc((X[0],...,X[k-1]))
例如，他會被當做具有相同類型的，k個元素的匿名數組 - T[]，X有k個元素（k假設為uint256的類型）：
enc(X) = enc(k) enc([X[1],...,X[k]])
例如，它會被當做靜態(tài)大小的數組來編碼 - k長度(被假設為uint256)的bytes
enc(X) = enc(k) pad_right(X),例如，bytes的數量被編碼為a
uint256 繼承了真實的值X作為byte序列，繼承了最小數量的零字節(jié)，因此len(enc(X))是32的倍數。 - string：enc(X)=enc(enc_utf8(X))，例如X是utf-8編碼，值是bytes類型，并且更進一步的編碼。注意，子字符串編碼的長度是utf-8編碼的bytes數，而不是字符數。
- uint<M>:enc(X)是大端編碼的X，對于負數左側填充0xff，正數左側填充0，最后長度為32的倍數
- address: 與uint160一致
- int<M>: enc(X)是x的大端2進制補碼編碼，對于負數左側填充0xff，正數左側填充0，最后長度為32的倍數
- bool:與uint8一致，1為true，0為false。
- fixed<M>x<N>:enc(X) 是 enc(X * 10N)，其中X * 10N 是int256的解釋
- fixed:和fixed128x19一致
- unfixed<M>x<N>: enc(X)和enc(X * 10 ** N)一直，其中 X * 10 ** N是uint256的解釋
- ufixed: 和ufixed128x19一樣
- bytes<M>: enc(X)是一系列的字節(jié)X，通過零字節(jié)填充的32長度的序列。
注意，對于任意X，len(enc(x))都是32的整數倍。
函數選擇器和參數編碼
總之，調用f函數，并傳遞a_1,...,a_n參數會被編碼為
function_selector(f) enc((a_1,...,a_n))
并且f的返回值v_1,...,v_k會被編碼為
enc((v_1,...v_k))
例如，返回值會組合為一個數組并且編碼。
例子
給定的合約如下所示：
pragma solidity ^0.4.0;
contract Foo {
function bar(bytes3[2] xy) {}
function baz(uint32 x, bool y) returns (bool r) { r = x > 32 || y; }
function sam(bytes name, bool z, uint[] data) {}
}
因此，對于Foo這個例子，如果我們想要調用baz，參數為69和true。我們就得傳遞總共68字節(jié)，可以分解為：
- 0xcdcd77c0：方法的ID，它來自于ASCII編碼的baz(uint32,bool)的keccak哈希的前4個字節(jié)。
- 0x0000000000000000000000000000000000000000000000000000000000000045，第一個參數，類型為uint32，值為69。
- 0x0000000000000000000000000000000000000000000000000000000000000001,第二個字節(jié)，布爾量true，填充為32位。
合并為
0xcdcd77c000000000000000000000000000000000000000000000000000000000000000450000000000000000000000000000000000000000000000000000000000000001
返回值為一個布爾量，例如，如果返回false，它的輸出為單個字節(jié)數組
，0x0000000000000000000000000000000000000000000000000000000000000000，一個布爾量。
如果我們想要調用bar，參數為["abc","def"]，我們就要傳遞總共68個字節(jié)，可以分解為
- 0xfce353f6:方法ID。它來自于對bar(bytes3[2])的簽名。
- 0x6162630000000000000000000000000000000000000000000000000000000000
- 0x6465660000000000000000000000000000000000000000000000000000000000
合并為
0xfce353f661626300000000000000000000000000000000000000000000000000000000006465660000000000000000000000000000000000000000000000000000000000
如果我們想要調用sam，參數為"dave"，true和[1,2,3]。我們總共會傳遞292個字節(jié)，可以分解為：
- 0xa5643bf2：方法ID，來自于sam(bytes,bool,uint256[])的簽名，注意uint被替換為它的同義表述，uint256
- 0x0000000000000000000000000000000000000000000000000000000000000060:第一個個參數（動態(tài)類型）的偏移位置，單位為bytes，從參數塊的起始開始。這個例子為，0x60。
- 0x0000000000000000000000000000000000000000000000000000000000000001:第二個參數，布爾量true。
- 0x00000000000000000000000000000000000000000000000000000000000000a0:第三個參數（動態(tài)類型）的偏移位置，單位為bytes。這個例子為，0xa0。
- 0x0000000000000000000000000000000000000000000000000000000000000004:第一個參數數據的一部分，它代表字節(jié)數組的長度。 這個例子是4.
- 0x6461766500000000000000000000000000000000000000000000000000000000:第一個參數的內容：“dave”的UTF-8（這個例子等價于ASCII）編碼，用0填充為32字節(jié)。
- 0x0000000000000000000000000000000000000000000000000000000000000003:第三個元素的數據的一部分，它代表數組長度的。這個例子為，3.
- 0x0000000000000000000000000000000000000000000000000000000000000001:第三個參數的第一個元素
- 0x0000000000000000000000000000000000000000000000000000000000000002:第三個參數的第二個元素
- 0x0000000000000000000000000000000000000000000000000000000000000003:第三個參數的第三個元素
合并為：
0xa5643bf20000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000464617665000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003
動態(tài)類型的使用
調用一個函數，f(uint,uint32[],bytes10,bytes)，參數為(0x123,[0x456,0x789],"1234567890","Hello,world!")，會通過下面的方式編碼：
我們取sha3(“f(uint256,uint32[],bytes10,bytes)”)的前四個字節(jié)，例如0x8be65246。然后我們編碼四個參數的頭部。對于靜態(tài)類型的uint256和bytes10，直接傳遞他們的值。但是對于動態(tài)類型uint32[]和bytes10，我們使用他們在數據區(qū)域的偏移，測量值編碼的起始位置（例如，不包含函數簽名hash的前四個字節(jié)）。它們是：
- 0x0000000000000000000000000000000000000000000000000000000000000123:（0x123擴展為32字節(jié)）
- 0x0000000000000000000000000000000000000000000000000000000000000080:(第二個參數在數據區(qū)域的偏移，4*32bytes，其實是頭部的大小)
- 0x3132333435363738393000000000000000000000000000000000000000000000:("1234567890"右填充為32個字節(jié))
- 0x00000000000000000000000000000000000000000000000000000000000000e0:(第四個參數在數據區(qū)域的偏移 = 第一個動態(tài)參數的數據的偏移 + 第一個動態(tài)參數的數據的大小 = 4*32 + 3 * 32)
這之后，后面緊跟第一個動態(tài)參數的數據部分，[0x456,0x789]：
- 0x0000000000000000000000000000000000000000000000000000000000000002:(數組的長度，2)
- 0x0000000000000000000000000000000000000000000000000000000000000456：（第一個參數）
- 0x0000000000000000000000000000000000000000000000000000000000000789：（第二個參數）
最后我們會編碼第二個動態(tài)參數的數據部分，”Hello world！“
- 0x000000000000000000000000000000000000000000000000000000000000000d：(元素的數量(這個例子為bytes)：13)
- 0x48656c6c6f2c20776f726c642100000000000000000000000000000000000000：(”Hello,world!“右填充為32個字節(jié))
合而為一，編碼如下（函數選擇器之后要換行，為了清晰，每行32字節(jié)）：
0x8be65246
0000000000000000000000000000000000000000000000000000000000000123
0000000000000000000000000000000000000000000000000000000000000080
3132333435363738393000000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000e0
0000000000000000000000000000000000000000000000000000000000000002
0000000000000000000000000000000000000000000000000000000000000456
0000000000000000000000000000000000000000000000000000000000000789
000000000000000000000000000000000000000000000000000000000000000d
48656c6c6f2c20776f726c642100000000000000000000000000000000000000
事件
事件是以太坊日志/事件監(jiān)聽協(xié)議的抽象。日志實體提供了合約的地址，一系列但最多4個主題和任意長度的二進制數據。事件整合已存在的ABI，將他（和接口描述一起）翻譯為合適類型的結構體。（？Events leverage the existing function ABI in order to interpret this (together with an interface spec) as a properly typed structure.）
給定一個事件名稱和一系列的事件參數，我們可以將它分為兩個子系列：被索引的和沒有被索引的。被索引的，最多3個，通過事件簽名的Keccak哈希來組成日志實體的主題。另外沒有索引的組成事件的byte數組。
實際上，使用ABI的日志實體被描述為：
- address:合約的地址(以太坊本身支持)
- topics[0]: keccak(EVENT_NAME+”(“+EVENT_ARGS.map(canonical_type_of).join(”,”)+”)”) （canonical_type_of 是一個函數，簡單的根據參數返回同義類型。例如，對于uint索引的foo，它會返回 uint256。）如果事件被描述為anonymous，topics[0]不會生成。
- topics[n]: EVENT_INDEXED_ARGS[n - 1](EVENT_INDEXED_ARGS是一系列被索引的EVENT_ARGS)
- data:abi_serialise(EVENT_NON_INDEXED_ARGS) (EVENT_NON_INDEXED_ARGS 是一系列沒有被索引的EVENT_ARGS，abi_serialise是ABI序列化函數，用來返回一系列類型的函數返回，如上面所述）
JSON
合約接口的JSON形式通過一個函數數組 和/或 事件描述 給定。函數描述是一個JSON對象，具有如下的字段:
type: "function","construct"或者"fallback"(沒有名字的默認函數)
name: 函數的名稱
-
inputs: 一個對象數組，每個對象包含：
- name:參數名稱
- type:參數類型的同義類型
outputs: 像inputs一樣的數組對象，如果沒有返回值，可以刪除這個字段
constant: 如果函數聲明為不改變區(qū)塊鏈狀態(tài)為true
payable: 如果函數接收以太幣，則為true，默認為false。
type可以刪除，默認為"function".
構造函數和fallback函數沒有名稱或者輸出。fallback函數也沒有輸入。
發(fā)送非零個以太幣到非payable的函數會有異常，不要這么干。
一個事件的描述，是一個差不多字段的JSON對象。
type: 總是”event“
name: 事件的名稱
-
inputs: 一個對象數組，每個對象包含
- name：參數名稱
- type：參數類型的同義類型
- indexed：如果字段是日志的topic，則為true，如果是日志的數據部分，則為false
anonymous: 如果事件被聲明為anonymous，則為true。
例如，
pragma solidity ^0.4.0;
contract Test {
function Test(){ b = 0x12345678901234567890123456789012; }
event Event(uint indexed a, bytes32 b)
event Event2(uint indexed a, bytes32 b)
function foo(uint a) { Event(a, b); }
bytes32 b;
}
JSON形式為：
[{
"type":"event",
"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
"name":"Event"
}, {
"type":"event",
"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
"name":"Event2"
}, {
"type":"function",
"inputs": [{"name":"a","type":"uint256"}],
"name":"foo",
"outputs": []
}]
