合約 ABI 編碼

什麼是合約 ABI 編碼？

合約 ABI 編碼是將智能合約的函式名稱、輸入值、回傳值、事件及錯誤轉換為 Ethereum Virtual Machine 能理解的二進位格式的過程。ABI 是 Application Binary Interface（應用程式二進位介面）的縮寫，作用類似智能合約、錢包、去中心化應用程式、開發者工具及區塊鏈節點之間共用的語言。在加密貨幣領域，合約 ABI 編碼最常用於討論 Ethereum 及其他與 EVM 相容的區塊鏈。使用者兌換代幣、傳送 ERC-20 代幣、授權智能合約、鑄造 NFT 或與去中心化應用程式互動時，交易資料通常會先經過 ABI 編碼，再提交至鏈上。

Solidity 合約 ABI 規格指出，ABI 是 Ethereum 生態系統中與合約互動的標準方式。

合約 ABI 編碼很重要，因為智能合約無法直接讀取「將 10 個代幣轉至此地址」這類易懂指令。相反地，合約會接收 calldata，也就是包含函式選擇器及編碼參數的十六進位位元組字串。這些編碼資料會告訴合約要執行哪個函式，以及要使用哪些數值。沒有 ABI 編碼，大多數面向使用者的加密貨幣應用程式就無法可靠地將按鈕點擊轉換為有效的智能合約呼叫。

合約 ABI 編碼為何對加密貨幣很重要

合約 ABI 編碼很重要，因為智能合約互動必須精確無誤。即使只有一個位元組錯誤，也可能呼叫錯誤的函式、傳入錯誤數量、將資金傳送至錯誤地址，或導致交易回復。加密貨幣使用者通常只會看到簡潔的錢包提示，但實際交易包含結構化資料，必須與合約介面相符。對開發者而言，ABI 編碼是核心技能，因為它說明前端、SDK、腳本、錢包及合約如何與鏈上程式碼溝通。對交易者和代幣持有者而言，ABI 編碼有助於理解授權、代幣轉帳、質押操作、治理投票、跨鏈橋呼叫及智能合約執行背後發生的事情。ABI 編碼也有助於提升交易透明度，因為解碼後的 calldata 可在簽署交易前顯示預計執行的函式及參數。因此，交易模擬工具、區塊鏈瀏覽器及錢包介面會嘗試將合約呼叫解碼為易讀資訊。ABI 資訊缺漏或不正確時，同一筆交易可能只會顯示原始十六進位資料，一般使用者更難理解。

合約 ABI 編碼的運作方式

標準外部函式呼叫會以 4 位元組的函式選擇器開頭。函式選擇器會根據函式簽章計算，函式簽章包含函式名稱及標準化的參數類型。Solidity ABI 規格指出，calldata 的前 4 個位元組會指定要呼叫的函式，並取自函式簽章 Keccak-256 雜湊值的前 4 個位元組。

例如，簽章

會產生一個 4 位元組選擇器，用來識別許多 ERC-20 合約採用的代幣轉帳函式。

選擇器之後的函式參數會依 ABI 類型進行編碼。大多數 ABI 編碼值會以 32 位元組的字組表示。

如

、、 和 等靜態值可直接放入編碼資料。

、 和動態陣列等動態值，則會使用偏移量指向其他資料位置。

只要知道正確的 ABI 結構，合約和開發者工具就能依照這套嚴格的位元組排列方式進行解碼。

函式簽章與函式選擇器

函式簽章是函式名稱後方以括號標示參數類型的文字形式。簽章必須使用標準 ABI 類型名稱，且不得包含空格。

例如，

是函式簽章，而 則不是計算選擇器時使用的標準形式。

回傳類型不會納入函式選擇器。

這表示具有一種回傳類型的

和具有另一種回傳類型的 ，不會單憑回傳值而得到不同選擇器。

因此，Solidity 函式多載必須依賴不同參數清單，而非不同回傳類型。函式選擇器很短，可讓 calldata 更精簡，但開發者也必須遵循確切的 ABI 規則。錢包或應用程式傳送交易時，選擇器會出現在交易輸入資料的開頭。合約會根據該選擇器，將呼叫導向正確的函式邏輯。

Calldata 與 ABI 編碼

Calldata 是外部呼叫智能合約時傳送的唯讀交易輸入資料。一般合約互動中的 calldata 會包含函式選擇器及其後經 ABI 編碼的參數。

Ethereum JSON-RPC 文件說明，合約呼叫輸入資料包含方法簽章雜湊值及編碼參數。

