HomeUsing KaleidoThe Blockchain NetworkConnecting to your Network

Connecting to your Network

Kaleido offers a number of avenues for connecting to a node and issuing blockchain transactions.  The two main doors are via the standard JSON/RPC interface with a web3 client library like Web3.js and popular Ethereum tooling like Truffle, or via the Enterprise REST API Gateway which provides simplified client-side communication not reliant on Ethereum APIs and language-specific libraries.  The Deploy, Invoke and Query a Smart Contract tutorial in the Quick Start category walks through a simple transaction via the REST API Gateway.  The Developers section of the docs contains a number of examples and deeper dives into both approaches.

Ways to connect

Kaleido Connect provides the following ways to connect securely to your node:

  • JSON/RPC over TLS-secured HTTPS or WebSockets
  • Webhooks for easy code-free submission of transactions via YAML or JSON over HTTPS
  • Kafka for high-throughput reliable asynchronous streaming of transactions into your node(s)

Authentication

All external connections to nodes on the Kaleido platform are protected through strongly-generated access keys. These must be passed during connection as follows:

  • JSON/RPC (HTTPS or WebSockets) – TLS transport encryption + Basic Auth credentials
  • Webhooks (HTTPS) – TLS transport encryption + Basic Auth credentials
  • Kafka – TLS transport encryption + SASL Plaintext credentials

Webhooks

The simplest way to get started submitting a transaction to Kaleido, is to use the Webhooks interface.

Only available for nodes created after upgrading to Release Version 0.1.10 or later

To get started, follow the instructions in the Submit a transaction with Kaleido Connect section.

For a deeper dive into the Webhooks feature of Kaleido Connect, please refer to the kaleido-io/ethconnect OSS project page on Github.

JSON/RPC

This is the low-level API exposed by the Ethereum node. Most applications will leverage an Ethereum-compatible client library to send transactions to the node, rather than communicating directly over JSON/RPC.

The JSON/RPC client libraries that have been validated against Kaleido nodes include:

Kafka

If you are building an application to exploit the asynchronous nature of Ethereum, or you have an Enterprise Service Bus (ESB) or other Enterprise Application Integration (EAI) tier in your architecture, you might consider streaming transactions into Kaleido directly over the reliable Kafka message bus built into the platform.

You can learn more about the Kafka feature of Kaleido Connect at the kaleido-io/ethconnect OSS project page on Github.

Topology and details

  • Each environment is created against the membership list defined within the consortium
  • Nodes are generated on behalf of a membership and within the context of an environment
  • App credentials are confined to a specific environment and, by extension, to the member nodes within that environment
  • The hierarchy can be seen as “Consortium” -> “Environment” -> “App Credentials”
  • App credentials CANNOT be leveraged across environments
  • Each environment supports up to 10 app credentials per the resource limitations of the default plan
  • Nodes can leverage multiple app credentials within the same environment. For example, take Environment A with member1.node and two app credentials – member1.appcreds.A & member1.appcreds.B. Both credentials can be used to connect to the member1.node within Environment A.

Generating the credentials

There are two approaches for generating the Basic Auth credentials – the user interface or the administrative API.

UI

  • Navigate to an existing environment within your consortium
  • Click the Create dropdown at the top right of the screen and select New App Credentials
  • Choose a membership for the credentials and optionally provide a name. You will only be able to create credentials for memberships owned by your organization.
  • When creating multiple sets of credentials, it is strongly recommended to supply a value for the name field. Click Next
  • Take note of the username and password. The password is generated by the Kaleido platform but is not stored by the backend (Kaleido only stores a salted hash for the password in order to validate it during login). As such, it is your responsibility to record this password and keep it in a safe place. If you lose the secret then you will have to recreate the credentials.
  • Credentials under your control will appear at the bottom of the environment panel.

REST API

