In this doc
HomeKaleido ServicesRotate SignersConfiguring and Activating the Rotate Signers Service

Configuring and Activating the Rotate Signers Service

Provisioning the Service

You can elect for one of two approaches to provision the Rotate Signers 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 instance of the Rotate Signers Service instance running within the specified environment.

UI:

  • Navigate to an existing environment and click the + ADD dropdown in the top portion right of the screen and click Add Services.
  • Select the Rotate Signers Service and click ADD.
  • Optionally supply an arbitrary name for the service and click ADD. click DONE to finish the deployment.
  • The newly created App to App Service instance will appear at the bottom of your environment panel under SERVICES.
  • The service is ready for use when a green dot appears next to it.

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 Understanding the Kaleido API for detailed descriptions of the various endpoints and routes. The formal API specification is served here.

The Rotate Signers service is provisioned against the /services API endpoint and exist as  a “utility” type service.  In other words, the resource is shared amongst the environment.  In a decentralized consortium, the service can only be deployed and operated by member organizations with the “manage environments” permission.

To programmatically create the Rotate Signers 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 or on Azure, make sure to modify your URL accordingly. The ap qualifier resolves to Sydney, while ko resolves to Seoul. The us1 qualifier designates an environment configured with Azure US West as the home region:

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"
export APIURL="https://console-us1.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":"exampleRotateSignersInstance", "service":"rotatesigners", "membership_id":"{membership_id}"}' | jq

This will return you a JSON payload containing the service ID. Keep the service ID handy, you will need it to configure and activate the service.

Next, you can call a GET on the /services endpoint and specify the service id in the route.  For example:

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

This call returns a JSON payload containing additional details for the Rotate Signers service instance.

Configuring, Activating and Operating the Service

UI:

Once the service is deployed in your environment, access the dashboard by clicking “Rotate Signers” under the SERVICES row or by expanding the ellipsis next to “Rotate Signers” and selecting the “view dashboard” option.

The service exposes four parameters in the lefthand navigation for optional configuration:

  • Target Number of Signers – the number of active signers in each rotation interval.  The minimum and default value is 4.  The maximum is 16.  The system monitor node is always configured as a signer in an IBFT environment.
  • Rotation Interval – the length, specified in minutes, between signer rotations.  The minimum and default value is 5 minutes.
  • Rotation Size – the number of signers to be added and removed in each rotation interval.
  • Rotation Algorithm – as of this writing, the algorithm is hardcoded, by default, to “Oldest Out First” meaning that the longest tenured signers will be the first to be removed.  Additional algorithms (e.g. randomization based) will be added in the future.

Once you have configured the available parameters, you can initialize the service by clicking the ACTIVATE button in the bottom left of the dashboard screen.

To perform additional administrative operations against the service (i.e. restart or delete), click the ACTIONS tab at the top of the screen.

API:

As with all Kaleido services, the same in-console actions can be accomplished via the administrative API.  Please refer to the API documentation for the full specification.  Below are some sample calls for configuration, activation and status.  Note that these are predicated on a deployed service instance and the corresponding service ID.

/configuration

For example, to configure the service with 5 active signing nodes, a batch size of 2 and a rotation interval of 15 minutes:

curl -X PATCH -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/rotatesigners/{service_id}/configuration" -d '{"targetSignerCount":5, "rotationInterval":15, "rotationSize":2, "rotationAlgorithm":"oldest-first"}'

Note that this call is a PATCH against the /configuration route and that the arguments for targetSignerCount, rotationInterval and rotationSize are specified as integers.  The algorithm must be enumerated and is supplied as a string.

/activate

For example, to activate your newly configured service:

curl -X POST -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/rotatesigners/{service_id}/activate" -d '{}'

Note that this call is a POST against the /activate route and requires an empty body to be supplied.

/deactivate

For example, to deactivate the service:

curl -X POST -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/rotatesigners/{service_id}/deactivate" -d '{}'

/currentSigners

For example, to retrieve the IBFT consensus identity of the currently active signing nodes:

curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/rotatesigners/{service_id}/currentSigners" | jq

/nextSigners

For example, to see the consensus identity of the signing nodes to be voted in during the next interval:

curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/rotatesigners/{service_id}/nextSigners" | jq