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

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

このガイドでは、Universal Ledger CLI の使用を開始する方法について説明します。学習内容:

  • Universal Ledger CLI を取得して設定します。

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

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

始める前に

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

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

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

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

CLI を設定する

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

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

Cloud Shell をアクティブにする

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

mkdir -p ~/.config/ul-cli

イメージを pull してエイリアスを構成する

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

docker pull \
    us-central1-docker.pkg.dev/universal-ledger-artifacts/release/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/release/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: ユーザー アカウントが残高から別のユーザー アカウントに金額を転送する場合。

次のステップ