creating-a-new-v3-ea.md

Creating a new v3 EA

This guide outlines the steps needed to setup a basic adapter.

This guide carries stylistic biases, mainly in the context of the collection of EAs found in the External Adapters Monorepo under packages/sources/. That being said, this framework can be used outside of that to build standalone adapters, in which case its organization does not need to follow the structure laid out in this guide.

Creating A New Adapter

The framework provides an interactive EA generator script to help create new adapters. To create a new adapter in the External Adapters Monorepo run yarn new. It will ask several questions regarding adapter and endpoints and will generate the file structure with all the boilerplate code.

Steps to create a new Adapter manually

1. Create the Folder Structure
2. Create a Transport
3. Create an Endpoint
4. Create the Adapter

Create the Folder Structure

An adapter built with the v3 framework has the following folder structure.

This structure is a standard we want to keep for consistency in the monorepo but it is not strictly required as it was in v2.

adapter // Name after the adapter
├─ config
│  ├─ index.ts // Custom settings. Optional but very common
│  ├─ overrides.json // Overrides file. Optional
|  └─ includes.json // Includes file (e.x. inverses). Optional
├─ endpoint
│  └─ endpoint.ts // Endpoint is defined here. Name after API endpoint
├─ transport
│  └─ transport.ts // Transport is defined here. Name as associated endpoint name
├─ index.ts // Adapter defined here
├─ test
├─ package.json
├─ CHANGELOG.md // Content auto-updated through changesets
├─ README.md // Content auto-generated by CI scripts
├─ test-payload.json
├─ tsconfig.json
└─ tsconfig.test.json

Create a Transport

Once the folder structure has been set up, a transport can be defined in its respective transport file in transport folder. The v3 framework provides different types of transports to allow data retrieval through different protocols, such as HTTP, Websocket, and SSE.

To learn more about transports and their specifications, please refer to the Transports Guide.

For the purpose of this guide, an example HTTP transport is shown below.

const transport = new HttpTransport<HttpTransportTypes>({
  // Return list of ProviderRequestConfigs
  prepareRequests: (params, config) => {
    return params.map((param) => {
      const symbol = param.symbol.toLowerCase()
      const url = `/price/${symbol}`

      return {
        params: param,
        request: {
          baseURL: config.API_ENDPOINT,
          url,
        },
      }
    })
  },
  // Parse response into individual ProviderResults for each set of params
  parseResponse: (params, res) => {
    return res.data.map((result) => {
      return {
        params: { symbol: result.symbol },
        response: {
          data: {
            result: result.price,
          },
          result: result.price,
        },
      }
    })
  },
})

Create an Endpoint

The endpoint can be defined referring to the transport created in the previous step as shown in the example below.

To learn more about AdapterEndpoint and its parameters, please refer to the Endpoints Guide.

import { AdapterEndpoint } from '@chainlink/external-adapter-framework/adapter'
import { transport } from '../transport/endpoint'

export const endpoint = new AdapterEndpoint({
  name: 'endpoint', // The name of this endpoint
  transport: transport, // The transport this endpoint is retrieves data through
  inputParameters, // Input parameters sent in requests to this endpoint
})

Create the Adapter

Finally, create the adapter in the root-level index.ts file. Reference the endpoint created in the previous step as shown in the example below.

To learn more about Adapter and its parameters, please refer to the Adapter Guide.

import { expose } from '@chainlink/external-adapter-framework'
import { endpoint } from './endpoint'

export const adapter = new Adapter({
  name: 'ADAPTER_NAME', // The EA name, in uppercase without any spaces
  endpoints: [endpoint], // An array of all endpoints available. Defined in the endpoints folder
})

// Expose the server to start the EA
export const server = () => expose(adapter)