這些輸入資料通常會顯示為以

開頭的十六進位字串。

前綴表示該值是十六進位資料。

每 2 個十六進位字元代表 1 個位元組。EVM 處理的是位元組，而非自然語言指令，因此 ABI 編碼是易讀合約介面與機器可讀執行資料之間的橋樑。使用者簽署交易時，即表示授權目標合約執行這些已編碼的 calldata。因此，清楚易讀的交易預覽對加密貨幣安全至關重要。

ABI 編碼中的靜態類型

ABI 靜態類型具有固定大小，因此可直接編碼到固定的 32 位元組欄位中。

常見靜態類型包括

、、、、 等固定大小位元組陣列，以及元素同樣為靜態類型的固定大小陣列。

值會編碼為 32 位元組的無號整數。

長度為 20 位元組，但會在 32 位元組欄位中以左側補零的方式編碼。

會在 32 位元組欄位中編碼為 （false）或 （true）。

等固定大小位元組值代表原始位元組，而非數字，因此補位方式不同。

ABI 類型規則很重要，因為同一個可見值可能會依宣告類型不同而採用不同編碼。

例如，

若是 ，處理方式就不同於將 視為數字。

ABI 編碼中的動態類型

ABI 動態類型在編譯時沒有固定的最終長度。

常見動態類型包括

、、 等動態陣列，以及至少包含一個動態元素的 tuple。

動態值通常採用 head-and-tail 結構編碼。Head 區段包含指向動態值起始位置的偏移量。Tail 區段則包含動態值的實際長度及資料。

對於

，會先將其轉換為 UTF-8 位元組，再以其位元組長度編碼，並補位至 32 的倍數。

對於動態陣列，編碼資料會包含元素數量，後面接著各元素的編碼資料。這種設計讓合約不必手動掃描所有前置參數，就能找到動態值。同時也讓巢狀陣列、字串、位元組欄位及包含多個 tuple 的合約呼叫能以一致方式實現。

Head 與 Tail 編碼

Head-and-tail 排列方式是合約 ABI 編碼中最重要的概念之一。Head 是編碼參數區域的前段。Tail 則是儲存動態資料的後段。靜態參數會直接編碼在 Head 中。動態參數會在 Head 中放入偏移量，並在 Tail 中儲存實際內容。偏移量是從已編碼參數區塊的起始位置計算，而不是從包含 4 位元組選擇器的整段交易輸入資料起始位置計算。手動解碼 calldata 時，這項細節很重要。若從錯誤的起點讀取偏移量，後續每一項解讀都可能出錯。即使使用者只輸入短字串或小數值，head-and-tail 模型仍會讓 ABI 編碼後的 calldata 看起來很長，並包含大量補位。

代幣轉帳的 ABI 編碼

代幣轉帳是理解合約 ABI 編碼的簡單方式。

許多同質化代幣合約遵循ERC-20 代幣標準，該標準定義了

、、 和 等函式。

使用者轉帳代幣時，交易通常會呼叫

。

Calldata 會以該簽章對應的函式選擇器開頭。第一個編碼參數是收款地址。第二個編碼參數是代幣數量，通常以代幣最小單位表示，而非介面上顯示的小數數量。

例如，小數位數為 18 的代幣，其介面顯示的 1 個代幣會以

個基本單位表示。

也就是說，除非應用程式已先將使用者輸入的數量轉換成正確整數值，否則 ABI 編碼本身並不知道「1 個代幣」代表什麼。

授權的 ABI 編碼

代幣授權是加密貨幣領域中 ABI 編碼的另一種常見用途。

授權交易通常會在代幣合約上呼叫

。

第一個參數是支出方地址。第二個參數是授權額度。授權確認後，支出方可能可以依照代幣合約規則及授權數量移動代幣。因此，使用者在簽署前應仔細檢查授權。ABI 編碼的 calldata 可能看起來像一長串十六進位字元，但解碼後可能代表一項非常重要的權限。若授權額度過大或無上限，而支出方合約不安全、遭到入侵或遭到誤解，可能會帶來風險。了解 ABI 編碼有助於使用者理解，授權並非例行的錢包提示，而是真正的合約權限。

ABI 編碼與智能合約事件

ABI 編碼不只用於函式呼叫。它也用於回傳值和事件資料。事件可讓智能合約發布結構化日誌，供外部工具讀取。

例如，代幣餘額變動後，通常會發出

事件。

