Request a new account

New accounts in a Universal Ledger network must be created by a privileged administrator account already present on the ledger. This privileged account must sign and submit a transaction to create the new account.

This guide describes how to request a new account in a Universal Ledger network. Learn how to:

Create asymmetric signing keys for the new account using Cloud Key Management Service.
Identify the owner of the appropriate privileged account who can create your account.
Confirm your account details once it's created on the ledger.

Before you begin

To complete this guide, you will need the following:

A Google Cloud project with the Universal Ledger API enabled.
An IAM role such as roles/universalledger.networkViewer so you can at least query the state of accounts in a Universal Ledger network.
A Google Cloud project with the Cloud KMS enabled.

During testing, this project can be the same as the one with Universal Ledger API enabled.

In production, we recommend you:
- Use a dedicated project for your Cloud KMS resources, separate from other Google Cloud resources.
- Create a separate Google Cloud project to manage the Cloud KMS keys for each Universal Ledger network you use.
The Cloud KMS Admin (roles/cloudkms.admin) IAM role on the project with Cloud KMS enabled, or on a parent resource.

Create your asymmetric signing keys

Every account operating on a Universal Ledger requires an asymmetric signing public-private key pair. The private key is used for signing transactions, and the public key is registered on the ledger to identify your account and verify signatures.

The following steps guide you through creating a suitable key pair using Cloud KMS and retrieving the public key. You can use other key management approaches as long as they produce keys and signatures compatible with Universal Ledger requirements, such as ECDSA P-256 keys with SHA-256 digests. For details about supported key formats, see the KeyFormat reference.

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell
Set the default project:
```
gcloud config set project KEYS_PROJECT
```
Replace KEYS_PROJECT with the ID of the project to be used for your Cloud KMS resources.
If you haven't already, create a key ring to hold your keys using the gcloud kms keyrings create command:
```
gcloud kms keyrings create KEY_RING \
    --location=KEY_LOCATION
```
Replace the following:
- KEY_RING: the name of the key ring to create, for example test-gcul-keys. This name is for your own organizational needs and does not need to be recorded on the ledger.
- KEY_LOCATION: the Google Cloud location for the key ring, for example global.
For each account you want to use on the ledger, create an asymmetric signing key for it using the gcloud kms keys create command:
```
gcloud kms keys create KEY_NAME \
    --keyring=KEY_RING \
    --location=KEY_LOCATION \
    --purpose="asymmetric-signing" \
    --default-algorithm="ec-sign-p256-sha256"
```
Replace the following:
- KEY_NAME: the name of the key to create, for example usd-operator or eur-clearinghouse. This name is for your own organizational needs and does not need to be recorded on the ledger.
- KEY_RING: the name of the key ring to hold the key.
- KEY_LOCATION: the Google Cloud location for the key.
This creates an ECDSA key pair on the P-256 Curve with a SHA-256 digest as supported by the Universal Ledger. For a list of supported formats, consult the KeyFormat reference.
Retrieve the public key portion of a key version using the gcloud kms keys versions get-public-key command:
```
gcloud kms keys versions get-public-key KEY_VERSION \
    --key=KEY_NAME \
    --keyring=KEY_RING \
    --location=KEY_LOCATION
```
Replace the following:
- KEY_VERSION: the version of the key to get, this is 1 for newly created keys.
- KEY_NAME: the name of the key.
- KEY_RING: the name of the key ring containing the key.
- KEY_LOCATION: the Google Cloud location of the key.
This command outputs the public key in a PEM-encoded format (KEY_FORMAT_PEM_EC_P256_SHA256) suitable to use with the Universal Ledger API such as:
```
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ/vWkd5wgakFbVD25k8WM9Ll6We+
c8RVDS0R4G8xetsmFjfNW/ZxwWeB86IvMjxY8ZsdU9+W7BL5YM6rUB5yCQ==
-----END PUBLIC KEY-----
```

Identify who can create your account

The type of account you want to create determines the privileged account on the ledger which has the permission to create it. You need to identify the owner of that privileged account. To learn about the types of accounts in the Universal Ledger, see Key concepts.

Account type	Is created by	Submitting the transaction
Currency Operator	Platform Operator	CreateCurrencyOperator
Clearinghouse	Currency Operator	CreateClearinghouse
Account Manager	Currency Operator	CreateAccountManager
Token Manager	Currency Operator	CreateTokenManager
User Account	Account Manager	CreateAccount

Once identified, you'll need to coordinate and share the following details with the owner of the privileged account who can create your account:

The name of the network where you want the account created. For a list of supported regions, see Available networks and regions.
The public portion of your asymmetric signing key and its corresponding KeyFormat. If you followed the gcloud commands in this guide, the format is KEY_FORMAT_PEM_EC_P256_SHA256.
An account comment string with any relevant information to record on the ledger associated with your new account. This is an opaque value that is stored on ledger but not interpreted otherwise by the Universal Ledger. Once created, this field is immutable and readable by anyone with access to the network.
Any additional details required to populate the transaction to be submitted when creating the account. For example, to create a Currency Operator you also need to specify the currency that will be managed by the new operator to be created.

During Preview, reach out to your contact at Google if you are unsure about who is the owner of the relevant privileged account for your use case.

Confirm your account is created

Once the transaction submitted by the privileged account is successfully executed and finalized on the ledger, the response from the QueryTransactionState method will include a TransactionCertificate with a transaction_output event containing the account ID of the newly created account.

The ID will look similar to the following example:

1:USR:XTS:025sAZ55EqGKF6vpXEpSS8X891nNDEQU9yFQKYkcFzAb6

You can confirm that your new account is present on the ledger by submitting the following REST request:

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

Replace the following:

PROJECT_ID: the ID of the project where the Universal Ledger API is enabled.
LOCATION: the location of the endpoint to reach.
NETWORK_NAME: the name of the network where your account was created.
ACCOUNT_ID: the ID of your newly created account.

You will see output similar to the following:

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

What's next

Learn how to send RPC requests to the Universal Ledger API.
Learn about transactions you can submit using your new account.