Kaleido Open Menu
Close Menu
Log In Try It Free

On-Chain Registry Introduction

On-chain Registry

An environmental utility service allowing for x509 identity certificates to be authoritatively mapped to organizational Ethereum addresses within a directory smart contract. Also exposes a key/value based smart contract (profiles) for any publicly accessible information that is needed by the rest of the consortia. Examples of publicly accessible info includes public keys for asymmetric encryption, private addresses for confidential transactions and destination certificates for encrypted App 2 App messaging.

Deploying the Registry Service

You can elect for one of two approaches to provision the Registry Service: Kaleido Console UI or Admin API. For users unfamiliar with the Kaleido REST API, the console interface is the recommended happy path. Both approaches will ultimately result in a new service instance and the deployment of two smart contracts (Directory and Profile) within the targeted environment.

Via the console

  • Navigate to an existing environment, and click the +ADD dropdown in the top right portion of the screen.
  • Select the Add Services option. This will open a new panel exposing the currently available Kaleido Services.
  • Click the ADD button beneath On-Chain Registry.
  • Supply a name for the utility and click ADD. Click DONE to finish the deployment.
  • The environment-specific registry will appear under the Services view on your environment dashboard.
  • Click the details dropdown next to the ID Registry Service and select View Dashboard to ascertain the service ID.
  • The ID is the last ten characters of the details URL – {consortia_id}/{environment_id}/{membership_id}/{service_id}.
  • Keep the ID handy, you will need it to programmatically interact with the service.
  • If you have already gone through the process of underpinning a membership with a valid x509 certificate, the ID will appear in an autogenerated YAML file displayed on this screen.

Via the API

NOTE: The following deployment approach assumes a strong understanding of the Kaleido APIs. Please refer to the Kaleido Resource Model for object relationships, the API 101 topic for sample CRUD operations and api.kaleido.io for detailed descriptions of the various endpoints and routes.

The ID Registry Service is provisioned against the /services API endpoint and exists as an environment-specific utility resource. The orchestration is similar to other services (e.g. HD Wallet), where the object is directly bound to one of the consortium’s membership IDs. However, in contrast to HD Wallet which is a “member” type service, the ID Registry is shared across the environment as a “utility” type service and cannot be deleted once it has been provisioned in a decentralized environment. The binding to a membership ID simply allows fellow members of the environment to identify the org that provisioned the service. It is NOT an indication of ownership. For centralized orchestrations (where all resources are owned an operated by a single organization), the Registry can be deleted by any organizational admin with access to the Kaleido console or a valid API Key.

To create the service, specify the consortia and environment IDs in the path and POST to the /services endpoint with a name, the service type and membership ID in the body of the call. The forthcoming sample commands assume that the following environment variables have been set as follows:

export APIURL="https://console.kaleido.io/api/v1"
export APIKEY="YOUR_API_KEY"
export HDR_AUTH="Authorization: Bearer $APIKEY"
export HDR_CT="Content-Type: application/json"

If you are targeting an environment outside of the US, make sure to modify your URL accordingly. The ap qualifier resolves to Sydney, while ko resolves to Seoul:

export APIURL="https://console-eu.kaleido.io/api/v1"
export APIURL="https://console-ap.kaleido.io/api/v1"
export APIURL="https://console-ko.kaleido.io/api/v1"

Use the POST method to provision the service and optionally format the output using jq:

# replace the membership_id placeholder with one of your membership IDs
curl -X POST -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/services" -d '{"name":"ExampleRegistryService", "service":"idregistry", "membership_id":"{membership_id}"}' | jq

This will return you the service ID. Alternatively, you can call a GET on the /services endpoint to expose all of the environment’s services and manually identify the ID:

curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/services" | jq

Keep the service ID handy, we will use it in an upcoming step to communicate with the registry.