API Reference for the Kaleido REST API Gateway (1.0)

Download OpenAPI specification:Download

Enterprise Grade Connectivity for your Applications

  • Deploy your first Smart Contract in seconds
  • REST APIs for your on-chain Logic & Data
  • Deploy and Manage Smart Contracts
  • OpenAPI Docs and API Exerciser built-in
  • Reliable Transaction Streaming (over Kafka)
  • Reliable Event Streams

Smart Contract REST APIs

Friendly and intuitive REST APIs generated for your smart contracts

Kaleido REST API Gateway (ethconnect) archtecture

    • Generated directly from your Solidity source code and devdocs
    • Simple JSON types
    • Familiar REST semantics
    • OpenAPI 2.0 (Swagger) compliant definitions
    • Built-in UI exerciser
    • Factory APIs to deploy contract instances
    • Instance APIs to query and transact with any deployed contract
    • Subscription APIs to deliver events reliably to Event Streams
    • Automated Gas estimation
  • Synchronous mode
    • Query on-chain data, returning simple JSON types
    • Simulate transactions
    • Submit transactions with blocking calls (just like web3 APIs)
  • Asynchronous mode
    • Reliably stream transactions onto the chain
    • Pre-built infrastructure that is required for production blockchain workloads at scale
    • Also ideal for webhooks - fire and forget
    • Optimized throughput, smoothing peaks in workload to avoid flooding blocks
    • Nonce management
    • Backed by a fully-managed reliable Kafka messaging backbone
    • Receipt store for transaction results
  • Private transaction support
    • Tessera (previously Constellation) - from the Quorum project
    • Orion (sister project to Hyperledger Besu) - from PegaSys engineering
  • High-performance gateway runtime
    • Written in Golang using optimized Ethereum libraries for ABI packing/unpacking
    • Colocated with the Ethereum node
    • Architected for both horizonal scale and ordered delivery
    • Core made available as Apache 2.0 open source in the ethconnect project

Webhook for async transactions

Send a simple JSON or YAML payload that can:

  • Compile and deploy contracts from in-line Solidity source code
  • Deploy contracts from bytecode
  • Asynchronously deliver transactions to your ethereum node over our Kafka backbone
  • Invoke solidity transactions without needing to first install an ABI

You get a response immediately, including an id that you can query for results in the receipt store later.

The same reliable transport as is used on POST methods of the installed REST Gateway generated interfaces (installed via the /abis paths), when kld-sync is unset.

Ideal for use as a webhook endpoint for an integration tool that can emit sevents over HTTPS. Also useful if your application wants to construct the full details for the transaction to sent to a contract, or install a new contract, without first teaching the REST API Gateway about the Solidity interface (ABI).

There are two variations of the webhook:

  • Fire & forget on / and /fasthook: responds as soon as the message is sent to the Kafka client library
  • Kafka acknowledged on /hook: responds only once Kafka has acknowledged receipt of the message

Request Body schema:
headers
required
object

Headers section used in requests, and extended in asynchronous response messages

from
required
string ^(0x)?[0-9a-zA-Z]{40}$

The address to use when signing the transaction. Must be a wallet managed by Kaleido. For example account[0] on the node.

to
string ^(0x)?[0-9a-zA-Z]{40}$

SendTransaction only: The contract address to send the transaction too.

methodName
string

SendTransaction only: The method name to invoke on the target contract.

params
Array of objects

The parameters to pass to the ethereum method or constructor.

soldity
string

DeployContract only: Soldity source code to compile.

contractName
string

DeployContract only: When there are multiple contracts in the compiler output, this field is required to select the contract to deploy.

compilerVersion
string
Default: "0.4"

DeployContract only: solc compiler version to use. Only the major version is used in the supplied semver, such as 0.4 or 0.5.

compiled
string <byte>

DeployContract only: Pre-compiled base64 encoded byecode - alternative to supplying Solidity code for compilation.

gas
string

The maximum gas the transaction can consume - omit to allow ethconnect to perform a gas estimation

gasPrice
string

The ETH price offered for gas - omit to use a gas price of zero

value
string

An optional ETH value to send along with the tranaction

nonce
string ^[0-9]+$

Assign an explicit nonce to the transaction - omit to allow ethconnect to manage the nonce

privateFrom
string

EEA privacy extensions privateFrom address for private transaction support (Quorum Tessera / PegaSys Orion)

privateFor
Array of strings

EEA privacy extensions privateFor addresses for private transaction support (Quorum Tessera / PegaSys Orion)

Responses

200

Webhook acknowledgement

post /

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/

Request samples

Content type
Copy
Expand all Collapse all
{
  • "headers":
    {
    },
  • "from": "string",
  • "to": "string",
  • "methodName": "string",
  • "params":
    [
    ],
  • "soldity": "string",
  • "contractName": "string",
  • "compilerVersion": "0.4",
  • "compiled": "string",
  • "gas": "string",
  • "gasPrice": "string",
  • "value": "string",
  • "nonce": "string",
  • "privateFrom": "string",
  • "privateFor":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "sent": true,
  • "msg": "string"
}

