NAV

Introduction

Welcome to the ChainLink API documentation. An oracle provides data into the blockchain that cannot be accessed by the blockchain itself, due to consensus constraints. ChainLink makes it easy to integrate external data with the blockchain, both passing it in and sending it out.

See the section on Assignments for information on how to specify the data you would like to connect to the blockchain.

ChainLink is the core of the Oracle Kit, learn more here.

Installation

Prerequisites

Install

docker pull smartcontract/chainlink
docker run -it --env-file=.env smartcontract/chainlink rake oracle:initialize

First set up your configuration, by creating a .env file, that has at least the variables set in the .env example.

Once you have set up your database and configuration, and you are ready to initialize ChainLink.

On initialization, the oracle will give the option to print the first list of coordinator credentials. Be sure to record the coordinator credentials for use with the oracle moving forward.

Run

docker run -t --env-file=.env smartcontract/chainlink

Once the database and Etehreum node are set up, you can run your oracle with your configured environment.

For more information on setting up an instance, or building it locally, visit the wiki page on installation. Alternatively, if you want to view the source code, you can do so on GitHub.


To have a managed instance spun up for you, contact us at [email protected].

Authentication

curl -u apiKey:apiSecret
  http://localhost:6688/assignments/f0577c3e-9e5a-4840-9c9b-37d326c3d2e3

Both coordinators and adapters need to authenticate to access the data they are allowed access to. In both cases authentication is handled via HTTP Authentication.

Coordinator Authentication

To access an assignment you must have a set of coordinator credentials. An initial set of coordinator credentials are generated and printed when the node’s initialize command is run.

All assignments are associated with a coordinator, so in order to create an assignment you must authenticate using its coordinator’s credentials. After creating an assignment all subsequent updates will be sent to its coordinator, if the coordinator has specified a URL.

Adapter Authentication

Assignments can optionally be associated with an external adapter. The adapter credentials are automatically generated when the adapter record is created. From then on ChainLink requires that all communication to and from that adapter must be authenticated.

Assignments

The work specified for ChainLink is called an Assignment. Assignments can be handled by the oracle itself, or the oracle’s capabilities can be expanded by creating an adapter for the oracle.

Assignments make up the specifcation of the work, but each piece of the ongoing work is captured in a snapshot. Snapshots are generated by whichever adapter is handling the work, recorded by the oracle, and reported back to the coordinator.

Anatomy of an Assignment

Assignments are the core of the ChainLink model, they are the specifications of work given to an oracle. The main pieces of an assignment consist of the adapter, the scheduling, and the payment specification. Optionally, an assignment can have a description and signatures from the parties involved.

Adapter Type and Parameters

Every assignment has a type, which specifies the kind of adapter the oracle will use to perform the work requested. Each different type of adapter requires different parameters, some passed on the blockchain, some passed off chain. The parameters each adapter will accept are specified ahead of time by the adapter’s creator.

ChainLink currently ships with several built in adapters, see the Core Adapters section for more information.

Subtasks

{
  "adapterType": "ethereumBytes32",
  "adapterParams": {
    "address": "0x34d946ab16079a97976e006079efe422b1fe1905",
    "method": "8b147245"
  }
}

Subtasks are a series of steps taken by the oracle to complete an assignment. Each time an assignment is updated it processes its pipeline of subtasks, each of which is handled by an adapter. The subtask’s initial configuration, along with any data passed from earlier subtasks in the pipeline are passed to the adapter for each update. The adapter’s output for the subtask is passed to the next subtask, until the final subtask’s output determines the values of the assignment’s latest snapshot.

Parameter Type Description
adapterType string identifies the type of work to be done
adapterParams object a JSON object meeting the requirements of the adapter’s schema, setting the initial configuration for the adapter

Scheduling

Some oracle services are needed on a scheduled basis. For these use cases, ChainLink provides a simple way to schedule tasks based on the Cron scheduling format, or specify times to run at.

