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

  • Crea y administra cuentas con la CLI.

  • Explora otros comandos disponibles en la CLI.

Antes de comenzar

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

  • Un proyecto de Google Cloud 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 Cómo solicitar una cuenta nueva.

Configura la CLI

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 quieres usar la CLI en un entorno diferente.

En la consola de Google Cloud , 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

Extrae la imagen y configura el alias

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

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

Configura la ul-cli

Ejecuta el siguiente comando para configurar la CLI.

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

Reemplaza lo siguiente:

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

Si necesitas ayuda para elegir un extremo adecuado, consulta Redes y ubicaciones de Universal Ledger.

Este comando crea el archivo de configuración de la CLI en ~/.config/ul-cli/config.yaml (en Linux y macOS).

Administra las 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 la CLI usa 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 Recupera el ID de un recurso para conocer 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.

Crear 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 la CLI usa 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 relevante 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 que el Universal Ledger no interpreta de otra manera. Una vez creado, este campo es inmutable y lo puede leer cualquier persona con acceso a la red.
  • NEW_ACCOUNT_ROLES: Es una lista separada por comas de roles que se asignarán 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 con anterioridad con la CLI.

Esto firmará y enviará una transacción 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 puedes crear.

Crea una cuenta nueva para otra persona

Para crear una cuenta para otra persona, pídele que comparta contigo su clave pública y que 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 el 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 la CLI usa 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 puedes firmar ni enviar transacciones.
  • NEW_ACCOUNT_COMMENT: Es una cadena con cualquier información relevante 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 que el Universal Ledger no interpreta de otra manera. Una vez creado, este campo es inmutable y lo puede leer cualquier persona con acceso a la red.
  • NEW_ACCOUNT_ROLES: Es una lista separada por comas de roles que se asignarán 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 con anterioridad con la CLI.

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

Las marcas --public-key y --key-format están disponibles para todos los subcomandos de accounts create, por lo que también puedes usarlas para crear otros tipos de cuentas. Para conocer los formatos de clave pública compatibles alternativos, 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 y, además, 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 cree o destruya 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?