Fire & forget webhook

Responds as soon as the message is passed to the Kafka client library.

Request Body schema:
headers
required
object

Headers section used in requests, and extended in asynchronous response messages

from
required
string ^(0x)?[0-9a-zA-Z]{40}$

The address to use when signing the transaction. Must be a wallet managed by Kaleido. For example account[0] on the node.

to
string ^(0x)?[0-9a-zA-Z]{40}$

SendTransaction only: The contract address to send the transaction too.

methodName
string

SendTransaction only: The method name to invoke on the target contract.

params
Array of objects

The parameters to pass to the ethereum method or constructor.

soldity
string

DeployContract only: Soldity source code to compile.

contractName
string

DeployContract only: When there are multiple contracts in the compiler output, this field is required to select the contract to deploy.

compilerVersion
string
Default: "0.4"

DeployContract only: solc compiler version to use. Only the major version is used in the supplied semver, such as 0.4 or 0.5.

compiled
string <byte>

DeployContract only: Pre-compiled base64 encoded byecode - alternative to supplying Solidity code for compilation.

gas
string

The maximum gas the transaction can consume - omit to allow ethconnect to perform a gas estimation

gasPrice
string

The ETH price offered for gas - omit to use a gas price of zero

value
string

An optional ETH value to send along with the tranaction

nonce
string ^[0-9]+$

Assign an explicit nonce to the transaction - omit to allow ethconnect to manage the nonce

privateFrom
string

EEA privacy extensions privateFrom address for private transaction support (Quorum Tessera / PegaSys Orion)

privateFor
Array of strings

EEA privacy extensions privateFor addresses for private transaction support (Quorum Tessera / PegaSys Orion)

Responses

200

Webhook acknowledgement

post /fasthook

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/fasthook

Request samples

Content type
Copy
Expand all Collapse all
{
  • "headers":
    {
    },
  • "from": "string",
  • "to": "string",
  • "methodName": "string",
  • "params":
    [
    ],
  • "soldity": "string",
  • "contractName": "string",
  • "compilerVersion": "0.4",
  • "compiled": "string",
  • "gas": "string",
  • "gasPrice": "string",
  • "value": "string",
  • "nonce": "string",
  • "privateFrom": "string",
  • "privateFor":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "sent": true
}

Kafka acknowledged webhook

Waits for an acknowledgment from Kafka that the message has been delivered to a topic partition before responding.
Recommended when reliable transaction delivery is required.

Request Body schema:
headers
required
object

Headers section used in requests, and extended in asynchronous response messages

from
required
string ^(0x)?[0-9a-zA-Z]{40}$

The address to use when signing the transaction. Must be a wallet managed by Kaleido. For example account[0] on the node.

to
string ^(0x)?[0-9a-zA-Z]{40}$

SendTransaction only: The contract address to send the transaction too.

methodName
string

SendTransaction only: The method name to invoke on the target contract.

params
Array of objects

The parameters to pass to the ethereum method or constructor.

soldity
string

DeployContract only: Soldity source code to compile.

contractName
string

DeployContract only: When there are multiple contracts in the compiler output, this field is required to select the contract to deploy.

compilerVersion
string
Default: "0.4"

DeployContract only: solc compiler version to use. Only the major version is used in the supplied semver, such as 0.4 or 0.5.

compiled
string <byte>

DeployContract only: Pre-compiled base64 encoded byecode - alternative to supplying Solidity code for compilation.

gas
string

The maximum gas the transaction can consume - omit to allow ethconnect to perform a gas estimation

gasPrice
string

The ETH price offered for gas - omit to use a gas price of zero

value
string

An optional ETH value to send along with the tranaction

nonce
string ^[0-9]+$

Assign an explicit nonce to the transaction - omit to allow ethconnect to manage the nonce

privateFrom
string

EEA privacy extensions privateFrom address for private transaction support (Quorum Tessera / PegaSys Orion)

privateFor
Array of strings

EEA privacy extensions privateFor addresses for private transaction support (Quorum Tessera / PegaSys Orion)

Responses

200

Webhook acknowledgement (with Kafka ack)

post /hook

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/hook

Request samples

Content type
Copy
Expand all Collapse all
{
  • "headers":
    {
    },
  • "from": "string",
  • "to": "string",
  • "methodName": "string",
  • "params":
    [
    ],
  • "soldity": "string",
  • "contractName": "string",
  • "compilerVersion": "0.4",
  • "compiled": "string",
  • "gas": "string",
  • "gasPrice": "string",
  • "value": "string",
  • "nonce": "string",
  • "privateFrom": "string",
  • "privateFor":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "sent": true,
  • "msg": "string"
}

