Configurer la CLI Universal Ledger

La CLI Universal Ledger est une interface de ligne de commande fournie à des fins d'expérimentation 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 faire vos premiers pas avec 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.

  • Découvrez 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 la CLI 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 destiné à contenir les fichiers de configuration de la CLI.

mkdir -p ~/.config/ul-cli

Extraire l'image et configurer l'alias

Exécutez chacune des commandes suivantes pour extraire l'image Docker ul-cli, définir un alias pour l'exécution du binaire et vérifier que le binaire fonctionne :

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

Configurer ul-cli

Exécutez la commande suivante pour configurer la CLI.

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 approprié, consultez Réseaux et emplacements Universal Ledger.

Cette commande crée le fichier de configuration de la CLI à l'emplacement ~/.config/ul-cli/config.yaml (sous Linux et macOS).

Gérer les comptes Universal Ledger

Cette section explique comment enregistrer un compte existant, créer un compte pour vous-même dans le registre 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 détails 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 des futurs appels de commande. 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. Consultez Récupérer l'ID d'une ressource pour connaître le format attendu.

Il s'agit d'une opération locale qui enregistre les détails du compte dans le fichier de configuration de la CLI, ce qui vous permet de signer et d'envoyer des requêtes au registre 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 des futurs appels de commande.
  • 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 registre associé au nouveau compte utilisateur. Il s'agit d'une valeur opaque stockée dans le registre, mais qui n'est pas interprétée autrement par le Universal Ledger. 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.

Cette opération signe et envoie 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 quelqu'un d'autre, demandez-lui de partager sa clé publique avec vous et stockez-la dans un fichier. Il est généralement recommandé d'utiliser le format d'encodage PEM pour les clés. Par exemple, si sa clé de signature utilise la courbe elliptique P-256 avec un 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 des futurs appels de commande. Notez toutefois que, comme vous ne disposez pas de sa clé privée, vous ne pouvez pas signer ni envoyer de transactions.
  • NEW_ACCOUNT_COMMENT : chaîne contenant toutes les informations pertinentes à enregistrer dans le registre associé au nouveau compte utilisateur. Il s'agit d'une valeur opaque stockée dans le registre, mais qui n'est pas interprétée autrement par le Universal Ledger. 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.

Cette opération signe et envoie une transaction CreateAccount au nom du responsable de compte donné.

Les options --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é publique 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 la CLI 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 dans la CLI Universal Ledger.

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

ul-cli --help

Cela inclut des sous-commandes permettant d'envoyer d'autres types de transactions, par exemple :

  • accounts : pour enregistrer ou créer des comptes, et effectuer des opérations de gestion sur des comptes existants, telles que l'ajout ou la suppression de rôles, et l'interrogation des détails du compte.
  • 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 pour effectuer des opérations de règlement.
  • tokens : pour qu'un gestionnaire de jetons puisse créer ou détruire 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