部署可编程合约

实验性：可编程合约是 Universal Ledger 的一项实验性功能。gculpyc 编译器正在积极开发中，以添加新功能并改进功能。因此，编译器生成的二进制文件可能会因所用版本而异。已部署的合约在重大更新后也可能会有不同的行为。如需了解有关此类变更的通知和指南，请参阅 GCULpy 语言参考文档中的版本说明。

Universal Ledger 支持可编程合约，这些合约可以部署在网络中，以自动执行和强制执行相关参与者之间的协议。

本教程向开发者展示了在 Universal Ledger 网络中开发、部署可编程合约并与之交互所需的步骤。

准备工作

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

• 在 Google Cloud 控制台中，激活 Cloud Shell。

  激活 Cloud Shell

• 拥有 ROLE_CONTRACT_CREATOR 的 Universal Ledger 用户账号。此账号将成为合同所有者。

• 一个或多个具有 ROLE_CONTRACT_PARTICIPANT 的 Universal Ledger 用户账号。它可以与合同所有者使用同一账号。

• （可选）设置 Universal Ledger CLI，以便能够代表这些用户账号签署和提交交易。

Universal Ledger 角色可在用户账号创建时由其客户经理分配，具体是在提交 CreateAccount 交易时分配，或者如果账号已存在，则可在之后通过 AddRoles 交易进行修改。出于实验目的，您还可以使用 Universal Ledger CLI 管理账号。

设置环境

为简化设置，本教程是针对 Cloud Shell 会话中提供的默认环境编写的。如果您使用的是其他环境，则可能需要修改这些命令。

实验性：gculpyc 二进制文件（以 Docker 映像的形式提供）正在积极开发中，可能会在产品的新版本中发生变化或被移除。

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 编写合约的语言。它是 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

后续步骤

• 探索 GCULpy 语言参考文档。
• 了解您可以提交到网络的其他交易。