Chainlink External Adapters (JavaScript)

This repository contains the source for Chainlink external adapters. Each adapter must document its own required parameters and output format.

Requirements

Yarn

Install

yarn

Installs packages for all workspaces.

Setup

yarn setup

Runs the setup step for all adapters. Typically this step just compiles TypeScript, but may involve other tasks.

Test

In order to test adapters locally, you may need to set an $API_KEY environment variable for the given API.

cd $adapter
yarn test

Create a new adapter

Run the command below to have the example directory cloned using the name you provide for $adapter:

make new adapter=my-adapter-name

If on a Mac, this requires gnu-sed to be installed and set as the default for the command sed.

Input

This is an example, a JSON body the adapter will receive when plugged into the Chainlink node pipeline:

{
  "id": "2cae6a10e5184aa685c3428964b02418",
  "data": { "from": "ETH", "to": "USD" },
  "meta": {
    "availableFunds": 99900000000000000000,
    "eligibleToSubmit": true,
    "latestAnswer": 39307000000,
    "oracleCount": 1,
    "paymentAmount": 100000000000000000,
    "reportableRoundID": 2,
    "startedAt": 0,
    "timeout": 0
  }
}

When the FluxMonitor posts to External Adapters, it will include the RoundState as the "meta" field in the request, serialized to a JSON object with lower camelCase keys.

Optionally data parameters can also be passed via a query string like: {ENDPOINT}?from=ETH&to=USD

Docker

To build a Docker container for a specific $adapter, use the following example:

make docker adapter=bravenewcoin

The naming convention for Docker containers will be $adapter-adapter.

Then run it with:

docker run -p 8080:8080 -e API_KEY='YOUR_API_KEY' -it bravenewcoin-adapter:latest

Serverless

Create the zip:

make zip adapter=bravenewcoin

The zip will be created as ./$adapter/dist/$adapter-adapter.zip.

Install to AWS Lambda

In Lambda Functions, create function
On the Create function page:
- Give the function a name
- Use Node.js 12.x for the runtime
- Choose an existing role or create a new one
- Click Create Function
Under Function code, select "Upload a .zip file" from the Code entry type drop-down
Click Upload and select the $adapter-adapter.zip file
Handler:
- index.handler (same as index.awsHandlerREST) for REST API Gateways (AWS Lambda default)
- index.awsHandlerREST for REST API Gateways
- index.awsHandlerHTTP for HTTP API Gateways
Add the environment variable (repeat for all environment variables):
- Key: API_KEY
- Value: Your_API_key
Save

By default, Lambda functions time out after 3 seconds. You may want to change that to 60s in case an API takes longer than expected to respond.

To Set Up an API Gateway (HTTP API)

If using a HTTP API Gateway, Lambda's built-in Test will fail, but you will be able to externally call the function successfully.

Click Add Trigger
Select API Gateway in Trigger configuration
Under API, click Create an API
Choose HTTP API
Select the security for the API
Click Add

To Set Up an API Gateway (REST API)

If using a REST API Gateway, you will need to disable the Lambda proxy integration for Lambda-based adapter to function.

Click Add Trigger
Select API Gateway in Trigger configuration
Under API, click Create an API
Choose REST API
Select the security for the API
Click Add
Click the API Gateway trigger
Click the name of the trigger (this is a link, a new window opens)
Click Integration Request
Uncheck Use Lamba Proxy integration
Click OK on the two dialogs
Click the Mapping Templates dropdown
Check "When there are no templates defined (recommended)"
Add new Content-Type application/json
Use Mapping Template:

#set($input.path("$").queryStringParameters = $input.params().querystring)
$input.json('$')

Click Save
Return to your function
Remove the API Gateway and Save
Click Add Trigger and use the same API Gateway
Select the deployment stage and security
Click Add

Install to GCP

In Functions, create a new function, choose to ZIP upload
Select Node.js 12 for the Runtime
Click Browse and select the $adapter-adapter.zip file
Select a Storage Bucket to keep the zip in
Function to execute: gcpHandler
Click More, Add variable (repeat for all environment variables)
- NAME: API_KEY
- VALUE: Your_API_key

Multiple API Key Support

In order to use multiple API keys for an adapter, simply comma delimit the keys where you define the environment variable. This will work for an arbitrary number of keys.

API_KEY=myapikey1,myapikey2,myapikey3

The external adapter will then randomly rotate the keys. Over time this should balance out the number of requests between each of the API keys.

lovesh/external-adapters-js