ユニバーサル台帳 CLI を設定する

Universal Ledger CLI は、トランザクションの送信と Universal Ledger ネットワークの操作を容易にするために、試験運用を目的として提供されるコマンドライン インターフェースです。本番環境のユースケースでは、代わりに Universal Ledger API を使用して統合を構築することをおすすめします。

このガイドでは、ユニバーサル台帳 CLI の使用を開始する方法について説明します。学習内容:

  • ユニバーサル台帳 CLI を取得して設定します。

  • CLI を使用してアカウントを作成、管理する。

  • CLI で使用可能な他のコマンドを確認する。

始める前に

このガイドを完了するには、次のものが必要です。

  • Universal Ledger API が有効になっている Google Cloud プロジェクト。

  • roles/universalledger.networkUser などの IAM ロール。これにより、Universal Ledger ネットワークでトランザクションを送信し、アカウントの状態をクエリできます。

  • ネットワーク上に作成された既存のユニバーサル台帳アカウント。まだお持ちでない場合は、新しいアカウントをリクエストするをご覧ください。

CLI を設定する

設定を簡素化するため、このガイドは Cloud Shell セッションで提供されるデフォルト環境を対象に作成されています。別の環境で CLI を使用する場合は、これらのコマンドの変更が必要になることがあります。

Google Cloud コンソールで Cloud Shell をアクティブにします。

Cloud Shell をアクティブにする

次のコマンドを実行して、CLI 構成ファイルを保持するディレクトリを作成します。

mkdir -p ~/.config/ul-cli

次の各コマンドを実行して、ul-cli Docker イメージを pull し、バイナリを実行するエイリアスを定義して、バイナリが動作することを確認します。

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 で使用および管理される構成。

ユニバーサル台帳アカウントを管理する

このセクションでは、既存のアカウントを登録する方法、台帳で自分用の新しいアカウントを作成する方法、他のユーザー用の新しいアカウントを作成する方法について説明します。

既存のアカウントを登録する

ネットワークの別の参加者がアカウントを作成したら、次のコマンドを使用して、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: 作成されたユニバーサル台帳アカウントの 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: 新しいユーザー アカウントに関連付けられた台帳に記録する関連情報を含む文字列。これは台帳に保存される不透明な値ですが、ユニバーサル台帳では解釈されません。作成後は変更できず、ネットワークにアクセスできるユーザーは誰でも読み取ることができます。
  • 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: 新しいユーザー アカウントに関連付けられた台帳に記録する関連情報を含む文字列。これは台帳に保存される不透明な値ですが、ユニバーサル台帳では解釈されません。作成後は変更できず、ネットワークにアクセスできるユーザーは誰でも読み取ることができます。
  • NEW_ACCOUNT_ROLES: 新しいユーザー アカウントに割り当てるロールのカンマ区切りリスト。例: payer、receiver、contract-creator、contract-participant。
  • ACCOUNT_MANAGER_ALIAS: 以前に登録されたか、CLI で作成されたアカウント マネージャーのエイリアス。

これにより、指定されたアカウント マネージャーに代わって CreateAccount トランザクションが署名されて送信されます。

--public-key フラグと --key-format フラグはすべての accounts create サブコマンドで使用できるため、これらを使用して他の種類のアカウントを作成することもできます。サポートされている代替の公開鍵形式については、ユニバーサル台帳 API リファレンスの KeyFormat をご覧ください。

管理対象アカウントの一覧を取得する

次のコマンドを実行して、Universal Ledger CLI でローカルに登録または作成されたすべてのアカウントを表示します。

ul-cli accounts list

他のコマンドを確認する

--help フラグを使用して、Universal Ledger CLI で使用可能な他のすべてのコマンドとサブコマンドを確認します。

たとえば、使用可能な最上位コマンドを表示するには、次のコマンドを実行します。

ul-cli --help

これには、次のような他の種類のトランザクションを送信するサブコマンドが含まれます。

  • accounts: アカウントの登録または作成、既存のアカウントに対する管理オペレーション（ロールの追加や削除、アカウントの詳細のクエリなど）の実行。
  • contracts: プログラマブル コントラクトでメソッドをデプロイ、権限付与、呼び出しを行う。
  • issuance: 清算機関がトークン マネージャーの発行上限を増減させ、決済オペレーションを実行できるようにします。
  • tokens: トークン マネージャーがユーザー アカウントでトークンを生成または破棄できるようにします。
  • wallet: ユーザー アカウントが残高から別のユーザー アカウントに金額を転送する場合。

次のステップ