You can elect for one of two routes to build your first consortium and the underlying environment. The first approach relies solely on the user interface, while the second option allows you to exercise the Kaleido REST API to send privileged calls to the backend server. Regardless of your selection, you must visit the Kaleido Dashboard and create an account prior to continuing.
An account is the access point to your Kaleido Organization. Before starting, select a Geo where your account information will be stored. The current geographies are US, Europe and Asia Pacific, with Sydney and Seoul available as sub-locales for the APAC geo.
- Supply a delegate email for your organization. This email will receive notifications related to your organization and will serve as the username for your login.
- Generate a strong password to secure access to your organization. The password must be eight characters and contain at least one capital letter and special character.
- Supply a name to identify your organization on the platform. This name will be your default membership identification within a consortium. Note that your Kaleido Organization name can be edited after creation and your membership identification within a consortium can be configured. For example, if your Kaleido Organization is
Bank A, you could edit the default membership value to exist in two consortia as
Bank A Commoditiesand
Bank A Currencies. The memberships for
Bank A Commoditiesand
Bank A Currenciesare simply bound to the Kaleido Organization –
- Confirm that you are not a robot and click Next.
- Input your first and last names. Use the dropdown menus and select applicable values for Job Title, Industry and Company Size. Click Next.
- Navigate to the delegate email you supplied for your Kaleido Organization and retrieve the verification code. Enter the code and click Verify Account to complete your registration.
This is the recommended route for first time users. Interacting through the UI is a straightforward process, however for the sake of clarity the basic flow is outlined below:
- Enter your email and password and click Sign In to access your organization through the Kaleido console.
- You will be redirected to the Kaleido home screen. Click the + Create Consortium button in the top right corner to begin crafting your first consortia.
Name & Mission
- Provide a name for your consortia and optionally supply a description for the consortia’s mission (e.g. share and exchange healthcare provider data).
- Select one of the available cloud providers and an underlying region as the Home Region for your consortia. This where the consortia’s metadata will be stored.
Additional Deployment Regions
- You can proceed to whitelist additional deployment zones and orchestrate a hybrid cross-cloud, multi-region consortia. Any enabled regions will be able to host nodes and Kaleido resources. Regions can still be enabled post consortia creation.
- Once you have selected your desired clouds and availability zones, click Finish.
- Upon creation of the consortium, you will be greeted with a popup modal allowing you to “introduce yourself” to fellow members of the consortium. Click the Upload New Identity hyperlink and follow the instructions to generate a Kaleido-compliant identity proof. This step involves binding your asserted membership to a pem-encoded x509 certificate so that the consortia members can independently audit and verify your identity attestation. For example, if an organization was claiming to be a reputable financial firm, the counter-parties in the consortium would want to see a robust certificate chain with a reputable external Certificate Authority as the root. This step can be performed now or at a later point in time by editing the membership.
- As the founding member of the consortium, your Kaleido Organization will automatically be allocated the first membership. Click the Add dropdown in the upper right portion of the screen to build out the membership for the consortium.
- The two potential selections for the consortium’s membership are – New Member and Invite Organization. Note that these are not mutually exclusive decisions, and you have the option of selecting both to craft a hybrid ownership model. More on the two membership approaches below.
A Word on Membership Models
As described in the Kaleido Resource Model, memberships have a one to one correlation with a Kaleido Organization and exist as individual objects within the context of a consortium. Any environmental resources (i.e. nodes, services and application credentials) will persist a direct relationship to one of the consortium’s memberships. The salient differentiator with the two membership approaches is the Kaleido Organization controlling the membership(s):
- Any new memberships will exist as sub-resources of your Kaleido Organization. The memberships will possess their own unique resource identifiers and can be distinctly bound to nodes and security credentials within an environment. These memberships will be the ostensible owners of environmental resources, however the true root control will exist with the owning Kaleido Organization (i.e. you). This means that you are responsible for managing the nodes and authentication credentials on behalf of the provisioned memberships, and ultimately control access to the network. For example, take a consortium with Kaleido Organization
ABCas the founding member. Memberships could be constructed for
ABC APACand resources could be provisioned against any of the three memberships. The administrator for Kaleido Organization
ABC, or any co-administrators, can manage the lifecycle for any of these memberships and their underlying resources.
- External organizations will receive an email allowing them to join the consortium. A snapshot of the consortium’s state (existing memberships and outbound invitations) will be presented to the recipient, allowing for an informed decision to be reached. Upon acceptance, any resources created by the “external” organization will exist under the sole control of their Kaleido account. Your Kaleido Organization will be unable to take lifecycle management actions against their resources. Additionally, any invited orgs will be afforded the same ability to establish multiple memberships within the consortium and they will also have the authority to issue their own external invitations. While this is likely the preferred model for true enterprise orchestrations, you should still be prudent when issuing the invitations so as to avoid excess access to the consortium. Membership aliases can be altered dynamically by the controlling Kaleido Organization and memberships cannot be revoked once the invitee has provisioned resources against the membership object.
NOTE: You must be subscribed to either the Business or Enterprise Plan in order to onboard external organizations.
The consortium needs an environment to host nodes and run blockchain transactions. Click the + ADD dropdown and select New Environment to provision the first domain.
- Supply a name for the new environment.
- Choose one of your whitelisted cloud providers and its underlying availability zone as the location for the environment. All of the environment’s resources will exist within the selected cloud and the enumerated AZ. Click Next.
- Choose a node client protocol – Quorum and Geth are the available implementations.
- Choose a consensus algorithm. PoA, Raft and IBFT are the available implementations, but are dependent on your choice of node client. Visit the Consensus Algorithms blog post to learn more about each choice.
- Click Finish to launch your environment.
The environment is simply an empty namespace until it is populated with nodes. Click the Add Node button at the bottom of the screen to provision your first node. Follow the Default instructions below to deploy your node with the standard security measures and no integration services. Refer to the Using AWS Integration Services topic for detailed instructions on configuring and implementing the services.
- Select a membership to bind the node to. You can only provision nodes against memberships under your Kaleido Organization’s control.
- If you are running on an Enterprise Plan and the targeted environment is configured to run IBFT or PoA consensus, you will be presented with the ability to provision the node as a signer. Configuring the node to be a signer means that the node will actively participate in the consensus algorithm by appending its digital signature to the block header on validated blocks. A non-signing node will still maintain the same copy of the chain, but will not play a role in the consensus process.
- Provide a name for the node and click Add.
- You will be redirected to a screen indicating a “Successful creation” of your node.
- Click Add Another Node to provision an additional node or click Done.
- Click Generate App Credentials to create the authentication credentials for the node. The credential creation is an optional step; Kaleido automatically provisions a valid set of application credentials upon creation of the node. However, while the creation of the credentials is optional, the usage of credentials to access nodes and services is enforced on all calls. The upcoming Kaleido Connect section expands on connection protocols in more detail.
NOTE: Each environment can host up to 4 nodes per the resource limitations of the default plan.
- From the environment home screen, click the Create dropdown and select New App Credentials
- Select a membership and supply a name for the credentials. Click Next.
- You will be supplied with a USERNAME and PASSWORD. Make sure to store the password somewhere safe. The Kaleido backend does not hold this key and it is not retrievable. You can, however, generate new authentication credentials if need be.
- Each membership bound to a node requires its own set of app credentials in order to achieve external connection to said node.
NOTE: Each environment can host up to 10 sets of active app credentials per the resource limitations of the default plan
The upcoming Kaleido Connect section describes in detail how to leverage these credentials to secure access to your node(s). Note that these credentials are NOT OPTIONAL and must be used by any external clients or applications attempting a connection.
Each environment exposes a set of services that offer supplementary functionality with the blockchain. These services are listed in a table at the bottom of your environment’s home screen.
- Block Explorer – a system level console that offers varying levels of chain analytics. See the Kaleido Explorer documentation for more information on its features.
- Ether Pool – a pre-funded wallet allowing for ether to be added to internal or external user accounts. Certain transactions using the Geth client require gas and users can optionally choose to integrate the native Ethereum currency into smart contracts and applications.
- Mainnet Tether – a network relay responsible for aggregating a collectively signed root hash of synchronized state snapshots and proxying the hash to a smart contract on the Ethereum main net. Protects against historical rewrites and retroactive collusion attempts.
- HD Wallet – a key tree offering an unlimited supply of Ethereum account addresses and private signing keys. The HD Wallet is a “member” type service that can be used to submit transactions anonymously by incrementing through account indices on a per-transaction basis. Use the +Add dropdown and select Add Services to provision an HD Wallet.
- IPFS – a file system node used to store large files/images off-chain. An IPFS node is a “member” type service that provide censorship resistance against unilateral deletion of a file and offer quick access to uploaded files by referencing a content hash. Files can be downloaded in their entirety or in portions by selecting one or more of the files shards. Use the +Add dropdown and select Add Services to provision an IPFS node.
- ID Registry – a decentralized on-chain registry of validated x509 certificates mapped to organizations, Ethereum addresses and end users. The ID Registry is a “utility” type service (owned by the environment) that allows incoming transactions to be unambiguously associated with a parent organization. The Registry also offers a public key/value database to store relevant information against registered Ethereum addresses. Use the +Add dropdown and select Add Services to provision an ID Registry.
The homepage of the Kaleido console will display all consortia associated with your organization. Click the Create Consortium button at the top right of the page to create an additional consortium. Alternatively, click on an existing consortium to visit its overview page.
Click the Support tab to discover different avenues for technical support. Additionally, you can utilize the Kaleido feedback tool located in the bottom right portion of all console screens.
Click the API tab at the top of the screen to manage API Keys associated with your organization. Click the Settings tab at the top of the screen to manage personal and organizational settings. You can use the Settings screen to update the name of your Kaleido Organization, change account password, link AWS accounts, onboard co-administrators, etc.
The overview page of a consortium lists out all provisioned environments, as well as the current and pending memberships. To create additional environments, click the Add dropdown and select New Environment. To add additional members, click the Add dropdown and select New Member. To invite an external organization to the consortium, click the Add dropdown and select Invite Organization. To add a node within an existing environment, click the Create dropdown and select New Node.
The overview page of an environment lists out all provisioned nodes, active configurations and active security credentials. To provision additional nodes, click the Add dropdown and select New Node. To provision additional application credentials, click the Add dropdown and select New App Credentials. To see low-level details of a node (e.g. endpoints, addresses, etc.) click the node name or the expandable dropdown at the far right of the node’s row.
The alternative approach for generating a consortium + environment is to utilize the Kaleido REST API to administratively build out your network. The comprehensive API 101 tutorial walks you through the process of calling these APIs to create your consortium, configure an environment, provision nodes and generate app credentials. If you elect for this approach, you will still need to briefly visit the UI in order to obtain an API key for these privileged calls.