事件日誌可包含索引參數和非索引參數。索引事件參數會儲存在 topics 中，非索引參數則會以 ABI 編碼儲存在 data 欄位。Solidity ABI 規格包含事件編碼規則，其中也包含對索引動態值的特殊處理方式。區塊鏈瀏覽器、分析工具、報稅軟體、投資組合追蹤器及風險系統，都依賴正確解碼事件來理解鏈上活動。如果事件 ABI 不正確，解碼結果可能會顯示錯誤的名稱、數值或地址。

ABI 編碼與回傳值

智能合約函式傳回資料時，回傳值會經過 ABI 編碼。

像

這類唯讀呼叫，可能會傳回以 32 位元組字組編碼的 。

若函式傳回字串、陣列或 tuple，則可能依動態類型規則傳回較長的編碼結構。開發者工具會使用 ABI 中預期的輸出類型解碼回傳位元組。因此，ABI JSON 會包含輸出定義，即使回傳類型不屬於函式選擇器的一部分。若缺少正確的輸出結構，工具可能會從節點接收到位元組，卻不知道如何呈現給使用者。在加密貨幣應用程式中，解碼回傳值對於顯示餘額、資金池儲備、代幣中繼資料、治理結果及金庫資訊都很重要。

ABI JSON 與易讀介面

ABI 通常會以 JSON 檔案或 JSON 物件分享。ABI JSON 會描述合約的函式、輸入、輸出、事件、錯誤、可變性及類型資訊。前端應用程式可使用 ABI JSON，在將交易傳送至錢包前進行編碼。錢包或區塊鏈瀏覽器可使用 ABI JSON，將交易資料解碼成易讀預覽。開發者腳本可使用 ABI JSON 呼叫已部署合約，無須手動建構 calldata。JSON ABI 本身不是智能合約位元組碼。它描述的是如何與位元組碼溝通。這就像是機器的操作選單：選單告訴使用者有哪些指令可用，但實際運作的仍是機器本身的邏輯。ABI 與已部署合約不相符時，呼叫可能失敗，或解碼結果可能不正確。

Solidity ABI 編碼函式

Solidity 提供內建函式，用於 ABI 編碼和解碼。

Solidity ABI 編碼與解碼函式包括

、

abi.decode

、

abi.encodeWithSelector

、

abi.encodeWithSignature

、

abi.encodeCall

和

abi.encodePacked

。

會使用標準 ABI 格式編碼數值。

會將 ABI 編碼的位元組解碼為指定類型。

會在編碼參數前加上 4 位元組選擇器。

會根據簽章字串計算選擇器，並將其加到編碼參數前方。

可針對函式指標及其參數進行類型檢查。

使用非標準的緊密排列格式，雖然較短，但遇到動態值時可能產生歧義。

在大多數一般智能合約呼叫中，標準 ABI 編碼比緊密編碼更安全且清楚。

標準 ABI 編碼與緊密編碼

標準 ABI 編碼會使用 32 位元組對齊、偏移量、長度和補位。緊密編碼會將數值排列得更緊密，並可能省略補位或長度欄位。緊密編碼適用於緊湊資料的雜湊，但必須審慎使用。Solidity 文件提醒，涉及多個動態值時，緊密編碼可能產生歧義。例如，如果邊界不明確，不同的兩組字串可能會產生相同的緊密編碼位元組序列。這可能在簽章、身分驗證檢查或資料完整性邏輯中造成雜湊碰撞風險。

需要明確且無歧義的結構化編碼時，開發者通常偏好使用

。

使用

時，開發者應確保類型及資料邊界不會混淆。

這項問題對加密貨幣特別重要，因為細微的編碼錯誤可能演變成實際的安全漏洞。

ABI 編碼與低階呼叫

Solidity 支援

、 和 等低階呼叫。

Solidity 文件說明，低階呼叫會接收 bytes 參數，並可使用 ABI 編碼函式將結構化資料編碼。

低階呼叫讓開發者擁有更大的控制權，但也伴隨較高風險。一般的型別化合約呼叫能在編譯時更清楚地檢查目標介面。低階呼叫可能在位元組層面成功執行，實際行為卻與開發者預期不同。因此，若有型別化介面可用，開發者應避免不必要的低階呼叫。若必須使用低階呼叫，ABI 編碼必須完全正確，因為合約只會收到原始位元組。開發者也應謹慎處理回傳值、回復、Gas 行為及重入風險。

錢包中的 ABI 編碼與解碼

錢包會使用 ABI 資料協助使用者了解自己正在簽署的內容。

若 ABI 資訊可用，錢包可能會顯示

或 等函式名稱，而非只呈現原始交易輸入資料。

