Configura la CLI de Universal Ledger

La CLI de Universal Ledger es una interfaz de línea de comandos que se proporciona con fines de experimentación para facilitar el envío de transacciones y la interacción con una red de Universal Ledger. Para los casos de uso de producción, se recomienda compilar integraciones con las APIs de Universal Ledger.

En esta guía, se describe cómo comenzar a usar la CLI de Universal Ledger. Aprenderás a realizar estas tareas:

  • Obtener y configurar la CLI de Universal Ledger

  • Crear y administrar cuentas con la CLI

  • Explorar otros comandos disponibles en la CLI

Antes de comenzar

Para completar esta guía, necesitarás lo siguiente:

  • Un Google Cloud proyecto con la API de Universal Ledger habilitada

  • Un rol de IAM, como roles/universalledger.networkUser, para que puedas enviar transacciones y consultar el estado de las cuentas en una red de Universal Ledger

  • Una cuenta de Universal Ledger existente creada para ti en la red Si aún no tienes una, consulta Solicita una cuenta nueva.

Configura la CLI de

Para simplificar la configuración, esta guía se escribió para el entorno predeterminado que se proporciona en una sesión de Cloud Shell. Es posible que debas modificar estos comandos si deseas usar la CLI en un entorno diferente.

En la Google Cloud consola, activa Cloud Shell.

Activa Cloud Shell

Ejecuta el siguiente comando para crear un directorio que contenga los archivos de configuración de la CLI.

mkdir -p ~/.config/ul-cli

Ejecuta cada uno de los siguientes comandos para extraer la imagen de Docker ul-cli, definir un alias para ejecutar el objeto binario y confirmar que funciona.

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

Ejecuta el siguiente comando para configurar la CLI de :

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del Google Cloud proyecto en el que está habilitada la API de Universal Ledger.
  • REGION: Es la región del extremo al que deseas llegar.
  • NETWORK_NAME: Es el nombre de la red con la que deseas interactuar.

Si necesitas ayuda para elegir un extremo adecuado, consulta Redes y regiones disponibles.

El comando anterior creará un archivo en

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

con la configuración que usará y mantendrá la CLI.

Administra cuentas de Universal Ledger

En esta sección, se explica cómo registrar una cuenta existente, crear una cuenta nueva para ti en el libro mayor y crear cuentas nuevas para otra persona.

Registra una cuenta existente

Una vez que otro participante de la red haya creado una cuenta para ti, puedes usar el siguiente comando para registrar los detalles de la cuenta en la libreta de direcciones de la CLI.

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

Reemplaza lo siguiente:

  • ACCOUNT_ALIAS: Es una cadena corta que usa la CLI de forma local para identificar esta cuenta en invocaciones de comandos futuras. Por ejemplo: usd-operator, my-token-manager o test-user-account.
  • ACCOUNT_ID: Es el ID de la cuenta de Universal Ledger que se creó para ti.
  • ACCOUNT_KMS_KEY: Es el ID de recurso completo de la versión de clave de Cloud KMS que usa esta cuenta. La cuenta debe haberse creado con la parte pública de esta versión de clave específica. Consulta Cómo recuperar el ID de un recurso para obtener el formato esperado.

Esta es una operación local que registrará los detalles de la cuenta en el archivo de configuración de la CLI, lo que te permitirá firmar y enviar solicitudes al libro mayor en nombre de esta cuenta.

Crea una cuenta nueva para ti

Se pueden crear cuentas nuevas con el subcomando ul-cli accounts create. Por ejemplo, para crear una cuenta de usuario nueva, puedes usar lo siguiente:

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

Reemplaza lo siguiente:

  • NEW_ACCOUNT_ALIAS: Es una cadena corta que usa la CLI de forma local para identificar esta cuenta en invocaciones de comandos futuras.
  • NEW_ACCOUNT_KMS_KEY: Es el ID de recurso completo de la versión de clave de Cloud KMS que usará la cuenta de usuario nueva.
  • NEW_ACCOUNT_COMMENT: Es una cadena con cualquier información pertinente para registrar en el libro mayor asociado con la cuenta de usuario nueva. Este es un valor opaco que se almacena en el libro mayor, pero Universal Ledger no lo interpreta de otra manera. Una vez creado, este campo es inmutable y cualquier persona con acceso a la red puede leerlo.
  • NEW_ACCOUNT_ROLES: Es una lista separada por comas de la función que se asignará a la cuenta de usuario nueva. Por ejemplo: payer, receiver, contract-creator o contract-participant.
  • ACCOUNT_MANAGER_ALIAS: Es el alias de un administrador de cuentas registrado o creado anteriormente con la CLI.

Esto firmará y enviará una CreateAccount en nombre del administrador de cuentas determinado.

Ejecuta ul-cli accounts create --help para ver las opciones disponibles para otros tipos de cuentas que se pueden crear.

Crea una cuenta nueva para otra persona

Para crear una cuenta para otra persona, pídele que comparta su clave pública contigo y la almacene en un archivo. Por lo general, se recomienda usar el formato de codificación PEM para las claves. Por ejemplo, si su clave de firma usa la curva elíptica P-256 con resumen SHA256, guárdala en un archivo llamado pem_ec_p256_sha256.pub:

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

Luego, ejecuta el siguiente comando para crear la cuenta:

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

Reemplaza lo siguiente:

  • NEW_ACCOUNT_ALIAS: Es una cadena corta que usa la CLI de forma local para identificar esta cuenta en invocaciones de comandos futuras. Sin embargo, ten en cuenta que, como no tienes su clave privada, no podrás firmar ni enviar transacciones.
  • NEW_ACCOUNT_COMMENT: Es una cadena con cualquier información pertinente para registrar en el libro mayor asociado con la cuenta de usuario nueva. Este es un valor opaco que se almacena en el libro mayor, pero Universal Ledger no lo interpreta de otra manera. Una vez creado, este campo es inmutable y cualquier persona con acceso a la red puede leerlo.
  • NEW_ACCOUNT_ROLES: Es una lista separada por comas de la función que se asignará a la cuenta de usuario nueva. Por ejemplo: payer, receiver, contract-creator o contract-participant.
  • ACCOUNT_MANAGER_ALIAS: Es el alias de un administrador de cuentas registrado o creado anteriormente con la CLI.

Esto firmará y enviará una CreateAccount en nombre del administrador de cuentas determinado.

Las marcas --public-key y --key-format están disponibles para todos los subcomandos accounts create, por lo que también puedes usarlas para crear otros tipos de cuentas. Para obtener formatos de clave pública alternativos compatibles, consulta KeyFormat en la referencia de la API de Universal Ledger.

Enumera las cuentas administradas

Ejecuta el siguiente comando para ver todas las cuentas registradas o creadas de forma local con la CLI de Universal Ledger:

ul-cli accounts list

Explora otros comandos

Usa la marca --help para explorar todos los demás comandos y subcomandos disponibles en la CLI de Universal Ledger.

Por ejemplo, para ver los comandos de nivel superior disponibles, ejecuta lo siguiente:

ul-cli --help

Esto incluye subcomandos para enviar otros tipos de transacciones, como los siguientes:

  • accounts: Para registrar o crear cuentas, y realizar operaciones de administración en cuentas existentes, como agregar o quitar roles, y consultar detalles de la cuenta
  • contracts: Para implementar, otorgar permisos e invocar métodos en contratos programables
  • issuance: Para que una cámara de compensación aumente o disminuya el límite de emisión de un administrador de tokens y realice operaciones de liquidación
  • tokens: Para que un administrador de tokens acuñe o queme tokens en una cuenta de usuario
  • wallet: Para que una cuenta de usuario transfiera un importe de su saldo a otra cuenta de usuario

¿Qué sigue?