Assignments that do not require a schedule, instead work on demand, can skip the schedule or offer a combination of both on demand updates and scheduled updates.

All assignments require a end time and allow for an optional start time, defaulting to the assignment start time. Times are specified using Unix timestamps(UTC).

{
  "minute": "1",
  "hour": "17",
  "dayOfMonth": "*",
  "monthOfYear": "*",
  "dayOfWeek": "*",
  "startAt": "1477941966",
  "endAt": "1793474734",
  "runAt": ["1518726087", "1802722889"]
}
Parameter Type Description
minute string cron style minute listing for how often to run recurring snapshots
hour string cron style hour listing for how often to run recurring snapshots
dayOfMonth string cron style day of month listing for how often to run recurring snapshots
monthOfYear string cron style month of year listing for how often to run recurring snapshots
dayOfWeek string cron style day of week listing for how often to run recurring snapshots
startAt string a unix timestamp for when to start the recurring snapshot schedule. Optional defaults to the time the assignment is created.
endAt string a unix timestamp for when to end the recurring snapshot schedule
runAt array an array of unix timestamps for discrete update times

Payment

{
  "currency": "ETH",
  "perDay": "0",
  "perRequest": "1000000000000000"
}

Space on blockchains is limited and thus costly to utilize. On the other side of the oracle, API calls to protected APIs are often behind pay walls. Oracle services by their nature come with expenses. For this reason, the ChainLink platform has a way to specify service prices for each adapter.

Prices are generally set per request made by the oracle; This can be prepaid for scheduled services, or paid per request for on demand services. Additionally, prices can be set based on the duration of required availability of the oracle.

The currency is configurable based on the networks that the oracle operates in. Currency amounts are always specified in the lowest possible denomination of the currency(Satoshis, Wei, etc.).

Create

curl -u apiKey:apiSecret -X POST -H 'Content-Type: application/json'
  -d '{"assignment":{"subtasks":[{"adapterType": "httpGetJSON", "adapterParams": {"endpoint": "https://bitstamp.net/api/ticker/", "fields": ["last"]}},{"adapterType":"ethereumBytes32"}]}, "schedule":{"endAt":"1478028219","hour":"0","minute":"0"}},"version":"1.0.0"}'
  http://localhost:6688/assignments

JSON response:

{
  "assignmentHash": "b2e55902bb7728871fa69f503007577ef8a1ae449f486b5c0aaf644661d216d1",
  "signature": "1cb6770f6977710c7c3e0d336d3d2244a0d276056029cb83f414d8641ef412218d2a36df9ccde31ee50310d9eef098fa153b34ad9075d02737243a59c5dbd6d357",
  "xid": "561b78af-e163-4972-9d4a-5dc15e02d977"
}

A POST to /assignments will return the XID, or external ID, which is used to identify the assignment in the future. The response also includes a hash of the assignment specified, and a signature of that hash to attest to the oracle’s acceptance of the assignment.

Parameter Type Description
subtasks array an ordered list of the assignment’s subtasks
schedule object an assignment schedule object
version string specify the version of the assignment spec, use “1.0.0” for the latest version

Show

curl -u apiKey:apiSecret http://localhost:6688/assignments/f0577c3e-9e5a-4840-9c9b-37d326c3d2e3

JSON response:

{
  "adapterType": "ethereumBytes32JSON",
  "endAt": "1480720191",
  "parameters": {
    "fields": ["last"],
    "endpoint": "https://bitstamp.net/api/ticker/"
  },
  "snapshots": [
    {
      "description": "Blockchain Record: 0x865167b8e74daec5e0f2faf4975b7fe21d791b83d7c6ba10ece7e4d0b193461e",
      "descriptionURL": "https://testnet.etherscan.io/tx/0x865167b8e74daec5e0f2faf4975b7fe21d791b83d7c6ba10ece7e4d0b193461e",
      "details": {
        "value": "726.60"
      },
      "summary": "Assignment \"1\" updated its value to \"726.60\".",
      "value": "726.60",
      "xid": "0x865167b8e74daec5e0f2faf4975b7fe21d791b83d7c6ba10ece7e4d0b193461e"
    }
  ],
  "startAt": "1478128191",
  "status":"in progress",
  "xid": "f0577c3e-9e5a-4840-9c9b-37d326c3d2e3"
}

