@api3/airnode-examples

A public list of examples showcasing the features of Airnode

This project contains runnable scripts that will guide you through the necessary steps to run an Airnode instance. You are encouraged to read through the contents of the scripts before you run them.

Airnode is flexible and can be used in a variety of ways on multiple Ethereum Virtual Machine (EVM) compatible chains.

The examples support running Airnode locally as a Docker container and on cloud services, specifically AWS Lambda and GCP Cloud Functions.

The Airnode Examples support a subset of common EVM chains which will be presented when you run yarn choose-integration. Optionally you may also adapt the configuration to support your target chain.

Documentation

Request-Response protocol (RRP)

Currently, all of the examples utilize the RRP protocol. The example RRP flow consists of two high level parts:

1. Deploy an AirnodeRrpV0 contract and a RrpRequesterV0 contract on a supported chain
2. Deploy Airnode on a cloud provider, or run locally in a docker container, and make a request using the deployed requester

If you would like to know more about RRP, read the API3 docs.

Available examples

The examples are called "integrations" because they are integrations with a public API. Each integration offers a different scenario for running an Airnode instance. The integrations have been designed to highlight various Airnode functionality and use cases, from simple price requests to more complex authenticated requests encoding multiple reserved parameters. The following list orders integrations alphabetically:

• authenticated-coinmarketcap - authenticated cryptocurrency price request.
• coingecko - unauthenticated cryptocurrency price request.
• coingecko-cross-chain-authorizer - demonstration of a cross-chain authorizer.
• coingecko-http-gateways - demonstration of the HTTP gateway and HTTP signed data gateway.
• coingecko-post-processing - demonstration of the post-processing feature.
• coingecko-pre-processing - demonstration of the pre-processing feature.
• coingecko-template - demonstration of template requests.
• failing-example - demonstration of Airnode error handling through an invalid request.
• relay-security-schemes - demonstration of how to relay multiple request metadata like chain ID and sponsor address to the API endpoint.
• weather-multi-value - authenticated weather request encoding multiple parameters including the transaction timestamp, time of sunset, temperature, and a description of the weather.

Setup

First, download the repository source code at a specific tag or release, or, alternatively, clone the repository and check out a specific git commit tag; the unreleased master branch is not supported and is for development purposes only. Run the following to check out a tag, for example v0.6:

git fetch --tags && git checkout v0.6

Next, make sure you have yarn installed and then follow the repository instructions to install dependencies and build the packages. If you want to run Airnode as a docker container, you'll also need to have docker installed.

Instructions

The following instructions will guide you step by step through the RRP flow. Please note, that some steps may be skipped depending on how you would like to run the example - e.g. you don't need to start a hardhat network locally when you intend to run the example with a public network.

If using a Linux distribution that enforces SELinux policies, make sure allow the Docker images access to the host directory by creating an appropriate rule.

1. Choose an example

The first step is to choose an integration and network.

If you intend to run an integration on a public network, you will also need a funded account to deploy the necessary contracts and trigger an Airnode request. For a hardhat network you can use the account derived by hardhat's default mnemonic which is already funded.

Run the following script to interactively choose your integration:

yarn choose-integration

After you have chosen an integration, be sure to read out its README for details. You will find it in integrations/<integration-name>/README.md.

2. (Only if using local blockchain) Start hardhat network

Run:

yarn eth-node

which will spin up a hardhat network on your machine.

3. (Optional) Print out the user account information

Run:

yarn print-account-details

This script will show you the address of the account derived from the specified mnemonic. This account will be used to deploy the contracts and make transactions, so make sure it is funded. The recommended amount is at least 0.3 ETH.

4. (Only if using local blockchain) Deploy the RRP contract

The RRP contract is a contract through which the requester triggers a request for Airnode. This contract is common for all Airnodes and requesters on a chain.

If you are using a local blockchain, deploy the contract using the first command below. Otherwise, the contract deployed by API3 on the chosen chain will be used automatically. The second command, also optional if using a public blockchain, deploys the contract necessary for gas estimation.

yarn deploy-rrp
yarn deploy-rrp-dry-run

5. (Only if deploying to AWS) Create AWS secrets file

If you intend to deploy Airnode on AWS, you will need to specify the credentials which will be used by the deployer. If you are not sure where to find these or how to create an AWS account, see the following docs section.

After you know the secrets, run the following script to specify them:

yarn create-aws-secrets

The credentials should be stored in the integration directory - e.g. if you have chosen the coingecko integration, store the file as integrations/coingecko/aws.env.

6. (Only if deploying to GCP) Create GCP credentials

If you intend to deploy Airnode on GCP, you will need to create a service account for your project and create and download an access key for the new account. If you haven't already done so, you will also need to enable billing for your project by pairing it with your credit card. The amount of resources used by the Airnode examples should fit well within the free tier, which means no charges will be incurred.

If you are not sure how to create a GCP service account, see or download the access key for it, the following docs section.

Store the access key file as gcp.json in the integration directory - e.g. if you have chosen the coingecko integration, store the file as integrations/coingecko/gcp.json.

7. Create Airnode configuration

