设置 Universal Ledger CLI

Universal Ledger CLI 是一个命令行界面，用于实验目的，以便于提交交易和与 Universal Ledger 网络交互。对于生产用例，建议改用 Universal Ledger API 构建集成。

本指南介绍了如何开始使用 Universal Ledger CLI。 了解如何：

  • 获取并设置 Universal Ledger CLI。

  • 使用 CLI 创建和管理账号。

  • 探索 CLI 中提供的其他命令。

准备工作

如需完成本指南，您需要以下各项：

  • 一个启用了 Universal Ledger API 的 Google Cloud 项目。

  • IAM 角色（例如 roles/universalledger.networkUser），以便您可以在 Universal Ledger 网络中提交交易和查询账号状态。

  • 在网络上为您创建的现有 Universal Ledger 账号。 如果您还没有账号，请参阅申请新账号。

设置 CLI

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

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

激活 Cloud Shell

运行以下命令，创建一个用于保存 CLI 配置文件的目录。

mkdir -p ~/.config/ul-cli

拉取映像并配置别名

运行以下每个命令，以拉取 ul-cli Docker 映像，定义用于运行二进制文件的别名，并确认二进制文件正常运行：

docker pull us-central1-docker.pkg.dev/universal-ledger-artifacts/images/client/ul-cli:stable
alias ul-cli="docker run --rm -i --user $(id -u):$(id -g) \
    --volume /tmp:/tmp \
    --volume ~/.config/ul-cli:/home/.config/ul-cli \
    --volume ~/.config/gcloud:/home/.config/gcloud \
    --volume .:/workspace \
    --env HOME=/home \
    --workdir /workspace \
    us-central1-docker.pkg.dev/universal-ledger-artifacts/images/client/ul-cli:stable"
ul-cli --help

配置 ul-cli

运行以下命令以配置 CLI。

ul-cli config setup projects/PROJECT_ID/locations/REGION/endpoints/NETWORK_NAME

替换以下内容：

  • PROJECT_ID：已启用 Universal Ledger API 的 Google Cloud 项目的 ID。
  • REGION：您要访问的端点所在的区域。
  • NETWORK_NAME：您要与之交互的网络的名称。

如果您在选择合适的端点时需要帮助，请参阅Universal Ledger 网络和位置。

此命令会在 ~/.config/ul-cli/config.yaml（在 Linux 和 macOS 上）创建 CLI 配置文件。

管理 Universal Ledger 账号

本部分介绍了如何注册现有账号、在账本上为自己创建新账号，以及为其他人创建新账号。

注册现有账号

当网络上的其他参与者为您创建账号后，您可以使用以下命令在 CLI 的通讯簿中注册账号详细信息。

ul-cli accounts register \
    --alias ACCOUNT_ALIAS \
    --account-id ACCOUNT_ID \
    --key-name ACCOUNT_KMS_KEY

替换以下内容：

  • ACCOUNT_ALIAS：CLI 在本地使用的短字符串，用于在未来的命令调用中标识此账号。例如：usd-operator、my-token-manager 或 test-user-account。
  • ACCOUNT_ID：为您创建的 Universal Ledger 账号的 ID。
  • ACCOUNT_KMS_KEY：此账号使用的 Cloud KMS 密钥版本的完整资源 ID。该账号必须是使用此特定密钥版本的公开部分创建的。如需了解预期格式，请参阅检索资源的 ID。

这是一项本地操作，会在 CLI 配置文件中记录账号详细信息，以便您代表此账号签署请求并将其提交到账本。

为您创建新账号

您可以使用 ul-cli accounts create 子命令创建新账号。例如，如需创建新的用户账号，您可以使用：

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --key-name NEW_ACCOUNT_KMS_KEY \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

替换以下内容：

  • NEW_ACCOUNT_ALIAS：CLI 在本地使用的短字符串，用于在未来的命令调用中标识此账号。
  • NEW_ACCOUNT_KMS_KEY：新用户账号要使用的 Cloud KMS 密钥版本的完整资源 ID。
  • NEW_ACCOUNT_COMMENT：一个字符串，包含要记录在与新用户账号关联的账本上的任何相关信息。这是一个不透明的值，存储在账本中，但不会被 Universal Ledger 以其他方式解读。创建后，此字段不可变，任何有权访问网络的人都可以读取。
  • NEW_ACCOUNT_ROLES：要分配给新用户账号的角色的英文逗号分隔列表。例如：payer、receiver、contract-creator 或 contract-participant。
  • ACCOUNT_MANAGER_ALIAS：之前使用 CLI 注册或创建的客户经理的别名。

这将代表指定的账号管理员签署并提交 CreateAccount 交易。

运行 ul-cli accounts create --help，查看可创建的其他类型账号的可用选项。

为他人创建新账号

如需为其他人创建账号，请让他们与您分享其公钥并将其存储在文件中。通常，建议您对密钥使用 PEM 编码格式。例如，如果其签名密钥使用具有 SHA256 摘要的 P-256 椭圆曲线，请将其保存在名为 pem_ec_p256_sha256.pub 的文件中：

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ/vWkd5wgakFbVD25k8WM9Ll6We+
c8RVDS0R4G8xetsmFjfNW/ZxwWeB86IvMjxY8ZsdU9+W7BL5YM6rUB5yCQ==
-----END PUBLIC KEY-----

然后，运行以下命令创建账号：

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --public-key "$(cat pem_ec_p256_sha256.pub)" \
    --key-format pem_ec_p256_sha256 \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

替换以下内容：

  • NEW_ACCOUNT_ALIAS：CLI 在本地使用的短字符串，用于在未来的命令调用中标识此账号。但请注意，由于您没有其私钥，因此无法签署或提交交易。
  • NEW_ACCOUNT_COMMENT：一个字符串，包含要记录在与新用户账号关联的账本上的任何相关信息。这是一个不透明的值，存储在账本中，但不会被 Universal Ledger 以其他方式解读。创建后，此字段不可变，任何有权访问网络的人都可以读取。
  • NEW_ACCOUNT_ROLES：要分配给新用户账号的角色的英文逗号分隔列表。例如：payer、receiver、contract-creator 或 contract-participant。
  • ACCOUNT_MANAGER_ALIAS：之前使用 CLI 注册或创建的客户经理的别名。

这将代表指定的账号管理员签署并提交 CreateAccount 交易。

--public-key 和 --key-format 标志适用于所有 accounts create 子命令，因此您也可以使用它们来创建其他类型的账号。如需了解其他受支持的公钥格式，请参阅 Universal Ledger API 参考文档中的 KeyFormat。

列出客户账号

运行以下命令，查看使用 Universal Ledger CLI 在本地注册或创建的所有账号：

ul-cli accounts list

探索其他命令

使用 --help 标志可探索 Universal Ledger CLI 上提供的所有其他命令和子命令。

例如，如需查看可用的顶级命令，请运行以下命令：

ul-cli --help

这包括用于提交其他类型交易的子命令，例如：

  • accounts：用于注册或创建账号，以及对现有账号执行管理操作，例如添加或移除角色，以及查询账号详细信息。
  • contracts：用于在可编程合约上部署、授予权限和调用方法。
  • issuance：供清算所增加或减少代币管理器的发行限额，以及执行结算操作。
  • tokens：供代币管理者在用户账号中铸造或销毁代币。
  • wallet：供用户账号将其余额中的金额转账到另一个用户账号。

后续步骤