Chainlink Node Setup

  1. Home
  2. Docs
  3. Chainlink Node Setup
  4. Building My First Chainlink Adapter

Building My First Chainlink Adapter

Building My First Chainlink Adapter

Secured By Chainlink
Source: https://chain.link/brand-assets

Article originally published by Zak Ayesh @ https://medium.com/chainlink-community/building-my-first-chainlink-adapter-996ab51dfe9

Chainlink is an open-source framework for creating decentralized blockchain oracles, which bring off-chain data on-chain. The open-source nature of this framework means anyone can contribute to the code base and one way you can contribute is by creating an “external adapter”. What is an external adapter? You can think of an external adapter as code (more specifically an API server) that sits between a data source and a Chainlink node. It allows the operator of a Chainlink node to create custom logic on how they want to interface with a particular data source that may not be available in the core node software.

Contributing to open-source software is a great way to add project work to your resume, learn some cool new skills, and contribute to tech that is accessible to all. So how can you build a Chainlink external adapter? Well, I just made one and the good news is it’s easy. You can find my code here, feel free to clone it, fork it, or use whatever you need. Before continuing I suggest you read Chainlink Lab’s official article on external adapters and their official docs. Here are the steps I took to create my first external adapter.

1). Pick a data source (that requires authentication)

You first have to decide on a data source that has data you would like to see on the blockchain. If you have a potential decentralized app idea try going with the data that the dapp would need. Or if this is just for fun and learning, pick data that you find interesting. You will want to pick an API that requires some type of Authorization; otherwise, a Chainlink node could access the data without an external adapter. Here is a Github repo with lots of different public API’s and includes if they require authorization. I chose anime data from MyAnimeList (MAL); because how fun would it be to allow anime fans to get tokens representing their favorite shows or create on-chain trade-able points for contributing to the website?

The MAL API is listed as requiring OAuth; specifically, it is using authorization code grant with PKCE style OAuth2.0. That may sound complicated but we’ll break down how to deal with this later. Other grant types for OAuth include resource owner password credentials grant, and a client credentials grant. You can read more about OAuth in its official spec. Other than OAuth the other primary authentication method is the “apiKey” authorization method. Patrick Collins already has a great video on how to build an adapter with this type of authorization that I recommend checking out. This video is also a great introduction to external adapters in general. I will be detailing the OAuth authorization code grant style since that was required for the adapter I created.

2). Set up an account at the data source

Since the API we chose requires authorization you will need to make an account with the website that is providing the data. Once an account has been created there you can usually find an API tab under the user settings. Once there you will typically have an area to register an application with the API (see “Create ID” below):

MyAnimeList API page
Example API page from MyAnimeList

On the client registration field, you will be required to fill out some information. The most important part is to fill out the AppRedirect URL properly with your callback: To follow along with me use http://localhost:8080/callbackBelow you will see a picture of what I filled out to use as an example:

Registering the adapter on MyAnimeList
Registering the adapter on MyAnimeList

Click submit and you see your adapter listed on the main API settings page. Click on it and you will see your Client ID and Client Secret.

3) Clone the external adapter template from GitHub

You can find the JavaScript template here:thodges-gh/CL-EA-NodeJS-TemplateThis template provides a basic framework for developing Chainlink external adapters in NodeJS. Comments are included to…github.com

or for Python:thodges-gh/CL-EA-Python-TemplateChainlink external adapter template for Python. Contribute to thodges-gh/CL-EA-Python-Template development by creating…github.com

I personally used the JavaScript template. Once you have cloned the repo you can delete the git repository found in its directory (on a mac you can use the following command in the repo’s directory: rm -rf .git).

There are two primary pieces of code that make up the bulk of the adapter template (I’m linking to my modified versions of them): app.js, and index.js. App.js simply runs the adapter as an API server, while index.js is where the request logic lies that will ultimately send a request to the chosen data source. Once again I recommend you check out this video by Patrick to get a better understanding of the template architecture.

4) Edit the template to meet your needs

The template is already set up with most of the logic we need to run the adapter but there is some custom logic we will need to make. First, let’s set our environment variables. In an.envrc file set your ClientId and ClientSecret with an export statement; remember to never check this file into GitHub! You don’t want anyone else to know your ClientId and ClientSecret. After this is complete, the biggest chunk of logic we will need to create is the logic to handle the OAuth2.0 flow. Luckily this is a problem many other programmers have faced so we can take advantage of pre-existing code! I used the yarn package “Simple Oauth2”. If building your own adapter add it to your project by running the following command in the project:

yarn add simple-oauth2

Once it has been added create a file called “oauth.js” and fill it with the logic you see here:ZakAyesh/Chainlink-External-AdaptersExternal Adapters Created for the Chainlink Oracle Network – ZakAyesh/Chainlink-External-Adaptersgithub.com

You will see that there are three main functions I created in my oauth.js: auth(), callback(), and refreshToken(). All of these functions are run after a call to our adapter is made and can be seen in app.js. The auth() function sends the initial authorization HTTP request and allows you to authorize the adapter from the MAL website itself.

Registering the adapter on MyAnimeList
Authorization screen on MyAnimeList

Once you click “allow” callback() will be triggered in the adapter which will then retrieve the access token we need. This access token needs to be appended to the headers of all requests to the MAL API in order to get the API to return data. Once you have set up the environment variables, created the OAuth logic, and run through the initial authorization we’re ready to send a request to our adapter!

5) Send a data request to the adapter

Looking at app.js, we can see that other than the“GET /authorize” and “GET /callback” routes, the only other main route our API has is for “POST” requests. This is where you will send any actual data requests to our adapter. In the last section, we got the adapter running and an authorization token stored, so now let’s send the adapter a request. My adapter takes a “type”, like movie, tv, or all, and a “rank” of the anime of that type and returns its id from MAL. Let’s search for the number one top anime out of all types on MAL. I like to use curl from the terminal but you can also use a tool like Postman. If using curl type the following command in the terminal (while the adapter is running and authorized of course):

curl -X POST -H “content-type:application/json” “http://localhost:8080/” — data ‘{ “id”: 1, “data”: { “type”: “all”, “rank”: 1 } }’

This should return the following:

Result:  {
"jobRunID": 1,
"data": {
"data": [
"[Object], [Object], [Object], [Object], [Object], [Object],
... 400 more items "
],
"paging": {
"next": "https://api.myanimelist.net/v2/anime/ranking?offset=500&ranking_type=all&limit=500"
},
"result": 5114
},
"result": 5114,
"statusCode": 200
}

}

And with a quick check at https://myanimelist.net/anime/5114, we see that it is indeed the number one rated anime on the site (well deserved might I add). Next, I wanted to list my adapter on a service so people can find it and utilize it for their needs. This takes us to our next step, listing on market.link.

6) List on Market.Link

Market.link is currently the leading listing service for Chainlink nodes and adapters so that’s where I went. Listing on market.link is fairly simple: make sure to have all your code in a public GitHub repo, add a .adapter.yml file like seen here, create an account on market.link and add your adapter. Now the world can find and use your creation!

Market.Link homepage
Where to add an adapter on Market.Link

Conclusion

If you want to contribute to the Chainlink codebase and don’t know where to start, I highly recommend you make your own external adapter. Making this adapter was a really fun endeavor and the knowledge that I gained was a plus. Also, it’s a great feeling to be directly contributing to my favorite open-source blockchain project! Feel free to reach out to me or a team member on the Chainlink discord if you need any help. Now let’s go make blockchains more data-rich one adapter at a time!

Was this article helpful to you? Yes No

How can we help?