OCAP Playground 入門

作者： Shijun（ArcBlock 工程團隊前端工程師）

如果你對區塊鏈技術已有基本認識，甚至親自開發過簡單的區塊鏈應用程式，我想你或許曾被各種鏈不同的介面和資料格式弄得困惑。大規模開發區塊鏈應用程式的最大障礙，是為了讀寫每條區塊鏈上的資料，都必須為各條鏈執行完整節點；即使對經驗豐富的開發者來說，完成這些「髒活」也需要花費大量時間。

身為開發者，你一定會想：有沒有一種對開發者更友善、更像傳統應用程式的方式來開發區塊鏈應用？ArcBlock 的工程師長期思考這個問題，經過數個月的開發，ArcBlock 將正式發布一個支援多鏈資料存取的解決方案：Open Chain Access Protocol（通常簡稱 OCAP）。

如果你對 OCAP 服務感興趣，或想用更熟悉的方式開發區塊鏈應用程式，我強烈建議你花5分鐘閱讀本文；我們將從開發者的角度介紹 OCAP Playground 的基本用法。

什麼是 OCAP Playground？

採用任何新技術之前，都有必要先弄清楚它是什麼。那麼，OCAP Playground 是什麼？我們可以從以下3個角度來定義它。

1. OCAP 服務的小型前端

幾乎所有複雜的現代系統都符合「大型後端、小型前端」的模式，ArcBlock 的 OCAP 服務也不例外。從使用者角度能夠接觸和感受到的前端，只是冰山一角：

OCAP Playground 是 OCAP 服務的小型前端，也是整個 OCAP 服務可見的部分。開發者可以在 OCAP Playground 中輕鬆探索 OCAP 服務的能力。Playground 的互動性和資料視覺化能力，讓開發者在探索過程中有所發現、獲得靈感，並協助開發者做好在 OCAP 服務上建構 DApp 的準備。

2. OCAP 服務的即時文件

由於 OCAP 按照 GraphQL 規範提供所有介面，得益於 GraphQL 的單一端點和強型別，OCAP Playground 成為 OCAP 服務的即時動態文件。開發者可以在 Playground 中瀏覽和搜尋文件，並在查詢編輯器中享受智慧自動完成，就像在熟悉的 IDE 中撰寫程式碼一樣。

3. ArcBlock 生態系統中的第一個 DApp

如果把 OCAP 服務視為黑盒，那麼 OCAP Playground 在整個 ArcBlock 生態系統中的角色可以如下圖所示：

如何使用 OCAP Playground？

在開始動手之前，我們需要做一些準備。

準備工作

建立區塊鏈資料的心智模型

從概念上理解一項技術，能讓我們更快掌握它；幾乎所有區塊鏈資料都有如下相同的心智模型：

大多數將全部或部分資料儲存在區塊鏈上的 DApp，實際上都在讀取或寫入區塊鏈上與帳戶、交易和區塊相關的資料，因此大多數 OCAP 服務 API 都圍繞這3個實體建構。

稍微了解 GraphQL 語法

OCAP 服務使用 GraphQL 作為查詢語言，jQuery 的創作者 John Resig 認為 GraphQL 是新一代 REST。從端點規範、錯誤定義、資料型別、參數驗證和 API 文件等方面來看，GraphQL 是更出色的 API 解決方案。GraphQL 社群發展非常迅速，一些數位貨幣交易所已開始使用 GraphQL 提供 API。

你可能會想：想在 OCAP 服務上開發 DApp 的人，都必須先學 GraphQL 嗎？答案是肯定的，但你不必擔心。GraphQL 的語法相當簡單，即使從未使用過，也可以直接開始使用 OCAP Playground。在下面的範例中，你可以感受它的直覺與簡潔。

Hello OCAP Playground!

少說空話，讓我看看程式碼。用你喜愛的瀏覽器開啟 ocap.arcblock.io，OCAP Playground 的預設畫面分成兩欄：左欄是查詢編輯器，右欄是結果檢視器。如果這是你第一次造訪 Playground，查詢編輯器中會填入預設查詢，並自動顯示查詢結果。

如何發起自訂查詢？清空查詢編輯器，輸入以下查詢。這個查詢會向 OCAP 服務要求 Bitcoin 創世區塊的資料；若要進一步了解 Bitcoin 區塊的資料結構，請見此處：

{
  genesisBlock {
    hash
    size
    total
    numberTxs
  }
}

接著點擊「執行」按鈕，或直接按下鍵盤快速鍵 CTRL + Enter（Mac 上應為 CMD + Enter），然後就能看到 Bitcoin 創世區塊資料以 JSON 格式顯示在結果檢視器中。

{
  "data": {
    "genesisBlock": {
      "total": 0,
      "size": 285,
      "numberTxs": 1,
      "hash": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
    }
  }
}

從資料可以看出，Bitcoin 創世區塊只包含1筆交易，區塊雜湊為 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f。

恭喜，你已成功完成 OCAP Playground 中的第一個查詢。

OCAP Playground 中的複雜查詢

Bitcoin 創世區塊中有交易資料嗎？如果有，接收者是誰？發送了多少 Bitcoin？Nakamoto 真的在創世區塊中為自己建立了50枚 Bitcoin 嗎？

借助 OCAP Playground，我們可以自行驗證。我們只需發起一次查詢，就能取得所有需要的區塊資料，沒有任何冗餘。大多數現有的區塊鏈資料查詢服務都會回傳完整的區塊資料，這些資料往往過大，可能拖慢我們的應用程式。

將以下查詢貼到查詢編輯器中，也建議你親手輸入以下查詢；在這個過程中，你將了解查詢編輯器的能力：