The API 101 tutorial walks through the process of using the administrative API key to exercise privileged API calls to the Kaleido backend. To recap:

  • generate an API Key for your account and set APIKEYAPIURLHDR_AUTH and HDR_CT as environment variables. Alternatively you can pass in the full values for each of these fields.
  • retrieve the membership details for your consortium. The following snippet assumes that the CONSORTIUM variable has been properly set:
curl -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/$CONSORTIUM/memberships" | jq
  • send a POST to the /appcreds API with the targeted membership ID and an optional name in the body of the call. The following snippet assumes that both the CONSORTIUM and ENVIRONMENTvariables have been properly set:
curl -X POST -d '{"membership_id":"abcde12345”, "name":"MY SECRET CREDENTIALS"}' -H "$HDR_AUTH" -H "$HDR_CT"  "$APIURL/consortia/$CONSORTIUM/environments/$ENVIRONMENT/appcreds" | jq
  • the POST will return a JSON array containing your username and password. For example:
{
  "membership_id": "abcde12345",
  "name": "MY SECRET CREDENTIALS",
  "auth_type": "basic_auth",
  "_id": "abcddbdoxy",
  "_revision": "0",
  "username": "abcddbdoxy",
  "password": "BXdqdrvTOdLZ44MXcEh3mvTPMvSxNH_ysUCBF94Xhec"
}

Examples

The Public & Private Transactions and Truffle tutorials provide thorough exposition on credential generation and URL construction. Each sample demonstrates how to leverage the Ethereum accessible web3 javascript API along with a Kaleido node endpoint and basic auth credentials to send external calls.

web3 syntax

Web3 requires the provider object and a specified connection protocol to communicate with a node. The Kaleido platform exposes the http and web socket endpoints for every node, which can be used accordingly with the web3-providers-http and web3-providers-ws sub packages for external connection.

The Web3.providers.HttpProvider method accepts one of two valid formats:

  • A fully qualified string constructed as: 'https://username:password@nodeURL'
  • An array of variables constructed as: 'nodeURL', 0, 'username', 'password'

The Web3.providers.WebsocketProvider method accepts only one valid format:

  • A fully qualified string constructed as: 'wss://username:password@nodeURL'

The test.js program from the Public & Private Transactions tutorial takes one of these formats (dependent on the method) as an argument to the url parameter when driving the application:

// application code from test.js using http
let web3 = new Web3(new Web3.providers.HttpProvider(url));

OR

// application code from test.js edited to use wss
let web3 = new Web3(new Web3.providers.WebsocketProvider(url));
# sample call for http
node test.js --url=https://cqylxek2ab:dcYmQkh2rkA64BF8TvYl3fAZx65FJ8NtoGGrvLxYNJs@thd1j9voab-xrcx9cvsab-rpc.stage.kaleido.io --deploy --verbose
# sample call for wss
node test.js --url=wss://cqylxek2ab:dcYmQkh2rkA64BF8TvYl3fAZx65FJ8NtoGGrvLxYNJs@thd1j9voab-xrcx9cvsab-wss.dev.kaleido.io --deploy --verbose
  • Example of a fully qualified string injected directly into an application using the http provider method:
web3 = new Web3(new Web3.providers.HttpProvider('https://cqylxek2ab:dcYmQkh2rkA64BF8TvYl3fAZx65FJ8NtoGGrvLxYNJs@thd1j9voab-xrcx9cvsab-rpc.stage.kaleido.io'))
  • Example of a fully qualified string injected directly into an application using the web socket provider method:
web3 = new Web3(new Web3.providers.WebsocketProvider('wss://cqylxek2ab:dcYmQkh2rkA64BF8TvYl3fAZx65FJ8NtoGGrvLxYNJs@thd1j9voab-xrcx9cvsab-wss.stage.kaleido.io'))
  • Example of a properly formatted array injected directly into an application using the http provider method:
web3 = new Web3(new Web3.providers.HttpProvider('https://thd1j9voab-xrcx9cvsab-rpc.stage.kaleido.io', 0, 'cqylxek2ab', 'dcYmQkh2rkA64BF8TvYl3fAZx65FJ8NtoGGrvLxYNJs'))