ChainLink

API

See the API documentation for more details about the API.

Overview

Assignments

Assignments are the main model for defining work to be done by ChainLink. An Assignment specifies a series of processing steps, Subtasks, which form a processing pipeline. Assignments include up front configuration for the Subtask pipeline, as well as instructions on when and how the Assignment can be triggered to run.

Snapshots

Whenever an Assignment is triggered to run, a Snapshot is created. The Snapshot is the record of the work that was done, and the steps taken along the way to reach the final Snapshot result.

Snapshots can be triggered either through upfront scheduling of the Assignment and/or by on demand requests through any of the Adapters.

Subtasks

Assignments are made up of a sequence of Subtasks. Subtasks are small specialized processes, designed to be modular and reusable with many other types of Subtasks.

Every time a Snapshot is created it starts by processing the first Subtask. The result of each Subtask is fed into the next Subtask, until the final Subtask is processed. The result of the final Subtask becomes the result of the entire Snapshot.

Data is passed between Subtasks as a JSON payload. By convention the main field that information is read from is stored as the top level key value, but other keys can be used and additional information can be stored in their payload.

Subtasks are initially configured when an assignment is defined, but they can also be dynamically configured with the data passed in from previous Subtasks.

Adapters

The processing work for each Subtask is handled by its Adapter. Adapters are where the processing and communication with external services happens. Subtasks are specific configurations of how work is to be handled by an Adapter.

ChainLink ships with a few adapters built in, but additional External Adapters can be created to add custom functionality. External Adapters are external services, which are communicated with via HTTP. External Adapters allow for functionality of ChainLink to be easily extended and can be written in which ever language is best suited. Conforming to a minimal HTTP interface is the only requirement for creating your custom External Adapters.

The Adapters that ship with ChainLink core are:

bitcoinComparisonJSON Returns a signed Bitcoin transaction. Signs either a completion transaction or a failure transaction based on a value comparison of the input.
ethereumBytes32 Formats the input as Ethereum bytes32 value and writes it into the specified contract. Returns the unformatted value that was provided as input.
ethereumInt256 Formats the input as Ethereum int256 value and writes it into the specified contract. Returns the unformatted value that was provided as input.
ethereumUint256 Formats the input as Ethereum uint256 value and writes it into the specified contract. Returns the unformatted value that was provided as input.
ethereumFormatted Writes a preformatted Ethereum hexadecimal value into the blockchain as configured. Returns the preformatted value that was provided as input.
ethereumLogWatcher Returns the data field of an Ethereum event log, if one is provided. Otherwise, returns the value that was provided as the input. (Requires WeiWatchers integration.)
httpGetJSON Retrieves JSON and returns the specific field selected in the configuration.
jsonReceiver Generates a URL for the oracle to receive JSON push notifications. Parses the pushed JSON and returns the specific field selected in the configuration.

If you are interested in other types of Adapters feel free to reach out.

Adapter Schemas

Adapter Schemas allow for Adapters to be modular enough to be used with many types of Adapters, but still remain reliable when used with other Adapters that may not even be defined yet. Adapter Schemas are JSON Schemas that specify the input requirements and output formats of each adapter. For more information on the various schemas used by ChainLink check out the Schemas repo.

Development

Requirements

ruby(v2.0.0+)
postgres(v9.3+)

Install

git clone https://github.com/oraclekit/chainlink && cd chainlink
gem install bundler && bundle
rake db:create db:migrate

Start

foreman start

Testing

To run the full test suite, including integration tests, you need an instance of DevNet running on your machine. This requires first installing Parity. Once Parity is installed, run the following commands:

git clone https://github.com/oraclekit/devnet.git
cd devnet
./start

Then to run the full test suite run:

rake

Or test a specific test:

rspec spec/models/assignment_spec.rb:57

smartcontractkit / chainlink-ruby

readme