A coordinator can check the state of one of their assignments and get a list of all the related snapshots.

Parameter Type Description
adapterType string identifies the type of work to be done
endAt string specify the time the assignment will run until (Unix timestamp)
parameters object a JSON object meeting the requirements of the adapter’s schema
snapshots array an list of associated snapshot objects
startAt string specify the time the assignment is/was scheduled to start at (Unix timestamp)
status string assignment’s current execution status
xid string a unique external ID to identify the assignment

Snapshots

Parameter Type Description
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Snapshots

Create

curl -u apiKey:apiSecret -X POST
  http://localhost:6688/assignments/f0577c3e-9e5a-4840-9c9b-37d326c3d2e3/snapshots

JSON response:

{
  "assignmentXID": "f0577c3e-9e5a-4840-9c9b-37d326c3d2e3",
  "description": "Blockchain record: 0x2d8b24bc521a7fb02c1eb3e157296517f628646f6b5b8ee8952034fa2ca7f385",
  "descriptionURL": "https://etherscan.io/tx/0x2d8b24bc521a7fb02c1eb3e157296517f628646f6b5b8ee8952034fa2ca7f385",
  "details": {
    "source": "bitstamp.net",
    "txid": "0x2d8b24bc521a7fb02c1eb3e157296517f628646f6b5b8ee8952034fa2ca7f385",
    "value": "1035.03"
  },
  "summary": "The oracle value was updated to \"1035.03\"",
  "value": "1035.03",
  "xid": "0799f829-15e8-475f-8f3e-a55488713da0"
}

A POST to /assignments/XID/snapshots will always return the XID of a snapshot. Depending on what steps are required of the assignment, it may return all of the snapshot immediately, or if the details take time to compute the results of the snapshot will be retrievable with the assignment’s XID.

Parameter Type Description
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Show

curl -u apiKey:apiSecret http://localhost:6688/snapshots/0799f829-15e8-475f-8f3e-a55488713da0

JSON response:

{
  "assignmentXID": "f0577c3e-9e5a-4840-9c9b-37d326c3d2e3",
  "description": "Blockchain record: 0x2d8b24bc521a7fb02c1eb3e157296517f628646f6b5b8ee8952034fa2ca7f385",
  "descriptionURL": "https://etherscan.io/tx/0x2d8b24bc521a7fb02c1eb3e157296517f628646f6b5b8ee8952034fa2ca7f385",
  "details": {
    "source": "bitstamp.net",
    "txid": "0x2d8b24bc521a7fb02c1eb3e157296517f628646f6b5b8ee8952034fa2ca7f385",
    "value": "1035.03"
  },
  "summary": "The oracle value was updated to \"1035.03\"",
  "value": "1035.03",
  "xid": "0799f829-15e8-475f-8f3e-a55488713da0"
}

To retrieve the details of a snapshot, you can issue a GET request to /snapshots/XID.

Parameter Type Description
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Core Adapters

Core Adapters are the built in adapters that ship with ChainLink. Below are the types of adapters available out of the box:

External Adapters can be configured if you would like to configure custom behavior and computation.

bitcoinComparisonJSON

Parses a GET request to a JSON API, compares the parsed value to the value passed into the configuration. Returns the signature of a Bitcoin transaction. If the comparison succeeds then adapter signs the success transaction, if the comparison does not succeed, no transaction is signed. If the deadline for the assignment passes, then the failure transaction is signed.

Configuration

