Solicita una cuenta nueva

Las cuentas nuevas en una red de Universal Ledger deben ser creadas por una cuenta de administrador con privilegios que ya esté presente en el libro mayor. Esta cuenta con privilegios 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:

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

  • Identificar al propietario de la cuenta con privilegios adecuada que puede crear tu cuenta

  • Confirmar los detalles de tu cuenta una vez que se cree en el libro mayor

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 Google Cloud proyecto con Cloud KMS habilitado

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

    En producción, te recomendamos lo siguiente:

    • Usa un proyecto dedicado para tus recursos de Cloud KMS, separado de otros Google Cloud recursos.
    • Crea un Google Cloud proyecto 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 superior

Crea tus claves de firma asimétricas

Cada cuenta que opera en Universal Ledger requiere un par de claves asimétricas de firma pública y privada. La clave privada se usa para firmar transacciones, y la clave pública se registra en el libro mayor para identificar tu cuenta y verificar las 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 que produzcan claves y firmas compatibles con los requisitos de Universal Ledger, como las claves ECDSA P-256 con resúmenes SHA-256. Para obtener detalles sobre los formatos de clave admitidos, consulta la KeyFormat referencia.

  1. En la Google Cloud consola, 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 gcloud kms keyrings create comando:

    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 registrarlo en el libro mayor.
    • KEY_LOCATION: Es la Google Cloud ubicación del llavero de claves, por ejemplo, global.

  4. Para cada cuenta que desees usar en el libro mayor, crea una clave de firma asimétrica con el 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"

    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 registrarlo en el libro mayor.
    • KEY_RING: Es el nombre del llavero de claves que contiene 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 compatible con Universal Ledger. Para obtener una lista de los formatos admitidos, consulta la KeyFormat referencia.

  5. Recupera la parte de clave pública de una versión de clave con el 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

    Reemplaza lo siguiente:

    • KEY_VERSION: Es la versión de la clave que se obtendrá. Es 1 para las claves recién creadas.
    • KEY_NAME: Es 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 codificado en 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 con privilegios en el libro mayor que tiene el permiso para crearla. Debes identificar al propietario de esa cuenta con privilegios. Para obtener información sobre los tipos de cuentas en el Universal Ledger, 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 con privilegios que puede crear tu cuenta:

  • El nombre de la red en la que deseas que se cree la cuenta. Para obtener una lista de las regiones admitidas, consulta Redes y regiones disponibles.
  • La parte pública de tu clave de firma asimétrica y su correspondiente KeyFormat. Si seguiste los comandos de gcloud de esta guía, el formato es KEY_FORMAT_PEM_EC_P256_SHA256.
  • Una cadena de comentarios de la cuenta con cualquier información pertinente para registrar en el libro mayor asociada con tu cuenta nueva. Este es un valor opaco que se almacena en el libro mayor, pero Universal Ledger no lo interpreta de otra manera. Una vez creado, este campo es inmutable y cualquier persona con acceso a la red puede leerlo.
  • Cualquier detalle adicional necesario para propagar la transacción que se enviará cuando se cree la cuenta. Por ejemplo, para crear un operador de moneda, también debes especificar la currency que administrará el nuevo operador que se creará.

Durante la versión preliminar, comunícate con tu contacto de Google si no estás seguro de quién es el propietario de la cuenta con privilegios pertinente para tu caso de uso.

Confirma que se creó tu cuenta

Una vez que la transacción enviada por la cuenta con privilegios se ejecute correctamente y finalice en el libro mayor, la respuesta del QueryTransactionState método 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 mayor, envía la siguiente solicitud 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 tu cuenta recién creada.

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?