Configurer la CLI Universal Ledger

L'interface de ligne de commande Universal Ledger est fournie à des fins de test pour faciliter l'envoi de transactions et l'interaction avec un réseau Universal Ledger. Pour les cas d'utilisation en production, il est recommandé de créer des intégrations à l'aide des API Universal Ledger.

Ce guide explique comment commencer à utiliser la CLI Universal Ledger. Découvrez comment :

  • Obtenez et configurez la CLI Universal Ledger.

  • Créez et gérez des comptes à l'aide de la CLI.

  • Explorez les autres commandes disponibles dans la CLI.

Avant de commencer

Pour suivre ce guide, vous aurez besoin des éléments suivants :

  • Un projet Google Cloud avec l'API Universal Ledger activée.

  • Un rôle IAM tel que roles/universalledger.networkUser pour pouvoir envoyer des transactions et interroger l'état des comptes dans un réseau Universal Ledger.

  • Un compte Universal Ledger existant créé pour vous sur le réseau. Si vous n'en avez pas encore, consultez Demander un nouveau compte.

Configurer la CLI

Pour simplifier la configuration, ce guide a été rédigé pour l'environnement par défaut fourni dans une session Cloud Shell. Vous devrez peut-être modifier ces commandes si vous souhaitez utiliser lCLI dans un autre environnement.

Dans la console Google Cloud , activez Cloud Shell.

Activer Cloud Shell

Exécutez la commande suivante pour créer un répertoire contenant les fichiers de configuration de la CLI.

mkdir -p ~/.config/ul-cli

Exécutez chacune des commandes suivantes pour extraire l'image Docker ul-cli, définir un alias pour exécuter le binaire et confirmer que le binaire fonctionne.

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

Exécutez la commande suivante pour configurer lCLI.

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud dans lequel l'API Universal Ledger est activée.
  • REGION : région du point de terminaison que vous souhaitez atteindre.
  • NETWORK_NAME : nom du réseau avec lequel vous souhaitez interagir.

Si vous avez besoin d'aide pour choisir un point de terminaison adapté, consultez Régions et réseaux disponibles.

La commande précédente crée un fichier sous

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

avec la configuration qui sera utilisée et gérée par la CLI.

Gérer les comptes Universal Ledger

Cette section explique comment enregistrer un compte existant, créer un compte pour vous-même sur le grand livre et créer des comptes pour quelqu'un d'autre.

Enregistrer un compte existant

Une fois qu'un compte a été créé pour vous par un autre participant du réseau, vous pouvez utiliser la commande suivante pour enregistrer les informations du compte dans le carnet d'adresses de la CLI.

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

Remplacez les éléments suivants :

  • ACCOUNT_ALIAS : chaîne courte utilisée localement par la CLI pour identifier ce compte lors de futures invocations de commandes. Par exemple : usd-operator, my-token-manager ou test-user-account.
  • ACCOUNT_ID : ID du compte Universal Ledger qui a été créé pour vous.
  • ACCOUNT_KMS_KEY : ID de ressource complet de la version de clé Cloud KMS utilisée par ce compte. Le compte doit avoir été créé à l'aide de la partie publique de cette version de clé spécifique. Pour connaître le format attendu, consultez Récupérer l'ID d'une ressource.

Il s'agit d'une opération locale qui enregistre les informations du compte dans le fichier de configuration de CLI de commande. Vous pouvez ainsi signer et envoyer des requêtes au grand livre au nom de ce compte.

Créer un compte pour vous

Vous pouvez créer des comptes à l'aide de la sous-commande ul-cli accounts create. Par exemple, pour créer un compte utilisateur, vous pouvez utiliser :

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

Remplacez les éléments suivants :

  • NEW_ACCOUNT_ALIAS : chaîne courte utilisée localement par la CLI pour identifier ce compte lors de futures invocations de commandes.
  • NEW_ACCOUNT_KMS_KEY : ID de ressource complet de la version de clé Cloud KMS à utiliser par le nouveau compte utilisateur.
  • NEW_ACCOUNT_COMMENT : chaîne contenant toutes les informations pertinentes à enregistrer dans le grand livre associé au nouveau compte utilisateur. Il s'agit d'une valeur opaque stockée dans le grand livre, mais qui n'est pas interprétée par le grand livre universel. Une fois créé, ce champ est immuable et lisible par toute personne ayant accès au réseau.
  • NEW_ACCOUNT_ROLES : liste de rôles séparés par une virgule à attribuer au nouveau compte utilisateur. Par exemple : payer, receiver, contract-creator ou contract-participant.
  • ACCOUNT_MANAGER_ALIAS : alias d'un responsable de compte précédemment enregistré ou créé avec la CLI.

Cela signera et enverra une transaction CreateAccount au nom du responsable de compte indiqué.

Exécutez ul-cli accounts create --help pour afficher les options disponibles pour les autres types de comptes à créer.

Créer un compte pour quelqu'un d'autre

Pour créer un compte pour une autre personne, demandez-lui de partager sa clé publique avec vous et de l'enregistrer dans un fichier. En général, nous vous recommandons d'utiliser le format d'encodage PEM pour les clés. Par exemple, si la clé de signature utilise la courbe elliptique P-256 avec le condensé SHA256, enregistrez-la dans un fichier nommé pem_ec_p256_sha256.pub :

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

Exécutez ensuite la commande suivante pour créer le compte :

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

Remplacez les éléments suivants :

  • NEW_ACCOUNT_ALIAS : chaîne courte utilisée localement par la CLI pour identifier ce compte lors de futures invocations de commandes. Toutefois, comme vous ne disposez pas de sa clé privée, vous ne pourrez pas signer ni envoyer de transactions.
  • NEW_ACCOUNT_COMMENT : chaîne contenant toutes les informations pertinentes à enregistrer dans le grand livre associé au nouveau compte utilisateur. Il s'agit d'une valeur opaque stockée dans le grand livre, mais qui n'est pas interprétée par le grand livre universel. Une fois créé, ce champ est immuable et lisible par toute personne ayant accès au réseau.
  • NEW_ACCOUNT_ROLES : liste de rôles séparés par une virgule à attribuer au nouveau compte utilisateur. Par exemple : payer, receiver, contract-creator ou contract-participant.
  • ACCOUNT_MANAGER_ALIAS : alias d'un responsable de compte précédemment enregistré ou créé avec la CLI.

Cela signera et enverra une transaction CreateAccount au nom du responsable de compte indiqué.

Les indicateurs --public-key et --key-format sont disponibles pour toutes les sous-commandes accounts create. Vous pouvez donc les utiliser pour créer d'autres types de comptes. Pour connaître les autres formats de clés publiques compatibles, consultez KeyFormat dans la documentation de référence de l'API Universal Ledger.

Lister les comptes gérés

Exécutez la commande suivante pour afficher tous les comptes enregistrés ou créés localement avec l'interface de ligne de commande Universal Ledger :

ul-cli accounts list

Découvrir d'autres commandes

Utilisez l'option --help pour explorer toutes les autres commandes et sous-commandes disponibles sur la CLI Universal Ledger.

Par exemple, pour afficher les commandes de premier niveau disponibles, exécutez :

ul-cli --help

Cela inclut les sous-commandes permettant d'envoyer d'autres types de transactions, telles que :

  • accounts : pour enregistrer ou créer des comptes, et effectuer des opérations de gestion sur les comptes existants, comme ajouter ou supprimer des rôles, et interroger les détails des comptes.
  • contracts : pour déployer, accorder des autorisations et appeler des méthodes sur des contrats programmables.
  • issuance : pour qu'une chambre de compensation augmente ou diminue la limite d'émission d'un gestionnaire de jetons et effectue des opérations de règlement.
  • tokens : pour qu'un gestionnaire de jetons puisse émettre ou brûler des jetons sur un compte utilisateur.
  • wallet : pour qu'un compte utilisateur transfère un montant de son solde vers un autre compte utilisateur.

Étapes suivantes