{
  "comparison": ">",
  "endpoint": "https://bitstamp.net/api/ticker/",
  "fields": ["last"],
  "value": "10000"
}
Parameter Type Description
comparison string The operation used to compare the base value to the dynamic value. Options: ===, <, >, or contains.
endpoint string The URL that the JSON is pulled from.
fields array The key path to follow to get the value to compare with the base value.
value string The base value which is compared to they dynamic value. If possible the base value is coerced to the type of the dynamic value, if it is not possible the comparison is treated as false and an empty value is returned.

Update Input

Parameter Type Description
_value string (optional) Input parameters are not used by this adapter.

Update Output

{
  "value": 2393.45
}
Parameter Type Description
value string The value parsed out of the JSON API.

ethereumBytes32

Formats the input as Ethereum bytes32 value and writes it into the specified contract. Deploys an oracle contract that is updated if a contract address is not provided. Returns the input value converted to a string and shortened to 32 characters, and the transaction ID of the update issued.

Configuration

{
  "address": "0x27B07c528de014E58AeEE3eaa0805a9b0f33fB1F",
  "functionID": "d529c153"
}
Parameter Type Description
address string (optional) Ethereum address to send the data to, if a contract to update already exists.
functionID string (optional) Ethereum function ID to send the data to, if a contract to update already exists.

Update Input

{
  "value": "2364.45"
}
Parameter Type Description
value string Converted to a string from which the first 32 bytes are pulled and formatted to be written into Ethereum bytes32 format.

Update Output

{
  "value": "2364.45",
  "txid": "0x3c5c7bd7e7be9d4e264b43f8f1c617c57ec93110576cdad171a76da988525478"
}
Parameter Type Description
value string The input value passed in, converted to string, and then pulled the first 32 bytes.
txid string ID of the transaction that was written into Ethereum to create the update.

ethereumFormatted

Writes a preformatted Ethereum hexadecimal value into the blockchain as configured. Returns the preformatted value that was provided as input.

ethereumFormatted can also be used as an alarm clock, which is preconfigured to call a function on a transaction.

Configuration

{
  "address": "0x27B07c528de014E58AeEE3eaa0805a9b0f33fB1F",
  "functionID": "d529c153",
  "data": "58ea975797ad9184869ce4a9505d02517b4faa5dc4de751fdabda9552b0ce514",
  "amount": 1000000000000000000
}
Parameter Type Description
address string Ethereum address to send the data to.
functionID string Ethereum function ID to send the data to.
data string (optional) Hexadecimal value to be sent in. This value is used as a fallback if no input value is passed in from the adapter pipeline.
amount integer (optional) Amount of Ether to send to the contract along with the data.

Update Input

{
  "value": "b4346adc850180266e030900a53167290c77e1bbaaf9b550dcf5b6d5f630a63e"
}
Parameter Type Description
value string Hexadecimal value that will be sent in to the Ethereum contract. Requires the value already be formatted as hex.

Update Output

{
  "value": "b4346adc850180266e030900a53167290c77e1bbaaf9b550dcf5b6d5f630a63e",
  "txid": "0x99a4ded175f0c6adc2edfb0a06da412f4201816d50fc1eb8d9bbfb19cd227bf3"
}
Parameter Type Description
value string The input value passed in as hexadecimal.
txid string ID of the transaction that was written into Ethereum to create the update.

ethereumInt256

Formats the input as Ethereum int256 value and writes it into the specified contract. Deploys an oracle contract that is updated if a contract address is not provided. Returns the input value multiplied by the resultMultiplier and converted to an integer, and the transaction ID of the update issued.

Due to constraints in the EVM, decimal value were not represented. The resultMultiplier parameter is an optional parameter to address that. If an input value has a decimal, the multiplier allows you to capture the decimal information by multiplying the value and increasing it orders of magnitude. For example if an API for Bitcoin price in US Dollars returns cents, you can set the multiplier to 100, and the value 2452.75 will be converted to 245275. By default the value is set to 1.

Configuration

