|
| 1 | +# Airnode starter |
| 2 | + |
| 3 | +> A starter project for deploying an Airnode and making requests to it |
| 4 | +
|
| 5 | +This project is composed of two steps: |
| 6 | +1. Deploy an Airnode on a supported chain |
| 7 | +1. Make a request to the deployed Airnode in a contract |
| 8 | + |
| 9 | +Currently supported chains: |
| 10 | +- Ropsten |
| 11 | +- Rinkeby |
| 12 | +- Goerli |
| 13 | +- Kovan |
| 14 | +- xDai |
| 15 | +- Fantom |
| 16 | + |
| 17 | +You can skip the first step and use the Airnode that we have deployed on **Ropsten** as well. |
| 18 | +You are recommended to read the contents of the scripts as you run them, and read the entire readme before starting. |
| 19 | + |
| 20 | +## Setup |
| 21 | + |
| 22 | +First, you need to create a wallet and fund it. |
| 23 | + |
| 24 | +1. Clone this repo |
| 25 | +2. Run the following to install the dependencies |
| 26 | +```sh |
| 27 | +npm install |
| 28 | +``` |
| 29 | +3. Run the following to build the contracts |
| 30 | +```sh |
| 31 | +npm run build |
| 32 | +``` |
| 33 | +4. Run the following to generate a wallet, whose mnemonic phrase will be displayed on the terminal and recorded in a `.env` file at the project root. |
| 34 | +```sh |
| 35 | +npm run generate-wallet |
| 36 | +``` |
| 37 | +5. Install [Metamask](https://metamask.io/) to your web browser |
| 38 | +6. Import the mnemonic phrase to Metamask |
| 39 | +7. Use the [faucet](https://faucet.metamask.io/) to get some Ropsten ETH, or use any other appropriate source for the chain you will be working on |
| 40 | + |
| 41 | +Then, you need to get a provider URL. |
| 42 | +This will be used both by the deployed Airnode and by you while interacting with contracts. |
| 43 | +If you will be working on Ropsten: |
| 44 | +1. Go to [Infura](https://infura.io/), create an account and get a Ropsten provider URL |
| 45 | +2. Replace `https://ropsten.infura.io/v3/{YOUR_KEY}` in your `.env` file with the URL you got from Infura |
| 46 | + |
| 47 | +Adapt the steps above if you will be using another chain. |
| 48 | +Note that you can use any other provider or your own node. |
| 49 | +However, if you will be deploying your own Airnode, the provider endpoint must be publicly accessible (i.e., `127.0.0.1:8545` will not work). |
| 50 | + |
| 51 | +*(You only need cloud credentials if you will not be skipping Step 1.)* |
| 52 | + |
| 53 | +Follow the [docs](https://api3dao.github.io/api3-docs/pre-alpha/guides/provider/deploying-airnode.html#creating-cloud-credentials) to create your cloud credentials. |
| 54 | +Place them at `/config/.env`, similar to [`/config/example.env`](/config/example.env). |
| 55 | +Do not confuse this `.env` file with the one in the project root that keeps your mnemonic phrase and provider URL. |
| 56 | + |
| 57 | +**Following these instructions to deploy an Airnode on AWS is [free](https://aws.amazon.com/free/) at the time this is being written.** |
| 58 | + |
| 59 | +## Step 1: Deploy an Airnode |
| 60 | + |
| 61 | +Normally, you would need to do two things before you deploy an Airnode: |
| 62 | +1. [Specify the API integration](https://api3dao.github.io/api3-docs/pre-alpha/guides/provider/api-integration.html) |
| 63 | +1. [Configure your Airnode](https://api3dao.github.io/api3-docs/pre-alpha/guides/provider/configuring-airnode.html) |
| 64 | + |
| 65 | +For this project, we specified a minimal integration to the popular and free [CoinGecko API](https://www.coingecko.com/en/api), and prepared the configuration files. |
| 66 | +We only integrated a single API operation, `GET` for `/coins/{id}`, which you can see below. |
| 67 | +The `localization`, `tickers`, `community_data`, `developer_data` and `sparkline` parameters are [fixed](https://api3dao.github.io/api3-docs/pre-alpha/guides/provider/api-integration.html#fixedoperationparameters) as `"false"`, while `market_data` is fixed as `"true"`. |
| 68 | +The `id` parameter will be provided by the requester (e.g., `"ethereum"`) under the name `coinId`. |
| 69 | +You can make test calls over the [CoinGecko API docs](https://www.coingecko.com/en/api) to see the response format. |
| 70 | + |
| 71 | +<p align="center"> |
| 72 | + <img src="https://user-images.githubusercontent.com/19530665/103151070-be14ea00-478b-11eb-9608-a967c4282d9f.png" width="1024" /> |
| 73 | +</p> |
| 74 | + |
| 75 | +See [config.example.json](/config/config.example.json) for how this integration is achieved. |
| 76 | +We fixed the [reserved parameters](https://api3dao.github.io/api3-docs/pre-alpha/guides/provider/api-integration.html#reservedparameters) to read the value from `market_data.current_price.usd`, cast it as an `int256` and multiply it by `1,000,000` before returning. |
| 77 | +No security scheme (i.e., API key) is defined in `config.json` or [`security.json`](/config/security.json) because the CoinGecko API is publicly accessible. |
| 78 | + |
| 79 | +### Customize your `config.json` |
| 80 | + |
| 81 | +Run the following to insert the contents of `.env` to `config/config.example.json` and save it as `config/config.json` |
| 82 | +```sh |
| 83 | +npm run customize-config |
| 84 | +``` |
| 85 | + |
| 86 | +### Deploy |
| 87 | + |
| 88 | +Now your `/config` directory should have the required [config.json](https://api3dao.github.io/api3-docs/pre-alpha/airnode/specifications/config-json.html), [security.json](https://api3dao.github.io/api3-docs/pre-alpha/airnode/specifications/security-json.html) and [.env](https://api3dao.github.io/api3-docs/pre-alpha/guides/provider/deploying-airnode.html#creating-cloud-credentials) files. |
| 89 | +Run the following to deploy your node: |
| 90 | + |
| 91 | +```sh |
| 92 | +cd config |
| 93 | +# The deployer has to be run in the directory where the configuration files are |
| 94 | +docker run -it --rm \ |
| 95 | + --env-file .env \ |
| 96 | + --env COMMAND=deploy-first-time \ |
| 97 | + -v $(pwd):/airnode/out \ |
| 98 | + api3/airnode-deployer:pre-alpha |
| 99 | +``` |
| 100 | + |
| 101 | +This will output a receipt file with the extension `.receipt.json`. |
| 102 | + |
| 103 | +### Fund your master wallet |
| 104 | + |
| 105 | +Run the following to send your master wallet 0.1 ETH for it to [create a provider record](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/provider.html#creating-a-provider-record) for you on-chain. |
| 106 | +```sh |
| 107 | +npm run fund-master-wallet |
| 108 | +``` |
| 109 | + |
| 110 | +Your deployed Airnode will use these funds to make the transaction that will create the provider record on the chain you are operating on, and send the leftover ETH back to your address automatically. |
| 111 | +**You will have to wait ~1 minute for this to happen, otherwise the next step will fail.** |
| 112 | + |
| 113 | +### Make your endpoint publicly accessible |
| 114 | + |
| 115 | +`config.json` defines an [endpoint](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/endpoint.html) named `coinMarketData`, whose [endpoint ID](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/endpoint.html#endpointid) is `0xf466b8feec41e9e50815e0c9dca4db1ff959637e564bb13fefa99e9f9f90453c`. |
| 116 | +Endpoints are not publicly accessible by default, so you will have to make a transaction for this. |
| 117 | +Run the following to set your endpoint's [authorizers](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/authorizer.html) to `[0x0000000000000000000000000000000000000000]`, which makes it [publicly accessible](https://api3dao.github.io/api3-docs/pre-alpha/guides/provider/setting-authorizers.html#allow-all): |
| 118 | +```sh |
| 119 | +npm run update-authorizers |
| 120 | +``` |
| 121 | + |
| 122 | +## Step 2: Make a request |
| 123 | + |
| 124 | +The scripts in this step will use the Airnode you have deployed if you have completed Step 1. |
| 125 | +Otherwise, it will use the `providerId` of the Airnode that we have deployed given in [`parameters.js`](/src/parameters.js). |
| 126 | +Note that the `endpointId` will be the same either way because it is [derived from the OIS and endpoint name](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/endpoint.html#endpointid). |
| 127 | + |
| 128 | +### Create a requester |
| 129 | + |
| 130 | +Run the following to create an on-chain [requester](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/requester.html) record: |
| 131 | +```sh |
| 132 | +npm run create-requester |
| 133 | +``` |
| 134 | + |
| 135 | +You can use this requester denoted with an index in other projects as well. |
| 136 | +Note that `requesterIndex` is chain-specific, so you will have to create another requester record on other chains. |
| 137 | + |
| 138 | +### Deploy the client contract |
| 139 | + |
| 140 | +Run the following to deploy `ExampleClient.sol`: |
| 141 | +```sh |
| 142 | +npm run deploy-client |
| 143 | +``` |
| 144 | + |
| 145 | +### Endorse the client |
| 146 | + |
| 147 | +Run the following to [endorse](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/endorsement.html) your deployed [client](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/client.html) contract using the requester you have created: |
| 148 | +```sh |
| 149 | +npm run endorse-client |
| 150 | +``` |
| 151 | + |
| 152 | +### Derive and fund the designated wallet |
| 153 | + |
| 154 | +First run the following to derive the [designated wallet](https://api3dao.github.io/api3-docs/pre-alpha/protocols/request-response/designated-wallet.html) for the provider–requester pair: |
| 155 | +```sh |
| 156 | +npm run derive-designated-wallet-address |
| 157 | +``` |
| 158 | +and then fund this designated wallet with 0.1 ETH: |
| 159 | +```sh |
| 160 | +npm run fund-designated-wallet |
| 161 | +``` |
| 162 | + |
| 163 | +The requests that the client contract will make will be funded by this 0.1 ETH. |
| 164 | +Note that you may have to run `fund-designated-wallet` again if you make too many requests and use up this 0.1 ETH (very unlikely). |
| 165 | + |
| 166 | +### Make a request |
| 167 | + |
| 168 | +Run the following to make a request: |
| 169 | +``` |
| 170 | +npm run make-request |
| 171 | +``` |
| 172 | +which should be fulfilled by the Airnode and printed out on the terminal. |
| 173 | +Note that now that the price is on-chain, you can use it in your contract to implement any arbitrary logic. |
| 174 | + |
| 175 | +Try replacing the `coinId` value in [`make-request.js`](/scripts/make-request.js) from `"ethereum"` to `"bitcoin"` and make another request. |
| 176 | +You can see the API docs to find out which coin IDs are supported. |
| 177 | + |
| 178 | +## Conclusion |
| 179 | + |
| 180 | +You deployed an Airnode, made a request to it and received the response at the contract. |
| 181 | +If you want to learn more, see the following resources: |
| 182 | + |
| 183 | +- [API3 whitepaper](https://github.com/api3dao/api3-whitepaper) will give you a broad overview of the project |
| 184 | +- [Medium posts](https://api3dao.github.io/api3-docs/pages/medium.html) are a more digestible version of the whitepaper |
| 185 | +- [API3 docs](https://api3dao.github.io/api3-docs/pre-alpha/) will provide you with the theory of how Airnode and its protocol works |
| 186 | +- [@api3/airnode-admin](https://github.com/api3dao/airnode/tree/pre-alpha/packages/admin) lets you interact with the Airnode contract (to create a request, endorse a client, etc.) using a CLI tool |
| 187 | +- [Airnode client examples](https://github.com/api3dao/airnode-client-examples) demonstrate different request patterns that the Airnode protocol supports (for example, we used a full request in this starter project) |
| 188 | + |
| 189 | +## Taking down your Airnode |
| 190 | + |
| 191 | +It is very unlikely for you to forget to take down your Airnode because it is designed to be *set-and-forget*. |
| 192 | +When you are done with this project, go to `config/` as your working directory and use the command below where `$RECEIPT_FILENAME` is replaced with the name of your receipt file ending with `.receipt.json` (you can refer to our [Docker instructions](https://github.com/api3dao/airnode/blob/pre-alpha/Docker.md) for more information) |
| 193 | + |
| 194 | +```sh |
| 195 | +docker run -it --rm \ |
| 196 | + --env-file .env \ |
| 197 | + --env COMMAND=remove-with-receipt \ |
| 198 | + --env RECEIPT_FILENAME=$RECEIPT_FILENAME \ |
| 199 | + -v $(pwd):/airnode/out \ |
| 200 | + api3/airnode-deployer:pre-alpha |
| 201 | +``` |
0 commit comments