Pedir uma nova conta

As novas contas em uma rede do Universal Ledger precisam ser criadas por uma conta de administrador privilegiada já presente no livro-razão. Essa conta privilegiada precisa assinar e enviar uma transação para criar a nova conta.

Este guia descreve como solicitar uma nova conta em uma rede do Universal Ledger. Saiba como:

  • Criar chaves de assinatura assimétricas para a nova conta usando o Cloud Key Management Service.

  • Identificar o proprietário da conta privilegiada adequada que pode criar sua conta.

  • Confirmar os detalhes da conta depois que ela for criada no livro-razão.

Antes de começar

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

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

  • Um papel do IAM, como roles/universalledger.networkViewer, para que você possa pelo menos consultar o estado das contas em uma rede do Universal Ledger.

  • Um Google Cloud projeto com o Cloud KMS ativado.

    Durante os testes, esse projeto pode ser o mesmo que tem a API Universal Ledger ativada.

    Na produção, recomendamos que você:

    • Use um projeto dedicado para os recursos do Cloud KMS, separado de outros Google Cloud recursos.
    • Crie um projeto separado Google Cloud para gerenciar as chaves do Cloud KMS de cada rede do Universal Ledger que você usa.

  • O papel do IAM de administrador do Cloud KMS (roles/cloudkms.admin) no projeto com o Cloud KMS ativado ou em um recurso pai.

Criar chaves de assinatura assimétricas

Cada conta que opera em um Universal Ledger requer um par de chaves pública-privada de assinatura assimétrica. A chave privada é usada para assinar transações, e a chave pública é registrada no livro-razão para identificar sua conta e verificar assinaturas.

As etapas a seguir orientam você na criação de um par de chaves adequado usando o Cloud KMS e na recuperação da chave pública. Você pode usar outras abordagens de gerenciamento de chaves, desde que elas produzam chaves e assinaturas compatíveis com os requisitos do Universal Ledger, como chaves ECDSA P-256 com resumos SHA-256. Para detalhes sobre os formatos de chave compatíveis, consulte a KeyFormat referência.

  1. No Google Cloud console, ative o Cloud Shell.

    Ativar o Cloud Shell

  2. Defina o projeto padrão.

    gcloud config set project KEYS_PROJECT

    Substitua KEYS_PROJECT pelo ID do projeto a ser usado para os recursos do Cloud KMS.

  3. Se ainda não tiver feito isso, crie um keyring para armazenar suas chaves usando o gcloud kms keyrings create comando:

    gcloud kms keyrings create KEY_RING \
    --location=KEY_LOCATION

    Substitua:

    • KEY_RING: o nome do keyring a ser criado, por exemplo, test-gcul-keys. Esse nome é para suas próprias necessidades organizacionais e não precisa ser registrado no livro-razão.
    • KEY_LOCATION: o Google Cloud local do keyring, por exemplo, global.

  4. Para cada conta que você quer usar no livro-razão, crie uma chave de assinatura assimétrica usando o gcloud kms keys create comando:

    gcloud kms keys create KEY_NAME \
    --keyring=KEY_RING \
    --location=KEY_LOCATION \
    --purpose="asymmetric-signing" \
    --default-algorithm="ec-sign-p256-sha256"

    Substitua:

    • KEY_NAME: o nome da chave a ser criada, por exemplo, usd-operator ou eur-clearinghouse. Esse nome é para suas próprias necessidades organizacionais e não precisa ser registrado no livro-razão.
    • KEY_RING: o nome do keyring para armazenar a chave.
    • KEY_LOCATION: o Google Cloud local da chave.

    Isso cria um par de chaves ECDSA na curva P-256 com um resumo SHA-256, conforme aceito pelo Universal Ledger. Para uma lista de formatos aceitos, consulte a KeyFormat referência.

  5. Recupere a parte da chave pública de uma versão da chave usando o gcloud kms keys versions get-public-key comando:

    gcloud kms keys versions get-public-key KEY_VERSION \
    --key=KEY_NAME \
    --keyring=KEY_RING \
    --location=KEY_LOCATION

    Substitua:

    • KEY_VERSION: a versão da chave a ser recebida. Esse é 1 para chaves recém-criadas.
    • KEY_NAME: o nome da chave.
    • KEY_RING: o nome do keyring que contém a chave.
    • KEY_LOCATION: o Google Cloud local da chave.

    Esse comando gera a chave pública em um formato codificado em PEM (KEY_FORMAT_PEM_EC_P256_SHA256) adequado para uso com a API Universal Ledger, como:

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

Identificar quem pode criar sua conta

O tipo de conta que você quer criar determina a conta privilegiada no livro-razão que tem permissão para criá-la. Você precisa identificar o proprietário dessa conta privilegiada. Para saber mais sobre os tipos de contas no Universal Ledger, consulte Principais conceitos.

Tipo de conta Criado por Envio da transação
Operador de moeda Operador de plataforma CreateCurrencyOperator
Câmara de compensação Operador de moeda CreateClearinghouse
Gerente de contas Operador de moeda CreateAccountManager
Gerente de tokens Operador de moeda CreateTokenManager
Conta de usuário Gerente de contas CreateAccount

Depois de identificado, você precisará coordenar e compartilhar os detalhes a seguir com o proprietário da conta privilegiada que pode criar sua conta:

  • O nome da rede em que você quer que a conta seja criada. Para uma lista de regiões aceitas, consulte Redes e regiões disponíveis.
  • A parte pública da sua chave de assinatura assimétrica e o correspondente KeyFormat. Se você seguiu os comandos gcloud neste guia, o formato é KEY_FORMAT_PEM_EC_P256_SHA256.
  • Uma string de comentário da conta com informações relevantes a serem registradas no livro-razão associado à sua nova conta. Esse é um valor opaco que é armazenado no livro-razão, mas não interpretado de outra forma pelo Universal Ledger. Depois de criado, esse campo é imutável e legível por qualquer pessoa com acesso à rede.
  • Todos os detalhes adicionais necessários para preencher a transação a ser enviada ao criar a conta. Por exemplo, para criar um operador de moeda, também é necessário especificar a currency que será gerenciada pelo novo operador a ser criado.

Durante a prévia, entre em contato com seu contato no Google se não tiver certeza de quem é o proprietário da conta privilegiada relevante para seu caso de uso.

Confirmar se a conta foi criada

Depois que a transação enviada pela conta privilegiada for executada e finalizada com sucesso no livro-razão, a resposta doQueryTransactionStatemétodo vai incluir umTransactionCertificatecom um transaction_output evento que contém o ID da conta recém-criada.

O ID será semelhante ao exemplo a seguir:

1:USR:XTS:025sAZ55EqGKF6vpXEpSS8X891nNDEQU9yFQKYkcFzAb6

É possível confirmar se a nova conta está presente no livro-razão enviando a seguinte solicitação REST:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://universalledger.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/NETWORK_NAME:queryAccount?account_id=ACCOUNT_ID

Substitua:

  • PROJECT_ID: o ID do projeto em que a API Universal Ledger está ativada.
  • LOCATION: o local do endpoint a ser alcançado.
  • NETWORK_NAME: o nome da rede em que sua conta foi criada.
  • ACCOUNT_ID: o ID da sua conta recém-criada.

Você verá um resultado semelhante a este:

{
  "account": {
    "publicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFSi92V2tkNXdnYWtGYlZEMjVrOFdNOUxsNldlKwpjOFJWRFMwUjRHOHhldHNtRmpmTlcvWnh3V2VCODZJdk1qeFk4WnNkVTkrVzdCTDVZTTZyVUI1eUNRPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t",
    "roundId": "10962032",
    "comment": "My Test Account",
    "userDetails": {
      "accountManager": {
        "id": "1:ACT:XTS:02f4VSHyPsXeMZmcogbNx7bP4kfn5DYvc7d2K52RYAFd3"
      },
      "tokenManager": {
        "id": "1:TKN:XTS:024fqJS87dJ94ETN9PGhTCGd86btXj9iyWLxGQWgC3dde"
      },
      "roles": [
        "ROLE_PAYER",
        "ROLE_RECEIVER"
      ],
      "accountStatus": "ACCOUNT_STATUS_ACTIVE",
    }
  }
}

A seguir