Airnode is configured by two files - config.json and secrets.env. The configuration changes based on where the Airnode is deployed due to differing cloud provider requirements and settings. These differences are minor but for your convenience the configuration in these examples is generated automatically.

To generate the config.json, run:

yarn create-airnode-config

8. Create Airnode secrets

Airnode is configured by two files - config.json and secrets.env. The config.json was created in previous step. The latter, secrets.env can be generated by running:

yarn create-airnode-secrets

If you are using Docker Desktop (on any platform) and you want to connect to your local hardhat network, you will need to modify the generated secrets.env file found in integrations/<integration-name>/ by replacing the provider URL with the following: PROVIDER_URL=http://host.docker.internal:8545. This is a docker limitation. See: https://stackoverflow.com/a/24326540. A symptom of needing this change is the following error when attempting to connect to your local hardhat network: could not detect network.

The create-airnode-secrets script will handle this for you on Mac, Windows, and WSL.

Refer to the documentation for more details.

9. (Only if deploying to a cloud provider) Deploy Airnode

Now you're ready to deploy Airnode on the cloud provider. To proceed, run:

yarn deploy-airnode

This command will use the released deployer Docker image corresponding to the tag checked out during Setup. The image itself is based on the deployer package. Note that deployment may take some time and should not be interrupted. Please be patient.

If you are a developer and would like to use a different deployer Docker image, provide the full image name as an additional argument. For example:

yarn deploy-airnode api3/airnode-deployer-dev:bb9b8118940ec852c4223b13eba5a6eb97aa3b97

10. (Only if running Airnode locally) Run the Airnode container

yarn run-airnode-locally

This command will use the released client Docker image corresponding to the tag checked out during Setup. Note that the containerized version runs a cron job which triggers every minute - this means that Airnode logs won't start appearing immediately.

If you are a developer and would like to use a different client Docker image, provide the full image name as an additional argument. For example:

yarn run-airnode-locally api3/airnode-client-dev:bb9b8118940ec852c4223b13eba5a6eb97aa3b97

11. Deploy a requester

At this point, you have an RRP contract deployed. You will also either have Airnode running as a Docker container locally or deployed to a cloud provider. Airnode is now listening for events (requests to be made) from the RRP contract. Requests via the RRP contract originate from requester contracts and therefore a requester contract will need to be deployed in order to make an on-chain request to your Airnode instance.

To deploy a requester contract, run:

yarn deploy-requester

12. Derive and fund the sponsor wallet

Airnode requests require a sponsor, which will pay for the response transaction made by Airnode. Each sponsor has a dedicated wallet for a given Airnode. This wallet is called a "sponsor wallet" and can be derived from a sponsor address and Airnode's extended public key with the admin CLI package. Refer to the documentation for more details.

To derive and fund the sponsor wallet, run:

yarn derive-and-fund-sponsor-wallet

This script will first derive the sponsor wallet and then fund it with 0.1 ETH. This means that your account (derived from the mnemonic by choose-integration script) must have enough funds.

13. Allow the sponsor to pay for requests made by the requester

In order to prevent misuse, each sponsor has to explicitly approve a requester. Once the requester is approved, requests can be paid by this sponsor.

yarn sponsor-requester

14. Make the request

The last step is to trigger an Airnode request using the requester contract:

yarn make-request

This command will create a transaction which calls a function on the requester contract. The requester contract will emit an event in response, which Airnode will detect during its next cycle. On receipt of this request event, Airnode will perform the associated API call and submit the response back on chain. The above command will wait for all of this to take place and once the request has been fulfilled the output will be sent to the terminal.

15. (Optional) Make a withdrawal request

Withdrawal requests instruct the Airnode return the funds of particular sponsor wallet back to the sponsor. This step is useful when testing on public testnets. To execute a withdrawal request run:

yarn make-withdrawal-request

16. (Only if deploying to a cloud provider) Remove Airnode from the cloud provider

If you wish to tear down the Airnode from the cloud provider run:

yarn remove-airnode

This will use the deployer to remove the Airnode functions from the cloud provider.

17. (Only if running Airnode locally) Stop the Airnode container

If you wish to stop the Airnode container running locally run:

yarn stop-local-airnode

For developers

When pulling or creating a new integration you need to run yarn build to create the necessary contract artifacts.

The main purpose of these examples is to demonstrate the flexibility and features of Airnode, whilst being easy to maintain. The main design choice is that all integrations share the same instructions. This has several trade-offs, notably:

1. Some instructions may be skipped depending on the setup.
2. Number of instructions will grow (but not by much) in the future.
3. Common instruction set is very convenient to test and maintain.
4. Integration configuration files need to be generated dynamically and this requires abstraction.
5. Reading the script sources is difficult.
6. It's very easy for the developer to add a new integration.
7. Integration-specific errata should be explained in the README.md of the particular integration. It is fine if this contains additional manual instructions.
8. The config.example.env and secrets.example.env are used for reference when browsing code on Github and to ensure they are up-to-date using the validator package.

End to end testing

The examples package is a nice fit for an end-to-end test of the entire Airnode infrastructure. We are using this to test the Airnode client docker image using a hardhat network with one of the basic examples.

When running locally, make sure to build the image yourself before running the test. This test also runs on CI, where the Airnode client image is built automatically.