{
  genesisBlock {
    hash
    size
    total
    numberTxs
    transactions {
      data {
        hash
        total
        inputs {
          data {
            account
            value
          }
        }
        outputs {
          data {
            account
            value
          }
        }
      }
    }
  }
}

這個查詢在 genesisBlock 查詢型別中加入了交易相關欄位；若要進一步了解 Bitcoin 交易資料格式，請見此處。執行查詢後，你會得到以下結果：

{
  "data": {
    "genesisBlock": {
      "transactions": {
        "data": [
          {
            "total": 5000000000,
            "outputs": {
              "data": [
                {
                  "value": 5000000000,
                  "account": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
                }
              ]
            },
            "inputs": {
              "data": [
                {
                  "value": 0,
                  "account": null
                }
              ]
            },
            "hash": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"
          }
        ]
      },
      "total": 0,
      "size": 285,
      "numberTxs": 1,
      "hash": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
    }
  }
}

從資料可以看出，創世區塊中只有1筆交易，該交易向地址為 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa 的帳戶發送了50枚 Bitcoin。這50枚 Bitcoin 是 Nakamoto 花掉的嗎？

我們可以使用 OCAP Playground 中的 transactionsByAddress 查詢型別進一步深入探究。

使用 OCAP Playground 的表格檢視

現在可以大膽假設 Nakamoto 的 Bitcoin 地址是 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa。自創世區塊以來，這個地址是否發送或接收了更多交易？這些交易轉移了多少金額？

我們可以使用以下查詢來查看 Nakamoto 帳戶的交易：

{
  transactionsByAddress(sender: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa") {
	data {
      hash
      total
    }
  }
}

結果如下：

{
  "data": {
    "transactionsByAddress": {
      "data": []
    }
  }
}

顯然，創世區塊中建立的 Bitcoin 從未被動用。有人向這個帳戶發送過 Bitcoin 嗎？我們可以用以下查詢回答這個問題：

{
  transactionsByAddress(receiver: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa") {
	data {
      hash
      total
    }
    page {
      cursor
      total
      next
    }
  }
}

由於單一地址可能包含許多筆交易，OCAP 服務會將大型資料集分頁，以提升效能；我們可以使用查詢中的 page.total 欄位取得交易總數。

{
  "data": {
    "transactionsByAddress": {
      "page": {
        "total": 1252,
        "next": true,
        "cursor": "pU7180SPAj6PCYTB1r%2BCHg%3D%3D"
      },
      "data": [
        {
          "total": 2267721,
          "hash": "256add784c8975fb357010b1b21539a5e55c25af231870616675ff757c5a64f5"
        },
        ...
      ]
    }
  }
}

Nakamoto 的帳戶收到1252筆交易；如果你願意，可以查看每筆交易的發送者和金額。

為了提供更好的查詢結果預覽，OCAP Playground 會偵測結果是否為清單型別資料，並將其呈現為表格：

同時，為了讓開發者更好地理解資料，我們在表格顯示欄位值時做了大量工作：

如果查詢結果包含巢狀資料，例如 transaction inputs 和 transaction outputs，或一個 block 中的多筆 transactions，表格檢視也能正確將其視覺化。想試試看嗎？你可以執行下一節中的查詢，並在表格檢視中查看呈現結果。

使用 OCAP Playground 的圖表檢視

一圖勝千言，ArcBlock 的工程師投入了大量工作，以正確呈現區塊鏈資料視覺化。以下面的查詢為例：

{
  transactionsByAddress(receiver: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa") {
    data {
      hash
      total
      inputs {
        data {
          account
          value
        }
      }
      outputs {
        data {
          account
          value
        }
      }
    }
    page {
      cursor
      total
      next
    }
  }
}

這個查詢會回傳所有發送到帳戶 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa 的交易。因為 Bitcoin 網路天生是分散式的，所以可以使用桑基圖將網路中的資金流動視覺化。我們把帳戶視為網路中的節點，把交易視為節點之間的資料流；在結果檢視器中切換到 chart view，並在圖表類型中選擇 sankey，就會得到以下視覺化結果：

可以看出，所有交易的金額都非常小，這很可能是區塊鏈社群在向 Nakamoto 捐款。

如果你在使用 sankey 圖表時遇到任何有趣的視覺化結果，請與我分享。

OCAP Playground 支援的更多查詢

以上所有範例從頭到尾都在談 Bitcoin，那麼多區塊鏈支援呢？如果你閱讀本文時確實親自使用了 OCAP Playground，一定已經發現如何在不同區塊鏈之間切換：Playground 支援以分頁形式建立多個查詢，每個分頁可以選擇不同的區塊鏈；你可以使用分頁左上角的下拉按鈕切換區塊鏈。

不同鏈所支援的查詢幾乎完全相同。例如，Ethereum 和 Bitcoin 都支援以下查詢型別，但資料結構可能略有不同。

代幣是 Ethereum 生態系統的重要組成部分，也在 Ethereum 區塊鏈上產生了大量資料。OCAP 服務也支援透過查詢型別 [transactionsByToken](https://ocap.arcblock.io/doc/ethereum/#transactionsbytoken) 依代幣查詢交易，很方便吧？

如果使用 OCAP Playground 時遇到問題怎麼辦？OCAP 服務會在後端和前端記錄每個例外。如果發現任何錯誤，我們會儘快修復。

還有一件事

對 Playground 的改進有任何建議嗎？請將建議寄給我：shijun@arcblock.io

區塊鏈時代的序幕已經拉開。我相信，在區塊鏈技術走向成熟和大規模普及的過程中，每位開發者都能發揮作用。與其站在一旁觀望，不如直接投入並做些事情。