{
  "address": "0x27B07c528de014E58AeEE3eaa0805a9b0f33fB1F",
  "functionID": "d529c153",
  "resultMultiplier": 100
}
Parameter Type Description
address string (optional) Ethereum address to send the data to, if a contract to update already exists.
functionID string (optional) Ethereum function ID to send the data to, if a contract to update already exists.
resultMultiplier integer (optional) Amount to multiply the value passed in by. Allows for decimal value to be increased so that their precision is accounted for by integers. Defaults to 1.

Update Input

{
  "value": "2364.45"
}
Parameter Type Description
value string Multiplied by the resultMultiplier and converted to an integer, then formatted to be written into Ethereum int256 format.

Update Output

{
  "value": "2364.45",
  "txid": "0x3c5c7bd7e7be9d4e264b43f8f1c617c57ec93110576cdad171a76da988525478"
}
Parameter Type Description
value integer The input value passed in mutliplied by the resultMultiplier and converted to an integer.
txid string ID of the transaction that was written into Ethereum to create the update.

ethereumLogWatcher

If an Ethereum event log which matches the configured filters is created, the adapter triggers a new snapshot. Wherever the adapter is in the pipeline, it stores the event log and uses that as the output passes down the pipeline.

If this adapter is present and a snapshot is triggered, but no event log is present, this adapter passes its inputs to the next adapter as its output, unmodified.

Useful for creating “pull” based oracles where the oracle values are requested on demand.

Configuration

{
  "address": "0x85A11A056D27c822fF1B9a429488EfCF9b5A8fa3",
  "topics": ["da39f17b584e804a6da2d1f5cd7428a108623a03167d8b5f3c1af14b0d34e021"]
}
Parameter Type Description
address string Ethereum address to watch for logs.
topics string Event topics to watch for in logs.

Update Input

Parameter Type Description
_value string (optional) Input parameters are not used by this adapter.

Update Output

{
  "address": "0x732777E1d2940CC7f1c6F1eff0c62Aa7844F7623",
  "blockHash": "0x7932fe0c2500450b41389caac75b086a10ffefff4a6b5f637d00988f9f7f810d",
  "blockNumber": 485196,
  "data": "0xe51ee529abdd443102533e0f12537b3f09789b73f9381d42c0bdb11818b724c8",
  "logIndex": 67,
  "topics": ["0xa81633b25c7ee4172722e6586eb1c6faf5b196dd75fc874d636fde119f9df31f"],
  "transactionHash": "0xeac26ca07de6a0c44d1ccb54c77ac50ff8f5179749512bc167e796950dc5a220",
  "transactionIndex": 87,
  "value": "0xe51ee529abdd443102533e0f12537b3f09789b73f9381d42c0bdb11818b724c8"
}
Parameter Type Description
address string Ethereum address where the log was generated.
blockHash string Hash of the block which generated the log.
blockNumber integer Block height at the time the log was generated.
data string Hexadecimal representation of the values logged by the event.
logIndex integer Count of logs occuring before the reported log in the transaction.
topics array List of topics that the log indicated as relevant.
transactionHash string Identifier of the tranasaction which generated the log.
transactionIndex integer Position of the transaction within the block that recorded the log.
value string Hexadecimal representation of the values logged by the event. (Same as data.)

ethereumUint256

Formats the input as Ethereum int256 value and writes it into the specified contract. Deploys an oracle contract that is updated if a contract address is not provided. Returns the input value multiplied by the resultMultiplier and converted to a positive integer, and the transaction ID of the update issued.

Due to constraints in the EVM, decimal value were not represented. The resultMultiplier parameter is an optional parameter to address that. If an input value has a decimal, the multiplier allows you to capture the decimal information by multiplying the value and increasing it orders of magnitude. For example if an API for Bitcoin price in US Dollars returns cents, you can set the multiplier to 100, and the value 2452.75 will be converted to 245275. By default the value is set to 1.

Configuration

  {
    "address": "0x27B07c528de014E58AeEE3eaa0805a9b0f33fB1F",
    "functionID": "d529c153",
    "resultMultiplier": 100
  }
