Configurar a CLI do Universal Ledger

A CLI do Universal Ledger é uma interface de linha de comando fornecida para fins de experimentação para facilitar 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:

  • Obter e configurar a CLI do Universal Ledger.

  • Criar e gerenciar contas usando a CLI.

  • Conheça 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 do Universal Ledger.

  • 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 conter os arquivos de configuração da CLI.

mkdir -p ~/.config/ul-cli

Extrair a imagem e configurar o alias

Execute cada um dos comandos a seguir para extrair a imagem Docker ul-cli, definir um alias para executar o binário e confirmar se ele funciona:

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

Configurar a ul-cli

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 projeto do Google Cloud em que a API Universal Ledger está ativada.
  • REGION: a região do endpoint que você quer acessar.
  • NETWORK_NAME: o nome da rede com que você quer interagir.

Se precisar de ajuda para escolher um endpoint adequado, consulte Redes e locais do Universal Ledger.

Esse comando cria o arquivo de configuração da CLI em ~/.config/ul-cli/config.yaml (no Linux e no macOS).

Gerenciar contas do Universal Ledger

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

Registrar uma conta atual

Depois que uma conta for criada para você por outro participante na rede, use o comando a seguir para registrar os detalhes da conta na lista de endereços 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 futuras invocações de comando. Por exemplo, usd-operator, my-token-manager ou test-user-account.
  • ACCOUNT_ID: o ID da conta do Universal Ledger que foi criada para você.
  • ACCOUNT_KMS_KEY: o ID de recurso completo da versão da chave do Cloud KMS usada por essa 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 vai registrar os detalhes da conta no arquivo de configuração da CLI, permitindo que você assine e envie solicitações ao livro contábil em nome dessa conta.

Criar uma conta para você

É possível criar novas contas usando o subcomando ul-cli accounts create. Por exemplo, para criar uma nova conta de 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 de recurso completo da versão da chave do Cloud KMS que será usada pela nova conta de usuário.
  • NEW_ACCOUNT_COMMENT: uma string com qualquer informação relevante a ser registrada no livro associado à nova conta de usuário. Esse é um valor opaco que é armazenado no livro, mas não é interpretado 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 contas em questão.

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

Criar uma conta para outra pessoa

Para criar uma conta para outra pessoa, peça para ela compartilhar com você a chave pública dela e armazene-a 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 o 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 seguinte comando 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 ou enviar transações.
  • NEW_ACCOUNT_COMMENT: uma string com qualquer informação relevante a ser registrada no livro associado à nova conta de usuário. Esse é um valor opaco que é armazenado no livro, mas não é interpretado 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 contas em questão.

As flags --public-key e --key-format estão disponíveis para todos os subcomandos accounts create. Assim, você também pode usá-las para criar outros tipos de contas. 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 ver todas as contas registradas ou criadas localmente com a CLI do Universal Ledger:

ul-cli accounts list

Conheça outros comandos

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

Por exemplo, para ver 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 atuais, 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 que um gerenciador de tokens emita ou queime tokens em uma conta de usuário.
  • wallet: para que uma conta de usuário transfira um valor do saldo para outra conta de usuário.

A seguir