若缺少 ABI 資訊，錢包可能會顯示難以閱讀的十六進位字串。這會讓使用者更難察覺可疑交易。現代加密貨幣安全工具通常會解碼 calldata、模擬執行，並在簽署前標示有風險的權限。不過，使用者不應假設所有解碼標籤都完全正確。惡意合約可能使用容易混淆的函式名稱、異常參數或誤導性流程。較安全的做法是結合易讀解碼、可信來源、已驗證合約、仔細核對地址，以及在可用時進行交易模擬。ABI 解碼可以提升資訊透明度，但不能取代使用者的判斷。

ABI 編碼與安全風險

不當使用合約 ABI 編碼可能帶來多種安全疑慮。第一，選擇器或簽章錯誤可能導致呼叫錯誤函式。第二，參數順序可能錯誤。第三，可能使用錯誤的整數大小或小數位轉換方式。第四，可能信任來自未驗證或不相符 ABI 的解碼資料。

第五，以

建立的雜湊可能存在歧義。

第六，可能只因函式名稱看起來熟悉，就假設交易安全。智能合約攻擊者常利用使用者簽署自己並未完全理解的資料。因此，ABI 編碼不只是開發者議題，也是使用者安全議題。易讀的 calldata 解碼可協助使用者在確認交易前辨識授權、轉帳、兌換、鑄造、領取獎勵、跨鏈橋操作及管理員呼叫。

開發者常見錯誤

常見錯誤之一是在某處使用

，卻忘記計算選擇器時使用的標準 ABI 名稱是 。

另一個常見錯誤是在

使用的函式簽章字串中加入空格。

第三個錯誤是將地址編碼為字串，而非

類型。

第四個錯誤是建立 calldata 時使用代幣顯示單位，而非基本單位。第五個錯誤是在雜湊多個動態值時使用緊密編碼。第六個錯誤是以錯誤的輸出類型解碼回傳資料。第七個錯誤是在未確認實際升級狀態前，就假設 Proxy 合約與目前實作合約具有相同 ABI。第八個錯誤是忘記同名多載函式必須使用不同的參數類型清單，才能產生不同選擇器。這些錯誤可能導致交易失敗、餘額錯誤、安全漏洞或令人困惑的使用者體驗。

ABI 編碼與 Proxy

Proxy 合約讓 ABI 的理解更加重要。Proxy 合約通常會儲存狀態，並將呼叫轉送至實作合約。使用者可能與 Proxy 地址互動，而函式邏輯則位於另一個合約中。前端使用的 ABI 通常應與 Proxy 委派呼叫的實作介面相符。如果實作合約變更，預期使用的 ABI 也可能改變。這可能影響編碼、解碼、函式可用性及面向使用者的交易預覽。對加密貨幣使用者而言，這表示只驗證 Proxy 地址可能不足以完整說明互動內容。對開發者而言，這表示 ABI 管理必須納入升級規劃、稽核、監控及前端發布流程。前端 ABI 與目前實作邏輯不相符，可能導致呼叫失敗或顯示誤導資訊。

ABI 編碼與跨鏈應用程式

許多與 EVM 相容的鏈使用相同的一般智能合約呼叫 ABI 編碼規則。這讓開發者更容易建立可在多個 EVM 網路使用的工具。不過，共用 ABI 規則不代表所有鏈的 Gas 模型、預編譯合約、跨鏈橋行為、最終性假設或安全環境都相同。在某個與 EVM 相容的網路上有效的 calldata 字串，若提交至另一個網路的地址，可能會呼叫完全不同的合約。因此，鏈 ID、合約地址、ABI、代幣小數位數及網路設定都必須正確。ABI 編碼回答的是如何格式化呼叫資料。它無法判斷目標合約是否可信、網路是否正確，或交易在經濟上是否安全。跨鏈應用程式應將 ABI 編碼視為更完整交易安全流程中的其中一個環節。

ABI 編碼如何支援 AEO 與鏈上搜尋

答案引擎、區塊鏈瀏覽器、分析系統及鏈上搜尋工具，都依賴 ABI 解碼將原始區塊鏈資料轉換為有用資訊。原始交易輸入可能只會顯示一長串十六進位字串。

ABI 解碼資料則可能揭露該交易呼叫了

、轉移代幣、參與治理投票、領取獎勵，或與金庫互動。