Add new contract REST API

Compiles the supplied Solidity source code into an ABI (and devdocs) from a single file or zip/tarball, then builds a new REST API that can then be used:

  • To query data from any existing contract deployed on-chain
  • As a factory to deploy contract instances on-chain
  • To subscribe for events matching the signatures defined in the Solidity source code
  • To install a friendly named API onto this node that binds a friendly API to an individual smart contract

As there are a number of functions performed by the installed REST API, and the paths are all bespoke to the methods in the Solidity itself, the installed API comes with its own OpenAPI 2.0 (Swagger) definition.

A link to the generated API definition is included in the response payload.

As the primary input is file data the Content-Type for the payload on route is multipart/form-data, rather than JSON.

Request Body schema: multipart/form-data
findsolidity
string

Discovery mode: If set then the response will be an array of Solidity files found in the supplied files, rather than attempting the compilation (can also be set as a URL query parameter)

findcontracts
string

Discovery mode: If set then the response will be an array of contract names returned by solc in the compiled output, rather than attempting to install the REST API (can also be set as a URL query parameter)

source
string

If a zip/tarball is supplied containing multiple solidity files, this field is required to set the Solidity source code file to compile (can also be set as a URL query parameter). Use findsolidity to find possible values.

contract
string

If the compilation results in multipel contracts, this field is required to set the contract name to use when deploying contracts via the factory methods (can also be set as a URL query parameter). Use findcontracts to find possible values.

*
string <binary>

Any other properties should be file-content: .sol .zip .tar .tgz .tar.gz .tar.bz2 files are supported

Responses

200

Installed ABI definition

post /abis

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/abis

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "created": "2020-03-16T13:19:23Z",
  • "id": "string",
  • "description": "string",
  • "path": "string",
  • "deployable": true,
  • "openapi": true,
  • "compilerVersion": true
}

List contract REST APIs

List the previously installed ABI definitions with available factory, query & event-subscription REST APIs

Responses

200

Installed ABI definition

get /abis

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/abis

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get contract REST API

List details of a single previously installed ABI definitions with a factory, query & event-subscription REST API

path Parameters
abi_id
required
string

The ID of the install ABI

Responses

200

Installed ABI definition

get /abis/{abi_id}

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/abis/{abi_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "created": "2020-03-16T13:19:23Z",
  • "id": "string",
  • "description": "string",
  • "path": "string",
  • "deployable": true,
  • "openapi": true,
  • "compilerVersion": true
}

List contract instance APIs

List the previously installed ABI definitions with available REST APIs

Responses

200

Installed ABI definition

get /contracts

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/contracts

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get contract instance API

List the previously installed ABI definitions with available REST APIs

path Parameters
contract_address_or_friendly_name
required
string

The ID of the install ABI

Responses

200

Installed ABI definition

get /contracts/{contract_address_or_friendly_name}

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/contracts/{contract_address_or_friendly_name}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "created": "2020-03-16T13:19:23Z",
  • "id": "string",
  • "description": "string",
  • "path": "string",
  • "deployable": true,
  • "openapi": true,
  • "compilerVersion": true
}

Event Streams

Reliably initiate apps and business processes from on-chain events, and sync data to an off-chain cache

Kaleido Event Streams

  • Intuitive REST API to subscribe to simple JSON events
    • Subscribe to events by name - no need to understand Ethereum 'topic' hashes
    • Subscribe to all events with a particular signature
    • Subscribe to events on individual constract instances
    • Delivered as a simple JSON array of events, with JSON types
    • Delivery over Webhooks (HTTPS) with support for custom authentication headers
  • At-least once delivery of events
    • Check-point restart based on block-number to restart streams after restarting a node
    • Exponential back-off retry of delivery for intermittent connectivity issues
    • Efficient blocking retry for longer periods of application downtime
  • High performance batched delivery
    • Batching of events for delivery to an analytics stream, or efficient insert into a database
    • No complexity required in the application itself
  • Ideal for serverless functions
    • AWS Lambda functions
    • Microsoft Azure functions

Add Event Stream

Add a new event stream, to which subscriptions can deliver messages

Responses

200

Event stream

post /eventstreams

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/eventstreams

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "created": "2020-03-16T13:19:23Z",
  • "id": "string",
  • "path": "string",
  • "type": "webhook",
  • "suspended": true,
  • "batchSize": 1,
  • "batchTimeoutMS": 5000,
  • "retryTimeoutSec": 0,
  • "errorHandling": "block",
  • "blockedReryDelaySec": 30,
  • "webhook":
    {
    }
}

List Event Streams

Returns a list of all event streams registered on this node

Responses

200

Event streams

get /eventstreams

Each Kaleido node gets assigned a unique REST API Gateway URL.
You can find it in the "+ Connect" panel of your node.

https://{environment_id}-{node_id}-connect.{zone_domain}.kaleido.io/eventstreams

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {