Solicita una cuenta nueva

Las cuentas nuevas en una red de libro contable universal deben ser creadas por una cuenta principal que ya esté presente en el libro contable. Esta cuenta principal debe firmar y enviar una transacción para crear la cuenta nueva.

En esta guía, se describe cómo solicitar una cuenta nueva en una red de Universal Ledger. Aprenderás a realizar estas tareas:

  • Crea claves de firma asimétricas para la cuenta nueva con Cloud Key Management Service.

  • Identifica al propietario de la cuenta principal adecuada para crear tu cuenta.

  • Confirma los detalles de tu cuenta una vez que se cree en el libro de contabilidad.

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.networkViewer, para que puedas, al menos, consultar el estado de las cuentas en una red de Universal Ledger.

  • Un proyecto Google Cloud con Cloud KMS habilitado.

    Durante las pruebas, este proyecto puede ser el mismo en el que está habilitada la API de Universal Ledger.

    En producción, te recomendamos que hagas lo siguiente:

    • Usa un proyecto dedicado para tus recursos de Cloud KMS, independiente de otros recursos de Google Cloud .
    • Crea un proyecto Google Cloud independiente para administrar las claves de Cloud KMS de cada red de Universal Ledger que uses.

  • El rol de IAM de administrador de Cloud KMS (roles/cloudkms.admin) en el proyecto con Cloud KMS habilitado o en un recurso principal

Crea tus claves de firma asimétricas

Cada cuenta que opera en un libro de contabilidad universal requiere un par de claves públicas y privadas de firma asimétrica. La clave privada se usa para firmar transacciones, y la clave pública se registra en el libro de contabilidad para identificar tu cuenta y verificar firmas.

En los siguientes pasos, se explica cómo crear un par de claves adecuado con Cloud KMS y recuperar la clave pública. Puedes usar otros enfoques de administración de claves, siempre y cuando produzcan claves y firmas compatibles con los requisitos de Universal Ledger, como las claves ECDSA P-256 con resúmenes SHA-256.

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

  2. Configura el proyecto predeterminado:

    gcloud config set project KEYS_PROJECT

    Reemplaza KEYS_PROJECT por el ID del proyecto que se usará para tus recursos de Cloud KMS.

  3. Si aún no lo hiciste, crea un llavero de claves para guardar tus claves con el comando gcloud kms keyrings create:

    gcloud kms keyrings create KEY_RING \
    --location=KEY_LOCATION

    Reemplaza lo siguiente:

    • KEY_RING: Es el nombre del llavero de claves que se creará, por ejemplo, test-gcul-keys. Este nombre es para tus propias necesidades organizativas y no es necesario que se registre en el libro de contabilidad.
    • KEY_LOCATION: La Google Cloud ubicación del llavero de claves, por ejemplo, global.

  4. Para cada cuenta que quieras usar en el libro de contabilidad, crea una clave de firma asimétrica con el comando gcloud kms keys create:

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

    Reemplaza lo siguiente:

    • KEY_NAME: Es el nombre de la clave que se creará, por ejemplo, usd-operator o eur-clearinghouse. Este nombre es para tus propias necesidades organizativas y no es necesario que se registre en el libro mayor.
    • KEY_RING: Es el nombre del llavero de claves en el que se guardará la clave.
    • KEY_LOCATION: Es la Google Cloud ubicación de la clave.

    Esto crea un par de claves ECDSA en la curva P-256 con un resumen SHA-256, tal como lo admite el Registro Universal. Para obtener una lista de los formatos admitidos, consulta la referencia de KeyFormat.

  5. Recupera la parte de clave pública de una versión de clave con el comando gcloud kms keys versions get-public-key:

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

    Reemplaza lo siguiente:

    • KEY_VERSION: Es la versión de la clave que se obtendrá. Es 1 para las claves creadas recientemente.
    • KEY_NAME: el nombre de la clave.
    • KEY_RING: Es el nombre del llavero de claves que contiene la clave.
    • KEY_LOCATION: Es la Google Cloud ubicación de la clave.

    Este comando genera la clave pública en un formato con codificación PEM (KEY_FORMAT_PEM_EC_P256_SHA256) adecuado para usar con la API de Universal Ledger, como el siguiente:

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

Identifica quién puede crear tu cuenta

El tipo de cuenta que deseas crear determina la cuenta principal en el libro de contabilidad que tiene permiso para crearla. Debes identificar al propietario de esa cuenta principal. Para obtener información sobre los tipos de cuentas en el libro contable universal, consulta Conceptos clave.

Tipo de cuenta Creado por Envío de la transacción
Operador de moneda Operador de plataforma CreateCurrencyOperator
Cámara de compensación Operador de moneda CreateClearinghouse
Administrador de cuentas Operador de moneda CreateAccountManager
Administrador de tokens Operador de moneda CreateTokenManager
Cuenta de usuario Administrador de cuentas CreateAccount

Una vez que lo identifiques, deberás coordinar y compartir los siguientes detalles con el propietario de la cuenta principal que puede crear tu cuenta:

  • Es el nombre de la red en la que deseas crear la cuenta. Para la versión preliminar privada, consulta la lista de redes disponibles.
  • La parte pública de tu clave de firma asimétrica y su KeyFormat correspondiente Si seguiste los comandos de gcloud en esta guía, el formato es KEY_FORMAT_PEM_EC_P256_SHA256.
  • Es una cadena de comentarios de la cuenta con cualquier información pertinente para registrar en el libro mayor asociado a tu cuenta nueva. Es un valor opaco que se almacena en el libro de contabilidad, pero que el libro de contabilidad universal no interpreta de otra manera. Una vez creado, este campo es inmutable y cualquier persona con acceso a la red puede leerlo.
  • Son los detalles adicionales necesarios para completar la transacción que se enviará cuando se cree la cuenta. Por ejemplo, para crear un operador de moneda, también debes especificar el currency que administrará el nuevo operador que se creará.

Durante la versión preliminar privada, comunícate con tu contacto de Google si no sabes quién es el propietario de la cuenta principal pertinente para tu caso de uso.

Confirma que se haya creado tu cuenta

Una vez que la transacción enviada por la cuenta principal se ejecute y finalice correctamente en el libro de contabilidad, la respuesta del método QueryTransactionState incluirá un TransactionCertificate con un evento transaction_output que contiene el ID de la cuenta recién creada.

El ID se verá similar al siguiente ejemplo:

1:USR:XTS:025sAZ55EqGKF6vpXEpSS8X891nNDEQU9yFQKYkcFzAb6

Para confirmar que tu cuenta nueva está presente en el libro de contabilidad, envía la siguiente solicitud de 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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto en el que está habilitada la API de Universal Ledger.
  • LOCATION: Es la ubicación del extremo al que se debe llegar.
  • NETWORK_NAME: Es el nombre de la red en la que se creó tu cuenta.
  • ACCOUNT_ID: Es el ID de la cuenta que acabas de crear.

Verás un resultado similar al siguiente:

{
  "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",
    }
  }
}

¿Qué sigue?