Parameter Type Description
address string (optional) Ethereum address to send the data to, if a contract to update already exists.
functionID string (optional) Ethereum function ID to send the data to, if a contract to update already exists.
resultMultiplier integer (optional) Amount to multiply the value passed in by. Allows for decimal value to be increased so that their precision is accounted for by integers. Defaults to 1.

Update Input

{
  "value": "2364.45"
}
Parameter Type Description
value string Multiplied by the resultMultiplier and converted to a positive integer, then formatted to be written into Ethereum uint256 format.

Update Output

{
  "value": "2364.45",
  "txid": "0x3c5c7bd7e7be9d4e264b43f8f1c617c57ec93110576cdad171a76da988525478"
}
Parameter Type Description
value integer The input value passed in mutliplied by the resultMultiplier and converted to a positive integer.
txid string ID of the transaction that was written into Ethereum to create the update.

httpGetJSON

Retrieves JSON and returns the specific field selected in the configuration.

Parses a specific field out of the response of a GET request to a JSON API.

Configuration

{
  "fields": ["recent", "0", "price"],
  "url": "https://api.example.com/feed",
  "basicAuth": {
    "username": "satoshi",
    "password": "I<3Ethereum"
  },
  "headers": "Content-Type: application/json"
}
Parameter Type Description
fields array The key path to follow to get the value to compare with the base value.
url string The URL that the JSON is pulled from.
basicAuth object (optional) JSON Object containing username and password fields.
headers string (optional) Headers to be included in request.

Update Input

Parameter Type Description
_value string (optional) Input parameters are not used by this adapter.

Update Output

{
  "value": "2350.00"
}
Parameter Type Description
value string The value parsed out of the JSON API.

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 this adapter is present and a snapshot is triggered, but no request was made to the API, this adapter passes its inputs to the next adapter as its output, unmodified.

Useful for creating “pull” based oracles where the oracle values are requested on demand.

Configuration

{
  "fields": ["recent", "0", "price"]
}
Parameter Type Description
fields array The key path to follow to get the value to compare with the base value.

Update Input

Parameter Type Description
_value string (optional) Input parameters are not used by this adapter.

Update Output

{
  "details": {
    "recent": [{
      "price": 2352.38
    }]
  },
  "value": 2352.38
}
Parameter Type Description
details object The full JSON payload passed into the oracle API endpoint.
value string The value parsed out of the JSON API.

External Adapters

ChainLink ships with out of the box functionality, including the ability to connect to Ethereum contracts and Bitcoin escrow released via JSON APIs. The real power of the ChainLink platform lies in its abilitiy to be extended. External Adapters can be configured with ChainLink to add specialized functionality. Whether it parsing a different data format like XML, or special computation, ChainLink makes it possible to further extend off-chain capabilities via adapters.

APIs

External Adapters are currently integrated in a service oriented fashion; they are run separately from the core, and are communicated with via REST APIs. This separation allows External Adapters to be written in whichever language is best suited to the task at hand. Additionally, the service oriented model allows for External Adapters to be either colocated on the same machine using something like Docker Compose, or they can run remotely on servers located on the other side of the world.

This flexiblity is possible via a few simple APIs. Which APIs an External Adapter requires depends on if it will pull or push new Snapshot updates; adapters must conform to at least the push or pull APIs, conforming to both allows for the most flexiblity.

Whether using the push or pull APIs, External Adapters need to format their output in a way that can be consumed by other adapters. This comes down to a few basic fields in JSON, with some optional support for human readability and feedback.

Parameter Type Description
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Oracle Schema

In order to make an adapter’s input and output predictable, adapters need to specify schemas. Schemas are created using a JSON Schema for expected prerequisites and on/off-chain inputs/outputs. See the specification here, or provide an empty schema to get started quickly. Schemas can be used to check the upfront configuration of an adapter, and the details of a snapshot.

