部署可程式化合約

通用帳本支援可程式化合約，可在網路中部署，自動執行並強制執行相關參與者之間的協議。

本教學課程將向開發人員說明，如何在通用帳本網路中開發、部署可程式化合約，並與之互動。

事前準備

如要完成本教學課程，您需要：

  • 在 Google Cloud 控制台中啟用 Cloud Shell。

    啟用 Cloud Shell

  • 具有 ROLE_CONTRACT_CREATOR 的 Universal Ledger 使用者帳戶。這個帳戶將成為合約擁有者。

  • 一或多個具有 ROLE_CONTRACT_PARTICIPANT 的通用帳本使用者帳戶。可以與合約擁有者使用同一帳戶。

  • (選用) 設定 Universal Ledger CLI，代表這些使用者帳戶簽署及提交交易。

帳戶管理員建立使用者帳戶時，可以指派通用帳本角色。提交 CreateAccount 交易時，或帳戶已存在時，都可以透過 AddRoles 交易修改角色。如要進行實驗，您也可以使用 Universal Ledger CLI 管理帳戶。

設定環境

為簡化設定，本教學課程是針對 Cloud Shell 工作階段提供的預設環境編寫。如果您使用其他環境，可能需要修改這些指令。

gculpyc 編譯器會採用以 GCULpy 語言編寫的原始碼，並產生 Universal Ledger 的位元碼。

執行下列各項指令，即可提取 gculpyc Docker 映像檔、定義執行二進位檔的別名，並確認二進位檔是否正常運作。

docker pull us-docker.pkg.dev/gcul-artifacts/images/client/gculpyc:preview
alias gculpyc="docker run --rm -i --user $(id -u):$(id -g) \
    --volume .:/workspace --workdir /workspace \
    us-docker.pkg.dev/gcul-artifacts/images/client/gculpyc:preview"
gculpyc --help

撰寫合約

GCULpy 是用來為通用帳本編寫合約的語言。這是 Python 的靜態型別子集，專為清楚、可稽核且容易理解的合約邏輯而設計。這項設計的優先考量是編寫安全程式碼，並限制非預期或不安全的行為。詳情請參閱 GCULpy 語言參考資料。

由於 GCULpy 是 Python 的嚴格子集，因此您可以繼續使用偏好的整合式開發環境 (IDE)，以及現有的工作流程和開發做法。

舉例來說，您的程式碼可能如下所示：

import gcul

class Counter(gcul.Contract):
    """Example contract implementing a counter."""

    value: int

    def increment(self) -> None:
        """Increments the counter value by 1."""
        self.value += 1

複製這個程式碼範例，並儲存至名為 counter.py 的檔案。

在本機測試

不久後，開發人員就能使用本機模擬環境。這個函式庫是 gcul Python 模組的一部分，可提供必要功能，在 Python 環境中原生模擬通用帳本網路。因此，您可以使用偏好的測試架構在本機執行合約並編寫單元測試，確保合約的可靠性和正確性，再進行部署。

編譯合約

使用下列 gculpyc 指令，將上述合約原始碼編譯為位元碼：

gculpyc --source_file counter.py --output_file counter.bin

部署合約

將合約部署至通用帳本網路，方法是提交由持有 ROLE_CONTRACT_CREATOR 的使用者帳戶簽署的 CreateContract 交易。

如果使用 Universal Ledger CLI，可以執行下列指令：

ul-cli contracts create \
    --alias counter-contract \
    --sender OWNER_ALIAS \
    counter.bin

更改下列內容：

  • OWNER_ALIAS：使用者帳戶的別名，包含 ROLE_CONTRACT_CREATOR。

交易完成後，這項指令的輸出內容會包含新部署合約的 ID。例如：

Contract created: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10

叫用合約方法

合約部署完成後，任何具有 ROLE_CONTRACT_PARTICIPANT 的使用者帳戶都可以提交 InvokeContractMethod 交易，叫用合約中的任何公開方法。

如果使用 Universal Ledger CLI，可以執行下列指令：

ul-cli contracts invoke \
    --alias counter-contract \
    --method-name increment \
    --sender PARTICIPANT_ALIAS

更改下列內容：

  • PARTICIPANT_ALIAS：使用者帳戶的別名，包含 ROLE_CONTRACT_PARTICIPANT。

讀取合約狀態

如要結束本教學課程，您可以提交 QueryAccount 要求，讀取並驗證儲存在帳本中的合約狀態。這個 API 方法與查詢及擷取任何通用帳本帳戶詳細資料的方法相同。

使用 Universal Ledger CLI，您可以執行下列操作：

ul-cli accounts describe --alias counter-contract

這應該會確認計數器值現在設為 1，並產生類似下列的輸出內容：

Account: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10
Contract account details:
  Owner: 1:USR:XCL:022uF6cVkTJBaa6pViqTuYqP4455jnRbRc4bWannZGg0b
  Contract fields:
    value: int64_value:1

  Balances:
    None

後續步驟