设置 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-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest
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-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest"
ul-cli --help

运行以下命令以配置 CLI。

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

替换以下内容：

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

如果您需要帮助选择合适的端点，请参阅 可用网络和区域。

上一个命令会在以下路径下创建一个文件

~/.config/ul-cli/config.yaml

其中包含 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 编码格式的密钥。例如，如果对方的签名密钥使用 P-256 椭圆曲线和 SHA256 摘要，请将其保存在名为 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 子命令，因此您也可以使用它们来创建其他类型的账号。如需了解其他受支持的公钥格式，请参阅 KeyFormat 中的 KeyFormat。

列出客户账号

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

ul-cli accounts list

探索其他命令

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

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

ul-cli --help

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

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

后续步骤