Authentication

When you create you configure your External Adapter with ChainLink, a set of basic auth credentials will be generated for you.

Create Assignment

Required: POST to adapter path /assignments

The action used for an oracle to pass an assignment to an adapter. The adapter response should include:

{
  "xid": "c21bd20f-2439-41e3-831d-d650f3d24e7e",
  "endAt": 1814134222,
  "data": {
    "some": "more information"
  }
}
Parameter Type Description
xid string the unique identifier to associate an assignment with
endAt string a Unix Timestamp of when the assignment must finish by
data object (optional) Subtask initialization results. Information that can be determined only once the subtask details have been given to the adapter. This will be used as initialization details sent to the coordinator once all subtasks have been initialized.

Create Snapshot (Pull)

POST to adapter path /assignments/:assignment_xid/snapshots

The action used for an oracle to pass a Snapshot update over to an adapter. The response should include:

{
  "description": "Payment was successfully released via FundFriend.",
  "descriptionURL": "https://fundfriend.com/transactions/21433245",
  "details": {
    "amount": 1000000.00,
    "currency": "USD"
  },
  "fulfilled": true,
  "status": "in progress",
  "summary": "Payment was released from Alice to Bob.",
  "value": "1000000.00",
  "xid": "d7e18eba-f5a1-45aa-a378-b4bcbbfbc4c6"
}
Parameter Type Description
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
fulfilled boolean marks whether the snapshot has been completed or not
status string a description of the assignment’s current status
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Unfulfilled Snapshots

Creating a snapshot may require more time than you are willing to leave a request hanging for. Snapshots that are requested via the pull style can be marked as unfulfilled upon creation, and fulfilled at a later time.

In order to fulfill an unfulfilled snapshot you must implement the update snapshot integration.

Delete Assignment

DELETE to /assignments/:xid

Used to indicate the end of an assignment.

{
  "status": "failed",
  "xid": "1f1b5d2a-8f2b-486d-bfe9-45385004cfa3"
}
Parameter Type Description
status string optional string to specify the final state of the assignment
xid string identifier of the assignment

Create Snapshot (Push)

POST pushed to the core path /snapshots

This is an integration that originates in the adapter and is pushed from the adapter to the core.

A pushed snapshot is automatically marked as fulfilled.

{
  "description": "Payment was successfully released via FundFriend.",
  "descriptionURL": "https://fundfriend.com/transactions/21433245",
  "details": {
    "amount": 1000000.00,
    "currency": "USD"
  },
  "fulfilled": true,
  "status": "in progress",
  "summary": "Payment was released from Alice to Bob.",
  "value": "1000000.00",
  "xid": "d7e18eba-f5a1-45aa-a378-b4bcbbfbc4c6"
}
Parameter Type Description
assignmentXID string identifier for the associated assignment
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
status string a description of the assignment’s current status
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Update Snapshot (Push)

PATCH pushed to the core path /snapshots/:xid

This is an integration that originates in the adapter and is pushed from the adapter to the core.

Only unfulfilled snapshots can be updated. When a snapshot is updated it is automatically marked as fulfilled.

{
  "description": "Payment was successfully released via FundFriend.",
  "descriptionURL": "https://fundfriend.com/transactions/21433245",
  "details": {
    "amount": 1000000.00,
    "currency": "USD"
  },
  "fulfilled": true,
  "status": "in progress",
  "summary": "Payment was released from Alice to Bob.",
  "value": "1000000.00",
  "xid": "d7e18eba-f5a1-45aa-a378-b4bcbbfbc4c6"
}
Parameter Type Description
assignmentXID string identifier for the associated assignment
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
status string a description of the assignment’s current status
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Coordinator Updates

Once an assignment is created, it will automatically run and update itself based on its schedule and the logic in the adapter. Updates cannot be fed in by the coordinator, but the coordinator can receive push notifications whenever the assignment is updated. Simply set the URL of the assignment’s coordinator to receive push notifications.