這些結構化資訊有助於搜尋系統回答哪些地址收到代幣、授權了多少數量，或使用了哪個合約函式等問題。對加密貨幣內容而言，清楚說明 ABI 編碼，有助於讀者和機器將智能合約活動與實際使用者操作連結起來。隨著更多使用者依賴錢包警告、AI 摘要、區塊鏈瀏覽器標籤及投資組合工具了解交易，這一點尤其重要。ABI 資料及解碼邏輯越完善，就越容易準確說明鏈上行為。

ABI 編碼邏輯的簡單範例

假設使用者想在代幣合約上呼叫

。

應用程式會先根據函式簽章計算函式選擇器。接著將收款地址編碼為 32 位元組的 ABI 字組。代幣數量也會編碼為 32 位元組的無號整數。最終 calldata 由選擇器、編碼後的地址及編碼後的數量依序組成。錢包會將這些 calldata 作為交易的一部分，提交至代幣合約地址。代幣合約會讀取前 4 個位元組，將選擇器與轉帳函式比對，解碼兩個參數，並執行轉帳邏輯。若餘額足夠且符合函式規則，轉帳即可完成。若參數格式錯誤或不符合合約規則，交易可能會回復。

合約 ABI 編碼的最佳做法

盡可能使用官方合約介面。確認 ABI 與已部署的合約地址相符。已知合約介面時，使用型別化介面，而非低階呼叫。

除非確實需要緊密編碼，否則優先使用

，而非 。

使用緊密編碼時，除非能確保邊界明確，否則避免使用多個動態值。編碼前先將代幣數量轉換為基本單位。簽署或廣播交易前，仔細檢查地址參數。在測試期間解碼交易 calldata，並確認其函式及參數符合預期。進行敏感的合約互動時，若可使用交易模擬，請先進行模擬。升級合約或變更前端整合時，記錄 ABI 變更。原始 calldata 會直接控制智能合約的執行內容，因此應視為高風險領域。

常見問題

合約 ABI 編碼代表什麼？

合約 ABI 編碼是將智能合約函式呼叫和值轉換成 EVM 可讀取並執行的位元組格式。

加密貨幣領域中的 ABI 是什麼縮寫？

ABI 是 Application Binary Interface（應用程式二進位介面）的縮寫，用來定義外部工具和其他合約如何與智能合約互動。

什麼是函式選擇器？

函式選擇器是函式簽章 Keccak-256 雜湊值的前 4 個位元組，用來告訴合約應呼叫哪個函式。

什麼是 calldata？

Calldata 是傳送至智能合約的交易輸入資料，通常包含函式選擇器及經 ABI 編碼的參數。

為什麼 ABI 編碼值通常是 32 位元組？

標準 ABI 編碼使用 32 位元組字組，以便對齊、確保解碼方式一致，並符合 EVM 的資料處理方式。

ABI 靜態類型與動態類型有什麼差異？

靜態類型具有固定大小，會直接在原位置編碼；動態類型則使用偏移量，並將實際資料儲存在獨立的 Tail 區段。

ABI 編碼等同於加密嗎？

不等同。ABI 編碼是為了格式化智能合約執行資料，並不會隱藏資料，因此不是加密。

使用者能讀取 ABI 編碼的交易資料嗎？

大多數使用者需要透過錢包、區塊鏈瀏覽器或開發者工具，將 ABI 編碼的交易資料解碼為易讀的函式名稱及數值。

ABI 編碼為什麼對代幣授權很重要？

ABI 編碼會定義授權交易中的支出方地址及授權額度，因此使用者需要正確解碼，才能了解自己授予的權限。

ABI 編碼錯誤時會發生什麼事？

交易可能回復、呼叫錯誤函式、傳入不正確數值、顯示誤導資訊，或造成安全問題。

結論

合約 ABI 編碼是將易讀的智能合約互動轉換為區塊鏈合約可執行位元組資料的技術流程。它透過共用資料格式，連結錢包、去中心化應用程式、開發者工具、區塊鏈瀏覽器及智能合約。ABI 編碼的主要組成部分包括函式簽章、4 位元組選擇器、calldata、靜態類型、動態類型、偏移量、補位、事件資料及回傳值解碼。對加密貨幣使用者而言，ABI 編碼說明了代幣轉帳、授權、兌換、質押操作、治理投票及其他合約互動背後的運作方式。對開發者而言，它是建置安全前端、腳本、整合、稽核及低階合約呼叫的必要知識。由於區塊鏈交易難以撤銷，準確的 ABI 編碼及清楚的 ABI 解碼，對使用便利性和安全性都至關重要。深入了解合約 ABI 編碼，有助於使用者更仔細地檢視交易、協助開發者避免代價高昂的錯誤，也讓整個加密貨幣生態系更容易理解鏈上活動。