部署可程式化合約

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

本教學課程說明開發人員在 Universal Ledger 網路中，開發、部署及與可程式化合約互動的必要步驟。

事前準備

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

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

    啟用 Cloud Shell

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

  • 一或多個具備 ROLE_CONTRACT_PARTICIPANT 的 Universal Ledger 使用者帳戶。可以與合約擁有者使用相同帳戶。

  • 您也可以設定 Universal Ledger CLI，代表這些使用者帳戶簽署及提交交易。

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

設定環境

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

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

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

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

撰寫合約

GCULpy 是用於編寫 Universal Ledger 合約的語言。Vyper 是 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 環境中原生模擬 Universal Ledger 網路。因此，您可以在本機執行合約，並使用偏好的測試架構編寫單元測試，確保合約在部署前可靠且正確。

編譯合約

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

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

部署合約

提交由持有 ROLE_CONTRACT_CREATOR 的使用者帳戶簽署的 CreateContract 交易，將合約部署至 Universal Ledger 網路。

如果使用 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 帳戶詳細資料的方法相同。

您可以使用 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

後續步驟