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": []
}]