All push notifications are authorized with the same credentials used to create the assignment.

Create Assignment Oracle

{
  "oracle": {
    "address": "0x72c8379f845bb3cb30e02ef1feb84742debc1efb",
    "jsonABI": "contract Oracle {\n  bytes32 currentValue;\n  address creator;\n\n  function Oracle() {\n    creator = msg.sender;\n  }\n\n  function update(bytes32 newCurrent) {\n    if (msg.sender != creator) return;\n    currentValue = newCurrent;\n  }\n\n  function current() constant returns (bytes32 current) {\n    return currentValue;\n  }\n\n  function () constant returns (bytes32 current) {\n    return currentValue;\n  }\n}",
    "readAddress": "9fa6a6e3",
    "solidityABI": "contract Oracle{function Oracle();function update(bytes32 newCurrent);function current()constant returns(bytes32 current);}"
  },
  "xid": "f0577c3e-9e5a-4840-9c9b-37d326c3d2e3"
}

POST to /assignments/:xid/instructions

If an assignment needs some on-chain setup, it cannot immediately respond with all of its integration details on creation, it needs to wait for the blockchain confirmations before. Once the confirmations needed for the assignment set up have occured, the oracle will push integration instructions to the coordinator.

Parameter Type Description
address string Ethereum address location
jsonABI string a stringified version of the JSON ABI for the contract
readAddress string the hash for the read function of the Ethereum contract
solidityABI string the Solidity ABI to include in a contract using this oracle
xid string the XID of the related assignment

Create Assignment Snapshot

{
  "assignmentXID": "f0577c3e-9e5a-4840-9c9b-37d326c3d2e3",
  "description": "Blockchain ID: 0x5803d6bb728b002d5a9aedc2eebec404fcbc2e2966f5e81abe297995b2980046",
  "descriptionURL": "https://testnet.etherscan.io/tx/0x5803d6bb728b002d5a9aedc2eebec404fcbc2e2966f5e81abe297995b2980046",
  "details": {
    "current": "10000000034567123",
    "total": "98700000035511224"
  },
  "status": "in progress",
  "summary": "Assignment 'f0577c3e-9e5a-4840-9c9b-37d326c3d2e3' updated its value to \"1,000,000.00\"",
  "value": "1,000,000.00",
  "xid": "0x5803d6bb728b002d5a9aedc2eebec404fcbc2e2966f5e81abe297995b2980046"
}

POST to /assignments/:assignment_xid/snapshots

Each time the assignment is updated it creates a snapshot. A snapshot is the current status of the assignment. Whenever a snapshot is created, it is pushed to the coordinator. Further information is provided in machine readable form in the details section, in various formats depending on the adapter. Information is provided in human readable form in the summary and description fields, as well as the descriptionURL.

Parameter Type Description
assignmentXID string the XID of the related assignment
description string a detailed human readable description of the snapshot
descriptionURL string a supporting URL relating to the update
details object a JSON object of extra supporting information returned by the adapter
status string a description of the assignment’s current status
summary string a short human readable summary of the snapshot
value string the latest value returned by the adapter
xid string a unique external ID to identify the snapshot by

Update Assignment

{
  "signatures": ["30450221009f4e3e0ab2ede2ca57a03ea67f6d16641568b214e38b650db95cd3490b3f213902202b8ba93235c6cafa4f8a643c72977427e8fde95a2e8010cb3336125182d62cef"],
  "status": "completed",
  "xid": "f0577c3e-9e5a-4840-9c9b-37d326c3d2e3"
}

PATCH to /assignments/:xid

When the assignment is finished, a notification will be pushed to the coordinator. If any signatures were needed from the oracle, for things like releasing Bitcoin escrow, a signature is returned in addition to a status update.

Parameter Type Description
signatures array(string) if a signature is required, like for Bitcoin escrow, it returns a signature for the outcome that was determined
status string Either “completed” or “failed”
xid string the XID of the related assignment