Configurar a CLI do Universal Ledger

A CLI do Universal Ledger é uma interface de linha de comando fornecida para fins de experimentação, facilitando o envio de transações e a interação com uma rede do Universal Ledger. Para casos de uso de produção, recomendamos criar integrações usando as APIs Universal Ledger.

Este guia descreve como começar a usar a CLI do Universal Ledger. Saiba como realizar as seguintes ações:

  • Adquira e configure a CLI do Universal Ledger.

  • Crie e gerencie contas usando a CLI.

  • Confira outros comandos disponíveis na CLI.

Antes de começar

Para concluir este guia, você vai precisar do seguinte:

  • Um projeto do Google Cloud com a API Universal Ledger ativada.

  • Um papel do IAM, como roles/universalledger.networkUser, para que você possa enviar transações e consultar o estado das contas em uma rede de livro razão universal.

  • Uma conta do Universal Ledger criada para você na rede. Se você ainda não tiver uma, consulte Solicitar uma nova conta.

Configurar a CLI

Para simplificar a configuração, este guia foi escrito para o ambiente padrão fornecido em uma sessão do Cloud Shell. Talvez seja necessário modificar esses comandos se você quiser usar a CLI em um ambiente diferente.

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Execute o comando a seguir para criar um diretório que vai armazenar os arquivos de configuração da CLI.

mkdir -p ~/.config/ul-cli

Execute cada um dos comandos a seguir para extrair a imagem Docker ul-cli, definir um alias para executar o binário e confirmar que ele 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

Execute o comando a seguir para configurar a CLI.

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

Substitua:

  • PROJECT_ID: o ID do Google Cloud projeto em que a API Universal Ledger está ativada.
  • REGION: a região do endpoint que você quer alcançar.
  • NETWORK_NAME: o nome da rede com que você quer interagir.

Se precisar de ajuda para escolher um endpoint adequado, consulte Redes e regiões disponíveis.

O comando anterior vai criar um arquivo em

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

com a configuração que será usada e mantida pela CLI.

Gerenciar contas do razão universal

Esta seção explica como registrar uma conta existente, criar uma conta para você no livro-razão e criar contas para outra pessoa.

Registrar uma conta existente

Depois que outro participante da rede criar uma conta para você, use o comando a seguir para registrar os detalhes da conta na agenda da CLI.

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

Substitua:

  • ACCOUNT_ALIAS: uma string curta usada localmente pela CLI para identificar essa conta em invocações de comando futuras. Por exemplo: usd-operator, my-token-manager ou test-user-account.
  • ACCOUNT_ID: o ID da conta do Universal Ledger criada para você.
  • ACCOUNT_KMS_KEY: o ID completo do recurso da versão da chave do Cloud KMS usada por esta conta. A conta precisa ter sido criada usando a parte pública dessa versão de chave específica. Consulte Como recuperar o ID de um recurso para saber o formato esperado.

Essa é uma operação local que registra os detalhes da conta no arquivo de configuração da CLI, permitindo que você assine e envie solicitações ao livro razão em nome dessa conta.

Criar uma nova conta para você

É possível criar novas contas usando o subcomando ul-cli accounts create. Por exemplo, para criar uma conta de novo usuário, use:

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

Substitua:

  • NEW_ACCOUNT_ALIAS: uma string curta usada localmente pela CLI para identificar essa conta em futuras invocações de comando.
  • NEW_ACCOUNT_KMS_KEY: o ID completo do recurso da versão da chave do Cloud KMS a ser usada pela nova conta de usuário.
  • NEW_ACCOUNT_COMMENT: uma string com informações relevantes para registrar no livro-razão associado à nova conta de usuário. Esse é um valor opaco armazenado no livro-razão, mas não interpretado de outra forma pelo Universal Ledger. Depois de criado, esse campo é imutável e pode ser lido por qualquer pessoa com acesso à rede.
  • NEW_ACCOUNT_ROLES: uma lista separada por vírgulas de papéis a serem atribuídos à nova conta de usuário. Por exemplo, payer, receiver, contract-creator ou contract-participant.
  • ACCOUNT_MANAGER_ALIAS: o alias de um gerente de contas registrado ou criado anteriormente com a CLI.

Isso vai assinar e enviar uma transação CreateAccount em nome do gerente de conta especificado.

Execute ul-cli accounts create --help para ver as opções disponíveis para outros tipos de contas.

Criar uma conta para outra pessoa

Para criar uma conta para outra pessoa, peça que ela compartilhe a chave pública com você e armazene em um arquivo. Em geral, recomendamos o uso do formato de codificação PEM para chaves. Por exemplo, se a chave de assinatura usar a curva elíptica P-256 com resumo SHA256, salve-a em um arquivo chamado pem_ec_p256_sha256.pub:

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

Em seguida, execute o comando a seguir para criar a conta:

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

Substitua:

  • NEW_ACCOUNT_ALIAS: uma string curta usada localmente pela CLI para identificar essa conta em futuras invocações de comando. No entanto, como você não tem a chave privada, não é possível assinar nem enviar transações.
  • NEW_ACCOUNT_COMMENT: uma string com informações relevantes para registrar no livro-razão associado à nova conta de usuário. Esse é um valor opaco armazenado no livro-razão, mas não interpretado de outra forma pelo Universal Ledger. Depois de criado, esse campo é imutável e pode ser lido por qualquer pessoa com acesso à rede.
  • NEW_ACCOUNT_ROLES: uma lista separada por vírgulas de papéis a serem atribuídos à nova conta de usuário. Por exemplo, payer, receiver, contract-creator ou contract-participant.
  • ACCOUNT_MANAGER_ALIAS: o alias de um gerente de contas registrado ou criado anteriormente com a CLI.

Isso vai assinar e enviar uma transação CreateAccount em nome do gerente de conta especificado.

As flags --public-key e --key-format estão disponíveis para todos os subcomandos accounts create. Portanto, é possível usá-las para criar outros tipos de contas também. Para outros formatos de chave pública compatíveis, consulte KeyFormat na referência da API Universal Ledger.

Listar contas gerenciadas

Execute o comando a seguir para conferir todas as contas registradas localmente ou criadas com a CLI do Universal Ledger:

ul-cli accounts list

Conheça outros comandos

Use a flag --help para conferir todos os outros comandos e subcomandos disponíveis na CLI do Universal Ledger.

Por exemplo, para conferir os comandos de nível superior disponíveis, execute:

ul-cli --help

Isso inclui subcomandos para enviar outros tipos de transações, como:

  • accounts: para registrar ou criar contas e realizar operações de gerenciamento em contas existentes, como adicionar ou remover papéis e consultar detalhes da conta.
  • contracts: para implantar, conceder permissões e invocar métodos em contratos programáveis.
  • issuance: para que uma câmara de compensação aumente ou diminua o limite de emissão de um gerenciador de tokens e realize operações de liquidação.
  • tokens: para um gerenciador de tokens emitir ou destruir tokens em uma conta de usuário.
  • wallet: para uma conta de usuário transferir um valor do saldo para outra conta de usuário.

A seguir