HD Wallet Introduction

An abbreviation for hierarchical determinism, the Kaleido HD Wallet is a key tree that provides a deterministic derivation of Ethereum account addresses and their corresponding private signing keys from a single seed phrase. The overall HD wallet implementation is a byproduct of several Bitcoin Improvement Proposals (BIP), specifically BIP32 for the core cryptography and key generation, BIP39 for seed phrase and recovery, and BIP44 for multi-protocol account hierarchy.

The seed phrase, a 12 word mnemonic, can be generated in one of two ways: either by the service via the BIP39 spec or submitted manually by the user as an “easy to remember hard to guess” expression. The seed phrase serves as the master root for the entire key tree, therefore strong entropy should be applied if manual submission is the desired course of action.

HD wallets provide an elegant solution for both account management and identity masking, as the key tree can be deterministically regenerated from the master seed phrase and users can increment their account index on a per-transaction basis to anonymize identity via unique signing keys.

Also see the Managed Wallet for a simple and secure way to manage key ownership for signing transactions.

Core Capabilities:

• Unlimited, Unique Accounts & Associated Private Keys: Mask your identity on a per-transaction basis via an unlimited supply of account addresses, each with their own unique, untraceable private key. Different accounts can be used for different transaction classes or to manage the end users of an organization.

• Regeneration: Easily backup and restore an exact replica of your wallet when you need it. Using a 12-word mnemonic "seed phrase” (entropy), each account can be recreated identically. Remember the mnemonic, never lose the wallet.

• Multiple Wallets for Account ID Management: Partition separate wallets across your organization to avoid key reuse and duplicate signing.

Provision the HD Wallet Service

You can elect for one of two approaches to provision the HD Wallet: 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 within the specified environment.

Via the console

• Navigate to the HD Wallet usage page for detailed instructions.

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 HD Wallet is provisioned against the /services API endpoint and exists as an environment-specific member resource. The orchestration is identical to nodes and application credentials, where the object is directly bound to one of the consortium’s membership IDs. 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. This sample assumes 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 <code

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 <code

# 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":"ExampleHDwallet", "service":"hdwallet", "membership_id":"{membership_id}"}' | jq

This will return you the 10 character HD wallet service ID. For example:

{
  "name": "ExampleHDwallet",
  "service": "hdwallet",
  "membership_id": "u0amsb3epp",
  "service_guid": "1878bcdf-a5b5-45a9-b279-5f8bb38d36da",
  "service_type": "member",
  "details": {},
  "zone_id": "u0iqva64fj",
  "state": "provisioning",
  "_id": "u0cyjmmgwt",
  "_revision": "0",
  "created_at": "2019-04-10T14:42:30.362Z",
  "environment_id": "u0n9z64z07"
}

Query the Service ID and Retrieve the URL

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

This will return you the HD Wallet details, including the targetable URL for account/key retrieval and transaction signing. For example:

{
  "_id": "u0cyjmmgwt",
  "name": "ExampleHDwallet",
  "service": "hdwallet",
  "membership_id": "u0amsb3epp",
  "service_guid": "1878bcdf-a5b5-45a9-b279-5f8bb38d36da",
  "service_type": "member",
  "details": {},
  "zone_id": "u0iqva64fj",
  "state": "started",
  "_revision": "1",
  "created_at": "2019-04-10T14:42:30.362Z",
  "environment_id": "u0n9z64z07",
  "urls": {
    "http": "https://u0n9z64z07-u0cyjmmgwt-hdwallet.us0-aws.kaleido.io"
  },
  "updated_at": "2019-04-10T14:42:40.431Z"
}

The URL of interest is "https://u0n9z64z07-u0cyjmmgwt-hdwallet.us0-aws.kaleido.io".

As with all Kaleido REST API calls, /api/v1 must be appended to the endpoint and application credentials must be supplied inline or as a base64 encoded object in the header auth. Therefore, using the above URL as a reference, the targetable endpoint would be as follows:

https://{username}:{password}@u0n9z64z07-u0cyjmmgwt-hdwallet.us0-aws.kaleido.io/api/v1

Resource Sizing

The following table serves to outline the available resource limitations based on the provisioned HD Wallet service size.