diff --git a/.prettierrc b/.prettierrc index 3300cdee..85badb4a 100644 --- a/.prettierrc +++ b/.prettierrc @@ -5,14 +5,5 @@ "tabWidth": 2, "trailingComma": "es5", "useTabs": false, - "overrides": [ - { - "files": "*.md", - "options": { - "parser": "markdown", - "proseWrap": "always" - } - } - ], "endOfLine": "lf" } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52a3f7fa..86b0e476 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,12 @@ ## Contributor's Guide -Welcome to the API3 Documentation Repository. This guide will help you get -started with contributing to the API3 documentation. +Welcome to the API3 Documentation Repository. This guide will help you get started with contributing to the API3 documentation. ## How to get started -The API3 Docs uses [VitePress](https://vitepress.dev/), a Vue-powered static -site generator. Follow the steps below to get started. +The API3 Docs uses [VitePress](https://vitepress.dev/), a Vue-powered static site generator. Follow the steps below to get started. -Make sure to check out https://docs.api3.org/dev/ for more details and -information about getting started and making a contribution to the API3 Docs. +Make sure to check out https://docs.api3.org/dev/ for more details and information about getting started and making a contribution to the API3 Docs. ### Pre-requisites @@ -38,13 +35,11 @@ The API3 Docs repository is structured as follows: - `/docs/guides`: All the guides that demonstrate the use of Airnode. - `/docs/reference`: Contains the core documentation for Airnode. -Each section will have a `sidebar.js` file that contains the sidebar structure -for that section. +Each section will have a `sidebar.js` file that contains the sidebar structure for that section. `/_components`: Contains the custom vue components used in the API3 Docs. -[Check this out](https://docs.api3.org/dev/docsets.html) for more info about the -structure of the docs. +[Check this out](https://docs.api3.org/dev/docsets.html) for more info about the structure of the docs. ### Building the static site @@ -54,8 +49,7 @@ pnpm docs:build ### Prettier Formatting -Make sure to run the following command before submitting a PR to format the -markdown. The Github action will check for prettier formatting: +Make sure to run the following command before submitting a PR to format the markdown. The Github action will check for prettier formatting: ```bash pnpm format @@ -63,9 +57,7 @@ pnpm format ### Formatting and Styling -You can use markdown to format the content. Check out the -[docs development section](https://docs.api3.org/dev/) for more info. Some -useful links: +You can use markdown to format the content. Check out the [docs development section](https://docs.api3.org/dev/) for more info. Some useful links: - [Page styling](https://docs.api3.org/dev/page-styling.html) - [Formatting guides](https://docs.api3.org/dev/guides-format.html) @@ -73,17 +65,13 @@ useful links: ### Git Workflow: -- `main` branch: for the current live site - [docs.api3.org](https://docs.api3.org) +- `main` branch: for the current live site [docs.api3.org](https://docs.api3.org) -[Check this out](https://docs.api3.org/dev/firebase.html#repo-branches) for more -info about the branches. +[Check this out](https://docs.api3.org/dev/firebase.html#repo-branches) for more info about the branches. ### Submitting an Issue -You can submit an issue if you find any bugs or have any feature requests. -Please make sure to check if the issue already exists before submitting a new -one. +You can submit an issue if you find any bugs or have any feature requests. Please make sure to check if the issue already exists before submitting a new one. You can: @@ -93,9 +81,4 @@ You can: ### Making a PR -After making changes in a feature branch, submit a PR against the `main` branch. -Make sure to link the corresponding GitHub Issue in the PR description e.g. -`Closes #1`. You will be able to see the changes within a Firebase preview -deployment that is unique to the PR. The PR will be reviewed by the team and -merged into the `main` branch, which will result in the changes going live into -production. +After making changes in a feature branch, submit a PR against the `main` branch. Make sure to link the corresponding GitHub Issue in the PR description e.g. `Closes #1`. You will be able to see the changes within a Firebase preview deployment that is unique to the PR. The PR will be reviewed by the team and merged into the `main` branch, which will result in the changes going live into production. diff --git a/README.md b/README.md index c5b437b7..9d87a884 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,10 @@ # API3 Airnode Technical Documentation -The Airnode technical documentation is maintained by the core technical team. -Please feel free to create -[issues](https://github.com/api3dao/airnode-docs/issues) for discussions, -proposals, additions, and changes in the repo `airnode-docs`. +The Airnode technical documentation is maintained by the core technical team. Please feel free to create [issues](https://github.com/api3dao/airnode-docs/issues) for discussions, proposals, additions, and changes in the repo `airnode-docs`. ## VitePress -The technical documentation has moved from -[VuePress](https://vuepress.vuejs.org) to -[VitePress](https://vitepress.vuejs.org). +The technical documentation has moved from [VuePress](https://vuepress.vuejs.org) to [VitePress](https://vitepress.vuejs.org). - `airnode-docs`: uses VitePress - `old-api3-docs`: uses VuePress @@ -25,24 +20,19 @@ Firebase is used to host the `airnode-docs` technical documentation. ### Previews -Additionally each PR has its own Firebase preview site. The URL will be -available in the PR's comments. +Additionally each PR has its own Firebase preview site. The URL will be available in the PR's comments. ## Making a Contribution -Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to make a -contribution. +Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to make a contribution. ## Legacy documentation -The original documentation for the repo `api3-docs` is now accessible via -https://old-docs.api3.org and is still hosted using `gh-pages`. +The original documentation for the repo `api3-docs` is now accessible via https://old-docs.api3.org and is still hosted using `gh-pages`. - DNS: http://old-docs.api3.org - Hosted with GitHub: https://api3dao.github.io/api3-docs ## /dev/ docset -Use https://docs.api3.org/dev/ to learn more about how the `airnode-docs` -documentation is managed. For the legacy documentation use -https://old-docs.api3.org/dev/. +Use https://docs.api3.org/dev/ to learn more about how the `airnode-docs` documentation is managed. For the legacy documentation use https://old-docs.api3.org/dev/. diff --git a/docs/dev/axios-scripts.md b/docs/dev/axios-scripts.md index b1230588..436fcfb4 100644 --- a/docs/dev/axios-scripts.md +++ b/docs/dev/axios-scripts.md @@ -12,24 +12,16 @@ tags: # {{$frontmatter.title}} -The script -[axiosBuildScripts.js](https://github.com/api3dao/airnode-docs/blob/main/libs/axiosBuildScripts.js) -is used to generated local data files. These files are rendered by certain -markdown pages as a data source. For example see these markdown files: +The script [axiosBuildScripts.js](https://github.com/api3dao/airnode-docs/blob/main/libs/axiosBuildScripts.js) is used to generated local data files. These files are rendered by certain markdown pages as a data source. For example see these markdown files: - [/reference/dapis/chains/chains-list.md](https://raw.githubusercontent.com/api3dao/airnode-docs/main/docs/reference/dapis/chains/chains-list.md) - [/reference/airnode/latest/index.md](https://raw.githubusercontent.com/api3dao/airnode-docs/main/docs/reference/airnode/latest/index.md) -The local data files provide for a better page load experience rather than -real-time data access from the monorepo. More importantly, the local data files -allow the vite build to pre-render the html so that Flex can index its content, -see -[Vue components and Flex indexes](/dev/flexsearch.md#vue-components-and-flex-indexes). +The local data files provide for a better page load experience rather than real-time data access from the monorepo. More importantly, the local data files allow the vite build to pre-render the html so that Flex can index its content, see [Vue components and Flex indexes](/dev/flexsearch.md#vue-components-and-flex-indexes). ## Building the local data files -The local data files can be refreshed by running the -`/libs/axiosBuildScripts.js` script as follows: +The local data files can be refreshed by running the `/libs/axiosBuildScripts.js` script as follows: ```sh pnpm axios:build diff --git a/docs/dev/containers.md b/docs/dev/containers.md index 64786074..b0e76c5e 100644 --- a/docs/dev/containers.md +++ b/docs/dev/containers.md @@ -12,8 +12,7 @@ tags: # {{$frontmatter.title}} -VitePress provides several containers. The following examples explain how they -should be used in `airnode-docs`. +VitePress provides several containers. The following examples explain how they should be used in `airnode-docs`. ::: info @@ -35,8 +34,7 @@ Express to the reader not to do something. ::: danger -Rarely used. Expresses an important failure concern to the reader should they -fail to follow instructions. +Rarely used. Expresses an important failure concern to the reader should they fail to follow instructions. ::: diff --git a/docs/dev/docsets.md b/docs/dev/docsets.md index 2fcc7819..86f2c10d 100644 --- a/docs/dev/docsets.md +++ b/docs/dev/docsets.md @@ -12,8 +12,7 @@ tags: # {{$frontmatter.title}} -A docset is a logically grouped set of pages. Every docset has a root folder. -The current docsets are as follows: +A docset is a logically grouped set of pages. Every docset has a root folder. The current docsets are as follows: - Explore: `/explore/` - Guides: `/guides` @@ -30,5 +29,4 @@ The current docsets are as follows: - DAO Members `/reference/dao-members/` - Docs Development `/dev/` -For more information about `/latest` and `/next` see -[Airnode/OIS Versioning](/dev/versioning.md). +For more information about `/latest` and `/next` see [Airnode/OIS Versioning](/dev/versioning.md). diff --git a/docs/dev/firebase.md b/docs/dev/firebase.md index 663fde1c..fd93195b 100644 --- a/docs/dev/firebase.md +++ b/docs/dev/firebase.md @@ -12,23 +12,17 @@ tags: # {{$frontmatter.title}} -All production and PR preview deployments are published on Firebase hosting and -are built automatically using GitHub -[workflows](https://github.com/api3dao/airnode-docs/tree/main/.github/workflows) -stored in the `airnode-docs` repo. +All production and PR preview deployments are published on Firebase hosting and are built automatically using GitHub [workflows](https://github.com/api3dao/airnode-docs/tree/main/.github/workflows) stored in the `airnode-docs` repo. - Production: https://vitepress-docs.web.app (and https://airnode-docs.api3.org) ## Repo Branches -When a PR is merged into the default branch, `main`, a Firebase deployment of -the docs production website is triggered. +When a PR is merged into the default branch, `main`, a Firebase deployment of the docs production website is triggered. ## Firebase emulator -You can run the docs using the firebase emulator after updating the flex indexes -and prior to pushing changes to the repo. Run the following commands from the -root of the project after ensuring that the firebase CLI is installed. +You can run the docs using the firebase emulator after updating the flex indexes and prior to pushing changes to the repo. Run the following commands from the root of the project after ensuring that the firebase CLI is installed. ```sh firebase:emulator diff --git a/docs/dev/flexsearch.md b/docs/dev/flexsearch.md index 6953605f..5a78a56c 100644 --- a/docs/dev/flexsearch.md +++ b/docs/dev/flexsearch.md @@ -12,25 +12,17 @@ tags: # {{$frontmatter.title}} -[FlexSearch](https://www.npmjs.com/package/flexsearch) is used to support -searching in the docs. The script -[/libs/flexBuildIndexes.js](https://github.com/api3dao/airnode-docs/blob/main/libs/flexBuildIndexes.js) -will index all HTML files in the `/dist` folder for the following directories: +[FlexSearch](https://www.npmjs.com/package/flexsearch) is used to support searching in the docs. The script [/libs/flexBuildIndexes.js](https://github.com/api3dao/airnode-docs/blob/main/libs/flexBuildIndexes.js) will index all HTML files in the `/dist` folder for the following directories: - `/dist/explore/` - `/dist/guides/` - `/dist/reference/` -Any files that are not part of the docs but are desired to be retained should go -into the `/archive` folder before running `pnpm docs:build` which will create -the `/dist` folder. This prevents such files from being indexed. +Any files that are not part of the docs but are desired to be retained should go into the `/archive` folder before running `pnpm docs:build` which will create the `/dist` folder. This prevents such files from being indexed. ## `` and `` -For the `/lib/flexBuildIndexes.js` script to extract the content from a markdown -file, the file must contain the markers `` and ``. -The script will only extract DOM text content between the markers. This will -result in the exclusion of headers and footers. +For the `/lib/flexBuildIndexes.js` script to extract the content from a markdown file, the file must contain the markers `` and ``. The script will only extract DOM text content between the markers. This will result in the exclusion of headers and footers. ```js{10,14} --- @@ -51,21 +43,13 @@ title: FlexSearch ## Vue components and Flex indexes -Vue components that do not immediately return HTML content will not index since -their content is generated at runtime in the browser. For example: a component -uses Axios to pull data from an API operation. +Vue components that do not immediately return HTML content will not index since their content is generated at runtime in the browser. For example: a component uses Axios to pull data from an API operation. -To overcome this short fall, the script -[/axiosBuildScripts.js](https://github.com/api3dao/airnode-docs/blob/main/libs/axiosBuildScripts.js) -gathers on-line data into local data files for markdown pages to use. This -allows for proper rendering of HTML at build time. A example of a markdown file -that uses a locally generated data file is -[chains-list.md](https://raw.githubusercontent.com/api3dao/airnode-docs/main/docs/reference/dapis/chains/chains-list.md). +To overcome this short fall, the script [/axiosBuildScripts.js](https://github.com/api3dao/airnode-docs/blob/main/libs/axiosBuildScripts.js) gathers on-line data into local data files for markdown pages to use. This allows for proper rendering of HTML at build time. A example of a markdown file that uses a locally generated data file is [chains-list.md](https://raw.githubusercontent.com/api3dao/airnode-docs/main/docs/reference/dapis/chains/chains-list.md). ## Creating/updating the index files -The following three sections represent the workflow to create the FlexSearch -indexes. +The following three sections represent the workflow to create the FlexSearch indexes. ### 1. Build the local data files @@ -77,9 +61,7 @@ pnpm axios:build ### 2. Build the `/dist` folder -Build the `/dist` folder with the latest HTML files. All markdown files in -`/docs` are converted to HTML files and are added to `/dist`. All files must -contain the extraction markers ``. +Build the `/dist` folder with the latest HTML files. All markdown files in `/docs` are converted to HTML files and are added to `/dist`. All files must contain the extraction markers ``. ```sh pnpm docs:build @@ -93,10 +75,7 @@ Builds the index files. pnpm flex:build ``` -Note the output from the command `pnpm flex:build` which displays file sizes. -Check the size of the three `map.json` files which should be in the range of -25-31 MB. If not refer to the -[Long strings warning](/dev/flexsearch.html#long-strings-warning) section below. +Note the output from the command `pnpm flex:build` which displays file sizes. Check the size of the three `map.json` files which should be in the range of 25-31 MB. If not refer to the [Long strings warning](/dev/flexsearch.html#long-strings-warning) section below. ```sh ----- Building FlexSearch Indexes ----- @@ -117,16 +96,13 @@ pnpm flex:test ### 5. Firebase emulator (optional step) -Using the [firebase emulator](/dev/firebase.md#firebase-emulator) run the docs -project locally and verify newly added functionality. +Using the [firebase emulator](/dev/firebase.md#firebase-emulator) run the docs project locally and verify newly added functionality. ## Long strings warning -When flex builds its indexes and encounters a long string such as those in an -`encodedValue` field, the index gets large very fast. +When flex builds its indexes and encounters a long string such as those in an `encodedValue` field, the index gets large very fast. -Example 1: The following will increase an index very little, around .02 MB (42 -characters). +Example 1: The following will increase an index very little, around .02 MB (42 characters). ``` 0xa0AD79D995DdeeB18a14eAef56A549A04e3Aa1Bd @@ -138,21 +114,13 @@ Example 2: The following will increase an index by some .8 MB (130 characters). 0x00000000000000000000000000000000000000000000000000000000001309ed00000000000000000000000000000000000000000000000000000000065b158a ``` -Example 3: Lastly the following will increase an index some 185 MB (1090 -characters). +Example 3: Lastly the following will increase an index some 185 MB (1090 characters). ``` 0x315353535300000000000000000000000000000000000000000000000000000076735f63757272656e63696573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000120696473000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001605f7061746800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001a05f7479706500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001e0000000000000000000000000000000000000000000000000000000000000000375736400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000007626974636f696e00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b626974636f696e2e7573640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006696e743235360000000000000000000000000000000000000000000000000000 ``` -The problem is an exponential one. As the string gets longer the index grows -more and more rapidly. - -Sometimes the need to display a long string is desired so that readers can copy -paste the string. However this must be avoided for very long strings. A possible -solution has been implemented in the -[Calling an Airnode](/guides/airnode/calling-an-airnode/) guide, example: -(`0x3...000`→). This -works because the string is a parameter of an HTML element. The flex search -index is only built from element `displayText`. +The problem is an exponential one. As the string gets longer the index grows more and more rapidly. + +Sometimes the need to display a long string is desired so that readers can copy paste the string. However this must be avoided for very long strings. A possible solution has been implemented in the [Calling an Airnode](/guides/airnode/calling-an-airnode/) guide, example: (`0x3...000`→). This works because the string is a parameter of an HTML element. The flex search index is only built from element `displayText`. diff --git a/docs/dev/frontmatter.md b/docs/dev/frontmatter.md index 28ac1c75..e6f9778d 100644 --- a/docs/dev/frontmatter.md +++ b/docs/dev/frontmatter.md @@ -12,10 +12,7 @@ tags: # {{$frontmatter.title}} -The frontmatter must be at the top of the Markdown file, and must take the form -of valid YAML set between triple-dashed lines. Each page must contain -`$frontmatter` which is used to provide navigation, navigation labels, and -search criteria. Below is the `$frontmatter` for this page. +The frontmatter must be at the top of the Markdown file, and must take the form of valid YAML set between triple-dashed lines. Each page must contain `$frontmatter` which is used to provide navigation, navigation labels, and search criteria. Below is the `$frontmatter` for this page. ```yaml --- @@ -36,42 +33,31 @@ Most `$frontmatter` keys are required. ### `title` -(required) Sets the page's title. This title is not used by the sidebars which -must provide a title for each page using the key `text`. They can be the same or -different. +(required) Sets the page's title. This title is not used by the sidebars which must provide a title for each page using the key `text`. They can be the same or different. ### `sidebarHeader` -(required) At the top of the sidebar is a text block (preceded by a folder -image). This label represents a selection from the navbar or other hidden -sections such as /dev or /operations. +(required) At the top of the sidebar is a text block (preceded by a folder image). This label represents a selection from the navbar or other hidden sections such as /dev or /operations. ### `sidebarSubHeader` -(required for Airnode and OIS) In the case of the navbar selection -**Reference**, there are sub-selections such as Airnode, OIS, dAPIs, etc. +(required for Airnode and OIS) In the case of the navbar selection **Reference**, there are sub-selections such as Airnode, OIS, dAPIs, etc. ### `pageHeader` -(required) Supplies the text used on each page above the `$frontmatter.title`. -This is a breadCrumb trail without the links. +(required) Supplies the text used on each page above the `$frontmatter.title`. This is a breadCrumb trail without the links. ### `path` -(required) The path to the page. The path is used by the search engine as a -target URL and to logically group search results for display to the reader. +(required) The path to the page. The path is used by the search engine as a target URL and to logically group search results for display to the reader. ### `version` -(required for Airnode and OIS) The version number for the Airnode and OIS -docsets. +(required for Airnode and OIS) The version number for the Airnode and OIS docsets. ### `outline` -(optional) Each page has its own table of contents component displayed on its -right side if the page use heading elements H2-H6. Without a value for `outline` -only H2 elements will be displayed. A value of deep will show all elements -H2-H6. +(optional) Each page has its own table of contents component displayed on its right side if the page use heading elements H2-H6. Without a value for `outline` only H2 elements will be displayed. A value of deep will show all elements H2-H6. - `outline: null`: Shows H2 - `outline: false`: The TOC is hidden @@ -80,5 +66,4 @@ H2-H6. ### `tags` -(optional) For future use, provides important key search words for the search -engine. +(optional) For future use, provides important key search words for the search engine. diff --git a/docs/dev/guides-format.md b/docs/dev/guides-format.md index 7cf678ac..aae21ab2 100644 --- a/docs/dev/guides-format.md +++ b/docs/dev/guides-format.md @@ -19,31 +19,17 @@ Guides can be broken into two categories. ## How to -This type of guide does not engage in a step-by-step instructional page. Often -it is short with a code example and a paragraph or two explaining the code -example. A majority of readers appreciate how to guides rather than tutorials. +This type of guide does not engage in a step-by-step instructional page. Often it is short with a code example and a paragraph or two explaining the code example. A majority of readers appreciate how to guides rather than tutorials. ## Tutorial -This type if guide steps the reader through a progression. Each step in the -progression is numbered. Once the progression starts it must be contiguous until -the progression ends. There can only be un-numbers sections (heading2) before -and after the progression. Each progression section must be heading2 and each -start with a number followed by a period _(1.)_. See the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guide -as an example. +This type if guide steps the reader through a progression. Each step in the progression is numbered. Once the progression starts it must be contiguous until the progression ends. There can only be un-numbers sections (heading2) before and after the progression. Each progression section must be heading2 and each start with a number followed by a period _(1.)_. See the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guide as an example. -Each section in the progression must instruct the reader to do something, an -action. Sections that are purely instructional must be placed before or after -the progression. Sections in the progression can contain instructional -explanations as they are related to the action the reader must perform. +Each section in the progression must instruct the reader to do something, an action. Sections that are purely instructional must be placed before or after the progression. Sections in the progression can contain instructional explanations as they are related to the action the reader must perform. ## Directory structure -Most guides use a simple directory structure to contain its markdown and other -asset files locally. As a rule the primary markdown page is named `index.md`. In -the example below, `src` might contain images, code sample, and other required -files. +Most guides use a simple directory structure to contain its markdown and other asset files locally. As a rule the primary markdown page is named `index.md`. In the example below, `src` might contain images, code sample, and other required files. ```sh testnets-metamask @@ -57,13 +43,7 @@ testnets-metamask 1. Minimize use of Vue components if any. 1. Simple (post heading 1) intro. 1. Each section (heading 2) involved in the guide’s progression is numbered. -1. Each section (heading 2) should fit (if possible) within the height of a - developer sized screen. +1. Each section (heading 2) should fit (if possible) within the height of a developer sized screen. 1. Avoid the use of heading 3-n sections if possible. -1. Operations related to any clicking widgets (panes, button, pick-list, etc.) - are in bold. -1. For tutorials, “unnumbered” sections (heading 2) can precede or follow a - series of numbered steps ( the tutorial's progression) which must be - contiguous. See the - [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) - guide as an example. +1. Operations related to any clicking widgets (panes, button, pick-list, etc.) are in bold. +1. For tutorials, “unnumbered” sections (heading 2) can precede or follow a series of numbered steps ( the tutorial's progression) which must be contiguous. See the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guide as an example. diff --git a/docs/dev/hyperlinks.md b/docs/dev/hyperlinks.md index 22c71253..1b07cffa 100644 --- a/docs/dev/hyperlinks.md +++ b/docs/dev/hyperlinks.md @@ -12,8 +12,7 @@ tags: # {{$frontmatter.title}} -Consider the following markdown based links in a file -`/reference/ois/latest/specifications.md`. +Consider the following markdown based links in a file `/reference/ois/latest/specifications.md`. - `/reference/ois/latest/reserved-parameters.md#gasprice` @@ -21,31 +20,16 @@ Consider the following markdown based links in a file - `./reserved-parameters.md#gasprice` -Because `reserved-parameters.md` is in the same folder as `specifications.md`, -all three links will work. However with the later two links, VitePress will add -`/reference/ois/latest/` at SPA runtime. This is problematic for link validator -scripts such as `/lib/link-validator.js`. +Because `reserved-parameters.md` is in the same folder as `specifications.md`, all three links will work. However with the later two links, VitePress will add `/reference/ois/latest/` at SPA runtime. This is problematic for link validator scripts such as `/lib/link-validator.js`. -During the release of VitePress 1.0.0-alpha.46 someone thought it best to add -the base path to all markdown URLS at runtime. This was not thought through. It -is entirely possible in the future they will flip on this. This was introduced -as a breaking change. +During the release of VitePress 1.0.0-alpha.46 someone thought it best to add the base path to all markdown URLS at runtime. This was not thought through. It is entirely possible in the future they will flip on this. This was introduced as a breaking change. ::: info VitePress 1.0.0-alpha.46 BREAKING CHANGES -build: base is now prepended to all internal (non-relative) links, including any -reference to a file present in the public directory. If you want the earlier -behavior for such links, use absolute links. +build: base is now prepended to all internal (non-relative) links, including any reference to a file present in the public directory. If you want the earlier behavior for such links, use absolute links. ::: -Even the description for the breaking change is poorly written. The commit can -be seen -[here](https://github.com/vuejs/vitepress/commit/dcf29419f24bfb0fe99e424771be931bf77b9961). +Even the description for the breaking change is poorly written. The commit can be seen [here](https://github.com/vuejs/vitepress/commit/dcf29419f24bfb0fe99e424771be931bf77b9961). -The safest solution is to use the full path from the root of `/docs` or in the -case of the examples above, -`/reference/ois/latest/reserved-parameters.md#gasprice`. Doing so will safe -guard the docs from pattern substitutions by VitePress that could change in -future releases. This will inconvenience writers of the docs but will will save -countless hours tracking down bad links. +The safest solution is to use the full path from the root of `/docs` or in the case of the examples above, `/reference/ois/latest/reserved-parameters.md#gasprice`. Doing so will safe guard the docs from pattern substitutions by VitePress that could change in future releases. This will inconvenience writers of the docs but will will save countless hours tracking down bad links. diff --git a/docs/dev/index.md b/docs/dev/index.md index 5db2fda0..54d64a5d 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -12,9 +12,7 @@ tags: # {{$frontmatter.title}} -Use newer versions of Nodejs. Currently the builds on GitHub are using `v22`. -Mac users (Apple silicon) should see the page -[Rosetta, Nodejs, esbuild](/dev/rosetta.md) if you get an error. +Use newer versions of Nodejs. Currently the builds on GitHub are using `v22`. Mac users (Apple silicon) should see the page [Rosetta, Nodejs, esbuild](/dev/rosetta.md) if you get an error. ::: info Nodejs `v22` @@ -46,8 +44,7 @@ pnpm docs:dev ## Push the working branch -Before pushing your working branch to the remote repo, be sure that the branch -builds. +Before pushing your working branch to the remote repo, be sure that the branch builds. ```sh pnpm docs:build @@ -64,16 +61,11 @@ build complete in 5.20s. ✨ Done in 6.19s. ``` -If the build displays errors or warnings (such as broken links) address them as -needed. +If the build displays errors or warnings (such as broken links) address them as needed. ## Memory -It maybe necessary to increase the memory for Nodejs to run `pnpm docs:dev` or -`pnpm docs:build`. This can be done with the command below, with a higher value -potentially necessary. For Apple silicon this may be a sign of a -[Rosetta issue](/dev/rosetta.md) which should be addressed before committing to -additional memory for Nodejs. +It maybe necessary to increase the memory for Nodejs to run `pnpm docs:dev` or `pnpm docs:build`. This can be done with the command below, with a higher value potentially necessary. For Apple silicon this may be a sign of a [Rosetta issue](/dev/rosetta.md) which should be addressed before committing to additional memory for Nodejs. ```sh export NODE_OPTIONS=--max_old_space_size=1024 diff --git a/docs/dev/link-validation.md b/docs/dev/link-validation.md index 0b307368..3736267a 100644 --- a/docs/dev/link-validation.md +++ b/docs/dev/link-validation.md @@ -12,21 +12,14 @@ tags: # {{$frontmatter.title}} -Use the script `/libs/link-validator.js` to validate links with or without -attached anchors. The link validator is a manual process that should be -performed as often as possible. +Use the script `/libs/link-validator.js` to validate links with or without attached anchors. The link validator is a manual process that should be performed as often as possible. The script is part of a three step process to keep the links in the docs clean. The three steps: -1. `pnpm dev:build`: When doing a local build VitePress will valid markdown - links and does so very well. Fix them before proceeding. This step will also - catch bad `src` paths for images. It does not validate anchors. -2. Search the code base for `](#`. This will show markdown links that link - directly to an anchor. While this will work, the anchors cannot be validated - by `/libs/link-validator.js`, see [Hyperlinks](/dev/hyperlinks.md) to - understand how to fix them. +1. `pnpm dev:build`: When doing a local build VitePress will valid markdown links and does so very well. Fix them before proceeding. This step will also catch bad `src` paths for images. It does not validate anchors. +2. Search the code base for `](#`. This will show markdown links that link directly to an anchor. While this will work, the anchors cannot be validated by `/libs/link-validator.js`, see [Hyperlinks](/dev/hyperlinks.md) to understand how to fix them. 3. Run the `/libs/link-validator.js` script. ## Using the script @@ -41,13 +34,11 @@ Build the docs as usual using the standard build command provided by VitePress. pnpm docs:build ``` -Note that the build script may in fact catch bad links in of itself. Any -reported links should be fixed before proceeding. +Note that the build script may in fact catch bad links in of itself. Any reported links should be fixed before proceeding. ### 2. Start the local VitePress server -VitePress has a built-in http server that publishes the files from the `/dist` -folder. +VitePress has a built-in http server that publishes the files from the `/dist` folder. ```sh pnpm docs:serve @@ -55,14 +46,9 @@ pnpm docs:serve ### 3. Run the script -Open a new terminal window to run the script. The script's output will display -an indicator for failures as it steps through each file. There will be a summary -of all link failures at the end of the script output. +Open a new terminal window to run the script. The script's output will display an indicator for failures as it steps through each file. There will be a summary of all link failures at the end of the script output. -You can run the Link Validator against the entire `/dist` folder which will -validate all docsets but this can be time consuming. Narrowing the scope of the -validation to a particular folder (docset) can hasten the validation process. Be -sure to use the correct port displayed by VitePress server. +You can run the Link Validator against the entire `/dist` folder which will validate all docsets but this can be time consuming. Narrowing the scope of the validation to a particular folder (docset) can hasten the validation process. Be sure to use the correct port displayed by VitePress server. ```sh node ./libs/link-validator.js http://localhost:8082 ./docs/.vitepress/dist/ diff --git a/docs/dev/page-styling.md b/docs/dev/page-styling.md index 3a81611c..7ab443ef 100644 --- a/docs/dev/page-styling.md +++ b/docs/dev/page-styling.md @@ -14,9 +14,7 @@ tags: # {{$frontmatter.title}} -You can add a style definition just for a single page. Be careful not to use -class names used by VitePress. Prefixing `api3` to all class names is a best -practice to protect VitePress classes. +You can add a style definition just for a single page. Be careful not to use class names used by VitePress. Prefixing `api3` to all class names is a best practice to protect VitePress classes.
this-smaller-font

diff --git a/docs/dev/rosetta.md b/docs/dev/rosetta.md index 234d4e2d..dc0b0c10 100644 --- a/docs/dev/rosetta.md +++ b/docs/dev/rosetta.md @@ -12,14 +12,7 @@ tags: # {{$frontmatter.title}} -This page refers to Apple silicon Macs that have implemented the use of Rosetta. -It is best not to use Rosetta with the VitePress docs. While it may work it -almost always results in longer builds and other processes. Other issues can -arise such as the Rosetta platform error. This usually happens when Nodejs and -NPM are installed using CLI running with Rosetta on, and NPM will install the -wrong [esbuild](https://esbuild.github.io/getting-started/) package. It is best -to use a version of Nodejs and NPM installed with its installer or install it -using your CLI with Rosetta deactivated. +This page refers to Apple silicon Macs that have implemented the use of Rosetta. It is best not to use Rosetta with the VitePress docs. While it may work it almost always results in longer builds and other processes. Other issues can arise such as the Rosetta platform error. This usually happens when Nodejs and NPM are installed using CLI running with Rosetta on, and NPM will install the wrong [esbuild](https://esbuild.github.io/getting-started/) package. It is best to use a version of Nodejs and NPM installed with its installer or install it using your CLI with Rosetta deactivated. ::: info Nodejs `v22` @@ -52,13 +45,9 @@ installing a package on multiple platforms simultaneously. ## How to correct -If you run `pnpm docs:build` and get the above error you may have an `esbuild` -package for use with the non-native platform for Apple silicon probably install -using NPM. Run the following (only using pnpm) to update `esbuild`. If your CLI -is not running under Rosetta, it will install for the proper platform. +If you run `pnpm docs:build` and get the above error you may have an `esbuild` package for use with the non-native platform for Apple silicon probably install using NPM. Run the following (only using pnpm) to update `esbuild`. If your CLI is not running under Rosetta, it will install for the proper platform. -`esbuild` will not appear in `packages.json` under `devDependencies`, but it -does update. +`esbuild` will not appear in `packages.json` under `devDependencies`, but it does update. ```sh pnpm install --dev esbuild diff --git a/docs/dev/ssr.md b/docs/dev/ssr.md index 138e83a0..874a8ac2 100644 --- a/docs/dev/ssr.md +++ b/docs/dev/ssr.md @@ -12,13 +12,8 @@ tags: # {{$frontmatter.title}} -API3 uses CloudFlare for DNS records which includes the docs. If SSR is turned -on for any domain related to the docs, then CloudFlare will minify the already -minified build files from Firebase. This will result in the merging of pages -visible to the reader. +API3 uses CloudFlare for DNS records which includes the docs. If SSR is turned on for any domain related to the docs, then CloudFlare will minify the already minified build files from Firebase. This will result in the merging of pages visible to the reader. -Because the docs are not using SSR and relying are on a CDN (Firebase), caching -isn't necessary. The CDN is effectively a cache as the data is static. So -caching for DNS records related to the docs should be turned off. +Because the docs are not using SSR and relying are on a CDN (Firebase), caching isn't necessary. The CDN is effectively a cache as the data is static. So caching for DNS records related to the docs should be turned off. diff --git a/docs/dev/versioning.md b/docs/dev/versioning.md index 854b7648..7dc3d168 100644 --- a/docs/dev/versioning.md +++ b/docs/dev/versioning.md @@ -12,9 +12,7 @@ tags: # {{$frontmatter.title}} -Versioning of a a [docset](/dev/docsets.md) only applies to Airnode and OIS. -There is the concept of `/latest` and `/next`. Consider the chart below which -represents Airnode: +Versioning of a a [docset](/dev/docsets.md) only applies to Airnode and OIS. There is the concept of `/latest` and `/next`. Consider the chart below which represents Airnode: | File path and URI | Version | | ------------------------- | ------- | @@ -42,20 +40,14 @@ reference In order to advance the versioning the following actions occur: -1. Rename (`git mv`) the `/latest` folder to the version that is being - superseded vX.YZ. +1. Rename (`git mv`) the `/latest` folder to the version that is being superseded vX.YZ. 2. Make a copy of `/next` as `/latest`. -Update links and other version specific content. For `vx.xx`, `/latest`, and -`/next` review the following and make the following changes where needed. +Update links and other version specific content. For `vx.xx`, `/latest`, and `/next` review the following and make the following changes where needed. -> Be careful with Airnode `migration.md` pages. Older version are mentioned as -> needed within. +> Be careful with Airnode `migration.md` pages. Older version are mentioned as needed within. -In the number steps below consider some of the search criteria listed below. -Narrow the search include/exclude pattern. `migration.md` should be updated -manually for each Airnode version. Make sure the version, latest, or next -attribute is correct for each version of Airnode or OIS. +In the number steps below consider some of the search criteria listed below. Narrow the search include/exclude pattern. `migration.md` should be updated manually for each Airnode version. Make sure the version, latest, or next attribute is correct for each version of Airnode or OIS. @@ -84,25 +76,15 @@ attribute is correct for each version of Airnode or OIS. 1. Update `themeConfig.sidebar` in `/.vitepress/config.js` 2. Update `/.vitepress/versions.json` to reflect the latest and next versions. -3. Update internal hyperlinks in the content. In latest use `/latest`, next use - `/next`. For folders of a specific version use the correct version number. +3. Update internal hyperlinks in the content. In latest use `/latest`, next use `/next`. For folders of a specific version use the correct version number. 4. Be sure the above step also changed the `path` in frontmatter. 5. Change frontmatter `version:` to the proper version. -6. For `/latest` look for and change external links to API3 repos that may use - older repo tags, `/master`, or `/main`. Some repos may not use tags and - `/main` must be used, some may have tags unrelated to Airnode. Evaluate each - link for changes as needed. +6. For `/latest` look for and change external links to API3 repos that may use older repo tags, `/master`, or `/main`. Some repos may not use tags and `/main` must be used, some may have tags unrelated to Airnode. Evaluate each link for changes as needed. 7. Look for links with versions that use x.x.x (i.e. Admin cli, 0.12.0) -8. Look for links to api3 repos that use older version such as Airnode `v0.11` - or OIS `v2.0`. These need to use the proper versions. -9. Verify links in Airnode releases reference the proper OIS release and - vice-versa. See the OIS [versions](/reference/ois/latest/versions.md) table. -10. For `/next` change frontmatter `pageHeader: Reference → Airnode → vx.x` to - the proper version. -11. `/next` will not have a repo tag created until its version is release. Use - the version of `/latest` in the mean time. -12. Update the [Versions](/reference/ois/latest/versions.md) page in OIS which - maps OIS versions to Airnode versions. -13. Update the [Versions](/reference/airnode/latest/versions.md) page in - Airnode. +8. Look for links to api3 repos that use older version such as Airnode `v0.11` or OIS `v2.0`. These need to use the proper versions. +9. Verify links in Airnode releases reference the proper OIS release and vice-versa. See the OIS [versions](/reference/ois/latest/versions.md) table. +10. For `/next` change frontmatter `pageHeader: Reference → Airnode → vx.x` to the proper version. +11. `/next` will not have a repo tag created until its version is release. Use the version of `/latest` in the mean time. +12. Update the [Versions](/reference/ois/latest/versions.md) page in OIS which maps OIS versions to Airnode versions. +13. Update the [Versions](/reference/airnode/latest/versions.md) page in Airnode. 14. Change OIS and Airnode versions in he quick start guides. diff --git a/docs/dev/zip-handling.md b/docs/dev/zip-handling.md index 111a3679..4a616b7f 100644 --- a/docs/dev/zip-handling.md +++ b/docs/dev/zip-handling.md @@ -24,9 +24,7 @@ To facilitate the creation of these zip files, the following script can be run: pnpm zip:create ``` -To ensure that the `config.json` files within these zip files do not get -out-of-sync with their input `config.json` files, the following script is run as -part of the pre-push hook (it can also be run independently): +To ensure that the `config.json` files within these zip files do not get out-of-sync with their input `config.json` files, the following script is run as part of the pre-push hook (it can also be run independently): ```sh pnpm zip:config-check diff --git a/docs/guides/airnode/calling-an-airnode/index.md b/docs/guides/airnode/calling-an-airnode/index.md index 12fd7534..800dff04 100644 --- a/docs/guides/airnode/calling-an-airnode/index.md +++ b/docs/guides/airnode/calling-an-airnode/index.md @@ -22,31 +22,21 @@ tags: ## Introduction -[Airnodes](/reference/airnode/latest/concepts/airnode.md) are first-party -oracles that are directly operated by the API Providers that provide data to any -on-chain dApp. The Smart Contracts can request data from the Airnodes without -going through any intermediary. +[Airnodes](/reference/airnode/latest/concepts/airnode.md) are first-party oracles that are directly operated by the API Providers that provide data to any on-chain dApp. The Smart Contracts can request data from the Airnodes without going through any intermediary. -This guide shows you how to code, deploy, and run a simple smart contract that -requests data from an Airnode, via the -[Request Response Protocol](/reference/airnode/latest/concepts/). +This guide shows you how to code, deploy, and run a simple smart contract that requests data from an Airnode, via the [Request Response Protocol](/reference/airnode/latest/concepts/). ## 1. Coding the Requester Contract ::: warning Check your Network! -Make sure you're on a Ethereum Sepolia testnet before trying to deploy the -contracts on-chain! +Make sure you're on a Ethereum Sepolia testnet before trying to deploy the contracts on-chain! ::: -Given below is an example of a basic -[Requester Contract](/reference/airnode/latest/concepts/requester.md) to request -data from any Airnode. To follow along, you can open the following contract in -Remix and try deploying your own Requester Contract. +Given below is an example of a basic [Requester Contract](/reference/airnode/latest/concepts/requester.md) to request data from any Airnode. To follow along, you can open the following contract in Remix and try deploying your own Requester Contract. -In this example, you will be calling the Coingecko Airnode to request the latest -price of an asset on Ethereum Sepolia. +In this example, you will be calling the Coingecko Airnode to request the latest price of an asset on Ethereum Sepolia. [Open in Remix](https://remix.ethereum.org/#url=https://github.com/api3-ecosystem/remix-contracts/blob/master/contracts/RequesterWithWithdrawal.sol&lang=en&optimize=false&runs=200&evmVersion=null&version=soljson-v0.8.9+commit.e5eed63a.js) @@ -110,9 +100,7 @@ contract Requester is RrpRequesterV0, Ownable { ### Request Parameters -A full request using the `AirnodeRrpV0.sol` contract's `makeFullRequest` -function requires all parameters needed by the Airnode application to be passed -at runtime. +A full request using the `AirnodeRrpV0.sol` contract's `makeFullRequest` function requires all parameters needed by the Airnode application to be passed at runtime. ```solidity function makeRequest( @@ -136,36 +124,21 @@ at runtime. } ``` -Since the `makeRequest` function makes a -[full request](/reference/airnode/latest/concepts/request.md#full-request), it -needs the following parameters to pass on to `airnodeRrp.makeFullRequest`. +Since the `makeRequest` function makes a [full request](/reference/airnode/latest/concepts/request.md#full-request), it needs the following parameters to pass on to `airnodeRrp.makeFullRequest`. -- `airnode` and `endpointId`: As a pair, these uniquely identify the endpoint - desired at a particular Airnode. +- `airnode` and `endpointId`: As a pair, these uniquely identify the endpoint desired at a particular Airnode. -- `sponsor`: The [sponsor](/reference/airnode/latest/concepts/sponsor.md) - address. +- `sponsor`: The [sponsor](/reference/airnode/latest/concepts/sponsor.md) address. -- `sponsorWallet`: The - [sponsor wallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) - address that the sponsor derived using the Airnode's address and extended - public key. +- `sponsorWallet`: The [sponsor wallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) address that the sponsor derived using the Airnode's address and extended public key. -- `fulfillAddress` and `fulfillFunctionId`: The public address of your requester - contract and its function that is called upon the return of the request. +- `fulfillAddress` and `fulfillFunctionId`: The public address of your requester contract and its function that is called upon the return of the request. -- `parameters`: Specify the API parameters and any - [reserved parameters](/reference/ois/latest/reserved-parameters.md), these - must be encoded. See - [Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md) - for how these are encoded. In most, cases the `parameters` are encoded - off-chain and passed to the requester which only forwards them. You can use - the `@api3/airnode-abi` package to perform the encoding and decoding. +- `parameters`: Specify the API parameters and any [reserved parameters](/reference/ois/latest/reserved-parameters.md), these must be encoded. See [Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md) for how these are encoded. In most, cases the `parameters` are encoded off-chain and passed to the requester which only forwards them. You can use the `@api3/airnode-abi` package to perform the encoding and decoding. ### Response Parameters -The callback to a requester contains two parameters, as shown in the `fulfill` -function in the code sample below. +The callback to a requester contains two parameters, as shown in the `fulfill` function in the code sample below. ```solidity function fulfill(bytes32 requestId, bytes calldata data) @@ -180,17 +153,12 @@ function in the code sample below. } ``` -- `requestId`: First acquired when making the request and passed here as a - reference to identify the request for which the response is intended. -- `data`: In case of a successful response, this is the requested data which has - been encoded and contains a timestamp in addition to other response data. - Decode it using the function decode() from the abi object. +- `requestId`: First acquired when making the request and passed here as a reference to identify the request for which the response is intended. +- `data`: In case of a successful response, this is the requested data which has been encoded and contains a timestamp in addition to other response data. Decode it using the function decode() from the abi object. ### Withdrawal -The `withdraw()` function is used to withdraw funds from the designated sponsor -wallet to the sponsor. In this case, we're using the `RrpRequesterV0` for which -the sponsor is the Requester contract itself. +The `withdraw()` function is used to withdraw funds from the designated sponsor wallet to the sponsor. In this case, we're using the `RrpRequesterV0` for which the sponsor is the Requester contract itself. It calls the `requestWithdrawal` function of the `airnodeRrp` contract. @@ -202,49 +170,31 @@ It calls the `requestWithdrawal` function of the `airnodeRrp` contract. :::warning Set up your Testnet Metamask Account! -Make sure you've already configured your Metamask wallet and funded it with some -testnet Sepolia ETH before moving forward. You can request some from -[here](https://www.alchemy.com/faucets/ethereum-sepolia) +Make sure you've already configured your Metamask wallet and funded it with some testnet Sepolia ETH before moving forward. You can request some from [here](https://www.alchemy.com/faucets/ethereum-sepolia) ::: -You now need to deploy the Requester Contract and call it through Remix. It will -be calling the Coingecko Airnode to request the latest price of Bitcoin on -Ethereum Sepolia testnet. +You now need to deploy the Requester Contract and call it through Remix. It will be calling the Coingecko Airnode to request the latest price of Bitcoin on Ethereum Sepolia testnet. ### Compile and Deploy the Requester Contract on Sepolia Testnet -- [Click here](https://remix.ethereum.org/#url=https://github.com/api3-ecosystem/remix-contracts/blob/master/contracts/RequesterWithWithdrawal.sol&lang=en&optimize=false&runs=200&evmVersion=null&version=soljson-v0.8.9+commit.e5eed63a.js) - to open the Requester Contract in Remix. +- [Click here](https://remix.ethereum.org/#url=https://github.com/api3-ecosystem/remix-contracts/blob/master/contracts/RequesterWithWithdrawal.sol&lang=en&optimize=false&runs=200&evmVersion=null&version=soljson-v0.8.9+commit.e5eed63a.js) to open the Requester Contract in Remix. > ![Opening the Requester Contract in Remix](src/s1.png) -- Click on the **COMPILE** tab on the left side of the dashboard and click on - **Compile Requester.sol** +- Click on the **COMPILE** tab on the left side of the dashboard and click on **Compile Requester.sol** > ![Compiling the Requester](./src/s2.png) -- Head to Deploy and run Transactions and select Injected Provider — MetaMask - option under Environment. Connect your MetaMask. Make sure you’re on the - Sepolia Testnet. +- Head to Deploy and run Transactions and select Injected Provider — MetaMask option under Environment. Connect your MetaMask. Make sure you’re on the Sepolia Testnet. -- The `_rrpAddress` is the main `airnodeRrpAddress`. The RRP Contracts have - already been deployed on-chain. You can check for your specific chain - [here](/reference/airnode/latest/). Fill it in and Deploy the Contract. +- The `_rrpAddress` is the main `airnodeRrpAddress`. The RRP Contracts have already been deployed on-chain. You can check for your specific chain [here](/reference/airnode/latest/). Fill it in and Deploy the Contract. > ![Deploying the Requester](./src/s3.png) ### Sponsor the Requester -The -[Sponsor Wallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) -needs to be derived from the requester's contract address, the Airnode address, -and the Airnode xpub. The wallet is used to pay gas costs of the transactions. -The sponsor wallet must be derived using the command -[derive-sponsor-wallet-address](/reference/airnode/latest/developers/requesters-sponsors.md#how-to-derive-a-sponsor-wallet) -from the [Admin CLI](/reference/airnode/latest/packages/admin-cli). Use the -value of the sponsor wallet address that the command outputs while making the -request. **This wallet needs to be funded.** +The [Sponsor Wallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) needs to be derived from the requester's contract address, the Airnode address, and the Airnode xpub. The wallet is used to pay gas costs of the transactions. The sponsor wallet must be derived using the command [derive-sponsor-wallet-address](/reference/airnode/latest/developers/requesters-sponsors.md#how-to-derive-a-sponsor-wallet) from the [Admin CLI](/reference/airnode/latest/packages/admin-cli). Use the value of the sponsor wallet address that the command outputs while making the request. **This wallet needs to be funded.** ::: details Coingecko's Airnode Details on Sepolia Testnet @@ -268,21 +218,13 @@ npx @api3/airnode-admin derive-sponsor-wallet-address \ ::: warning Designated Sponsor Wallets -Sponsors should not fund a `sponsorWallet` with more than they can trust the -Airnode with, as the Airnode controls the private key to the `sponsorWallet`. -The deployer of such Airnode undertakes no custody obligations, and the risk of -loss or misuse of any excess funds sent to the `sponsorWallet` remains with the -sponsor. +Sponsors should not fund a `sponsorWallet` with more than they can trust the Airnode with, as the Airnode controls the private key to the `sponsorWallet`. The deployer of such Airnode undertakes no custody obligations, and the risk of loss or misuse of any excess funds sent to the `sponsorWallet` remains with the sponsor. ::: ### Encoding parameters -`parameters` specify the API and Reserved Parameters (see -[Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md) -for how these are encoded). The parameters are required to be encoded in bytes32 -before you send it. Use the `@api3/airnode-abi` library to encode the parameters -off-chain and then send it to the Requester. +`parameters` specify the API and Reserved Parameters (see [Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md) for how these are encoded). The parameters are required to be encoded in bytes32 before you send it. Use the `@api3/airnode-abi` library to encode the parameters off-chain and then send it to the Requester. You can encode your API Parameters off-chain using the following code snippet. @@ -305,23 +247,18 @@ console.log(encodedData); console.log(decodedData); ``` -It should output the encoded parameters. If you want, you can copy the encoded -parameters directly from here: (`0x3...000`→) ## 3. Making the Request -Head over to the **Deploy & run transactions** tab, click on the `contract` -dropdown and select `Requester.sol` +Head over to the **Deploy & run transactions** tab, click on the `contract` dropdown and select `Requester.sol` -Now select the `makeRequest` dropdown to see all the parameters you need to pass -in order to make a full request to the Airnode. Populate all the fields and -click on Transact. +Now select the `makeRequest` dropdown to see all the parameters you need to pass in order to make a full request to the Airnode. Populate all the fields and click on Transact. > ![Making the Request](src/s5.png) -Head over to [Sepolia Testnet Explorer](https://sepolia.etherscan.io/) and check -your `sponsorWallet` for any new transactions. +Head over to [Sepolia Testnet Explorer](https://sepolia.etherscan.io/) and check your `sponsorWallet` for any new transactions. > ![Making the Request](src/s6.png) @@ -329,30 +266,21 @@ Here, you can see the latest `Fulfill` transaction. ::: info You might need to wait for a minute or two -The Airnode calls the fulfill() function in `AirnodeRrpV0.sol` that will in turn -call back the requester contract at `fulfillAddress` using function -`fulfillFunctionId` to deliver data. +The Airnode calls the fulfill() function in `AirnodeRrpV0.sol` that will in turn call back the requester contract at `fulfillAddress` using function `fulfillFunctionId` to deliver data. ::: -Now go back on Remix and check for `requestId` under logs for the latest -transaction. +Now go back on Remix and check for `requestId` under logs for the latest transaction. -Copy your `requestId` and paste it under the `fulfilledData` method to decode -the response. Click on call and you will see the API response. Here, you can see -your requested data decoded in `int256` +Copy your `requestId` and paste it under the `fulfilledData` method to decode the response. Click on call and you will see the API response. Here, you can see your requested data decoded in `int256` > ![Making the Request](src/s7.png) ## 4. Withdrawing Funds from the `sponsorWallet` (optional) -You can withdraw funds from the sponsor wallet to address of the owner by -calling the `withdraw()` function. +You can withdraw funds from the sponsor wallet to address of the owner by calling the `withdraw()` function. -The Airnode listens for withdrawal requests and fulfills them automatically. -Therefore, the Requester contract makes a request for withdrawal to the Airnode. -The Airnode then fulfills the request, calls the `receive()` function in the -Requester contract, that sends the funds back to the owner. +The Airnode listens for withdrawal requests and fulfills them automatically. Therefore, the Requester contract makes a request for withdrawal to the Airnode. The Airnode then fulfills the request, calls the `receive()` function in the Requester contract, that sends the funds back to the owner. ```solidity receive() external payable { @@ -360,18 +288,15 @@ Requester contract, that sends the funds back to the owner. } ``` -The `sponsorWallet` does not get deleted, and can be used in the future simply -by funding it again. +The `sponsorWallet` does not get deleted, and can be used in the future simply by funding it again. -Simply pass in the `airnode` and the `sponsorWallet` address and click -**transact**. Confirm the transaction on Metamask. +Simply pass in the `airnode` and the `sponsorWallet` address and click **transact**. Confirm the transaction on Metamask. > ![Making the Request](src/s8.png) _[Click here to read more about how sponsors, requesters and withdrawals work](/reference/airnode/latest/concepts/sponsor.md)_ -Now wait for the Airnode to fulfill the withdrawal request. You can check the -sponsor wallet for any new transactions. +Now wait for the Airnode to fulfill the withdrawal request. You can check the sponsor wallet for any new transactions. > ![Making the Request](src/s9.png) @@ -381,25 +306,15 @@ The funds from the `sponsorWallet` have been transferred to the owner. ## 5. Using HTTP Gateways (optional) -You can use -[HTTP Gateways](/reference/airnode/latest/understand/http-gateways.html) to make -requests to the Airnode off-chain. HTTP Gateways are usually used to test and -ensure if the Airnode is configured properly and working as expected without -having the need to make a request on-chain. +You can use [HTTP Gateways](/reference/airnode/latest/understand/http-gateways.html) to make requests to the Airnode off-chain. HTTP Gateways are usually used to test and ensure if the Airnode is configured properly and working as expected without having the need to make a request on-chain. [Read more about HTTP Gateways here.](/reference/airnode/latest/understand/http-gateways.html) -Once you deploy an Airnode, the HTTP Gateway and the HTTP Signed data Gateway -URLs are displayed on the terminal at the end of the deployment process. You can -use these URLs to make HTTP requests to the Airnode. +Once you deploy an Airnode, the HTTP Gateway and the HTTP Signed data Gateway URLs are displayed on the terminal at the end of the deployment process. You can use these URLs to make HTTP requests to the Airnode. -For this example, we are going to use the Coingecko's Airnode HTTP Gateway URL -to to make a request to the Airnode. You can use a tool like -[Postman](https://www.postman.com/) or CURL to make a POST request. +For this example, we are going to use the Coingecko's Airnode HTTP Gateway URL to to make a request to the Airnode. You can use a tool like [Postman](https://www.postman.com/) or CURL to make a POST request. -To make a request for the HTTP Gateway, you need to make a POST request to the -HTTP Gateway URL followed by the endpoint ID along with the following parameters -defined in the request body. +To make a request for the HTTP Gateway, you need to make a POST request to the HTTP Gateway URL followed by the endpoint ID along with the following parameters defined in the request body. ```bash curl \ @@ -409,10 +324,7 @@ curl \ 'https://v5smo0rs75.execute-api.us-east-1.amazonaws.com/v1/d8c1ffa0-6e08-a88c-c999-a31f2acc2c22/0x5dbf4e8c53ad4ffdec277ec4df847e6272597fd851f147c93208e0cff99df72d' ``` -Similarly, for a HTTP Signed data Gateway request, you need to pass in the -encoded parameters defined as `encodedParameters` in the request body. You can -use the `@api3/airnode-abi` library to encode the parameters like previously -shown. +Similarly, for a HTTP Signed data Gateway request, you need to pass in the encoded parameters defined as `encodedParameters` in the request body. You can use the `@api3/airnode-abi` library to encode the parameters like previously shown. ```bash curl \ diff --git a/docs/guides/airnode/deploy-airnode/deploy-aws/index.md b/docs/guides/airnode/deploy-airnode/deploy-aws/index.md index e4d0023e..7fa2a5f4 100644 --- a/docs/guides/airnode/deploy-airnode/deploy-aws/index.md +++ b/docs/guides/airnode/deploy-airnode/deploy-aws/index.md @@ -16,37 +16,15 @@ tags: # {{$frontmatter.title}} -This guide demonstrates the deployment of an Airnode followed by an off-chain -[HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md) request. -Configuration files are provided with only minor changes to be made. The -[latest release](https://hub.docker.com/r/api3/airnode-deployer/tags) of the -Airnode [deployer image](/reference/airnode/latest/docker/deployer-image.md) -will be used to deploy the off-chain component of Airnode (a.k.a., the node) to -AWS. - -This Airnode contains a single API operation (`GET /simple/price`) from -[CoinGecko](https://docs.coingecko.com/reference/introduction) which returns the -current value of a coin. This guide does not detail the overall configuration of -an Airnode, it is just a quick start guide then lends itself to understanding an -Airnode deployment. - -Please note that this tutorial does not involve the blockchain nor an RRP -(request-response protocol) call from a smart contract. If you wish to make an -RRP call, please see the guides -[Making an RRP Request](/guides/airnode/rrp-request.md) and -[Calling an Airnode](/guides/airnode/calling-an-airnode/). +This guide demonstrates the deployment of an Airnode followed by an off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md) request. Configuration files are provided with only minor changes to be made. The [latest release](https://hub.docker.com/r/api3/airnode-deployer/tags) of the Airnode [deployer image](/reference/airnode/latest/docker/deployer-image.md) will be used to deploy the off-chain component of Airnode (a.k.a., the node) to AWS. + +This Airnode contains a single API operation (`GET /simple/price`) from [CoinGecko](https://docs.coingecko.com/reference/introduction) which returns the current value of a coin. This guide does not detail the overall configuration of an Airnode, it is just a quick start guide then lends itself to understanding an Airnode deployment. + +Please note that this tutorial does not involve the blockchain nor an RRP (request-response protocol) call from a smart contract. If you wish to make an RRP call, please see the guides [Making an RRP Request](/guides/airnode/rrp-request.md) and [Calling an Airnode](/guides/airnode/calling-an-airnode/). ## Configuration Files -An Airnode deployment on AWS uses the Docker -[deployer image](/reference/airnode/latest/docker/deployer-image.md) which -requires three files as input: -[config.json](/guides/airnode/deploy-airnode/deploy-aws/index.md#config-json), -[secrets.env](/guides/airnode/deploy-airnode/deploy-aws/index.md#secrets-env), -and [aws.env](/guides/airnode/deploy-airnode/deploy-aws/index.md#aws-env). These -files have been created and only require a few minor changes to make the -deployment of the Airnode successful. The changes are needed to supply AWS -credentials, a chain provider url, and a mnemonic. +An Airnode deployment on AWS uses the Docker [deployer image](/reference/airnode/latest/docker/deployer-image.md) which requires three files as input: [config.json](/guides/airnode/deploy-airnode/deploy-aws/index.md#config-json), [secrets.env](/guides/airnode/deploy-airnode/deploy-aws/index.md#secrets-env), and [aws.env](/guides/airnode/deploy-airnode/deploy-aws/index.md#aws-env). These files have been created and only require a few minor changes to make the deployment of the Airnode successful. The changes are needed to supply AWS credentials, a chain provider url, and a mnemonic. ## 1. Install Prerequisites @@ -54,8 +32,7 @@ Install the [Docker Desktop](https://docs.docker.com/get-docker/) and launch it. ## 2. Project Folder -Download the -quick-start-aws.zip project folder. Extract it into any location. +Download the quick-start-aws.zip project folder. Extract it into any location. ``` quick-start-aws @@ -66,9 +43,7 @@ quick-start-aws ## 3. Prepare Configuration Files -Prepare the three configuration files. The Airnode deployer image looks for -`config.json`, `secrets.env`, and `aws.env` in the project root directory and -writes `receipt.json` to the project root folder. +Prepare the three configuration files. The Airnode deployer image looks for `config.json`, `secrets.env`, and `aws.env` in the project root directory and writes `receipt.json` to the project root folder. ### config.json @@ -80,19 +55,9 @@ writes `receipt.json` to the project root folder. ::: -This file requires no changes on your part. It has been created with just one -API endpoint and configured to listen to requests on the Sepolia test network, -though this tutorial will not make any such requests. There are a few variables -this file will interpolate from `secrets.env`. +This file requires no changes on your part. It has been created with just one API endpoint and configured to listen to requests on the Sepolia test network, though this tutorial will not make any such requests. There are a few variables this file will interpolate from `secrets.env`. -Note that `nodeSetting.cloudProvider.disableConcurrencyReservations` has been -set to `true`. This is a precaution for new AWS accounts that have yet to -address concurrency management. For production deployments, -`disableConcurrencyReservations` should be set to `false`. See -[disableConcurrencyReservations](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider-disableconcurrencyreservations) -under the `cloudProvider` key and -[maxConcurrency](/reference/airnode/latest/deployment-files/config-json.md#maxconcurrency) -for more information. +Note that `nodeSetting.cloudProvider.disableConcurrencyReservations` has been set to `true`. This is a precaution for new AWS accounts that have yet to address concurrency management. For production deployments, `disableConcurrencyReservations` should be set to `false`. See [disableConcurrencyReservations](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider-disableconcurrencyreservations) under the `cloudProvider` key and [maxConcurrency](/reference/airnode/latest/deployment-files/config-json.md#maxconcurrency) for more information. ### secrets.env @@ -104,16 +69,11 @@ for more information. ::: -There are two values `config.json` interpolates from `secrets.env`. Add values -for each of these fields. +There are two values `config.json` interpolates from `secrets.env`. Add values for each of these fields. -- `CHAIN_PROVIDER_URL`: A blockchain provider url from a provider such as - [Infura](https://www.infura.io/). Use a url for the Sepolia test network. +- `CHAIN_PROVIDER_URL`: A blockchain provider url from a provider such as [Infura](https://www.infura.io/). Use a url for the Sepolia test network. -- `AIRNODE_WALLET_MNEMONIC`: Provide the seed phrase (mnemonic) to a new digital - wallet. The wallet does not need to be funded. Use the Admin CLI command - [generate-airnode-mnemonic](/reference/airnode/latest/packages/admin-cli.md#generate-airnode-mnemonic) - to create one. +- `AIRNODE_WALLET_MNEMONIC`: Provide the seed phrase (mnemonic) to a new digital wallet. The wallet does not need to be funded. Use the Admin CLI command [generate-airnode-mnemonic](/reference/airnode/latest/packages/admin-cli.md#generate-airnode-mnemonic) to create one. ```sh [generate-airnode-mnemonic] npx @api3/airnode-admin generate-airnode-mnemonic @@ -129,35 +89,20 @@ for each of these fields. ::: -Add the access credentials from your AWS account. The deployer image will use -these to install the Airnode functions to Lambda under your account's control. -If you do not have an account watch this -[video](https://www.youtube.com/watch?v=KngM5bfpttA) to create one. Unlike -`secrets.env`, you cannot surround values with double quotes ("). +Add the access credentials from your AWS account. The deployer image will use these to install the Airnode functions to Lambda under your account's control. If you do not have an account watch this [video](https://www.youtube.com/watch?v=KngM5bfpttA) to create one. Unlike `secrets.env`, you cannot surround values with double quotes ("). - `AWS_ACCESS_KEY_ID`: Is ACCESS_KEY_ID in IAM. - `AWS_SECRET_ACCESS_KEY`: Is SECRET_ACCESS_KEY in IAM. ## 4. Deploy -Make sure Docker is running and then execute the deployer image from the root of -the `quick-start-aws` folder. A `receipt.json` file will be created upon -completion. It contains some deployment information and is used to remove the -Airnode. +Make sure Docker is running and then execute the deployer image from the root of the `quick-start-aws` folder. A `receipt.json` file will be created upon completion. It contains some deployment information and is used to remove the Airnode. -Run the following command to deploy the Airnode. Normally (for Linux/Mac/WSL2) -the deployer image `deploy` command is run by the user root. This may cause -permission issues when the `receipt.json` file is generated. Optionally you can -specify the -UID -(user identifier) and GID -(group identifier) that the deployer image should use. Do so by setting the -environment variables USER_ID and GROUP_ID, otherwise omit the line containing -these variables. +Run the following command to deploy the Airnode. Normally (for Linux/Mac/WSL2) the deployer image `deploy` command is run by the user root. This may cause permission issues when the `receipt.json` file is generated. Optionally you can specify the UID (user identifier) and GID (group identifier) that the deployer image should use. Do so by setting the environment variables USER_ID and GROUP_ID, otherwise omit the line containing these variables. ::: code-group @@ -178,8 +123,7 @@ docker run -it --rm ^ ::: -Make note of the `HTTP gateway URL` in your output as shown below as it will be -different. You will need it to test the Airnode. +Make note of the `HTTP gateway URL` in your output as shown below as it will be different. You will need it to test the Airnode. ```sh [output] ✔ Deployed Airnode 0x6A6cF2d0094c73b7aBb22Cd6196824BCBB830125 quick-aws to aws us-east-1 @@ -190,16 +134,11 @@ different. You will need it to test the Airnode. ## 5. Test the Airnode -After a successful deployment the Airnode can be tested directly using its -off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md). -As a reminder, this is independent of the blockchain and RRP contract. +After a successful deployment the Airnode can be tested directly using its off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md). As a reminder, this is independent of the blockchain and RRP contract. ### HTTP Gateway -Looking at the `config.json` code snippet below shows that the HTTP gateway is -configured for the Airnode. Furthermore, the endpoint for `/simple/price` (with -an `endpointId` of `0x6...af6`) is present in `triggers.http[n]`. Only those -endpoints added to the `http` array can be tested using the HTTP gateway. +Looking at the `config.json` code snippet below shows that the HTTP gateway is configured for the Airnode. Furthermore, the endpoint for `/simple/price` (with an `endpointId` of `0x6...af6`) is present in `triggers.http[n]`. Only those endpoints added to the `http` array can be tested using the HTTP gateway. ::: details Expand to view: HTTP gateway and endpoint ID @@ -237,28 +176,18 @@ endpoints added to the `http` array can be tested using the HTTP gateway. ### Execute Endpoint -Use CURL to execute a HTTP gateway request for the CoinGecko endpoint -`/simple/price`. +Use CURL to execute a HTTP gateway request for the CoinGecko endpoint `/simple/price`. -As an alternative to CURL, an app such as [Insomnia](https://insomnia.rest/) or -[Postman](https://www.postman.com/product/rest-client/) can be used. Windows -users can also use -[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) -(WSL2) to run CURL on Linux. +As an alternative to CURL, an app such as [Insomnia](https://insomnia.rest/) or [Postman](https://www.postman.com/product/rest-client/) can be used. Windows users can also use [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) (WSL2) to run CURL on Linux. -In order to test an endpoint, make a HTTP POST request with the `Content-Type` -header set to `application/json`, the endpoint parameters in the request body, -and the `endpointId` as a path parameter. +In order to test an endpoint, make a HTTP POST request with the `Content-Type` header set to `application/json`, the endpoint parameters in the request body, and the `endpointId` as a path parameter. - `-X`: POST - `-H`: The `Content-Type` using the value of `application/json`. - `-d`: Use request body data to pass the endpoint parameter key/value pair. - `url`: - - ``: The HTTP gateway URL as displayed in the terminal at the - end of an Airnode deployment, less the `:endpointId` placeholder. - - 0x6db9...c27af6: Passed as a - path parameter, the `endpointId` to call. The value originates from - `triggers.rrp[0].endpointId` in the `config.json` file. + - ``: The HTTP gateway URL as displayed in the terminal at the end of an Airnode deployment, less the `:endpointId` placeholder. + - 0x6db9...c27af6: Passed as a path parameter, the `endpointId` to call. The value originates from `triggers.rrp[0].endpointId` in the `config.json` file. #### Request @@ -296,9 +225,7 @@ curl -v ^ ## 6. Remove the Airnode -When you are done with this guide you can remove the deployed Airnode. The -following command uses the `receipt.json` file that was created when the Airnode -was deployed. +When you are done with this guide you can remove the deployed Airnode. The following command uses the `receipt.json` file that was created when the Airnode was deployed. ::: code-group @@ -320,22 +247,10 @@ docker run -it --rm ^ ## Summary -You have deployed an Airnode on AWS with its HTTP gateway enabled. The Airnode, -upon deployment, started contacting the `AirnodeRrpV0` contract on the Sepolia -test network to gather any requests made by requesters to this Airnode. However -this guide did not address making a request on-chain as its purpose was to -quickly deploy a functional Airnode. See the guides -[Making an RRP Request](/guides/airnode/rrp-request.md) and -[Calling an Airnode](/guides/airnode/calling-an-airnode/) to learn how your -smart contract can make an RRP call to an Airnode. - -Finally the API integration was tested using the Airnode's off-chain -[HTTP gateway](/reference/airnode/latest/understand/http-gateways.md). You made -a CURL request (using HTTP) to the HTTP gateway. Airnode queried the API -provider and sent back a response. All of this was performed without accessing -the blockchain. - -Learn more about AWS resources that Airnode uses in the -[Cloud Resources](/reference/airnode/latest/cloud-resources.md) doc. +You have deployed an Airnode on AWS with its HTTP gateway enabled. The Airnode, upon deployment, started contacting the `AirnodeRrpV0` contract on the Sepolia test network to gather any requests made by requesters to this Airnode. However this guide did not address making a request on-chain as its purpose was to quickly deploy a functional Airnode. See the guides [Making an RRP Request](/guides/airnode/rrp-request.md) and [Calling an Airnode](/guides/airnode/calling-an-airnode/) to learn how your smart contract can make an RRP call to an Airnode. + +Finally the API integration was tested using the Airnode's off-chain [HTTP gateway](/reference/airnode/latest/understand/http-gateways.md). You made a CURL request (using HTTP) to the HTTP gateway. Airnode queried the API provider and sent back a response. All of this was performed without accessing the blockchain. + +Learn more about AWS resources that Airnode uses in the [Cloud Resources](/reference/airnode/latest/cloud-resources.md) doc. diff --git a/docs/guides/airnode/deploy-airnode/deploy-container/index.md b/docs/guides/airnode/deploy-airnode/deploy-container/index.md index 4a36a40f..8f0fcd17 100644 --- a/docs/guides/airnode/deploy-airnode/deploy-container/index.md +++ b/docs/guides/airnode/deploy-airnode/deploy-container/index.md @@ -16,37 +16,15 @@ tags: # {{$frontmatter.title}} -This guide demonstrates local deployment of an Airnode followed by an off-chain -[HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md) request. -Configuration files are provided with only minor changes to be made. The -[latest release](https://hub.docker.com/r/api3/airnode-client/tags) of the -Airnode [client image](/reference/airnode/latest/docker/client-image.md) will be -used to deploy the off-chain component of Airnode (a.k.a., the node) to a Docker -container, in this case a locally run Docker container. - -This Airnode contains a single API operation (`GET /simple/price`) from -[CoinGecko](https://docs.coingecko.com/reference/introduction) which returns the -current value of a coin. This guide does not detail the overall configuration of -an Airnode, it is just a quick start guide then lends itself to understanding an -Airnode deployment. - -Please note that this tutorial does not involve the blockchain nor an RRP -(request-response protocol) call from a smart contract. If you wish to make an -RRP call, please see the guides -[Making an RRP Request](/guides/airnode/rrp-request.md) and -[Calling an Airnode](/guides/airnode/calling-an-airnode/). +This guide demonstrates local deployment of an Airnode followed by an off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md) request. Configuration files are provided with only minor changes to be made. The [latest release](https://hub.docker.com/r/api3/airnode-client/tags) of the Airnode [client image](/reference/airnode/latest/docker/client-image.md) will be used to deploy the off-chain component of Airnode (a.k.a., the node) to a Docker container, in this case a locally run Docker container. + +This Airnode contains a single API operation (`GET /simple/price`) from [CoinGecko](https://docs.coingecko.com/reference/introduction) which returns the current value of a coin. This guide does not detail the overall configuration of an Airnode, it is just a quick start guide then lends itself to understanding an Airnode deployment. + +Please note that this tutorial does not involve the blockchain nor an RRP (request-response protocol) call from a smart contract. If you wish to make an RRP call, please see the guides [Making an RRP Request](/guides/airnode/rrp-request.md) and [Calling an Airnode](/guides/airnode/calling-an-airnode/). ## Configuration Files -An Airnode Docker container deployment uses a Docker image (called -[client image](/reference/airnode/latest/docker/client-image.md)) which requires -two files as input: -[config.json](/guides/airnode/deploy-airnode/deploy-container/index.md#config-json) -and -[secrets.env](/guides/airnode/deploy-airnode/deploy-container/index.md#secrets-env). -These files have been created and only require a few minor changes on your part -to make the deployment of the demo Airnode successful. The changes are needed to -supply a chain provider url and a mnemonic. +An Airnode Docker container deployment uses a Docker image (called [client image](/reference/airnode/latest/docker/client-image.md)) which requires two files as input: [config.json](/guides/airnode/deploy-airnode/deploy-container/index.md#config-json) and [secrets.env](/guides/airnode/deploy-airnode/deploy-container/index.md#secrets-env). These files have been created and only require a few minor changes on your part to make the deployment of the demo Airnode successful. The changes are needed to supply a chain provider url and a mnemonic. ## 1. Install Prerequisites @@ -54,8 +32,7 @@ Install the [Docker Desktop](https://docs.docker.com/get-docker/) and launch it. ## 2. Project Folder -Download the -quick-start-container.zip project folder. Extract it into any location. +Download the quick-start-container.zip project folder. Extract it into any location. ``` quick-start-container @@ -65,8 +42,7 @@ quick-start-container ## 3. Prepare Configuration Files -Prepare the two configuration files `config.json` and `secrets.env`. By default, -the Airnode client image looks for them in the project root directory. +Prepare the two configuration files `config.json` and `secrets.env`. By default, the Airnode client image looks for them in the project root directory. ### config.json @@ -78,10 +54,7 @@ the Airnode client image looks for them in the project root directory. ::: -This file requires no changes on your part. It has been created with just one -API endpoint and configured to listen to requests on the Sepolia test network, -though this tutorial will not make any such requests. There are a few variables -this file will interpolate from `secrets.env`. +This file requires no changes on your part. It has been created with just one API endpoint and configured to listen to requests on the Sepolia test network, though this tutorial will not make any such requests. There are a few variables this file will interpolate from `secrets.env`. ### secrets.env @@ -93,17 +66,11 @@ this file will interpolate from `secrets.env`. ::: -There are two values `config.json` interpolates from `secrets.env`. Add values -for each of these fields. +There are two values `config.json` interpolates from `secrets.env`. Add values for each of these fields. -- `CHAIN_PROVIDER_URL`: A blockchain provider url (including its API key) from a - provider such as [Infura](https://www.infura.io/). Use a url for the Sepolia - test network. +- `CHAIN_PROVIDER_URL`: A blockchain provider url (including its API key) from a provider such as [Infura](https://www.infura.io/). Use a url for the Sepolia test network. -- `AIRNODE_WALLET_MNEMONIC`: Provide the seed phrase (mnemonic) to a new digital - wallet. The wallet does not need to be funded. Use the Admin CLI command - [generate-airnode-mnemonic](/reference/airnode/latest/packages/admin-cli.md#generate-airnode-mnemonic) - to create one. +- `AIRNODE_WALLET_MNEMONIC`: Provide the seed phrase (mnemonic) to a new digital wallet. The wallet does not need to be funded. Use the Admin CLI command [generate-airnode-mnemonic](/reference/airnode/latest/packages/admin-cli.md#generate-airnode-mnemonic) to create one. ```sh [generate-airnode-mnemonic] npx @api3/airnode-admin generate-airnode-mnemonic @@ -111,23 +78,13 @@ for each of these fields. ## 4. Deploy -If your Docker Desktop application already has an image named -`api3/airnode-client:latest` remove it first. The version behind `latest` may -have changed since it was last used. +If your Docker Desktop application already has an image named `api3/airnode-client:latest` remove it first. The version behind `latest` may have changed since it was last used. -For the Docker command below, note that `--publish HOST_PORT:CONTAINER_PORT` -parameter (Mac/WSL2/PowerShell) can have different values for the `HOST_PORT` -and `CONTAINER_PORT`, e.g. `--publish 8000:3000` would expose the web server on -port 8000 on the host machine. +For the Docker command below, note that `--publish HOST_PORT:CONTAINER_PORT` parameter (Mac/WSL2/PowerShell) can have different values for the `HOST_PORT` and `CONTAINER_PORT`, e.g. `--publish 8000:3000` would expose the web server on port 8000 on the host machine. -For Linux, it's recommended to use -[host networking](https://docs.docker.com/network/host/). When using host -networking, change the port via -[gatewayServerPort](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider-gatewayserverport) -property inside config.json. +For Linux, it's recommended to use [host networking](https://docs.docker.com/network/host/). When using host networking, change the port via [gatewayServerPort](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider-gatewayserverport) property inside config.json. -Run the following command to deploy the Airnode locally from the root of the -quick-deploy-container folder. +Run the following command to deploy the Airnode locally from the root of the quick-deploy-container folder. ::: code-group @@ -157,9 +114,7 @@ docker run \ ::: -In the console output, or equivalently in the `quick-deploy-container-airnode` -Docker desktop container logs, make note of the `HTTP gateway URL` as shown -below. It will be different and you will need it to test the Airnode. +In the console output, or equivalently in the `quick-deploy-container-airnode` Docker desktop container logs, make note of the `HTTP gateway URL` as shown below. It will be different and you will need it to test the Airnode. ```sh [output] # The following line should appear within the first ten lines of the output @@ -168,16 +123,11 @@ INFO HTTP (testing) gateway listening for request on "http://localhost:3000/http ## 5. Test the Airnode -After a successful deployment the Airnode can be tested directly using its -off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md). -As a reminder, this is independent of the blockchain and RRP contract. +After a successful deployment the Airnode can be tested directly using its off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md). As a reminder, this is independent of the blockchain and RRP contract. ### HTTP Gateway -Looking at the `config.json` code snippet below shows that the HTTP gateway is -configured for the Airnode. Furthermore, the endpoint for `/simple/price` (with -an `endpointId` of `0x6...af6`) is present in `triggers.http[n]`. Only those -endpoints added to the `http` array can be tested using the HTTP gateway. +Looking at the `config.json` code snippet below shows that the HTTP gateway is configured for the Airnode. Furthermore, the endpoint for `/simple/price` (with an `endpointId` of `0x6...af6`) is present in `triggers.http[n]`. Only those endpoints added to the `http` array can be tested using the HTTP gateway. ::: details Expand to view: HTTP gateway and endpoint ID @@ -215,28 +165,18 @@ endpoints added to the `http` array can be tested using the HTTP gateway. ### Execute Endpoint -Use CURL to execute a HTTP gateway request for the CoinGecko endpoint -`/simple/price`. +Use CURL to execute a HTTP gateway request for the CoinGecko endpoint `/simple/price`. -As an alternative to CURL, an app such as [Insomnia](https://insomnia.rest/) or -[Postman](https://www.postman.com/product/rest-client/) can be used. Windows -users can also use -[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) -(WSL2) to run CURL on Linux. +As an alternative to CURL, an app such as [Insomnia](https://insomnia.rest/) or [Postman](https://www.postman.com/product/rest-client/) can be used. Windows users can also use [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) (WSL2) to run CURL on Linux. -In order to test an endpoint, make a HTTP POST request with the `Content-Type` -header set to `application/json`, the endpoint parameters in the request body, -and the `endpointId` as a path parameter. +In order to test an endpoint, make a HTTP POST request with the `Content-Type` header set to `application/json`, the endpoint parameters in the request body, and the `endpointId` as a path parameter. - `-X`: POST - `-H`: The `Content-Type` using the value of `application/json`. - `-d`: Use request body data to pass the endpoint parameter key/value pair. - `url`: - - ``: The HTTP gateway URL as displayed in the terminal at the - end of an Airnode deployment, less the `:endpointId` placeholder. - - 0x6db9...c27af6: Passed as a - path parameter, the `endpointId` to call. The value originates from - `triggers.rrp[0].endpointId` in the `config.json` file. + - ``: The HTTP gateway URL as displayed in the terminal at the end of an Airnode deployment, less the `:endpointId` placeholder. + - 0x6db9...c27af6: Passed as a path parameter, the `endpointId` to call. The value originates from `triggers.rrp[0].endpointId` in the `config.json` file. ```sh # For Windows CMD replace line termination marker \ with ^ @@ -260,8 +200,7 @@ curl -X POST \ ## 6. Start and Stop -You can start and stop the Airnode with the Docker desktop application or via -terminal commands. +You can start and stop the Airnode with the Docker desktop application or via terminal commands. ```sh docker stop quick-start-container-airnode @@ -271,8 +210,7 @@ docker start quick-start-container-airnode ## 7. Logs -You can view the Airnode's logs with the Docker desktop application or via -terminal commands. +You can view the Airnode's logs with the Docker desktop application or via terminal commands. ```sh docker logs quick-start-container-airnode @@ -282,9 +220,7 @@ docker logs --follow quick-start-container-airnode ## 8. Remove the Airnode -When you are done with the demo Airnode you can remove it by using the Docker -desktop application or by using the following terminal command. When using the -terminal command be sure to stop the container first if running. +When you are done with the demo Airnode you can remove it by using the Docker desktop application or by using the following terminal command. When using the terminal command be sure to stop the container first if running. ```sh # Stop the container if it is running. @@ -295,18 +231,10 @@ docker rm quick-start-container-airnode ## Summary -You have deployed a local Airnode using the Docker client image and tested an -API integration using the Airnode's off-chain -[HTTP gateway](/reference/airnode/latest/understand/http-gateways.md). +You have deployed a local Airnode using the Docker client image and tested an API integration using the Airnode's off-chain [HTTP gateway](/reference/airnode/latest/understand/http-gateways.md). -To do so, you made a CURL request (using HTTP) to the HTTP gateway, following -which Airnode queried the API provider and returned a response. All of this was -performed without accessing the blockchain. +To do so, you made a CURL request (using HTTP) to the HTTP gateway, following which Airnode queried the API provider and returned a response. All of this was performed without accessing the blockchain. -This guide did not address making an on-chain request as its purpose was to -quickly deploy a functional Airnode. See the guides -[Making an RRP Request](/guides/airnode/rrp-request.md) and -[Calling an Airnode](/guides/airnode/calling-an-airnode/) to learn how your -smart contract can make an RRP call to an Airnode. +This guide did not address making an on-chain request as its purpose was to quickly deploy a functional Airnode. See the guides [Making an RRP Request](/guides/airnode/rrp-request.md) and [Calling an Airnode](/guides/airnode/calling-an-airnode/) to learn how your smart contract can make an RRP call to an Airnode. diff --git a/docs/guides/airnode/deploy-airnode/deploy-gcp/index.md b/docs/guides/airnode/deploy-airnode/deploy-gcp/index.md index dbd9c477..ce2e1406 100644 --- a/docs/guides/airnode/deploy-airnode/deploy-gcp/index.md +++ b/docs/guides/airnode/deploy-airnode/deploy-gcp/index.md @@ -16,37 +16,15 @@ tags: # {{$frontmatter.title}} -This guide demonstrates the deployment of an Airnode followed by an off-chain -[HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md) request. -Configuration files are provided with only minor changes to be made. The -[latest release](https://hub.docker.com/r/api3/airnode-deployer/tags) of the -Airnode [deployer image](/reference/airnode/latest/docker/deployer-image.md) -will be used to deploy the off-chain component of Airnode (a.k.a., the node) to -GCP. - -This Airnode contains a single API operation (`GET /simple/price`) from -[CoinGecko](https://docs.coingecko.com/reference/introduction) which returns the -current value of a coin. This guide does not detail the overall configuration of -an Airnode, it is just a quick start guide then lends itself to understanding an -Airnode deployment. - -Please note that this tutorial does not involve the blockchain nor an RRP -(request-response protocol) call from a smart contract. If you wish to make an -RRP call, please see the guides -[Making an RRP Request](/guides/airnode/rrp-request.md) and -[Calling an Airnode](/guides/airnode/calling-an-airnode/). +This guide demonstrates the deployment of an Airnode followed by an off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md) request. Configuration files are provided with only minor changes to be made. The [latest release](https://hub.docker.com/r/api3/airnode-deployer/tags) of the Airnode [deployer image](/reference/airnode/latest/docker/deployer-image.md) will be used to deploy the off-chain component of Airnode (a.k.a., the node) to GCP. + +This Airnode contains a single API operation (`GET /simple/price`) from [CoinGecko](https://docs.coingecko.com/reference/introduction) which returns the current value of a coin. This guide does not detail the overall configuration of an Airnode, it is just a quick start guide then lends itself to understanding an Airnode deployment. + +Please note that this tutorial does not involve the blockchain nor an RRP (request-response protocol) call from a smart contract. If you wish to make an RRP call, please see the guides [Making an RRP Request](/guides/airnode/rrp-request.md) and [Calling an Airnode](/guides/airnode/calling-an-airnode/). ## Configuration Files -An Airnode deployment on GCP uses the Docker -[deployer image](/reference/airnode/latest/docker/deployer-image.md) which -requires three files as input: -[config.json](/guides/airnode/deploy-airnode/deploy-gcp/index.md#config-json), -[secrets.env](/guides/airnode/deploy-airnode/deploy-gcp/index.md#secrets-env), -and gcp.json. The `config.json` and `secrets.env` files have been created and -only require a few minor changes to make the deployment of the Airnode -successful. The changes are needed to supply a GCP project ID, a chain provider -url, and a mnemonic. +An Airnode deployment on GCP uses the Docker [deployer image](/reference/airnode/latest/docker/deployer-image.md) which requires three files as input: [config.json](/guides/airnode/deploy-airnode/deploy-gcp/index.md#config-json), [secrets.env](/guides/airnode/deploy-airnode/deploy-gcp/index.md#secrets-env), and gcp.json. The `config.json` and `secrets.env` files have been created and only require a few minor changes to make the deployment of the Airnode successful. The changes are needed to supply a GCP project ID, a chain provider url, and a mnemonic. ## 1. Install Prerequisites @@ -54,8 +32,7 @@ Install the [Docker Desktop](https://docs.docker.com/get-docker/) and launch it. ## 2. Project Folder -Download the -quick-start-gcp.zip project folder. Extract it into any location. +Download the quick-start-gcp.zip project folder. Extract it into any location. ``` quick-start-gcp @@ -65,36 +42,19 @@ quick-start-gcp ## 3. GCP Project Setup & Credentials -- First - [create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) - (or use an existing GCP project) where the Airnode will be deployed. Once the - project is created, add the project ID to the - [secrets.env](/guides/airnode/deploy-airnode/deploy-gcp/#secrets-env) file. +- First [create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) (or use an existing GCP project) where the Airnode will be deployed. Once the project is created, add the project ID to the [secrets.env](/guides/airnode/deploy-airnode/deploy-gcp/#secrets-env) file. -- Make sure you have billing enabled for your project. To do so, you will need - to pair the project with your bank card, although no charges will be incurred - since the resource usage fits well within the free tier limit. +- Make sure you have billing enabled for your project. To do so, you will need to pair the project with your bank card, although no charges will be incurred since the resource usage fits well within the free tier limit. -- In order for Airnode to deploy successfully, you need to enable the - [App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) - specifically for the project. After enabling it, wait a few minutes before - deploying the Airnode for this change to take effect. +- In order for Airnode to deploy successfully, you need to enable the [App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) specifically for the project. After enabling it, wait a few minutes before deploying the Airnode for this change to take effect. -- Create a new service account from the - [IAM and admin > Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) - menu. Grant this account access to the project by adding the role `Owner` - during creation. +- Create a new service account from the [IAM and admin > Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) menu. Grant this account access to the project by adding the role `Owner` during creation. -- Once the new service account is created, click on it to bring up its - management page. Select the KEYS tab and add a new access key of type JSON for - this account. Download the key file and place in the root of the - `/quick-start-gcp` project directory. Rename it `gcp.json`. +- Once the new service account is created, click on it to bring up its management page. Select the KEYS tab and add a new access key of type JSON for this account. Download the key file and place in the root of the `/quick-start-gcp` project directory. Rename it `gcp.json`. ## 4. Prepare Configuration Files -Prepare the three configuration files. The Airnode deployer image looks for -`config.json`, `secrets.env`, and `gcp.json` in the project root directory and -writes `receipt.json` to the project root directory. +Prepare the three configuration files. The Airnode deployer image looks for `config.json`, `secrets.env`, and `gcp.json` in the project root directory and writes `receipt.json` to the project root directory. ### config.json @@ -106,10 +66,7 @@ writes `receipt.json` to the project root directory. ::: -This file requires no changes on your part. It has been created with just one -API endpoint and configured to listen to requests on the Sepolia test network, -though this tutorial will not make any such requests. There are a few variables -this file will interpolate from `secrets.env`. +This file requires no changes on your part. It has been created with just one API endpoint and configured to listen to requests on the Sepolia test network, though this tutorial will not make any such requests. There are a few variables this file will interpolate from `secrets.env`. ### secrets.env @@ -121,53 +78,31 @@ this file will interpolate from `secrets.env`. ::: -There are three values `config.json` interpolates from `secrets.env`. Add values -for each of these fields. +There are three values `config.json` interpolates from `secrets.env`. Add values for each of these fields. -- `CHAIN_PROVIDER_URL`: A blockchain provider url (including its API key) from a - provider such as [Infura](https://www.infura.io/). Use a url for the Sepolia - test network. +- `CHAIN_PROVIDER_URL`: A blockchain provider url (including its API key) from a provider such as [Infura](https://www.infura.io/). Use a url for the Sepolia test network. -- `AIRNODE_WALLET_MNEMONIC`: Provide the seed phrase (mnemonic) to a new digital - wallet. The wallet does not need to be funded. Use the Admin CLI command - [generate-airnode-mnemonic](/reference/airnode/latest/packages/admin-cli.md#generate-airnode-mnemonic) - to create one. +- `AIRNODE_WALLET_MNEMONIC`: Provide the seed phrase (mnemonic) to a new digital wallet. The wallet does not need to be funded. Use the Admin CLI command [generate-airnode-mnemonic](/reference/airnode/latest/packages/admin-cli.md#generate-airnode-mnemonic) to create one. ```sh [generate-airnode-mnemonic] npx @api3/airnode-admin generate-airnode-mnemonic ``` -- `PROJECT_ID`: Project ID of your GCP project. During - [step #3](/guides/airnode/deploy-airnode/deploy-gcp/#_3-gcp-project-setup-credentials) - above you should have added the project ID to the `secrets.env` file. +- `PROJECT_ID`: Project ID of your GCP project. During [step #3](/guides/airnode/deploy-airnode/deploy-gcp/#_3-gcp-project-setup-credentials) above you should have added the project ID to the `secrets.env` file. ### gcp.json -During -[step #3](/guides/airnode/deploy-airnode/deploy-gcp/#_3-gcp-project-setup-credentials) -above, the `gcp.json` file should have been placed into the `/quick-start-gcp` -project folder root. +During [step #3](/guides/airnode/deploy-airnode/deploy-gcp/#_3-gcp-project-setup-credentials) above, the `gcp.json` file should have been placed into the `/quick-start-gcp` project folder root. ## 5. Deploy -Make sure Docker is running and then execute the deployer image from the root of -the `quick-start-gcp` folder. A `receipt.json` file will be created upon -completion. It contains some deployment information and is used to remove the -Airnode. +Make sure Docker is running and then execute the deployer image from the root of the `quick-start-gcp` folder. A `receipt.json` file will be created upon completion. It contains some deployment information and is used to remove the Airnode. -Run the following command to deploy the Airnode. Normally (for Linux/Mac/WSL2) -the deployer image `deploy` command is run by the user root. This may cause -permission issues when the `receipt.json` file is generated. Optionally you can -specify the -UID -(user identifier) and GID -(group identifier) that the deployer image should use. Do so by setting the -environment variables USER_ID and GROUP_ID, otherwise omit the line containing -these variables. +Run the following command to deploy the Airnode. Normally (for Linux/Mac/WSL2) the deployer image `deploy` command is run by the user root. This may cause permission issues when the `receipt.json` file is generated. Optionally you can specify the UID (user identifier) and GID (group identifier) that the deployer image should use. Do so by setting the environment variables USER_ID and GROUP_ID, otherwise omit the line containing these variables. ::: code-group @@ -188,8 +123,7 @@ docker run -it --rm ^ ::: -Make note of the `HTTP gateway URL` in your output shown below as it will be -different. You will need it to test the Airnode. +Make note of the `HTTP gateway URL` in your output shown below as it will be different. You will need it to test the Airnode. ```sh [output] ✔ Deployed Airnode 0x6A6cF2d0094c73b7aBb22Cd6196824BCBB830125 tutorial-gcp to gcp us-east1 @@ -200,16 +134,11 @@ different. You will need it to test the Airnode. ## 6. Test the Airnode -After a successful deployment the Airnode can be tested directly using its -off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md). -As a reminder, this is independent of the blockchain and RRP contract. +After a successful deployment the Airnode can be tested directly using its off-chain [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md). As a reminder, this is independent of the blockchain and RRP contract. ### HTTP Gateway -Looking at the `config.json` code snippet below shows that the HTTP gateway is -configured for the Airnode. Furthermore, the endpoint for `/simple/price` (with -an `endpointId` of `0x6...af6`) is present in `triggers.http[n]`. Only those -endpoints added to the `http` array can be tested using the HTTP gateway. +Looking at the `config.json` code snippet below shows that the HTTP gateway is configured for the Airnode. Furthermore, the endpoint for `/simple/price` (with an `endpointId` of `0x6...af6`) is present in `triggers.http[n]`. Only those endpoints added to the `http` array can be tested using the HTTP gateway. ::: details Expand to view: HTTP gateway and endpoint ID @@ -247,28 +176,18 @@ endpoints added to the `http` array can be tested using the HTTP gateway. ### Execute Endpoint -Use CURL to execute a HTTP gateway request for the CoinGecko endpoint -`/simple/price`. +Use CURL to execute a HTTP gateway request for the CoinGecko endpoint `/simple/price`. -As an alternative to CURL, an app such as [Insomnia](https://insomnia.rest/) or -[Postman](https://www.postman.com/product/rest-client/) can be used. Windows -users can also use -[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) -(WSL2) to run CURL on Linux. +As an alternative to CURL, an app such as [Insomnia](https://insomnia.rest/) or [Postman](https://www.postman.com/product/rest-client/) can be used. Windows users can also use [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) (WSL2) to run CURL on Linux. -In order to test an endpoint, make a HTTP POST request with the `Content-Type` -header set to `application/json`, the endpoint parameters in the request body, -and the `endpointId` as a path parameter. +In order to test an endpoint, make a HTTP POST request with the `Content-Type` header set to `application/json`, the endpoint parameters in the request body, and the `endpointId` as a path parameter. - `-X`: POST - `-H`: The `Content-Type` using the value of `application/json`. - `-d`: Use request body data to pass the endpoint parameter key/value pair. - `url`: - - ``: The HTTP gateway URL as displayed in the terminal at the - end of an Airnode deployment, less the `:endpointId` placeholder. - - 0x6db9...c27af6: Passed as a - path parameter, the `endpointId` to call. The value originates from - `triggers.rrp[0].endpointId` in the `config.json` file. + - ``: The HTTP gateway URL as displayed in the terminal at the end of an Airnode deployment, less the `:endpointId` placeholder. + - 0x6db9...c27af6: Passed as a path parameter, the `endpointId` to call. The value originates from `triggers.rrp[0].endpointId` in the `config.json` file. #### Request @@ -306,9 +225,7 @@ curl -v ^ ## 7. Remove the Airnode -When you are done with this guide you can remove the deployed Airnode. The -following command uses the `receipt.json` file that was created when the Airnode -was deployed. +When you are done with this guide you can remove the deployed Airnode. The following command uses the `receipt.json` file that was created when the Airnode was deployed. ::: code-group @@ -330,31 +247,16 @@ docker run -it --rm ^ ::: danger Post Removal -After removing an Airnode it may be necessary to wait several minutes before -deploying or redeploying Airnode again to the same GCP project. GCP takes -several minutes to complete its behind the scenes clean-up of configured -resources. +After removing an Airnode it may be necessary to wait several minutes before deploying or redeploying Airnode again to the same GCP project. GCP takes several minutes to complete its behind the scenes clean-up of configured resources. ::: ## Summary -You have deployed an Airnode on GCP with its HTTP gateway enabled. The Airnode, -upon deployment, started contacting the `AirnodeRrpV0` contract on the Sepolia -test network to gather any requests made by requesters to this Airnode. However -this guide did not address making a request on-chain as its purpose was to -quickly deploy a functional Airnode. See the guides -[Making an RRP Request](/guides/airnode/rrp-request.md) and -[Calling an Airnode](/guides/airnode/calling-an-airnode/) to learn how your -smart contract can make an RRP call to an Airnode. - -Finally the API integration was tested using the Airnode's off-chain -[HTTP gateway](/reference/airnode/latest/understand/http-gateways.md). You made -a CURL request (using HTTP) to the HTTP gateway. Airnode queried the API -provider and sent back a response. All of this was performed without accessing -the blockchain. - -Learn more about GCP resources that Airnode uses in the -[Cloud Resources](/reference/airnode/latest/cloud-resources.md) doc. +You have deployed an Airnode on GCP with its HTTP gateway enabled. The Airnode, upon deployment, started contacting the `AirnodeRrpV0` contract on the Sepolia test network to gather any requests made by requesters to this Airnode. However this guide did not address making a request on-chain as its purpose was to quickly deploy a functional Airnode. See the guides [Making an RRP Request](/guides/airnode/rrp-request.md) and [Calling an Airnode](/guides/airnode/calling-an-airnode/) to learn how your smart contract can make an RRP call to an Airnode. + +Finally the API integration was tested using the Airnode's off-chain [HTTP gateway](/reference/airnode/latest/understand/http-gateways.md). You made a CURL request (using HTTP) to the HTTP gateway. Airnode queried the API provider and sent back a response. All of this was performed without accessing the blockchain. + +Learn more about GCP resources that Airnode uses in the [Cloud Resources](/reference/airnode/latest/cloud-resources.md) doc. diff --git a/docs/guides/airnode/deploy-airnode/generate-config-chainapi/index.md b/docs/guides/airnode/deploy-airnode/generate-config-chainapi/index.md index 983726fd..9cf57285 100644 --- a/docs/guides/airnode/deploy-airnode/generate-config-chainapi/index.md +++ b/docs/guides/airnode/deploy-airnode/generate-config-chainapi/index.md @@ -19,20 +19,13 @@ tags: # {{$frontmatter.title}} -[ChainAPI](https://chainapi.com/) is a platform that enables you to integrate -and deploy the open-source [Airnode](/reference/airnode/latest/understand/) with -its step-by-step integration and deployment tools. It helps streamline the -Airnode integration process for API providers. +[ChainAPI](https://chainapi.com/) is a platform that enables you to integrate and deploy the open-source [Airnode](/reference/airnode/latest/understand/) with its step-by-step integration and deployment tools. It helps streamline the Airnode integration process for API providers. -Using ChainAPI, API providers can configure and deploy an Airnode which links -their API data to several blockchains. +Using ChainAPI, API providers can configure and deploy an Airnode which links their API data to several blockchains. -ChainAPI can connect almost any API, whether open or authenticated, to Airnode. -Airnode then queries your API operations to be consumed by EVM on-chain dApps, -by using the request/response protocol. +ChainAPI can connect almost any API, whether open or authenticated, to Airnode. Airnode then queries your API operations to be consumed by EVM on-chain dApps, by using the request/response protocol. -To get started, go to [ChainAPI](https://chainapi.com/) and login using -[MetaMask](https://metamask.io/). +To get started, go to [ChainAPI](https://chainapi.com/) and login using [MetaMask](https://metamask.io/). diff --git a/docs/guides/airnode/monorepo-examples.md b/docs/guides/airnode/monorepo-examples.md index 1352f7e3..9bba454f 100644 --- a/docs/guides/airnode/monorepo-examples.md +++ b/docs/guides/airnode/monorepo-examples.md @@ -16,37 +16,16 @@ tags: # {{$frontmatter.title}} -There are examples of various Airnode functionality in the -[airnode-examples package](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples) -of the Airnode monorepo: +There are examples of various Airnode functionality in the [airnode-examples package](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples) of the Airnode monorepo: -- [authenticated-coinmarketcap](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-examples/integrations/authenticated-coinmarketcap) - - cryptocurrency price request using - [authentication](/reference/airnode/latest/understand/api-security.md#airnode-authentication-security-schemes). -- [coingecko](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-examples/integrations/coingecko) - - unauthenticated cryptocurrency price request. -- [coingecko-post-processing](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-post-processing) - - demonstration of the [post-processing](/reference/ois/latest/processing.md) - feature. -- [coingecko-pre-processing](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-pre-processing) - - demonstration of the [pre-processing](/reference/ois/latest/processing.md) - feature. -- [coingecko-http-gateways](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-http-gateways) - demonstration of the - [HTTP gateway and HTTP signed data gateway](/reference/airnode/latest/understand/http-gateways.md). -- [coingecko-template](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-template) - - demonstration of - [template](/reference/airnode/latest/developers/using-templates.md) requests. -- [failing-example](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/failing-example) - - demonstration of Airnode error handling through an invalid request. -- [relay-security-schemes](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/relay-security-schemes) - - demonstration of how to - [relay multiple request metadata](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) - like chain ID and sponsor address to the API endpoint. -- [weather-multi-value](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/weather-multi-value) - - authenticated weather request - [encoding multiple parameters](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values) - including the transaction timestamp, time of sunset, temperature, and a - description of the weather. +- [authenticated-coinmarketcap](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-examples/integrations/authenticated-coinmarketcap) - cryptocurrency price request using [authentication](/reference/airnode/latest/understand/api-security.md#airnode-authentication-security-schemes). +- [coingecko](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-examples/integrations/coingecko) - unauthenticated cryptocurrency price request. +- [coingecko-post-processing](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-post-processing) - demonstration of the [post-processing](/reference/ois/latest/processing.md) feature. +- [coingecko-pre-processing](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-pre-processing) - demonstration of the [pre-processing](/reference/ois/latest/processing.md) feature. +- [coingecko-http-gateways](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-http-gateways) demonstration of the [HTTP gateway and HTTP signed data gateway](/reference/airnode/latest/understand/http-gateways.md). +- [coingecko-template](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-template) - demonstration of [template](/reference/airnode/latest/developers/using-templates.md) requests. +- [failing-example](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/failing-example) - demonstration of Airnode error handling through an invalid request. +- [relay-security-schemes](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/relay-security-schemes) - demonstration of how to [relay multiple request metadata](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) like chain ID and sponsor address to the API endpoint. +- [weather-multi-value](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/weather-multi-value) - authenticated weather request [encoding multiple parameters](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values) including the transaction timestamp, time of sunset, temperature, and a description of the weather. diff --git a/docs/guides/airnode/post-processing/index.md b/docs/guides/airnode/post-processing/index.md index fc2d2971..49fb5d57 100644 --- a/docs/guides/airnode/post-processing/index.md +++ b/docs/guides/airnode/post-processing/index.md @@ -16,30 +16,20 @@ tags: # {{$frontmatter.title}} -This guide demonstrates Airnode's ability to execute its -[`postProcessingSpecifications`](/reference/ois/latest/processing.md) capability -which runs user defined code during its run cycle. The following describes the -workflow Airnode uses: +This guide demonstrates Airnode's ability to execute its [`postProcessingSpecifications`](/reference/ois/latest/processing.md) capability which runs user defined code during its run cycle. The following describes the workflow Airnode uses: 1. Run `preProcessingSpecifications` 2. Airnode calls requested OIS endpoint 3. Run `postProcessingSpecifications` 4. Airnode encodes the response values defined by reservedParameters -In this guide you will use `postProcessingSpecifications` to get the average -price of the API3 token and its average market cap for the last seven days. This -will be calculated after calling the CoinGecko operation -`/coins/{coin}/market_chart`. +In this guide you will use `postProcessingSpecifications` to get the average price of the API3 token and its average market cap for the last seven days. This will be calculated after calling the CoinGecko operation `/coins/{coin}/market_chart`. ## 1. Setup a Docker container to run Airnode -A local Docker container running Airnode is needed. Go to the guide -[Deploying Airnode locally using Docker](/guides/airnode/deploy-airnode/deploy-container/index.md) -and run steps #1-3. Make the following adjustment when doing so: +A local Docker container running Airnode is needed. Go to the guide [Deploying Airnode locally using Docker](/guides/airnode/deploy-airnode/deploy-container/index.md) and run steps #1-3. Make the following adjustment when doing so: -- After downloading the - [Project folder](/guides/airnode/deploy-airnode/deploy-container/#_2-project-folder) - (step #2) replace the `config.json` file's content with the following content. +- After downloading the [Project folder](/guides/airnode/deploy-airnode/deploy-container/#_2-project-folder) (step #2) replace the `config.json` file's content with the following content. ::: details Copy/paste config.json @@ -49,15 +39,11 @@ and run steps #1-3. Make the following adjustment when doing so: ::: -Once the project folder from the **Deploying Airnode locally using Docker** -guide has been downloaded and the `config.json` file updated, return to step #2 -below. But first read about the changes made to the newer `config.json` file -shown below. +Once the project folder from the **Deploying Airnode locally using Docker** guide has been downloaded and the `config.json` file updated, return to step #2 below. But first read about the changes made to the newer `config.json` file shown below. ### `paths` -The newer `config.json` file points to a different API provider operation -(`/coins/{coin}/market_chart`). +The newer `config.json` file points to a different API provider operation (`/coins/{coin}/market_chart`). ```js "paths": { @@ -73,10 +59,7 @@ The newer `config.json` file points to a different API provider operation ### `postProcessingSpecifications` -After calling the API provider's operation but before encoding the resulting -values for on-chain use, Airnode will run the post processing code defined in -`postProcessingSpecifications`. During execution of this code, the data from the -API provider operation can be summarized into the values needed. +After calling the API provider's operation but before encoding the resulting values for on-chain use, Airnode will run the post processing code defined in `postProcessingSpecifications`. During execution of this code, the data from the API provider operation can be summarized into the values needed. ```js "preProcessingSpecifications": [], @@ -89,12 +72,7 @@ API provider operation can be summarized into the values needed. ] ``` -Below is a more human readable rendering of the post processing code. The -`input` variable contains the response from the API provider's operation. The -`output` variable must be set before the code exists as Airnode uses it to -encode any values for use on-chain. See more about -[Input and Output](/reference/ois/latest/processing.md#input-and-output) in the -OIS reference. +Below is a more human readable rendering of the post processing code. The `input` variable contains the response from the API provider's operation. The `output` variable must be set before the code exists as Airnode uses it to encode any values for use on-chain. See more about [Input and Output](/reference/ois/latest/processing.md#input-and-output) in the OIS reference. ```js let avg_price = 0; @@ -112,8 +90,7 @@ output = input; ## 2. Deploy the Docker container -From your project root run the Docker container deploy command. It will use the -updated `config.json` file. +From your project root run the Docker container deploy command. It will use the updated `config.json` file. ::: code-group @@ -143,9 +120,7 @@ docker run \ ::: -Leave the command active in the terminal window. It will display the log items -resulting from the container's deployment. Note the line in the output contains -the `httpGateway` URL which you will use in step #3. +Leave the command active in the terminal window. It will display the log items resulting from the container's deployment. Note the line in the output contains the `httpGateway` URL which you will use in step #3. ```sh (2) ... @@ -156,12 +131,7 @@ the `httpGateway` URL which you will use in step #3. ## 3. Call the Airnode endpoint -Use CURL and call the Airnode endpoint that gets the market data from the -CoinGecko operation `/coins/{coin}/market_chart`. The CURL command will call the -httpGateway exposed by the Airnode. This avoids the need to use a smart contract -to get the response. The -[httpGateway](/reference/airnode/latest/understand/http-gateways.md) is a -testing tool not normally enabled on production systems. +Use CURL and call the Airnode endpoint that gets the market data from the CoinGecko operation `/coins/{coin}/market_chart`. The CURL command will call the httpGateway exposed by the Airnode. This avoids the need to use a smart contract to get the response. The [httpGateway](/reference/airnode/latest/understand/http-gateways.md) is a testing tool not normally enabled on production systems. ### Request @@ -212,34 +182,22 @@ curl -X POST \ } ``` -The data retrieved from the API provider CoinGecko (`market_caps`, `prices`, and -`total_volumes` ) was added to the `rawValue` field. Then the `rawValue` (as the -`input` variable) was "piped" through the `postProcessingSpecifications` user -defined code which in turn calculated the price and market cap averages which -were added back into `rawValue` via the `output` variable. +The data retrieved from the API provider CoinGecko (`market_caps`, `prices`, and `total_volumes` ) was added to the `rawValue` field. Then the `rawValue` (as the `input` variable) was "piped" through the `postProcessingSpecifications` user defined code which in turn calculated the price and market cap averages which were added back into `rawValue` via the `output` variable. - `"avg_price" : "1.2477250309068642"` - `"avg_market_cap" : "106632586.97711395"` -After the `postProcessingSpecifications` user defined code exited Airnode used -the mappings of the `reservedParameters` field in the `config.json` file to -determine what data should go into the `values` field. Airnode then encoded the -values into the `encodedValue` field suitable for use on-chain. +After the `postProcessingSpecifications` user defined code exited Airnode used the mappings of the `reservedParameters` field in the `config.json` file to determine what data should go into the `values` field. Airnode then encoded the values into the `encodedValue` field suitable for use on-chain. ## 4. Verify `encodedValue` -Verify that `encodedValue` actually contains the two numbers in the `values` -field. Copy and paste the `encodedValue` string you received after executing the -Airnode endpoint into the form below and select the **Decode** button. +Verify that `encodedValue` actually contains the two numbers in the `values` field. Copy and paste the `encodedValue` string you received after executing the Airnode endpoint into the form below and select the **Decode** button. ## Summary -In this guide you extended the data from the API operation with additional -summary values using post processing. For more examples on how to use -`preProcessingSpecifications` and `postProcessingSpecifications` see the -following monorepo examples. +In this guide you extended the data from the API operation with additional summary values using post processing. For more examples on how to use `preProcessingSpecifications` and `postProcessingSpecifications` see the following monorepo examples. - [coingecko-pre-processing](https://github.com/api3dao/airnode/tree/master/packages/airnode-examples/integrations/coingecko-pre-processing) - [coingecko-post-processing](https://github.com/api3dao/airnode/tree/master/packages/airnode-examples/integrations/coingecko-post-processing) diff --git a/docs/guides/airnode/rrp-request.md b/docs/guides/airnode/rrp-request.md index 10531b1b..613b6144 100644 --- a/docs/guides/airnode/rrp-request.md +++ b/docs/guides/airnode/rrp-request.md @@ -16,31 +16,19 @@ tags: # {{$frontmatter.title}} -This guide steps through the process of making a direct request of an Airnode -using RRP (request-response protocol) to get data from an API provider. +This guide steps through the process of making a direct request of an Airnode using RRP (request-response protocol) to get data from an API provider. -An Airnode is a first-party oracle that can push off-chain API data to on-chain -smart contracts, known as a requester, using RRP. A requester is any smart -contract that executes an Airnode request. Learn about the mechanics of -[Airnode's request-response protocol](/reference/airnode/latest/developers/index.md) -(RRP) as used by a requester. +An Airnode is a first-party oracle that can push off-chain API data to on-chain smart contracts, known as a requester, using RRP. A requester is any smart contract that executes an Airnode request. Learn about the mechanics of [Airnode's request-response protocol](/reference/airnode/latest/developers/index.md) (RRP) as used by a requester. ::: info Consider dAPIs -While using the Airnode's RRP protocol to acquire API provider data is usable it -is not as efficient or as straightforward as using a dAPI. Therefore, best -practices usually entail using a -[dAPI](https://docs.api3.org/oev-searchers/in-depth/dapis/) -to acquire API provider data. +While using the Airnode's RRP protocol to acquire API provider data is usable it is not as efficient or as straightforward as using a dAPI. Therefore, best practices usually entail using a [dAPI](https://docs.api3.org/oev-searchers/in-depth/dapis/) to acquire API provider data. ::: ## 1. Inherit RrpRequesterV0.sol -A requester inherits from the -[RrpRequesterV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/requesters/RrpRequesterV0.sol) -contract. This will expose the AirnodeRrpV0.sol protocol contract to the -requester allowing it to make Airnode requests. +A requester inherits from the [RrpRequesterV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/requesters/RrpRequesterV0.sol) contract. This will expose the AirnodeRrpV0.sol protocol contract to the requester allowing it to make Airnode requests. ```solidity import "@api3/airnode-protocol/contracts/rrp/requesters/RrpRequesterV0.sol"; @@ -55,34 +43,15 @@ contract MyRequester is V0 { } ``` -Note the constructor parameter `airnodeRrpAddress`, which is the public address -of the AirnodeRrpV0.sol protocol contract on the blockchain you wish to use. It -is used by RrpRequesterV0.sol to point itself to AirnodeRrpV0.sol. See the list -of all [Airnode contract addresses](/reference/airnode/latest/) in the reference -section. +Note the constructor parameter `airnodeRrpAddress`, which is the public address of the AirnodeRrpV0.sol protocol contract on the blockchain you wish to use. It is used by RrpRequesterV0.sol to point itself to AirnodeRrpV0.sol. See the list of all [Airnode contract addresses](/reference/airnode/latest/) in the reference section. ## 2. Implement the request logic -There are two types of requests provided by the AirnodeRrpV0.sol contract. See -the concepts and definitions -[Request](/reference/airnode/latest/concepts/request.md) page for information -related to each request type. - -This example uses a -[full request](/reference/airnode/latest/concepts/request.md#full-request) type -(note the `airnodeRrp.makeFullRequest()` function call in the code below) which -is called from the requester's own function `callTheAirnode()`. The function -`makeFullRequest()` requires that the requester pass all parameters needed by -Airnode to call its underlying API. - -Once the request has been made to `airnodeRrp.makeFullRequest()`, the -AirnodeRrpV0.sol contract returns a `requestId` confirming the request has been -accepted and is in process of being executed. Your requester would most likely -wish to track all `requestId`s. Note the line -`incomingFulfillments[requestId] = true;` in the code below that stores the -`requestId`s in a mapping. This is useful when the Airnode responds to the -requester later at the function (`airnodeCallback()`) with the `requestId` and -the `data` requested. +There are two types of requests provided by the AirnodeRrpV0.sol contract. See the concepts and definitions [Request](/reference/airnode/latest/concepts/request.md) page for information related to each request type. + +This example uses a [full request](/reference/airnode/latest/concepts/request.md#full-request) type (note the `airnodeRrp.makeFullRequest()` function call in the code below) which is called from the requester's own function `callTheAirnode()`. The function `makeFullRequest()` requires that the requester pass all parameters needed by Airnode to call its underlying API. + +Once the request has been made to `airnodeRrp.makeFullRequest()`, the AirnodeRrpV0.sol contract returns a `requestId` confirming the request has been accepted and is in process of being executed. Your requester would most likely wish to track all `requestId`s. Note the line `incomingFulfillments[requestId] = true;` in the code below that stores the `requestId`s in a mapping. This is useful when the Airnode responds to the requester later at the function (`airnodeCallback()`) with the `requestId` and the `data` requested. ```solidity import "@api3/airnode-protocol/contracts/rrp/requesters/RrpRequesterV0.sol"; @@ -130,44 +99,21 @@ contract MyRequester is RrpRequesterV0 { ### Request Parameters -A full request using the AirnodeRrpV0.sol contract `makeFullRequest()` function -requires all parameters needed by the Airnode application to be passed at -runtime. This is in contrast to a template request that would use a template for -some or all of the required parameters. Learn more about using templates in the -[Using RRP Templates](/guides/airnode/using-rrp-templates.md) guide. - -Since the requester's `callTheAirnode()` function makes a -[full request](/reference/airnode/latest/concepts/request.md#full-request), it -must gather the following parameters to pass on to -`airnodeRrp.makeFullRequest()`. - -- **airnode** and **endpointId**: As a pair, these uniquely identify the - endpoint desired at a particular Airnode. - -- **sponsor**: The - [sponsor](/reference/airnode/latest/developers/requesters-sponsors.md#what-is-a-sponsor) - address. - -- **sponsorWallet**: The - [sponsor wallet](/reference/airnode/latest/developers/requesters-sponsors.md#how-to-derive-a-sponsor-wallet) - address that the sponsor received when deriving the wallet for the Airnode - being called. - -- **fulfillAddress** and **fulfillFunctionId**: The public address of your - requester contract and its function that is called upon the return of the - request. - -- **parameters**: Specify the API parameters and any - [reserved parameters](/reference/airnode/latest/specifications/reserved-parameters.md) - which must be encoded. See - [Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md) - for how these are encoded. - - In most, cases the parameters are encoded off-chain and passed to the - requester which only forwards them. You can use the - [@api3/airnode-abi](/reference/airnode/latest/packages/airnode-abi.md) package - to perform the encoding and decoding. Take a look at the JavaScript snippet - below. +A full request using the AirnodeRrpV0.sol contract `makeFullRequest()` function requires all parameters needed by the Airnode application to be passed at runtime. This is in contrast to a template request that would use a template for some or all of the required parameters. Learn more about using templates in the [Using RRP Templates](/guides/airnode/using-rrp-templates.md) guide. + +Since the requester's `callTheAirnode()` function makes a [full request](/reference/airnode/latest/concepts/request.md#full-request), it must gather the following parameters to pass on to `airnodeRrp.makeFullRequest()`. + +- **airnode** and **endpointId**: As a pair, these uniquely identify the endpoint desired at a particular Airnode. + +- **sponsor**: The [sponsor](/reference/airnode/latest/developers/requesters-sponsors.md#what-is-a-sponsor) address. + +- **sponsorWallet**: The [sponsor wallet](/reference/airnode/latest/developers/requesters-sponsors.md#how-to-derive-a-sponsor-wallet) address that the sponsor received when deriving the wallet for the Airnode being called. + +- **fulfillAddress** and **fulfillFunctionId**: The public address of your requester contract and its function that is called upon the return of the request. + +- **parameters**: Specify the API parameters and any [reserved parameters](/reference/airnode/latest/specifications/reserved-parameters.md) which must be encoded. See [Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md) for how these are encoded. + + In most, cases the parameters are encoded off-chain and passed to the requester which only forwards them. You can use the [@api3/airnode-abi](/reference/airnode/latest/packages/airnode-abi.md) package to perform the encoding and decoding. Take a look at the JavaScript snippet below. ```javascript // JavaScript snippet @@ -184,8 +130,7 @@ must gather the following parameters to pass on to // '0x...' ``` - However, this is not a hard requirement and you can encode the parameters - on-chain as well. Take a look at the Solidity snippet below. + However, this is not a hard requirement and you can encode the parameters on-chain as well. Take a look at the Solidity snippet below. ```solidity // Solidity snippet @@ -197,20 +142,11 @@ must gather the following parameters to pass on to ) ``` -For additional information on request parameters when calling -`airnodeRrp.makeFullRequest()`, see -[Request Parameters](/reference/airnode/latest/concepts/request.md#request-parameters) -in the Reference section. +For additional information on request parameters when calling `airnodeRrp.makeFullRequest()`, see [Request Parameters](/reference/airnode/latest/concepts/request.md#request-parameters) in the Reference section. ## 3. Capture the Response -As soon as the Airnode gathers a request, from the event log of the on-chain -contract `AirnodeRrpV0.sol`, it gets the data from the API provider, encodes it, -and starts an on-chain transaction responding to the request. The Airnode calls -the `AirnodeRrpV0.sol` contract function `fulfill()`, which in turn calls the -requester at `airnodeCallback()`. For the purposes of the callback, recall the -request supplied the request contract address and the desired callback function -which the AirnodeRrpV0.sol protocol contract stored with the `requestId`. +As soon as the Airnode gathers a request, from the event log of the on-chain contract `AirnodeRrpV0.sol`, it gets the data from the API provider, encodes it, and starts an on-chain transaction responding to the request. The Airnode calls the `AirnodeRrpV0.sol` contract function `fulfill()`, which in turn calls the requester at `airnodeCallback()`. For the purposes of the callback, recall the request supplied the request contract address and the desired callback function which the AirnodeRrpV0.sol protocol contract stored with the `requestId`. ```solidity import "@api3/airnode-protocol/contracts/rrp/requesters/RrpRequesterV0.sol"; @@ -246,22 +182,13 @@ contract MyRequester is RrpRequester { ### Response Parameters -The callback to a requester contains two parameters, as shown in the -`airnodeCallback()` function in the code sample above. +The callback to a requester contains two parameters, as shown in the `airnodeCallback()` function in the code sample above. -- **requestId**: First acquired when making the request and passed here as a - reference to identify the request for which the response is intended. -- **data**: In case of a successful response, this is the requested data which - has been encoded and contains a - [timestamp](/reference/ois/latest/reserved-parameters.md#timestamp-encoded-to-uint256-on-chain) - in addition to other response data. Decode it using the function `decode()` - from the `abi` object. +- **requestId**: First acquired when making the request and passed here as a reference to identify the request for which the response is intended. +- **data**: In case of a successful response, this is the requested data which has been encoded and contains a [timestamp](/reference/ois/latest/reserved-parameters.md#timestamp-encoded-to-uint256-on-chain) in addition to other response data. Decode it using the function `decode()` from the `abi` object. ## 4. Deploy and Sponsor the Requester -Deploy the requester to the desired blockchain and then sponsor the requester. -See -[Requesters and Sponsors](/reference/airnode/latest/developers/requesters-sponsors.md#how-to-sponsor-a-requester) -to learn more about sponsoring a requester. +Deploy the requester to the desired blockchain and then sponsor the requester. See [Requesters and Sponsors](/reference/airnode/latest/developers/requesters-sponsors.md#how-to-sponsor-a-requester) to learn more about sponsoring a requester. diff --git a/docs/guides/airnode/setting-up-airnode/index.md b/docs/guides/airnode/setting-up-airnode/index.md index 488eaa9a..35f5c478 100644 --- a/docs/guides/airnode/setting-up-airnode/index.md +++ b/docs/guides/airnode/setting-up-airnode/index.md @@ -21,36 +21,23 @@ tags: ## Introduction -[Airnode](/reference/airnode/latest/concepts/airnode.md) is a first-party oracle -node deployed and operated by the API provider to provide any data from their -REST API on-chain. It is a lightweight, serverless, and cost-efficient oracle -node that can be deployed in minutes. +[Airnode](/reference/airnode/latest/concepts/airnode.md) is a first-party oracle node deployed and operated by the API provider to provide any data from their REST API on-chain. It is a lightweight, serverless, and cost-efficient oracle node that can be deployed in minutes. -This guide will walk you through the steps to set up an Airnode with your own -REST API. +This guide will walk you through the steps to set up an Airnode with your own REST API. ## ChainAPI -[ChainAPI](https://chainapi.com/) is a platform that enables you to integrate -and deploy the open-source [Airnode](/reference/airnode/latest/understand/) with -its step-by-step integration and deployment tools. It helps streamline the -Airnode integration process for API providers. +[ChainAPI](https://chainapi.com/) is a platform that enables you to integrate and deploy the open-source [Airnode](/reference/airnode/latest/understand/) with its step-by-step integration and deployment tools. It helps streamline the Airnode integration process for API providers. -Using ChainAPI, API providers can configure and deploy an Airnode which allows -them to provide their API data to multiple chains. +Using ChainAPI, API providers can configure and deploy an Airnode which allows them to provide their API data to multiple chains. -ChainAPI can connect almost any API, whether open or authenticated, to Airnode. -Airnode then queries your API operations to be consumed by EVM on-chain dApps, -by using the [Request-Response Protocol](/reference/airnode/latest/concepts/). +ChainAPI can connect almost any API, whether open or authenticated, to Airnode. Airnode then queries your API operations to be consumed by EVM on-chain dApps, by using the [Request-Response Protocol](/reference/airnode/latest/concepts/). -To get started, go to [ChainAPI](https://chainapi.com/) and login using -[MetaMask](https://metamask.io/). +To get started, go to [ChainAPI](https://chainapi.com/) and login using [MetaMask](https://metamask.io/). -Sign in with your MetaMask account. If you don't have a MetaMask account, you -can create one by following the instructions -[here](https://metamask.io/download/). +Sign in with your MetaMask account. If you don't have a MetaMask account, you can create one by following the instructions [here](https://metamask.io/download/). After registering, you will be redirected to the ChainAPI dashboard. @@ -58,52 +45,34 @@ After registering, you will be redirected to the ChainAPI dashboard. ## Creating a New Integration -To create a new integration, click on the **Integrate** button on the top left -corner of the dashboard and select **Integrate API**. +To create a new integration, click on the **Integrate** button on the top left corner of the dashboard and select **Integrate API**. -Enter your API name, select the category and description and click on -**Create**. +Enter your API name, select the category and description and click on **Create**. -Enter the base URL for your API and click on **Next**. You can also add in -support for security schemes like API keys or an HTTP bearer token by clicking -on **Add Security Scheme**. +Enter the base URL for your API and click on **Next**. You can also add in support for security schemes like API keys or an HTTP bearer token by clicking on **Add Security Scheme**. -You will now be redirected to the next step where you can add your API -endpoints. For each endpoint you want to add, click on **Add Endpoint** and -enter the endpoint name, path, method, and description. +You will now be redirected to the next step where you can add your API endpoints. For each endpoint you want to add, click on **Add Endpoint** and enter the endpoint name, path, method, and description. -You can now add all the parameters for your endpoint. Click on **Add parameter** -and enter the parameter name and type(query/header/path/cookie). You can also -define the parameter as a user-defined or a fixed value. You can add multiple -parameters for each endpoint by clicking on **Add parameter**. +You can now add all the parameters for your endpoint. Click on **Add parameter** and enter the parameter name and type(query/header/path/cookie). You can also define the parameter as a user-defined or a fixed value. You can add multiple parameters for each endpoint by clicking on **Add parameter**. -[Reserved parameters](/reference/ois/latest/reserved-parameters) define what -part of the response is to be picked and encoded before fulfillment. It can be -defined by the requester or can also be hardcoded in the Airnode configuration. -To hardcode the reserved parameters, click on **Reserved Parameters** to define -the parameter's `_name`, `_path` and `_times`. +[Reserved parameters](/reference/ois/latest/reserved-parameters) define what part of the response is to be picked and encoded before fulfillment. It can be defined by the requester or can also be hardcoded in the Airnode configuration. To hardcode the reserved parameters, click on **Reserved Parameters** to define the parameter's `_name`, `_path` and `_times`. -[Pre/Post Processing](/reference/ois/latest/processing) allows you to specify -snippets of Javascript code to be run before or after a request is made to your -Airnode. Click on **Advanced** and select **Add Pre-processing** or **Add -Post-processing** to add your snippets. +[Pre/Post Processing](/reference/ois/latest/processing) allows you to specify snippets of Javascript code to be run before or after a request is made to your Airnode. Click on **Advanced** and select **Add Pre-processing** or **Add Post-processing** to add your snippets. - Pre-processing snippets are executed before making the request to the Airnode. -- Post-processing snippets are executed after receiving the response from the - Airnode. +- Post-processing snippets are executed after receiving the response from the Airnode. -To read more about pre and post-processing, click -[here](/reference/ois/latest/processing). +To read more about pre and post-processing, click [here](/reference/ois/latest/processing). After adding all the required endpoints and parameters, click on **Finish**. @@ -111,46 +80,32 @@ After adding all the required endpoints and parameters, click on **Finish**. ## Setting up a Deployment -To set up a new deployment for your Airnode, click on the **Deploy** button on -the top left corner of the dashboard and select **New Deployment**. +To set up a new deployment for your Airnode, click on the **Deploy** button on the top left corner of the dashboard and select **New Deployment**. -Enter your deployment name and select the integration you would want to use with -the deployment. Click on **Next**. +Enter your deployment name and select the integration you would want to use with the deployment. Click on **Next**. -Select the cloud provider you would want to use for your deployment. You can -choose between AWS or GCP. Choose the region and the Airnode version and click -on **Next**. +Select the cloud provider you would want to use for your deployment. You can choose between AWS or GCP. Choose the region and the Airnode version and click on **Next**. -Select the chains you would want to use your Airnode on. You can choose any of -the supported chains (Mainnets/Testnets) with up to 10 custom providers for each -chain. Click on **Next** after selecting the chains and the number of providers. +Select the chains you would want to use your Airnode on. You can choose any of the supported chains (Mainnets/Testnets) with up to 10 custom providers for each chain. Click on **Next** after selecting the chains and the number of providers. -[Authorizer](/reference/airnode/latest/concepts/authorizers) contracts allow you -to specify which smart contracts can make requests to your Airnode’s endpoints. +[Authorizer](/reference/airnode/latest/concepts/authorizers) contracts allow you to specify which smart contracts can make requests to your Airnode’s endpoints. -When an Airnode receives a request, it can use on-chain authorizer contracts to -verify if a response is warranted. This allows the Airnode to implement a wide -variety of policies and to authorize requester contract access to its underlying -API. +When an Airnode receives a request, it can use on-chain authorizer contracts to verify if a response is warranted. This allows the Airnode to implement a wide variety of policies and to authorize requester contract access to its underlying API. -- Public Authorizers will allow any smart contract to make requests to your - Airnode. -- Restricted Authorizers will only allow smart contract addresses that have been - granted access to make requests to your Airnode. +- Public Authorizers will allow any smart contract to make requests to your Airnode. +- Restricted Authorizers will only allow smart contract addresses that have been granted access to make requests to your Airnode. -To read more about authorizers, click -[here](/reference/airnode/latest/concepts/authorizers). +To read more about authorizers, click [here](/reference/airnode/latest/concepts/authorizers). -For basic deployments, you can keep the authorizer as **Public**. Click on -**Next**. +For basic deployments, you can keep the authorizer as **Public**. Click on **Next**. @@ -158,14 +113,10 @@ Review your configuration for the final time and click on **Next**. -You will now be redirected to download the configuration files for your Airnode. -Click on **Download Files** to download the configuration file. +You will now be redirected to download the configuration files for your Airnode. Click on **Download Files** to download the configuration file. -You can now deploy your Airnode using the configuration file. You can either -refer to the steps on-screen or follow the deployment guide -[here](/guides/airnode/deploy-airnode/deploy-aws/). +You can now deploy your Airnode using the configuration file. You can either refer to the steps on-screen or follow the deployment guide [here](/guides/airnode/deploy-airnode/deploy-aws/). -Once you are done deploying your Airnode, you can click on **Finish Deployment** -to view your deployment status. +Once you are done deploying your Airnode, you can click on **Finish Deployment** to view your deployment status. diff --git a/docs/guides/airnode/using-rrp-templates.md b/docs/guides/airnode/using-rrp-templates.md index 05d09a1c..06ce9a15 100644 --- a/docs/guides/airnode/using-rrp-templates.md +++ b/docs/guides/airnode/using-rrp-templates.md @@ -15,31 +15,15 @@ outline: deep # {{$frontmatter.title}} -This guide steps through the process of making a template request of an Airnode -using RRP (request-response protocol) to get data from an API provider. This -approach allows a smart contract to store the parameters for an RRP call in a -template. This is advantageous when a call to an Airnode will be made using the -same parameters each time. See -[Using Templates (RRP)](/reference/airnode/latest/developers/using-templates.md) -and -[Coingecko example](https://github.com/api3dao/airnode/tree/master/packages/airnode-examples/integrations/coingecko-template) -to learn more about the technical specifications of a template as used by a -requester. As a prerequisite to this guide first try the guide -[Making an RRP Request](/guides/airnode/rrp-request.md). +This guide steps through the process of making a template request of an Airnode using RRP (request-response protocol) to get data from an API provider. This approach allows a smart contract to store the parameters for an RRP call in a template. This is advantageous when a call to an Airnode will be made using the same parameters each time. See [Using Templates (RRP)](/reference/airnode/latest/developers/using-templates.md) and [Coingecko example](https://github.com/api3dao/airnode/tree/master/packages/airnode-examples/integrations/coingecko-template) to learn more about the technical specifications of a template as used by a requester. As a prerequisite to this guide first try the guide [Making an RRP Request](/guides/airnode/rrp-request.md). ::: info Consider dAPIs -While using the Airnode's RRP protocol to acquire API provider data is usable it -is not as efficient or as straightforward as using a dAPI. Therefore, best -practices usually entail using a -[dAPI](https://docs.api3.org/oev-searchers/in-depth/dapis/) -to acquire API provider data. +While using the Airnode's RRP protocol to acquire API provider data is usable it is not as efficient or as straightforward as using a dAPI. Therefore, best practices usually entail using a [dAPI](https://docs.api3.org/oev-searchers/in-depth/dapis/) to acquire API provider data. ::: -There are just a few steps to create and place a template on-chain for use by a -requester (smart contract). Each template is identified by a `templateId`, which -is the hash of its contents. +There are just a few steps to create and place a template on-chain for use by a requester (smart contract). Each template is identified by a `templateId`, which is the hash of its contents. ## 1. Create a template @@ -64,19 +48,11 @@ First create a file that contains a JSON object, see the example below. } ``` -- `airnode`: You will need the address of the `AirnodeRrpV0.sol` contract on a - desired network. See [Airnode Contract Addresses](/reference/airnode/latest/) - for a listings of several networks. The example above uses an address on - Sepolia. +- `airnode`: You will need the address of the `AirnodeRrpV0.sol` contract on a desired network. See [Airnode Contract Addresses](/reference/airnode/latest/) for a listings of several networks. The example above uses an address on Sepolia. -- `endpointId`: Declared inside an Airnode's configuration file which is created - by the API provider that owns the Airnode. You may need to contact the API - provider if they do not publish their `endpointIds`. +- `endpointId`: Declared inside an Airnode's configuration file which is created by the API provider that owns the Airnode. You may need to contact the API provider if they do not publish their `endpointIds`. -- `parameters`: The parameters that the Airnode endpoint needs. All parameters - needed by the endpoint do not need to be included as they could also be passed - to the `makeTemplateRequest()` function of Airnode along with the - `templateId`. +- `parameters`: The parameters that the Airnode endpoint needs. All parameters needed by the endpoint do not need to be included as they could also be passed to the `makeTemplateRequest()` function of Airnode along with the `templateId`. Below are links that further discuss request parameters if you additional help. @@ -85,12 +61,7 @@ Below are links that further discuss request parameters if you additional help. ## 2. Upload the template -Use the -[create-template](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin#create-template) -command in the @api3/airnode-admin package to move your template on-chain. The -command`create-template`reads a file, uses its contents to create a template and -returns a`templateId`. To create a new template record on-chain you will need -the following. +Use the [create-template](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin#create-template) command in the @api3/airnode-admin package to move your template on-chain. The command`create-template`reads a file, uses its contents to create a template and returns a`templateId`. To create a new template record on-chain you will need the following. - A providerURL from your blockchain provider. - A mnemonic for gas to fund the record creation. @@ -98,10 +69,7 @@ the following. ::: info mnemonic -This wallet pays the transaction gas costs to write the template record -on-chain. This is not the wallet(s) that will pay gas costs to actually execute -any Airnode, for that the Airnode themselves will create sponsor wallets on -behalf of your sponsor record. +This wallet pays the transaction gas costs to write the template record on-chain. This is not the wallet(s) that will pay gas costs to actually execute any Airnode, for that the Airnode themselves will create sponsor wallets on behalf of your sponsor record. ::: @@ -112,22 +80,17 @@ npx @api3/airnode-admin create-template \ --templateFilePath ./template.json ``` -The above command will return a `templateId`. This is the ID used when calling -the Airnode function `makeTemplateRequest()`. +The above command will return a `templateId`. This is the ID used when calling the Airnode function `makeTemplateRequest()`. ```sh Template ID: 0x006154fb94631d2bd66f36565824a6ed0f4c979eb26173ef9e4aad15dd03e6df ``` -When creating more than one template using the same parameter values for an -Airnode/endpointId pair, the same `templateId`will be returned for each. Only -one template is created when the parameters are the same. +When creating more than one template using the same parameter values for an Airnode/endpointId pair, the same `templateId`will be returned for each. Only one template is created when the parameters are the same. ## 3. Retrieving the template -You can retrieve the template from the chain using the Admin CLI command -[get-template](/reference/airnode/latest/packages/admin-cli.md#get-template) -using the `templateId`. Note that the parameters are ABI encoded. +You can retrieve the template from the chain using the Admin CLI command [get-template](/reference/airnode/latest/packages/admin-cli.md#get-template) using the `templateId`. Note that the parameters are ABI encoded. ```sh npx @api3/airnode-admin get-template \ @@ -144,20 +107,11 @@ npx @api3/airnode-admin get-template \ ## 4. Make a request using the template -A requester can use the template by calling a different function from -`AirnodeRrpV0.sol` when making a request. See the guide -[Making an RRP Request](/guides/airnode/rrp-request.md#_2-implement-the-request-logic) -and use the function `makeTemplateRequest()` rather than `makeFullRequest()`. -Note that the parameter for each are slightly different. The `templateId ` -replaces both the `airnode` and `endpointId`. +A requester can use the template by calling a different function from `AirnodeRrpV0.sol` when making a request. See the guide [Making an RRP Request](/guides/airnode/rrp-request.md#_2-implement-the-request-logic) and use the function `makeTemplateRequest()` rather than `makeFullRequest()`. Note that the parameter for each are slightly different. The `templateId ` replaces both the `airnode` and `endpointId`. -When calling `makeTemplateRequest()` the parameter `parameters` is used to -provide addition parameters to those in the template, if any are required. +When calling `makeTemplateRequest()` the parameter `parameters` is used to provide addition parameters to those in the template, if any are required. -Replace the function call `makeFullRequest()` with `makeTemplateRequest()` in -the -[Making an RRP Request](/guides/airnode/rrp-request.md#_2-implement-the-request-logic) -guide. +Replace the function call `makeFullRequest()` with `makeTemplateRequest()` in the [Making an RRP Request](/guides/airnode/rrp-request.md#_2-implement-the-request-logic) guide. ```solidity bytes32 requestId = airnodeRrp.makeTemplateRequest( diff --git a/docs/guides/index.md b/docs/guides/index.md index afb8084a..fa1497f3 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -16,10 +16,6 @@ tags: # {{$frontmatter.title}} -Each guide is a complete standalone step-by-step introduction to Airnode. For -Airnode the guides work with the latest version of Airnode. If you have an idea -for a guide that you wish was here, please create a -[GitHub issue](https://github.com/api3dao/airnode-docs). This will help us -create a full and comprehensive list. +Each guide is a complete standalone step-by-step introduction to Airnode. For Airnode the guides work with the latest version of Airnode. If you have an idea for a guide that you wish was here, please create a [GitHub issue](https://github.com/api3dao/airnode-docs). This will help us create a full and comprehensive list. diff --git a/docs/index.md b/docs/index.md index 19e1cf97..fc6ab355 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,9 +4,7 @@ layout: home hero: name: Airnode text: Documentation - tagline: - API3 builds solutions that bridge the gap between off-chain data and - on-chain applications with maximum security and minimal latency. + tagline: API3 builds solutions that bridge the gap between off-chain data and on-chain applications with maximum security and minimal latency. image: src: /img/beacons.svg alt: API3 diff --git a/docs/reference/airnode/latest/chain-idiosyncrasies.md b/docs/reference/airnode/latest/chain-idiosyncrasies.md index 2965ce3e..df638536 100644 --- a/docs/reference/airnode/latest/chain-idiosyncrasies.md +++ b/docs/reference/airnode/latest/chain-idiosyncrasies.md @@ -19,60 +19,28 @@ tags: # {{$frontmatter.title}} -Differences in chain design inevitably lead to some unique chain-specific -considerations. Below are idiosyncrasies we have identified, though it may not -be comprehensive and we are interested in hearing if you encounter others. +Differences in chain design inevitably lead to some unique chain-specific considerations. Below are idiosyncrasies we have identified, though it may not be comprehensive and we are interested in hearing if you encounter others. ## config.json - `chains` field -The idiosyncrasies below relate to the `chains` field of `config.json` discussed -in -[Configuring Airnode](/reference/airnode/latest/understand/configuring.md#chains) -and -[Deployment Files](/reference/airnode/latest/deployment-files/config-json.md#chains) -section. +The idiosyncrasies below relate to the `chains` field of `config.json` discussed in [Configuring Airnode](/reference/airnode/latest/understand/configuring.md#chains) and [Deployment Files](/reference/airnode/latest/deployment-files/config-json.md#chains) section. ### Avalanche -Gas prices on Avalanche mainnet are often underestimated when getting `type 0` -estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error -manifests as the `maxFeePerGas` being set to less than the block -`baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set -`recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. +Gas prices on Avalanche mainnet are often underestimated when getting `type 0` estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error manifests as the `maxFeePerGas` being set to less than the block `baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set `recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. ### Arbitrum -Execution costs on Arbitrum are calculated slightly differently than Ethereum, -which impacts the gas required to fulfill requests. To account for this, it is -recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when -using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is -optional, so if it is not specified, Airnode will attempt to estimate the -appropriate gas limit automatically. Read more about -[ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. +Execution costs on Arbitrum are calculated slightly differently than Ethereum, which impacts the gas required to fulfill requests. To account for this, it is recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. Read more about [ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. ### Metis -On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is -recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that -`fulfillmentGasLimit` is optional, so if it is not specified, Airnode will -attempt to estimate the appropriate gas limit automatically. +On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. ### Optimism -Using `type 0` transaction types is recommended over `type 2` so the use of -`providerRecommendedEip1559GasPrice` is discouraged. - -As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, -which are -[accounted for separately](https://docs.optimism.io/stack/transactions/fees). To -cover the L1 data fee when a sponsor requests a -[withdrawal](/reference/airnode/latest/concepts/sponsor.md#withdrawals), an -amount has to be subtracted from the funds returned to the sponsor. The -`withdrawalRemainder` parameter has been introduced specifically for this -reason, though the value required will differ between Optimism mainnet and -testnet due to differences in L1 gas fees. For Optimism testnet, a -`withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a -value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover -an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. +Using `type 0` transaction types is recommended over `type 2` so the use of `providerRecommendedEip1559GasPrice` is discouraged. + +As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, which are [accounted for separately](https://docs.optimism.io/stack/transactions/fees). To cover the L1 data fee when a sponsor requests a [withdrawal](/reference/airnode/latest/concepts/sponsor.md#withdrawals), an amount has to be subtracted from the funds returned to the sponsor. The `withdrawalRemainder` parameter has been introduced specifically for this reason, though the value required will differ between Optimism mainnet and testnet due to differences in L1 gas fees. For Optimism testnet, a `withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. diff --git a/docs/reference/airnode/latest/cloud-resources.md b/docs/reference/airnode/latest/cloud-resources.md index f7523d7f..62334f26 100644 --- a/docs/reference/airnode/latest/cloud-resources.md +++ b/docs/reference/airnode/latest/cloud-resources.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain -resources to fully operate and supports most regions. +When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain resources to fully operate and supports most regions. ## Resources diff --git a/docs/reference/airnode/latest/concepts/airnode-auth.md b/docs/reference/airnode/latest/concepts/airnode-auth.md index 6f6cafec..8f0980a3 100644 --- a/docs/reference/airnode/latest/concepts/airnode-auth.md +++ b/docs/reference/airnode/latest/concepts/airnode-auth.md @@ -19,40 +19,24 @@ tags: # {{$frontmatter.title}} -API providers can instruct Airnode to authenticate requests to their endpoints. -This is done by setting up a security scheme in the config.json file for their -Airnode. Airnode supports three methods of authentication from the OpenAPI -specification. +API providers can instruct Airnode to authenticate requests to their endpoints. This is done by setting up a security scheme in the config.json file for their Airnode. Airnode supports three methods of authentication from the OpenAPI specification. > -[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) -uses the term **security scheme** for authentication and authorization schemes. -Airnode only uses standard OAS defined authentication schemes to identify itself -to API endpoints. Airnode supports two types of authentication, `http` and -`apiKey`. +[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) uses the term **security scheme** for authentication and authorization schemes. Airnode only uses standard OAS defined authentication schemes to identify itself to API endpoints. Airnode supports two types of authentication, `http` and `apiKey`. -- HTTP authentication schemes (using the `Authorization` header) supported by - Airnode: +- HTTP authentication schemes (using the `Authorization` header) supported by Airnode: - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) - [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) -- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in - the request header, cookie in header or query string +- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in the request header, cookie in header or query string -How Airnode sends the authentication data is explained in the sections **Basic, -Bearer and API Key** below. +How Airnode sends the authentication data is explained in the sections **Basic, Bearer and API Key** below. ## Basic -Basic authentication is a simple authentication scheme built into the HTTP -protocol. The Authorization request header contains the Base64-encoded username -and password, separated by a colon. When handling the request, the server -decodes the login details and checks if the user can access the requested -content. +Basic authentication is a simple authentication scheme built into the HTTP protocol. The Authorization request header contains the Base64-encoded username and password, separated by a colon. When handling the request, the server decodes the login details and checks if the user can access the requested content. -The header field is in the form of `Authorization: Basic ` where -`credentials` is the Base64 encoding of a username and password joined by a -single colon (`airnode:airnode-password`). +The header field is in the form of `Authorization: Basic ` where `credentials` is the Base64 encoding of a username and password joined by a single colon (`airnode:airnode-password`). `Authorization: Basic ` @@ -63,10 +47,7 @@ curl -H "Authorization: Basic YW5kZXJzb25AZ21haWwuY29tOjEyM215cGFzc3dvcmQ=" \ ## Bearer -Bearer authentication (also called token authentication) is an HTTP -authentication scheme that involves security tokens called bearer tokens. The -API provider supplies a token used by Airnode to authenticate itself to API -endpoints. +Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The API provider supplies a token used by Airnode to authenticate itself to API endpoints. The header field is in the form of `Authorization: Bearer `. @@ -77,9 +58,7 @@ curl -H "Authorization: Bearer RZ8Y65TG" \ ## API Key -Some APIs use an `apiKey` for authentication. The API provider supplies an -`apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can -send the `apiKey` three ways. +Some APIs use an `apiKey` for authentication. The API provider supplies an `apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can send the `apiKey` three ways. ```sh # In the query string. diff --git a/docs/reference/airnode/latest/concepts/airnode.md b/docs/reference/airnode/latest/concepts/airnode.md index 19483e3e..93098c8a 100644 --- a/docs/reference/airnode/latest/concepts/airnode.md +++ b/docs/reference/airnode/latest/concepts/airnode.md @@ -19,37 +19,17 @@ tags: # {{$frontmatter.title}} -Airnode is a serverless oracle node implemented with a "set and forget" -philosophy. Airnode is flexible in that it can move API provider data on-chain -for multiple purposes. The most important of which are data feeds -([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in -response to dApp direct requests for API provider data -([RRP](/reference/airnode/latest/developers/)). +Airnode is a serverless oracle node implemented with a "set and forget" philosophy. Airnode is flexible in that it can move API provider data on-chain for multiple purposes. The most important of which are data feeds ([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in response to dApp direct requests for API provider data ([RRP](/reference/airnode/latest/developers/)). ## Airnode sources data to dAPIs -An Airnode supplies API provider data to beacons from API providers. These -beacons are the underlying data source for data feeds known as dAPIs. +An Airnode supplies API provider data to beacons from API providers. These beacons are the underlying data source for data feeds known as dAPIs. -API providers, owners of first-party Airnodes, store data feed values on-chain -as individual beacons that in are turn sourced by the -[Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) -contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). -Airnode has an internal mechanism that looks for a deviation in the value of API -provider's API operations. This mechanism updates beacons on-chain as needed. +API providers, owners of first-party Airnodes, store data feed values on-chain as individual beacons that in are turn sourced by the [Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). Airnode has an internal mechanism that looks for a deviation in the value of API provider's API operations. This mechanism updates beacons on-chain as needed. ## Airnode processes RRP requests -An Airnode is capable of serving the data from one or more APIs directly to -[requesters](/reference/airnode/latest/concepts/requester.md) (which are -on-chain smart contracts) that request data served by a particular Airnode. This -is done using the request-response protocol (RRP) mechanism of Airnode. The -AirnodeRrpV0 protocol is designed to be flexible and is meant to serve a variety -of use cases. See the the -[Calling Airnode (RRP)](/reference/airnode/latest/developers/index.md) for more -details on how an RRP request is made. Also see the Airnode -[requester examples](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/contracts) -for potential design patterns. +An Airnode is capable of serving the data from one or more APIs directly to [requesters](/reference/airnode/latest/concepts/requester.md) (which are on-chain smart contracts) that request data served by a particular Airnode. This is done using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 protocol is designed to be flexible and is meant to serve a variety of use cases. See the the [Calling Airnode (RRP)](/reference/airnode/latest/developers/index.md) for more details on how an RRP request is made. Also see the Airnode [requester examples](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/contracts) for potential design patterns. diff --git a/docs/reference/airnode/latest/deployment-files/templates/aws-env.md b/docs/reference/airnode/latest/deployment-files/templates/aws-env.md index cb500258..daa3daef 100644 --- a/docs/reference/airnode/latest/deployment-files/templates/aws-env.md +++ b/docs/reference/airnode/latest/deployment-files/templates/aws-env.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -The `aws.env` contains AWS credentials from an IAM user. These credentials are -used by the Docker -[deployer image](/reference/airnode/latest/docker/deployer-image.md) to deploy -an Airnode to AWS. For more details, see the full description of the -[aws.env](/reference/airnode/latest/deployment-files/templates/aws-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `aws.env` contains AWS credentials from an IAM user. These credentials are used by the Docker [deployer image](/reference/airnode/latest/docker/deployer-image.md) to deploy an Airnode to AWS. For more details, see the full description of the [aws.env](/reference/airnode/latest/deployment-files/templates/aws-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AWS_ACCESS_KEY_ID= diff --git a/docs/reference/airnode/latest/deployment-files/templates/config-json.md b/docs/reference/airnode/latest/deployment-files/templates/config-json.md index e0023f9c..e7de635f 100644 --- a/docs/reference/airnode/latest/deployment-files/templates/config-json.md +++ b/docs/reference/airnode/latest/deployment-files/templates/config-json.md @@ -19,33 +19,23 @@ tags: # {{$frontmatter.title}} -A template for an Airnode's configuration file. Below are notations to help -explain contents of the template. +A template for an Airnode's configuration file. Below are notations to help explain contents of the template. -- `, , `: The value added is independent from - other fields and a value is needed unless otherwise indicated. These values - are not considered secret unless you want them to be. +- `, , `: The value added is independent from other fields and a value is needed unless otherwise indicated. These values are not considered secret unless you want them to be. -- ``: If two fields contain the same - expression, use the same value in them because they are referencing each - other. Usually these are not considered to be secret. +- ``: If two fields contain the same expression, use the same value in them because they are referencing each other. Usually these are not considered to be secret. -- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to - `secrets.env` though it is not required. +- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to `secrets.env` though it is not required. Consider the following relationships. - `ois[0].title` is related to `triggers.rrp[0].oisTitle`. -- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to - ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in -- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to - ois[0].endpoints[0].parameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to ois[0].endpoints[0].parameters[0].operationParameter.in -See -[config.json](/reference/airnode/latest/deployment-files/templates/config-json.md) -as a reference while building a config.json file. +See [config.json](/reference/airnode/latest/deployment-files/templates/config-json.md) as a reference while building a config.json file. ```json { diff --git a/docs/reference/airnode/latest/deployment-files/templates/ois-json.md b/docs/reference/airnode/latest/deployment-files/templates/ois-json.md index e7683853..3b16c7af 100644 --- a/docs/reference/airnode/latest/deployment-files/templates/ois-json.md +++ b/docs/reference/airnode/latest/deployment-files/templates/ois-json.md @@ -19,11 +19,6 @@ tags: # {{$frontmatter.title}} -An [OIS (Oracle Integration Specifications)](/reference/ois/latest/) JSON object -is part of an Airnode's -[config.json](/reference/airnode/latest/deployment-files/templates/config-json.md) -file. There can be more than one OIS object in the `config.json` file that -defines an Airnode. See the [OIS Template](/reference/ois/latest/template.md) in -the OIS document set. +An [OIS (Oracle Integration Specifications)](/reference/ois/latest/) JSON object is part of an Airnode's [config.json](/reference/airnode/latest/deployment-files/templates/config-json.md) file. There can be more than one OIS object in the `config.json` file that defines an Airnode. See the [OIS Template](/reference/ois/latest/template.md) in the OIS document set. diff --git a/docs/reference/airnode/latest/deployment-files/templates/secrets-env.md b/docs/reference/airnode/latest/deployment-files/templates/secrets-env.md index f9d00b33..f768c264 100644 --- a/docs/reference/airnode/latest/deployment-files/templates/secrets-env.md +++ b/docs/reference/airnode/latest/deployment-files/templates/secrets-env.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The `secrets.env` contains the secrets that the respective Airnode deployments -will need. All variables defined in a `secrets.env` can be interpolated inside -`config.json`. For more details, see the full description of the -[secrets.env](/reference/airnode/latest/deployment-files/secrets-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `secrets.env` contains the secrets that the respective Airnode deployments will need. All variables defined in a `secrets.env` can be interpolated inside `config.json`. For more details, see the full description of the [secrets.env](/reference/airnode/latest/deployment-files/secrets-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AIRNODE_WALLET_MNEMONIC="" diff --git a/docs/reference/airnode/latest/developers/fees.md b/docs/reference/airnode/latest/developers/fees.md index dc1a1a5d..f0ab4437 100644 --- a/docs/reference/airnode/latest/developers/fees.md +++ b/docs/reference/airnode/latest/developers/fees.md @@ -19,18 +19,11 @@ tags: # {{$frontmatter.title}} -There are some one-time setup/maintenance costs and some ongoing costs of -calling an Airnode. The Airnode protocol is designed in a way that the requester -assumes all gas costs, including the request fulfillment (response) -transactions. +There are some one-time setup/maintenance costs and some ongoing costs of calling an Airnode. The Airnode protocol is designed in a way that the requester assumes all gas costs, including the request fulfillment (response) transactions. ## Sponsors -Fees are encountered when a sponsor engages in setup activity such as sponsoring -a requester. These are per call transaction gas costs and are relatively small. -The funds come from the wallet mnemonic that the sponsor supplies when calling -certain [admin commands](/reference/airnode/latest/packages/admin-cli.md) as -shown below. +Fees are encountered when a sponsor engages in setup activity such as sponsoring a requester. These are per call transaction gas costs and are relatively small. The funds come from the wallet mnemonic that the sponsor supplies when calling certain [admin commands](/reference/airnode/latest/packages/admin-cli.md) as shown below. - [sponsor-requester](/reference/airnode/latest/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/latest/packages/admin-cli.md#unsponsor-requester) @@ -39,33 +32,18 @@ shown below. ## Airnodes -The fees take the form of transaction gas costs. These are applied when funding -a requester's sponsor wallet for an Airnode and when executing the Airnode in -response to a request. +The fees take the form of transaction gas costs. These are applied when funding a requester's sponsor wallet for an Airnode and when executing the Airnode in response to a request. -- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is - funded manually by a sponsor using their preferred wallet management tool such - as MetaMask. +- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is funded manually by a sponsor using their preferred wallet management tool such as MetaMask. -- [Calling](/reference/airnode/latest/developers/index.md) an Airnode: - Transaction gas fees are withdrawn from the sponsor wallet related to the - Airnode being called by a sponsored requester. +- [Calling](/reference/airnode/latest/developers/index.md) an Airnode: Transaction gas fees are withdrawn from the sponsor wallet related to the Airnode being called by a sponsored requester. -Learn more about -[sponsor wallets](/reference/airnode/latest/concepts/sponsor.md) in the -reference section. +Learn more about [sponsor wallets](/reference/airnode/latest/concepts/sponsor.md) in the reference section. ## API Provider Fees -Some API providers charge a subscription fee for access to their data. This is a -typical practice and usually requires the requester to create an account on the -provider's website and then subscribe to a level of service offered. These types -of services are usually billed monthly and can be based on an annual rate to -save costs. The subscription (even if free) will most likely involve the use of -a security scheme such as an API key that must be used to access the data. See -[Calling an Airnode](/reference/airnode/latest/developers/index.md) to learn -more on how to pass the security credentials to an Airnode. +Some API providers charge a subscription fee for access to their data. This is a typical practice and usually requires the requester to create an account on the provider's website and then subscribe to a level of service offered. These types of services are usually billed monthly and can be based on an annual rate to save costs. The subscription (even if free) will most likely involve the use of a security scheme such as an API key that must be used to access the data. See [Calling an Airnode](/reference/airnode/latest/developers/index.md) to learn more on how to pass the security credentials to an Airnode. diff --git a/docs/reference/airnode/latest/developers/index.md b/docs/reference/airnode/latest/developers/index.md index 1f602e91..b340a7ca 100644 --- a/docs/reference/airnode/latest/developers/index.md +++ b/docs/reference/airnode/latest/developers/index.md @@ -19,47 +19,22 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that can push off-chain API data to an on-chain -contract. While dApp developers will find -[dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the -most useful aspect of an Airnode's capabilities, there is the option for -developers to access Airnode data using its request-response protocol (RRP). The -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract facilitates RRP and is designed to be flexible and is meant to -serve a variety of use cases. See the Airnode -[requester examples](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/contracts) -for potential design patterns. +Airnode is a first-party oracle that can push off-chain API data to an on-chain contract. While dApp developers will find [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the most useful aspect of an Airnode's capabilities, there is the option for developers to access Airnode data using its request-response protocol (RRP). The [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract facilitates RRP and is designed to be flexible and is meant to serve a variety of use cases. See the Airnode [requester examples](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/contracts) for potential design patterns. ## It starts with a requester -A requester is a smart contract that can trigger an Airnode RRP request. To do -so, the requester needs to be sponsored and make the request using a matching -sponsor wallet. See -[Requesters and Sponsors](/reference/airnode/latest/developers/requesters-sponsors.md) -on how to sponsor a requester and derive the sponsor wallet. +A requester is a smart contract that can trigger an Airnode RRP request. To do so, the requester needs to be sponsored and make the request using a matching sponsor wallet. See [Requesters and Sponsors](/reference/airnode/latest/developers/requesters-sponsors.md) on how to sponsor a requester and derive the sponsor wallet. ## A simplified understanding -In the diagram below, any typical smart contract is called a requester if it -makes a request of Airnode's RRP protocol. It makes a request to the on-chain -RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event -logs. The off-chain Airnode then accesses the event logs, gets the API data and -performs a callback to the requester. +In the diagram below, any typical smart contract is called a requester if it makes a request of Airnode's RRP protocol. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event logs. The off-chain Airnode then accesses the event logs, gets the API data and performs a callback to the requester. In summary, the requester will do two things. -- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol - contract, which returns a - [`requestId`](/reference/airnode/latest/concepts/request.md#requestid). -- Add a `myFulfill()` function (call it what you like) to your requester where - the off-chain Airnode can send the requested data when ready. The data - includes the same `requestId` as the one returned at the time of making the - request. +- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol contract, which returns a [`requestId`](/reference/airnode/latest/concepts/request.md#requestid). +- Add a `myFulfill()` function (call it what you like) to your requester where the off-chain Airnode can send the requested data when ready. The data includes the same `requestId` as the one returned at the time of making the request. -In the diagram below a requester makes a request to the on-chain RRP protocol -contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its -run cycle the off-chain Airnode accesses the event logs, gets the requested data -from the the API provider, then performs a callback to the requester. +In the diagram below a requester makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its run cycle the off-chain Airnode accesses the event logs, gets the requested data from the the API provider, then performs a callback to the requester. > > @@ -68,19 +43,13 @@ from the the API provider, then performs a callback to the requester. > 3.

Airnode gathers response data from the API specified in the request.

> 4.

Airnode performs a callback to a named function myFulfill() in myContract.sol via the AirnodeRrpV0.sol function fulfill() with the requested data and the requestId.

-See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn -how to make a RRP request of an Airnode. +See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn how to make a RRP request of an Airnode. ## A deeper dive -This section, through its detailed illustration, builds on the previous section -([A simplified understanding](/reference/airnode/latest/developers/index.md#a-simplified-understanding)) -in an attempt to further illustrate and explain the mechanics of how an Airnode -response to a request made by a requester. +This section, through its detailed illustration, builds on the previous section ([A simplified understanding](/reference/airnode/latest/developers/index.md#a-simplified-understanding)) in an attempt to further illustrate and explain the mechanics of how an Airnode response to a request made by a requester. -Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") -deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain -**protocol contract** AirnodeRrpV0.sol. +Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain **protocol contract** AirnodeRrpV0.sol. > > diff --git a/docs/reference/airnode/latest/developers/requesters-sponsors.md b/docs/reference/airnode/latest/developers/requesters-sponsors.md index 356b4355..33ae0774 100644 --- a/docs/reference/airnode/latest/developers/requesters-sponsors.md +++ b/docs/reference/airnode/latest/developers/requesters-sponsors.md @@ -19,143 +19,80 @@ tags: # {{$frontmatter.title}} -As a dApp developer it helps to understand what a **requester** is and what a -**sponsor** does. They are both important parts of the Airnode ecosystem. This -doc will further define them and walk you through the process of sponsoring a -requester and deriving a sponsor wallet using the admin CLI commands. +As a dApp developer it helps to understand what a **requester** is and what a **sponsor** does. They are both important parts of the Airnode ecosystem. This doc will further define them and walk you through the process of sponsoring a requester and deriving a sponsor wallet using the admin CLI commands. ## What is a Requester? -The term [requester](/reference/airnode/latest/concepts/requester.md) is -important to remember. When requester is mentioned, the reference is to your -smart contract that makes a request of an Airnode. +The term [requester](/reference/airnode/latest/concepts/requester.md) is important to remember. When requester is mentioned, the reference is to your smart contract that makes a request of an Airnode. > -As an example see the `myContract.sol` contract in the diagram within the -[Overview](/reference/airnode/latest/concepts/) doc, it is a requester. +As an example see the `myContract.sol` contract in the diagram within the [Overview](/reference/airnode/latest/concepts/) doc, it is a requester. ## What is a Sponsor? -Equally important is the term -[sponsor](/reference/airnode/latest/concepts/sponsor.md). A sponsor is an entity -such as yourself, an organization, etc. Sponsors create relationships between -requesters and Airnodes. +Equally important is the term [sponsor](/reference/airnode/latest/concepts/sponsor.md). A sponsor is an entity such as yourself, an organization, etc. Sponsors create relationships between requesters and Airnodes. ### Sponsor's Requester/Airnode Relationships -As a sponsor you will use the public address from an account within a mnemonic -you own to "**sponsor a requester**" and then use the public address (known as a -[sponsorAddress](/reference/airnode/latest/concepts/sponsor.md#sponsoraddress)) -to "**derive a -[sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet)**" -for an Airnode. This action creates a relationship between a sponsor's requester -and a particular Airnode. You do this because a sponsor is the entity that pays -for the fulfillment of a request, the gas costs the Airnode will incur. These -costs will be withdrawn from the `sponsorWallet` of the Airnode when the -requester calls it. +As a sponsor you will use the public address from an account within a mnemonic you own to "**sponsor a requester**" and then use the public address (known as a [sponsorAddress](/reference/airnode/latest/concepts/sponsor.md#sponsoraddress)) to "**derive a [sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet)**" for an Airnode. This action creates a relationship between a sponsor's requester and a particular Airnode. You do this because a sponsor is the entity that pays for the fulfillment of a request, the gas costs the Airnode will incur. These costs will be withdrawn from the `sponsorWallet` of the Airnode when the requester calls it. ::: info sponsorAddress -A [sponsorAddress](/reference/airnode/latest/concepts/sponsor.md#sponsoraddress) -is a public address of an account from a mnemonic, usually the default account. -Rather than the default account another account from the mnemonic can be used. -The `sponsorAddress` is used to uniquely identify a sponsor. +A [sponsorAddress](/reference/airnode/latest/concepts/sponsor.md#sponsoraddress) is a public address of an account from a mnemonic, usually the default account. Rather than the default account another account from the mnemonic can be used. The `sponsorAddress` is used to uniquely identify a sponsor. ::: -1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester - with the Admin CLI. The CLI will use the default address of the mnemonic - passed as the `sponsorAddress` for the sponsorship unless another account is - specified. +1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester with the Admin CLI. The CLI will use the default address of the mnemonic passed as the `sponsorAddress` for the sponsorship unless another account is specified. -2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the - `sponsorAddress`. +2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the `sponsorAddress`. 3. The requester can now make requests of the Airnode. > -In the above diagram it is possible to use the same sponsorAddress -`(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is -possible to sponsor more than one requester with the same `sponsorAddress`. -However it is important to remember that all requesters can now access all the -Airnodes regardless if they need to. There is no harm in this scenario. +In the above diagram it is possible to use the same sponsorAddress `(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is possible to sponsor more than one requester with the same `sponsorAddress`. However it is important to remember that all requesters can now access all the Airnodes regardless if they need to. There is no harm in this scenario. ### Advanced Scenarios - **Two requesters, one Airnode, one sponsorWallet**: - Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) - would access the same Airnode using a single sponsorWallet derived by the - `sponsorAddress`. + Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) would access the same Airnode using a single sponsorWallet derived by the `sponsorAddress`. - **Two requesters, one Airnode, two sponsorWallets**: - Sponsor two different requesters each with a different `sponsorAddress` (e.g., - `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you - can derive two separate sponsorWallets for the same Airnode. Now each - requester will deplete funds from a separate Airnode sponsorWallet when using - the Airnode. + Sponsor two different requesters each with a different `sponsorAddress` (e.g., `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you can derive two separate sponsorWallets for the same Airnode. Now each requester will deplete funds from a separate Airnode sponsorWallet when using the Airnode. - **One requester, two Airnodes, two sponsorWallets**: - A requester can make requests from two different Airnodes. Sponsor the - requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of - two the Airnodes, using the `sponsorAddress`. Despite the fact that the - sponsorWallet for each Airnode was derived with the same `sponsorAddress` the - sponsorWallets are different since they are derived using the airnode's xpub - plus the `sponsorAddress`. The sponsor must fund both wallets separately using - the unique `sponsorWallet` address of the two sponsorWallets. + A requester can make requests from two different Airnodes. Sponsor the requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of two the Airnodes, using the `sponsorAddress`. Despite the fact that the sponsorWallet for each Airnode was derived with the same `sponsorAddress` the sponsorWallets are different since they are derived using the airnode's xpub plus the `sponsorAddress`. The sponsor must fund both wallets separately using the unique `sponsorWallet` address of the two sponsorWallets. ### Things to Remember -When you sponsor a requester with a `sponsorAddress` you are giving it -permission to use the sponsorWallet (associated with a Airnode) that was derived -using the same `sponsorAddress`. +When you sponsor a requester with a `sponsorAddress` you are giving it permission to use the sponsorWallet (associated with a Airnode) that was derived using the same `sponsorAddress`. -When the requester makes a request to the Airnode, the Airnode will use funds -from the corresponding sponsorWallet to pay gas costs in response to the -request. Therefore the sponsor pays for the fulfillment of the request. +When the requester makes a request to the Airnode, the Airnode will use funds from the corresponding sponsorWallet to pay gas costs in response to the request. Therefore the sponsor pays for the fulfillment of the request. -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/latest/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/latest/developers/fees.md#api-provider-fees). ## Admin CLI Commands -There are several sponsor and requester related commands in the -[Admin CLI Commands](/reference/airnode/latest/packages/admin-cli.md) package. -You can also see a list of available commands using -`npx @api3/airnode-admin --help`. +There are several sponsor and requester related commands in the [Admin CLI Commands](/reference/airnode/latest/packages/admin-cli.md) package. You can also see a list of available commands using `npx @api3/airnode-admin --help`. -In the next two sections of this doc you will use two commands from the -`@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor -wallet_. +In the next two sections of this doc you will use two commands from the `@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor wallet_. -1. [sponsor-requester](/reference/airnode/latest/packages/admin-cli.md#sponsor-requester) - sponsors a requester. -2. [derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address)creates - a sponsor wallet associated with an Airnode. +1. [sponsor-requester](/reference/airnode/latest/packages/admin-cli.md#sponsor-requester) sponsors a requester. +2. [derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address)creates a sponsor wallet associated with an Airnode. ## How to Sponsor a Requester -To sponsor a requester execute the `sponsor-requester` command using the -parameters detailed in the list below. Your requester should already be deployed -on-chain. This command has transaction gas costs. +To sponsor a requester execute the `sponsor-requester` command using the parameters detailed in the list below. Your requester should already be deployed on-chain. This command has transaction gas costs. -- `providerURL`: A blockchain provider URL (such as Infura) with providerID for - the desired network. -- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to - derive the sponsorAddress from the default address. The sponsorAddress will be - needed to derive a sponsorWallet for an Airnode. +- `providerURL`: A blockchain provider URL (such as Infura) with providerID for the desired network. +- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to derive the sponsorAddress from the default address. The sponsorAddress will be needed to derive a sponsorWallet for an Airnode. - `requester-address`: Address of the requester contract. -- `derivation-path (optional)` (_not used in the example below_): Selects an - alternate account to use from the mnemonic rather than the default account. +- `derivation-path (optional)` (_not used in the example below_): Selects an alternate account to use from the mnemonic rather than the default account. -Executing the command -[sponsor-requester](/reference/airnode/latest/packages/admin-cli.md#sponsor-requester) -will sponsor a requester and returns the requesterAddress and sponsorAddress. +Executing the command [sponsor-requester](/reference/airnode/latest/packages/admin-cli.md#sponsor-requester) will sponsor a requester and returns the requesterAddress and sponsorAddress. ::: code-group @@ -181,27 +118,15 @@ npx @api3/airnode-admin sponsor-requester ^ ## How to Derive a Sponsor Wallet -To use a particular Airnode you must _derive a sponsorWallet_. Once the -sponsorWallet is created it must be funded using the public address -(`sponsorWallet` address) returned by the command -`derive-sponsor-wallet-address`. Each Airnode keeps a separate list of -individual sponsorWallets that can access the Airnode. Learn more about a -[sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). +To use a particular Airnode you must _derive a sponsorWallet_. Once the sponsorWallet is created it must be funded using the public address (`sponsorWallet` address) returned by the command `derive-sponsor-wallet-address`. Each Airnode keeps a separate list of individual sponsorWallets that can access the Airnode. Learn more about a [sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). -To derive a sponsorWallet for an Airnode execute the -[derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) -command using the parameters detailed in the list below. There are no -transaction gas costs to do so. +To derive a sponsorWallet for an Airnode execute the [derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) command using the parameters detailed in the list below. There are no transaction gas costs to do so. -- `airnode-xpub`: The extended public address of the Airnode for path - m/44'/60'/0'. +- `airnode-xpub`: The extended public address of the Airnode for path m/44'/60'/0'. - `airnode-address`: The public address of the desired Airnode. -- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) - owned by a sponsor. Usually the sponsorAddress is the one returned when - sponsoring a requester. +- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) owned by a sponsor. Usually the sponsorAddress is the one returned when sponsoring a requester. -The command `derive-sponsor-wallet-address` will return the public address -(`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. +The command `derive-sponsor-wallet-address` will return the public address (`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. ::: code-group @@ -225,22 +150,15 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ::: -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/latest/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/latest/developers/fees.md#api-provider-fees). -If you forget the public address (`sponsorWallet` address) of the sponsorWallet -simply run `derive-sponsor-wallet-address` again. Since the wallet already -exists for the airnodeAddress/sponsorAddress pair it will just return the -address. +If you forget the public address (`sponsorWallet` address) of the sponsorWallet simply run `derive-sponsor-wallet-address` again. Since the wallet already exists for the airnodeAddress/sponsorAddress pair it will just return the address. ## Record Keeping -During and after sponsoring requesters and deriving a sponsorWallet there are a -few things to keep track of. +During and after sponsoring requesters and deriving a sponsorWallet there are a few things to keep track of. | Item | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -248,11 +166,6 @@ few things to keep track of. | sponsor address | The public address of an account derived from a sponsor's mnemonic when sponsoring a requester. Record which `sponsorAddress` was used to create a sponsorWallet for each Airnode. | | sponsor wallet address | Record the `sponsorWallet` address of the sponsorWallet derived for an Airnode. For each Airnode you have derived a sponsorWallet, the Airnode keeps the private key and returns the public address (`sponsorWallet` address) which is used to fund the sponsorWallet. | -You can acquire the public address (`sponsorWallet` address) of a sponsorWallet -later, if you lose it, by running the command `derive-sponsor-wallet-address` -again. Since the sponsorWallet was already created for the -`sponsorAddress/airnodeAddress` pair, the command will only return the public -address for the wallet. However you must use the same `sponsorAddress` used when -the wallet was first created or a new sponsorWallet will be created. +You can acquire the public address (`sponsorWallet` address) of a sponsorWallet later, if you lose it, by running the command `derive-sponsor-wallet-address` again. Since the sponsorWallet was already created for the `sponsorAddress/airnodeAddress` pair, the command will only return the public address for the wallet. However you must use the same `sponsorAddress` used when the wallet was first created or a new sponsorWallet will be created. diff --git a/docs/reference/airnode/latest/developers/using-templates.md b/docs/reference/airnode/latest/developers/using-templates.md index a3d7b708..08b4cfc5 100644 --- a/docs/reference/airnode/latest/developers/using-templates.md +++ b/docs/reference/airnode/latest/developers/using-templates.md @@ -19,15 +19,7 @@ tags: # {{$frontmatter.title}} -A request to an Airnode can have many parameters. It is very common for -requester contracts (e.g., a data feed) to make repeated requests with the exact -same parameters. In such instances, it is wasteful to pass all of these -parameters repeatedly. Templates are used to hold a set of parameter values -on-chain that can be used repeatedly when calling -the`makeTemplateRequest()`function in -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). -Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester -pass`templateId`which identifies a template. +A request to an Airnode can have many parameters. It is very common for requester contracts (e.g., a data feed) to make repeated requests with the exact same parameters. In such instances, it is wasteful to pass all of these parameters repeatedly. Templates are used to hold a set of parameter values on-chain that can be used repeatedly when calling the`makeTemplateRequest()`function in [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester pass`templateId`which identifies a template. ```solidity function makeTemplateRequest( @@ -40,10 +32,7 @@ function makeTemplateRequest( ) external override returns (bytes32 requestId) { ``` -When a template is used to make a request, both the parameters encoded in -parameters of the template and parameters provided at request-time (if any) will -be used by the Airnode. In case the two include a parameter with the same name, -the one provided at request-time will be used. +When a template is used to make a request, both the parameters encoded in parameters of the template and parameters provided at request-time (if any) will be used by the Airnode. In case the two include a parameter with the same name, the one provided at request-time will be used. The structure of a template, as shown below, is simple. @@ -59,10 +48,6 @@ struct Template { } ``` -See the guide -[Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn -how to create and use a template. Also visit the -[coingecko-template](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/integrations/coingecko-template) -monorepo example demonstrates template requests. +See the guide [Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn how to create and use a template. Also visit the [coingecko-template](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/integrations/coingecko-template) monorepo example demonstrates template requests. diff --git a/docs/reference/airnode/latest/developers/verify-airnode-addresses.md b/docs/reference/airnode/latest/developers/verify-airnode-addresses.md index b05e34d9..845aad51 100644 --- a/docs/reference/airnode/latest/developers/verify-airnode-addresses.md +++ b/docs/reference/airnode/latest/developers/verify-airnode-addresses.md @@ -19,18 +19,9 @@ tags: # {{$frontmatter.title}} -An Airnode is owned and operated by an API provider. Every Airnode has a unique -on-chain -[`airnodeAddress`](/reference/airnode/latest/concepts/airnode.md#airnodeaddress) -created and known by its API provider. API providers normally announce their -Airnode addresses in the form of a DNS `TXT` record within their DNS -registration, which also serves to prove ownership. An API provider's Airnode -address is the same for all chains. - -The key for the `TXT` record is `chainapi-verification-keys` and is an array of -Airnode addresses owned by the API provider. Below is an example of the Airnode -for -[dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). +An Airnode is owned and operated by an API provider. Every Airnode has a unique on-chain [`airnodeAddress`](/reference/airnode/latest/concepts/airnode.md#airnodeaddress) created and known by its API provider. API providers normally announce their Airnode addresses in the form of a DNS `TXT` record within their DNS registration, which also serves to prove ownership. An API provider's Airnode address is the same for all chains. + +The key for the `TXT` record is `chainapi-verification-keys` and is an array of Airnode addresses owned by the API provider. Below is an example of the Airnode for [dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). ![dxfeed-txt-record](../assets/images/txt-record-dxfeed.png) diff --git a/docs/reference/airnode/latest/docker/admin-cli-image.md b/docs/reference/airnode/latest/docker/admin-cli-image.md index 590283fc..ede40dbd 100644 --- a/docs/reference/airnode/latest/docker/admin-cli-image.md +++ b/docs/reference/airnode/latest/docker/admin-cli-image.md @@ -22,24 +22,15 @@ tags: -Use the admin CLI image as an alternative method to execute -[Admin CLI](/reference/airnode/latest/packages/admin-cli.md) using npx. Either -method will achieve the same results. The image forgoes downloading the admin -CLI package each time a command is executed using npx. +Use the admin CLI image as an alternative method to execute [Admin CLI](/reference/airnode/latest/packages/admin-cli.md) using npx. Either method will achieve the same results. The image forgoes downloading the admin CLI package each time a command is executed using npx. -If you want to build the admin CLI image from the source yourself, you can find -the -[image built instructions](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin/docker) -in the Airnode repository. +If you want to build the admin CLI image from the source yourself, you can find the [image built instructions](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin/docker) in the Airnode repository. -Additional information about the -[admin CLI image](/reference/airnode/latest/packages/admin-cli.md#using-docker) -is available in the admin CLI commands doc. +Additional information about the [admin CLI image](/reference/airnode/latest/packages/admin-cli.md#using-docker) is available in the admin CLI commands doc. ## Usage -The following example shows the difference between using the docker image versus -npx when executing the `get-sponsor-status` admin CLI command. +The following example shows the difference between using the docker image versus npx when executing the `get-sponsor-status` admin CLI command. ```sh #npx diff --git a/docs/reference/airnode/latest/docker/client-image.md b/docs/reference/airnode/latest/docker/client-image.md index 28ad01b3..a227ffaa 100644 --- a/docs/reference/airnode/latest/docker/client-image.md +++ b/docs/reference/airnode/latest/docker/client-image.md @@ -19,29 +19,17 @@ tags: # {{$frontmatter.title}} -Usually the Airnode is deployed on a serverless platform using the -[deployer](/reference/airnode/latest/docker/deployer-image.md). However, there -is another option which is to run the Airnode in a docker container on your -machine locally, on premise or cloud hosted. +Usually the Airnode is deployed on a serverless platform using the [deployer](/reference/airnode/latest/docker/deployer-image.md). However, there is another option which is to run the Airnode in a docker container on your machine locally, on premise or cloud hosted. -A docker client image has been published on -[Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build -the container from the source yourself, you can find the image and built -instructions in the -[Airnode repository](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-node/docker). +A docker client image has been published on [Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build the container from the source yourself, you can find the image and built instructions in the [Airnode repository](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-node/docker). ## Configuration -The Airnode needs two configuration files for its run: `config.json` and -`secrets.env`. These files need to be passed to the Docker container via -volumes. +The Airnode needs two configuration files for its run: `config.json` and `secrets.env`. These files need to be passed to the Docker container via volumes. -The Docker container looks for configuration files mounted internally in the -`/app/config` directory. +The Docker container looks for configuration files mounted internally in the `/app/config` directory. -Your current working directory should contain the configuration files above and -you bind it to the `/app/config` directory for the docker using the `--volume` -parameter. +Your current working directory should contain the configuration files above and you bind it to the `/app/config` directory for the docker using the `--volume` parameter. ::: code-group @@ -73,8 +61,7 @@ $ docker run --volume %cd%:/config:/app/config ... ## Usage -Example directory structure and commands for running the Airnode Docker -container. The below commands are run from the depicted directory. +Example directory structure and commands for running the Airnode Docker container. The below commands are run from the depicted directory. ### Running Airnode @@ -105,18 +92,11 @@ docker run ^ ::: -> If you want to connect Airnode to a blockchain running on localhost, you need -> to make the blockchain accessible from within the docker itself. If you use -> docker for linux you can use `--network="host"` parameter. If you are using -> Docker Desktop (on any platform), connect to -> `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See -> [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). +> If you want to connect Airnode to a blockchain running on localhost, you need to make the blockchain accessible from within the docker itself. If you use docker for linux you can use `--network="host"` parameter. If you are using Docker Desktop (on any platform), connect to `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). ### Checking Airnode logs -Logs will be output to the console after running the above command. If you -decide to run Airnode in detached mode with `--detach`, you need to use the -`logs` command, optionally with `--follow`, to access the logs. +Logs will be output to the console after running the above command. If you decide to run Airnode in detached mode with `--detach`, you need to use the `logs` command, optionally with `--follow`, to access the logs. ```bash docker logs airnode diff --git a/docs/reference/airnode/latest/docker/deployer-image.md b/docs/reference/airnode/latest/docker/deployer-image.md index 01a71fc7..a0fafeb3 100644 --- a/docs/reference/airnode/latest/docker/deployer-image.md +++ b/docs/reference/airnode/latest/docker/deployer-image.md @@ -19,26 +19,17 @@ tags: # {{$frontmatter.title}} -Use the deployer image to deploy or remove an Airnode with a cloud provider such -as AWS. The simplest way is to use the pre-built packages. If you would rather -build the images yourself see the -[README](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/docker) -in the deployer package. +Use the deployer image to deploy or remove an Airnode with a cloud provider such as AWS. The simplest way is to use the pre-built packages. If you would rather build the images yourself see the [README](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/docker) in the deployer package. ::: info Quick Deploy Demos -See the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -guides to quickly deploy and remove a preconfigured Airnode using the deployer -image. +See the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guides to quickly deploy and remove a preconfigured Airnode using the deployer image. ::: ## Configuration Files -The files `config.json` and `secrets.env` are used to configure the Airnode. The -`aws.env` and `gcp.json` files are used to define environment information the -deployer uses to connect to these cloud providers. +The files `config.json` and `secrets.env` are used to configure the Airnode. The `aws.env` and `gcp.json` files are used to define environment information the deployer uses to connect to these cloud providers. ``` my-airnode @@ -50,22 +41,15 @@ my-airnode ## Cloud Provider Credentials -In order to deploy Airnode to a serverless cloud provider, you need to provide -cloud provider credentials to the Airnode deployer image. The deployer image -currently supports deploying to AWS and GCP. For AWS deployment, see the -[AWS Setup](/reference/airnode/latest/understand/configuring.md#aws-setup-aws-deployment-only) -and for GCP deployment, see the -[GCP Setup](/reference/airnode/latest/understand/configuring.md#gcp-setup-gcp-deployment-only). +In order to deploy Airnode to a serverless cloud provider, you need to provide cloud provider credentials to the Airnode deployer image. The deployer image currently supports deploying to AWS and GCP. For AWS deployment, see the [AWS Setup](/reference/airnode/latest/understand/configuring.md#aws-setup-aws-deployment-only) and for GCP deployment, see the [GCP Setup](/reference/airnode/latest/understand/configuring.md#gcp-setup-gcp-deployment-only). ## Deployer Logs -The deployer saves log files by default into the `config/logs/` direcotry, but -this can be changed by passing a `--logs` argument to the command. +The deployer saves log files by default into the `config/logs/` direcotry, but this can be changed by passing a `--logs` argument to the command. ## Deployer Image Commands -Commands are similar for AWS and GCP. Any differences between AWS and GCP are -noted where they exist. +Commands are similar for AWS and GCP. Any differences between AWS and GCP are noted where they exist. - `deploy` - `list` @@ -77,22 +61,16 @@ noted where they exist. ### `deploy` -The [deploy](/reference/airnode/latest/packages/deployer.md#deploy) command will -create the Airnode with a cloud provider or update it if it already exists. -Three files are needed to run the deploy command. +The [deploy](/reference/airnode/latest/packages/deployer.md#deploy) command will create the Airnode with a cloud provider or update it if it already exists. Three files are needed to run the deploy command. - config.json - secrets.env - aws.env (AWS only) - gcp.json (GCP only) -See -[Deploying an Airnode](/reference/airnode/latest/understand/deploying.md#deploy-with-docker) -for deployment commands specific to various operating systems and cloud -providers. +See [Deploying an Airnode](/reference/airnode/latest/understand/deploying.md#deploy-with-docker) for deployment commands specific to various operating systems and cloud providers. -Note that a `receipt.json` file will be created upon completion. It contains -some deployment information and is used to remove the Airnode. +Note that a `receipt.json` file will be created upon completion. It contains some deployment information and is used to remove the Airnode. @@ -120,24 +98,14 @@ docker run -it --rm ^ #### Re-deployments -A unique deployment is defined by the value of -[nodeSetting.stage](/reference/airnode/latest/deployment-files/config-json.md#stage). -If you deploy again, using the same `nodeSetting.stage` value, then you are -re-deploying or updating the previous deployment. +A unique deployment is defined by the value of [nodeSetting.stage](/reference/airnode/latest/deployment-files/config-json.md#stage). If you deploy again, using the same `nodeSetting.stage` value, then you are re-deploying or updating the previous deployment. -By default the deployer will attempt to remove the Airnode should either a -deployment or re-deployment fail. But if either fails (and -[--auto-remove](/reference/airnode/latest/packages/deployer.md#deploy) is false) -then the Airnode will not be removed, however it could be left in an unstable -state. You can alter the `deploy` command to change this behavior using the -following. +By default the deployer will attempt to remove the Airnode should either a deployment or re-deployment fail. But if either fails (and [--auto-remove](/reference/airnode/latest/packages/deployer.md#deploy) is false) then the Airnode will not be removed, however it could be left in an unstable state. You can alter the `deploy` command to change this behavior using the following. - `--auto-remove true|false`: defaults to true - `--no-auto-remove` -Auto removal is usually recommended for development deployments. For production -deployments, consider changing the value of `nodeSetting.stage` to create a new -deployment and follow-up by removing the previous deployment. +Auto removal is usually recommended for development deployments. For production deployments, consider changing the value of `nodeSetting.stage` to create a new deployment and follow-up by removing the previous deployment. Use the following example to avoid the automatic removal of the Airnode. @@ -150,12 +118,7 @@ api3/airnode-deployer:0.14.1 deploy --auto-remove false ### `list` -Once one or more Airnodes were deployed using the -[deploy](/reference/airnode/latest/docker/deployer-image.md#deploy) command -above, the [list](/reference/airnode/latest/packages/deployer.md#list) command -can be used to list currently deployed Airnodes. Files for cloud provider -authentication are needed for the command to run correctly: `aws.env` (for AWS) -and/or `gcp.json` (for GCP). +Once one or more Airnodes were deployed using the [deploy](/reference/airnode/latest/docker/deployer-image.md#deploy) command above, the [list](/reference/airnode/latest/packages/deployer.md#list) command can be used to list currently deployed Airnodes. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -174,9 +137,7 @@ docker run -it --rm ^ ::: -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ::: code-group @@ -197,14 +158,7 @@ docker run -it --rm ^ ### `info` -Retrieve more information about a deployment with the -[info](/reference/airnode/latest/packages/deployer.md#info) command. Use the -deployment ID from the -[list](/reference/airnode/latest/docker/deployer-image.md#list) command above to -request information about a specific deployment. The retrieved information -include deployment's Airnode address, stage, Airnode version and the update -history. Files for cloud provider authentication are needed for the command to -run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). +Retrieve more information about a deployment with the [info](/reference/airnode/latest/packages/deployer.md#info) command. Use the deployment ID from the [list](/reference/airnode/latest/docker/deployer-image.md#list) command above to request information about a specific deployment. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -225,17 +179,7 @@ docker run -it --rm ^ ### `rollback` -To revert to a previous version of a deployment, use the -[rollback](/reference/airnode/latest/packages/deployer.md#rollback) command. -Provide the deployment ID from the -[list](/reference/airnode/latest/docker/deployer-image.md#list) command above to -specify which deployment will be changed. Also provide the desired version ID -from the [info](/reference/airnode/latest/docker/deployer-image.md#info) command -above to revert to. The -[rollback](/reference/airnode/latest/packages/deployer.md#rollback) command will -then fetch the configuration files of the specified version and deploy the -version using its configuration. Check this with the -[info](/reference/airnode/latest/docker/deployer-image.md#info) command above. +To revert to a previous version of a deployment, use the [rollback](/reference/airnode/latest/packages/deployer.md#rollback) command. Provide the deployment ID from the [list](/reference/airnode/latest/docker/deployer-image.md#list) command above to specify which deployment will be changed. Also provide the desired version ID from the [info](/reference/airnode/latest/docker/deployer-image.md#info) command above to revert to. The [rollback](/reference/airnode/latest/packages/deployer.md#rollback) command will then fetch the configuration files of the specified version and deploy the version using its configuration. Check this with the [info](/reference/airnode/latest/docker/deployer-image.md#info) command above. ::: code-group @@ -256,23 +200,7 @@ docker run -it --rm ^ ### `fetch-files` -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the -[fetch-files](/reference/airnode/latest/packages/deployer.md#fetch-files) -command to retrieve them. You need to provide the deployment ID from the -[list](/reference/airnode/latest/docker/deployer-image.md#list) command above to -specify the desired deployment. By default, the files from the latest version of -this deployment are fetched. Alternatively, you can additionally provide a -deployment version ID from the -[info](/reference/airnode/latest/docker/deployer-image.md#info) command above to -specify the desired deployment version. By default, the archive with the files -is stored in the `config` directory **within the Docker container** that is, in -the example below, mapped to your current working directory. You can change the -output directory by providing an `--output-dir` option specifying a different -directory instead. Don't forget to add a mapping for the new output directory so -you'll be able to access the files. Files for cloud provider authentication are -needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for -GCP). +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the [fetch-files](/reference/airnode/latest/packages/deployer.md#fetch-files) command to retrieve them. You need to provide the deployment ID from the [list](/reference/airnode/latest/docker/deployer-image.md#list) command above to specify the desired deployment. By default, the files from the latest version of this deployment are fetched. Alternatively, you can additionally provide a deployment version ID from the [info](/reference/airnode/latest/docker/deployer-image.md#info) command above to specify the desired deployment version. By default, the archive with the files is stored in the `config` directory **within the Docker container** that is, in the example below, mapped to your current working directory. You can change the output directory by providing an `--output-dir` option specifying a different directory instead. Don't forget to add a mapping for the new output directory so you'll be able to access the files. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -293,16 +221,7 @@ docker run -it --rm ^ ### `remove` -A deployed Airnode can be removed via the -[remove](/reference/airnode/latest/packages/deployer.md#remove) command. To -remove Airnode, use the deployment ID from the -[list](/reference/airnode/latest/docker/deployer-image.md#list) command above. -Airnode's update history, that can be seen by the -[info](/reference/airnode/latest/docker/deployer-image.md#info) command, will be -removed as well. Files for cloud provider authentication are needed for the -command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is -the recommended way to remove a deployment, but an alternative is the -`remove-with-receipt` command. +A deployed Airnode can be removed via the [remove](/reference/airnode/latest/packages/deployer.md#remove) command. To remove Airnode, use the deployment ID from the [list](/reference/airnode/latest/docker/deployer-image.md#list) command above. Airnode's update history, that can be seen by the [info](/reference/airnode/latest/docker/deployer-image.md#info) command, will be removed as well. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is the recommended way to remove a deployment, but an alternative is the `remove-with-receipt` command. ::: code-group @@ -323,12 +242,7 @@ docker run -it --rm ^ ### `remove-with-receipt` -When an Airnode was deployed using the `deploy` command, a `receipt.json` file -was created. This file is used to remove the Airnode. The -[remove-with-receipt](/reference/airnode/latest/packages/deployer.md#remove-with-receipt) -command is identical for AWS and GCP. Files for cloud provider authentication -are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` -(for GCP). +When an Airnode was deployed using the `deploy` command, a `receipt.json` file was created. This file is used to remove the Airnode. The [remove-with-receipt](/reference/airnode/latest/packages/deployer.md#remove-with-receipt) command is identical for AWS and GCP. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -349,22 +263,11 @@ docker run -it --rm ^ ## Manual Removal -Optionally you can remove an Airnode manually though it is highly recommended -that you do so using the deployer image's `remove-with-receipt` or `remove` -commands. When removing manually, you will need the Airnode's deployment ID, -`deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., -`production`). They can be found in the -[receipt.json](/reference/airnode/latest/deployment-files/receipt-json.md) file -generated when deploying the Airnode. These are included in the element name of -AWS and GCP deployed features. Airnode has a presence in several areas of both -AWS and GCP as listed below. +Optionally you can remove an Airnode manually though it is highly recommended that you do so using the deployer image's `remove-with-receipt` or `remove` commands. When removing manually, you will need the Airnode's deployment ID, `deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., `production`). They can be found in the [receipt.json](/reference/airnode/latest/deployment-files/receipt-json.md) file generated when deploying the Airnode. These are included in the element name of AWS and GCP deployed features. Airnode has a presence in several areas of both AWS and GCP as listed below. ::: danger Remember -Only delete elements of a feature with the `deploymentId` and `stage` name -contained in the element's name. There can be more than one Airnode. Example: -(airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the -deploymentId and `production` is the stage name. +Only delete elements of a feature with the `deploymentId` and `stage` name contained in the element's name. There can be more than one Airnode. Example: (airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the deploymentId and `production` is the stage name. ::: @@ -376,7 +279,6 @@ deploymentId and `production` is the stage name. -Learn more about AWS or GCP resources that Airnode uses in the -[Cloud Resources](/reference/airnode/latest/cloud-resources.md) doc. +Learn more about AWS or GCP resources that Airnode uses in the [Cloud Resources](/reference/airnode/latest/cloud-resources.md) doc. diff --git a/docs/reference/airnode/latest/docker/index.md b/docs/reference/airnode/latest/docker/index.md index 4a921f99..5998b410 100644 --- a/docs/reference/airnode/latest/docker/index.md +++ b/docs/reference/airnode/latest/docker/index.md @@ -19,31 +19,19 @@ tags: # {{$frontmatter.title}} -Using Docker is the easiest way to both deploy an Airnode to a cloud provider -and to run an Airnode locally. There are two Docker images: the Airnode deployer -image and the Airnode client image. +Using Docker is the easiest way to both deploy an Airnode to a cloud provider and to run an Airnode locally. There are two Docker images: the Airnode deployer image and the Airnode client image. -There is also a docker image wrapping the admin CLI package, as an alternative -to using `npx`. +There is also a docker image wrapping the admin CLI package, as an alternative to using `npx`. -To use these images first install [Docker](https://docs.docker.com/get-docker/) -if it is not present on your system. +To use these images first install [Docker](https://docs.docker.com/get-docker/) if it is not present on your system. -If using a Linux distribution that enforces Selinux policies, allow the Docker -images access to the host directory by -[creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). +If using a Linux distribution that enforces Selinux policies, allow the Docker images access to the host directory by [creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). -- The [deployer image](/reference/airnode/latest/docker/deployer-image.md) - deploys the node in the form of serverless functions to a serverless cloud - provider (e.g. AWS Lambda). +- The [deployer image](/reference/airnode/latest/docker/deployer-image.md) deploys the node in the form of serverless functions to a serverless cloud provider (e.g. AWS Lambda). -- The [client image](/reference/airnode/latest/docker/client-image.md) is the - node itself, containerized. The container can be run locally or deployed to a - cloud hosting service (e.g. AWS EC2 or Lightsail). +- The [client image](/reference/airnode/latest/docker/client-image.md) is the node itself, containerized. The container can be run locally or deployed to a cloud hosting service (e.g. AWS EC2 or Lightsail). -- The [admin CLI image](/reference/airnode/latest/docker/admin-cli-image.md) - wraps the admin CLI package in a docker image to provide an alternative usage - option to the Admin CLI commands (npx). +- The [admin CLI image](/reference/airnode/latest/docker/admin-cli-image.md) wraps the admin CLI package in a docker image to provide an alternative usage option to the Admin CLI commands (npx). ## DockerHub diff --git a/docs/reference/airnode/latest/index.md b/docs/reference/airnode/latest/index.md index 9cc4e72e..4e2bf669 100644 --- a/docs/reference/airnode/latest/index.md +++ b/docs/reference/airnode/latest/index.md @@ -19,17 +19,9 @@ tags: # {{$frontmatter.title}} -Use the contract addresses listed in the tables below to interact with Airnode -on EVM-compatible blockchains. Additional addresses will be added as contracts -are deployed, but feel free to -[submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a -new deployment. - -The contract addresses listed below are sourced from the Airnode monorepo -[airnode-protocol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol) -and can be found in its -[deployments](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/deployments) -directory. +Use the contract addresses listed in the tables below to interact with Airnode on EVM-compatible blockchains. Additional addresses will be added as contracts are deployed, but feel free to [submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a new deployment. + +The contract addresses listed below are sourced from the Airnode monorepo [airnode-protocol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol) and can be found in its [deployments](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/deployments) directory. ## AirnodeRrpV0 diff --git a/docs/reference/airnode/latest/migration.md b/docs/reference/airnode/latest/migration.md index 286d1e9c..b88c7ced 100644 --- a/docs/reference/airnode/latest/migration.md +++ b/docs/reference/airnode/latest/migration.md @@ -19,13 +19,11 @@ tags: # {{$frontmatter.title}} -This document describes changes to `config.json` as well as to user facing -services related to Airnode, such as airnode-deployer, airnode-admin, etc. +This document describes changes to `config.json` as well as to user facing services related to Airnode, such as airnode-deployer, airnode-admin, etc. ## Changes to `config.json` -The following assumes a valid v0.13 `config.json` file. All changes listed below -must be implemented in order to migrate to Airnode v0.14.1. +The following assumes a valid v0.13 `config.json` file. All changes listed below must be implemented in order to migrate to Airnode v0.14.1. 1. `nodeSettings.nodeVersion` @@ -51,22 +49,16 @@ Updated to "2.3.2". ## Breaking changes outside of `config.json` -The following are not expected to have an impact on users, but are listed here -for completeness. +The following are not expected to have an impact on users, but are listed here for completeness. - The OEV interface has changed in the following ways: - `api3ServerV1` has replaced `dapiServerAddress` - `templateId` has replaced `endpointId` and `encodedParameters` -- `chainNames` and `networks` are no longer exported from `references.json` of - `airnode-protocol`. +- `chainNames` and `networks` are no longer exported from `references.json` of `airnode-protocol`. - Support for `boba-avalanche` has been removed as the chain has shut down. ## New features and fixes -- In conjunction with OIS v2.3.2, there is now a version 2 of pre-processing and - post-processing. More details can be found in the - [OIS reference](/reference/ois/latest/processing.md#v2). +- In conjunction with OIS v2.3.2, there is now a version 2 of pre-processing and post-processing. More details can be found in the [OIS reference](/reference/ois/latest/processing.md#v2). - OEV gateway AWS lambda memory has been increased from 256 MB to 2048 MB -- Airnode protocol contracts have been deployed on LightLink, LightLink Goerli - Testnet, and Blast Sepolia Testnet chains. You can find the addresses on the - [Contracts page](/reference/airnode/next/index.md). +- Airnode protocol contracts have been deployed on LightLink, LightLink Goerli Testnet, and Blast Sepolia Testnet chains. You can find the addresses on the [Contracts page](/reference/airnode/next/index.md). diff --git a/docs/reference/airnode/latest/packages/adapter.md b/docs/reference/airnode/latest/packages/adapter.md index e953bc5f..a6ce3826 100644 --- a/docs/reference/airnode/latest/packages/adapter.md +++ b/docs/reference/airnode/latest/packages/adapter.md @@ -19,56 +19,36 @@ tags: # {{$frontmatter.title}} -The -[airnode-adapter](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-adapter) -package has multiple responsibilities. It is used for building requests from an -[Oracle Integration Specification (OIS)](/reference/ois/latest/), executing -them, parsing the responses, but also converting and encoding them for on chain -use. +The [airnode-adapter](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-adapter) package has multiple responsibilities. It is used for building requests from an [Oracle Integration Specification (OIS)](/reference/ois/latest/), executing them, parsing the responses, but also converting and encoding them for on chain use. -It is an internal dependency of Airnode, but can also be used standalone as an -API. +It is an internal dependency of Airnode, but can also be used standalone as an API. ## Installation -You can install `@api3/airnode-adapter` by adding it to the `package.json` file -in your project. +You can install `@api3/airnode-adapter` by adding it to the `package.json` file in your project. ```sh npm install --save @api3/airnode-adapter ``` -You shouldn't need to use the adapter package directly. However, you might want -to use its API to double check the conversion or encoding behavior for which you -can install this package and verify your assumptions. +You shouldn't need to use the adapter package directly. However, you might want to use its API to double check the conversion or encoding behavior for which you can install this package and verify your assumptions. ## Conversion -While the adapter package has many responsibilities, many of those can be -treated as implementation details. On the other hand, there are a few important -behaviors to be noted when converting the response values based on the target -type and making the response transaction on chain. +While the adapter package has many responsibilities, many of those can be treated as implementation details. On the other hand, there are a few important behaviors to be noted when converting the response values based on the target type and making the response transaction on chain. Altogether, the response cycle consists of multiple steps 1. A successful API call is made and Airnode receives a response value. -2. The value to be converted is extracted from the response using the - [\_path](/reference/ois/latest/reserved-parameters.md#path) from the OIS - object. -3. This extracted value is converted to the target type. Conversions are - performed internally by the `castValue(value, type)` function. -4. The converted value is encoded to the native solidity type based on the - [\_type](/reference/ois/latest/reserved-parameters.md#type) from the OIS - object. Encoding is performed internally by the `encodeValue(value, type)` - function. +2. The value to be converted is extracted from the response using the [\_path](/reference/ois/latest/reserved-parameters.md#path) from the OIS object. +3. This extracted value is converted to the target type. Conversions are performed internally by the `castValue(value, type)` function. +4. The converted value is encoded to the native solidity type based on the [\_type](/reference/ois/latest/reserved-parameters.md#type) from the OIS object. Encoding is performed internally by the `encodeValue(value, type)` function. -If any of the steps above fail, an error is thrown. This will fail the given API -request and the error reason can be found in the logs. +If any of the steps above fail, an error is thrown. This will fail the given API request and the error reason can be found in the logs. -The rest of this section covers the conversion logic for all of the supported -types. +The rest of this section covers the conversion logic for all of the supported types. ### `int256` or `uint256` @@ -87,8 +67,7 @@ const ERROR_VALUES = [ ]; ``` -There are a few special strings and boolean values that are convertible to -`int256` or `uint256`: +There are a few special strings and boolean values that are convertible to `int256` or `uint256`: ```ts const SPECIAL_INT_VALUES = [false, 'false', true, 'true']; @@ -98,11 +77,7 @@ console.log(values); // [0, 0, 1, 1]; ``` -Number strings and numbers will attempt to be converted to -[BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be -multiplied by the value of the -[\_times](/reference/ois/latest/reserved-parameters.md#times) parameter if it is -present. +Number strings and numbers will attempt to be converted to [BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be multiplied by the value of the [\_times](/reference/ois/latest/reserved-parameters.md#times) parameter if it is present. ```ts const VALID_INT_VALUES = ['123.456', 7777]; @@ -112,17 +87,11 @@ console.log(values); // [new BigNumber(123.456), new BigNumber(7777)]; ``` -Conversion for `int256` and `uint256` is the same - this means that `-123` can -be converted to `uint256`. However, an error will be thrown while encoding. +Conversion for `int256` and `uint256` is the same - this means that `-123` can be converted to `uint256`. However, an error will be thrown while encoding. :::warning Flooring -Beware that any floating point number will be **floored**. This is necessary, -because floating point numbers are not valid in solidity. To mitigate precision -loss, you can use the -[`_times`](/reference/ois/latest/reserved-parameters.md#times) parameter that is -sufficiently large. For example, if the API response is a USD currency, you -might want to use `_times: "100"` to convert the value to cents. +Beware that any floating point number will be **floored**. This is necessary, because floating point numbers are not valid in solidity. To mitigate precision loss, you can use the [`_times`](/reference/ois/latest/reserved-parameters.md#times) parameter that is sufficiently large. For example, if the API response is a USD currency, you might want to use `_times: "100"` to convert the value to cents. ::: @@ -145,17 +114,9 @@ All other values are converted to `true`. ### `bytes32` -There is no conversion for `bytes32` - the value is expected to be a valid hex -string representing the encoded 32 bytes value. This means that the encoding -**must** be implemented on the API side. If you want to delegate the encoding to -Airnode, see the documentation for -[`string32`](/reference/airnode/latest/packages/adapter.md#string32). +There is no conversion for `bytes32` - the value is expected to be a valid hex string representing the encoded 32 bytes value. This means that the encoding **must** be implemented on the API side. If you want to delegate the encoding to Airnode, see the documentation for [`string32`](/reference/airnode/latest/packages/adapter.md#string32). -For example, let's say the API wants to encode the following string -`simple string` with length 13. Its encoding is -0x73696d706c6520737472696e6700000000000000000000000000000000000000. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. +For example, let's say the API wants to encode the following string `simple string` with length 13. Its encoding is 0x73696d706c6520737472696e6700000000000000000000000000000000000000. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. You can use [ethers](https://docs.ethers.io/v5/) to encode these on the API side @@ -167,29 +128,16 @@ console.log(encoded); // 0x73696d706c6520737472696e67000000000000000000000000000 ### `address` -There is no conversion for `address` - the value is expected to be a string -representing a valid address. Valid examples are: +There is no conversion for `address` - the value is expected to be a string representing a valid address. Valid examples are: -- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) - of an address. -- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - - all lowercase address. +- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) of an address. +- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - all lowercase address. ### `bytes` -There is no conversion for `bytes` - the value is expected to be a valid hex -string representing the encoded value. This means that the encoding to bytes -**must** be implemented on the API side. If you want to send a string, see the -documentation for -[`string`](/reference/airnode/latest/packages/adapter.md#string). +There is no conversion for `bytes` - the value is expected to be a valid hex string representing the encoded value. This means that the encoding to bytes **must** be implemented on the API side. If you want to send a string, see the documentation for [`string`](/reference/airnode/latest/packages/adapter.md#string). -For example, let's say the API wants to encode the following string -`this is an example string that is a bit longer`. Its encoding is -0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these -on the API side. +For example, let's say the API wants to encode the following string `this is an example string that is a bit longer`. Its encoding is 0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these on the API side. ```js const value = 'this is an example string that is a bit longer'; @@ -199,9 +147,7 @@ console.log(encodedValue); // 0x7468697320697320616e206578616d706c6520737472696e ### `string` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. All other values will be converted to -`string` and before encoded on chain using the `string` type. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. All other values will be converted to `string` and before encoded on chain using the `string` type. ```js const values = [ @@ -221,20 +167,11 @@ const mappedValues = values.map((v) => { ### `string32` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. -However, there is one exception, if the stringified value contains more than 31 -characters it will be **trimmed down** to only the first 31 characters during -conversion. +However, there is one exception, if the stringified value contains more than 31 characters it will be **trimmed down** to only the first 31 characters during conversion. -For example, if the API response is the following string -`this is an example string that is a bit longer` with length 46. It will be -first trimmed to 31 characters, string `this is an example string that ` and -afterwards converted to -0x7468697320697320616e206578616d706c6520737472696e6720746861742000. -Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using -the following snippet +For example, if the API response is the following string `this is an example string that is a bit longer` with length 46. It will be first trimmed to 31 characters, string `this is an example string that ` and afterwards converted to 0x7468697320697320616e206578616d706c6520737472696e6720746861742000. Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using the following snippet ```js const encoded = @@ -245,18 +182,11 @@ console.log(decoded); // "this is an example string that " ### Arrays -Conversion of arrays depends on the primitive type. All values of the array (or -nested array) will be converted according to the rules of the primitive type. +Conversion of arrays depends on the primitive type. All values of the array (or nested array) will be converted according to the rules of the primitive type. For example: -- `int256[]` - has primitive type `int256`. All elements of this array follow - the - [`int256`](/reference/airnode/latest/packages/adapter.md#int256-or-uint256) - rules. -- `string32[7][][5]` - is a multidimensional array, where some dimensions are - fixed and some not. This is irrelevant though, and all the elements are - converted based on - [`string32`](/reference/airnode/latest/packages/adapter.md#string32) rules. +- `int256[]` - has primitive type `int256`. All elements of this array follow the [`int256`](/reference/airnode/latest/packages/adapter.md#int256-or-uint256) rules. +- `string32[7][][5]` - is a multidimensional array, where some dimensions are fixed and some not. This is irrelevant though, and all the elements are converted based on [`string32`](/reference/airnode/latest/packages/adapter.md#string32) rules. diff --git a/docs/reference/airnode/latest/packages/admin-cli.md b/docs/reference/airnode/latest/packages/admin-cli.md index 6b0c1eba..93c27dad 100644 --- a/docs/reference/airnode/latest/packages/admin-cli.md +++ b/docs/reference/airnode/latest/packages/admin-cli.md @@ -19,55 +19,26 @@ tags: # {{$frontmatter.title}} -Use the -[airnode-admin](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin) -Admin CLI tool to interact with Airnode across blockchains. There are commands -for both developers (dApp) and API providers. Developers can sponsor -[requester](/reference/airnode/latest/concepts/requester.md) contracts and -derive -[sponsorWallets](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) -for Airnodes. API providers can build -[Airnodes](/reference/airnode/latest/concepts/airnode.md) that serve their API -data to requester contracts. +Use the [airnode-admin](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin) Admin CLI tool to interact with Airnode across blockchains. There are commands for both developers (dApp) and API providers. Developers can sponsor [requester](/reference/airnode/latest/concepts/requester.md) contracts and derive [sponsorWallets](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) for Airnodes. API providers can build [Airnodes](/reference/airnode/latest/concepts/airnode.md) that serve their API data to requester contracts. ::: warning Transaction Gas Costs -Some commands will incur transaction fees. These are per call transaction gas -costs and are relatively small. See the -[Developer Fees](/reference/airnode/latest/developers/fees.md) -doc. +Some commands will incur transaction fees. These are per call transaction gas costs and are relatively small. See the [Developer Fees](/reference/airnode/latest/developers/fees.md) doc. ::: -Almost all commands require you to provide a blockchain `providerUrl`. Following -are just two examples of many possibilities. See the -[Chain Providers](/reference/airnode/latest/concepts/chain-providers.md) doc for -more information. +Almost all commands require you to provide a blockchain `providerUrl`. Following are just two examples of many possibilities. See the [Chain Providers](/reference/airnode/latest/concepts/chain-providers.md) doc for more information. - `https://eth-goerli.gateway.pokt.network/v1/lb/` - `https://sepolia.infura.io/v3/` -The CLI connects to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -or the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract, which addresses are derived from the current chain. You can optionally -specify the contract addresses yourself by providing optional -`airnode-rrp-address` or `requester-authorizer-with-airnode` command argument -with the address of the deployed contract on your targeted chain. - -Commands that require `mnemonic` will make an on-chain transaction. The -application will derive the account from the mnemonic with default ethereum -derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional -parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet -that is associated with the mnemonic is funded on the target chain. The -application will not exit until the transaction is confirmed. +The CLI connects to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) or the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract, which addresses are derived from the current chain. You can optionally specify the contract addresses yourself by providing optional `airnode-rrp-address` or `requester-authorizer-with-airnode` command argument with the address of the deployed contract on your targeted chain. + +Commands that require `mnemonic` will make an on-chain transaction. The application will derive the account from the mnemonic with default ethereum derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet that is associated with the mnemonic is funded on the target chain. The application will not exit until the transaction is confirmed. ### Using transaction overrides -CLI commands also support the following transaction overrides as optional -arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and -`max-priority-fee` (EIP-1559 transactions) and `nonce`. +CLI commands also support the following transaction overrides as optional arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and `max-priority-fee` (EIP-1559 transactions) and `nonce`. ### Default transaction overrides @@ -116,9 +87,7 @@ docker run api3/airnode-admin:0.14.1 $COMMAND --help ## SDK -You can also use the package programmatically. The SDK exports respective -functions for all CLI commands as well as helper functions for obtaining the -contract instance on the targeted chain. +You can also use the package programmatically. The SDK exports respective functions for all CLI commands as well as helper functions for obtaining the contract instance on the targeted chain. ```js import { sponsorRequester, getAirnodeRrpWithSigner } from '@api3/airnode-admin'; @@ -134,9 +103,7 @@ const airnodeRrp = await getAirnodeRrpWithSigner( const requester = await sponsorRequester(airnodeRrp, requester); ``` -If you plan to use multiple commands it might be tedious to pass the contract -instance to every function call. For this reason there is also class based -`AdminSdk` which you initialize with `AirnodeRrp` contract only once. +If you plan to use multiple commands it might be tedious to pass the contract instance to every function call. For this reason there is also class based `AdminSdk` which you initialize with `AirnodeRrp` contract only once. ```js import { AdminSdk } from '@api3/airnode-admin'; @@ -158,14 +125,11 @@ const requester = await adminSdk.sponsorRequester(requester); adminSdk.airnodeRrp = airnodeRrp.connect(someOtherWallet); ``` -The SDK will also provide TS typings out of the box. Please, refer to the -implementation for more details. +The SDK will also provide TS typings out of the box. Please, refer to the implementation for more details. ### Using transaction overrides -You can also use transaction overrides to customize gas limits and fee settings. -The SDK simply passes the overrides parameter to the contract method so you can -use any overrides supported by the ethers library. +You can also use transaction overrides to customize gas limits and fee settings. The SDK simply passes the overrides parameter to the contract method so you can use any overrides supported by the ethers library. ```js import { ethers } from 'ethers'; @@ -189,14 +153,7 @@ const requester = await adminSdk.sponsorRequester(requester, overrides); ## Sponsors -Commands related to a [sponsor's](/reference/airnode/latest/concepts/sponsor.md) -relationships between -[requesters](/reference/airnode/latest/concepts/requester.md) and -[sponsorWallets](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) as -well as [templates](/reference/airnode/latest/concepts/template.md) used by a -sponsor's requesters. Some of these commands connect to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract where the signer is sponsor account. +Commands related to a [sponsor's](/reference/airnode/latest/concepts/sponsor.md) relationships between [requesters](/reference/airnode/latest/concepts/requester.md) and [sponsorWallets](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) as well as [templates](/reference/airnode/latest/concepts/template.md) used by a sponsor's requesters. Some of these commands connect to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract where the signer is sponsor account. - [sponsor-requester](/reference/airnode/latest/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/latest/packages/admin-cli.md#unsponsor-requester) @@ -211,39 +168,19 @@ protocol contract where the signer is sponsor account. ### `sponsor-requester` -[Sponsors](/reference/airnode/latest/concepts/sponsor.md) a -[requester](/reference/airnode/latest/concepts/requester.md) contract so that -its requests can be fulfilled by the -[sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) of -an Airnode. The account derived from the `mnemonic` you provide must belong to -the sponsor. +[Sponsors](/reference/airnode/latest/concepts/sponsor.md) a [requester](/reference/airnode/latest/concepts/requester.md) contract so that its requests can be fulfilled by the [sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) of an Airnode. The account derived from the `mnemonic` you provide must belong to the sponsor. -Sponsoring a requester and using the returned `sponsorAddress` to derive a -`sponsorWallet` for an Airnode creates a -[relationship](/reference/airnode/latest/concepts/sponsor.md) between the -requester and the Airnode, see the -[`derive-sponsor-wallet-address`](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Sponsoring a requester and using the returned `sponsorAddress` to derive a `sponsorWallet` for an Airnode creates a [relationship](/reference/airnode/latest/concepts/sponsor.md) between the requester and the Airnode, see the [`derive-sponsor-wallet-address`](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a - `sponsorAddress` as the default account of the mnemonic unless a - `derivation-path` is specified. It's also used to pay gas costs from the - mnemonic's default account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a `sponsorAddress` as the default account of the mnemonic unless a `derivation-path` is specified. It's also used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to sponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. If this parameter is not provided, it will be deduced from - the current chain. If there is no RRP address found for the given chain an - error is thrown. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. If this parameter is not provided, it will be deduced from the current chain. If there is no RRP address found for the given chain an error is thrown. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -266,29 +203,17 @@ npx @api3/airnode-admin sponsor-requester ^ ### `unsponsor-requester` -Removes the sponsorship of a -[requester](/reference/airnode/latest/concepts/requester.md) contract so that -its requests can no longer be fulfilled by the -[sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). -The account derived from the `mnemonic` you provide here has to belong to the -sponsor. +Removes the sponsorship of a [requester](/reference/airnode/latest/concepts/requester.md) contract so that its requests can no longer be fulfilled by the [sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). The account derived from the `mnemonic` you provide here has to belong to the sponsor. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used - to sponsor the requester. Used to pay gas costs from the mnemonic's default - account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used to sponsor the requester. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to unsponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -311,17 +236,12 @@ npx @api3/airnode-admin unsponsor-requester ^ ### `get-sponsor-status` -Returns the sponsor status for a given -[sponsor](/reference/airnode/latest/concepts/sponsor.md) and -[requester](/reference/airnode/latest/concepts/requester.md) (`true` if -sponsored, `false` otherwise). +Returns the sponsor status for a given [sponsor](/reference/airnode/latest/concepts/sponsor.md) and [requester](/reference/airnode/latest/concepts/requester.md) (`true` if sponsored, `false` otherwise). - `provider-url`: A valid blockchain provider URL. -- `sponsor-address`: The `sponsorAddress` returned when the requester was - sponsored. +- `sponsor-address`: The `sponsorAddress` returned when the requester was sponsored. - `requester-address`: The requester contract address. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -343,16 +263,9 @@ npx @api3/airnode-admin get-sponsor-status ^ ### `derive-sponsor-wallet-address` -Derives the address of the wallet designated by an Airnode for a -[sponsor](/reference/airnode/latest/concepts/sponsor.md), which is called the -[sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). -This command will error if `airnode-xpub` does not belong to the HDNode with the -path `m/44'/60'/0'` of the Airnode wallet. See the -[`derive-airnode-xpub`](/reference/airnode/latest/packages/admin-cli.md#derive-airnode-xpub) -command. +Derives the address of the wallet designated by an Airnode for a [sponsor](/reference/airnode/latest/concepts/sponsor.md), which is called the [sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). This command will error if `airnode-xpub` does not belong to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. See the [`derive-airnode-xpub`](/reference/airnode/latest/packages/admin-cli.md#derive-airnode-xpub) command. -- `airnode-xpub`: The extended public address of the Airnode for path - `m/44'/60'/0'`. +- `airnode-xpub`: The extended public address of the Airnode for path `m/44'/60'/0'`. - `airnode-address`: The public address of the Airnode. - `sponsor-address`: The address of the sponsor account. @@ -376,27 +289,17 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ### `create-template` -Reads a file, uses its contents to create a -[template](/reference/airnode/latest/concepts/template.md) and returns a -`template-id`. Also see -[Using Templates](/reference/airnode/latest/developers/using-templates.md) for -an example template file. +Reads a file, uses its contents to create a [template](/reference/airnode/latest/concepts/template.md) and returns a `template-id`. Also see [Using Templates](/reference/airnode/latest/developers/using-templates.md) for an example template file. - `provider-url`: A valid blockchain provider URL. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `template-file-path`: Path to the template file to create on-chain. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -419,20 +322,11 @@ npx @api3/airnode-admin create-template ^ ### `create-inline-template` -It is possible to inline Airnode templates inside config.json in a `templates` -section. These templates need to be published on chain, but inlining them inside -config provides more clarity which templates can be used for template requests -and also saves a blockchain call . +It is possible to inline Airnode templates inside config.json in a `templates` section. These templates need to be published on chain, but inlining them inside config provides more clarity which templates can be used for template requests and also saves a blockchain call . -The command reads a template file, uses its contents to create a -[template](/reference/airnode/latest/concepts/template.md) and returns the data -necessary to inline the template inside config. See -[Using Templates](/reference/airnode/latest/developers/using-templates.md) for -an example template file. +The command reads a template file, uses its contents to create a [template](/reference/airnode/latest/concepts/template.md) and returns the data necessary to inline the template inside config. See [Using Templates](/reference/airnode/latest/developers/using-templates.md) for an example template file. -This command does **not** create a template on chain. Be sure to use the -[create-template](/reference/airnode/latest/packages/admin-cli.md#create-template) -command on chain before making template requests. +This command does **not** create a template on chain. Be sure to use the [create-template](/reference/airnode/latest/packages/admin-cli.md#create-template) command on chain before making template requests. - `template-file-path`: Path to the template file to create on-chain. @@ -452,13 +346,11 @@ npx @api3/airnode-admin create-inline-template ^ ### `get-template` -Returns the [template](/reference/airnode/latest/concepts/template.md) for the -given `template-id`. +Returns the [template](/reference/airnode/latest/concepts/template.md) for the given `template-id`. - `provider-url`: A valid blockchain provider URL. - `template-id`: The id of a template to return. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -478,50 +370,28 @@ npx @api3/airnode-admin get-template ^ ### `request-withdrawal` -Requests a -[withdrawal](/reference/airnode/latest/concepts/sponsor.md#withdrawals) from a -[sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) -managed by an Airnode. +Requests a [withdrawal](/reference/airnode/latest/concepts/sponsor.md#withdrawals) from a [sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) managed by an Airnode. -The funds will be returned to the account derived from the `sponsor-mnemonic`. -This account must belong to a -[sponsor](/reference/airnode/latest/concepts/sponsor.md) for the specified -[sponsor wallet address](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) -in the command. +The funds will be returned to the account derived from the `sponsor-mnemonic`. This account must belong to a [sponsor](/reference/airnode/latest/concepts/sponsor.md) for the specified [sponsor wallet address](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) in the command. -After the request is made, it needs to be fulfilled by Airnode, so the return -value of this command is only a `withdrawal-request-id` which you can use to -call -[check-withdrawal-request](/reference/airnode/latest/packages/admin-cli.md#check-withdrawal-request) -to see whether the request was processed or not. +After the request is made, it needs to be fulfilled by Airnode, so the return value of this command is only a `withdrawal-request-id` which you can use to call [check-withdrawal-request](/reference/airnode/latest/packages/admin-cli.md#check-withdrawal-request) to see whether the request was processed or not. ::: warning Withdrawal Priority -Airnode will drop any pending API calls associated with a `sponsorWallet` once a -withdrawal is requested. +Airnode will drop any pending API calls associated with a `sponsorWallet` once a withdrawal is requested. ::: - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from - the mnemonic's default account unless a `derivation-path` is specified. - Withdrawn funds will be added to this mnemonic's default address unless a - `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. Withdrawn funds will be added to this mnemonic's default address unless a `derivation-path` is specified. - `airnode-address`: The public address of the Airnode. -- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw - from. This address was returned by the `derive-sponsor-wallet-address` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)` : The destination address of the `mnemonic` - parameter to add the withdrawn funds to if the default address is not desired. +- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw from. This address was returned by the `derive-sponsor-wallet-address` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)` : The destination address of the `mnemonic` parameter to add the withdrawn funds to if the default address is not desired. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -546,17 +416,11 @@ npx @api3/airnode-admin request-withdrawal ^ ### `check-withdrawal-request` -Checks the status of the -[withdrawal](/reference/airnode/latest/concepts/sponsor.md#withdrawals) request -with the given `withdrawal-request-id` from the -[request withdrawal command](/reference/airnode/latest/packages/admin-cli.md#request-withdrawal) -above. +Checks the status of the [withdrawal](/reference/airnode/latest/concepts/sponsor.md#withdrawals) request with the given `withdrawal-request-id` from the [request withdrawal command](/reference/airnode/latest/packages/admin-cli.md#request-withdrawal) above. - `provider-url`: A valid blockchain provider URL. -- `withdrawal-request-id`: This id was returned by the `request-withdrawal` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `withdrawal-request-id`: This id was returned by the `request-withdrawal` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -576,16 +440,7 @@ npx @api3/airnode-admin check-withdrawal-request ^ ### `verify-airnode-xpub` -Verifies that the `airnode-xpub` belongs to the HDNode with the path -`m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode -address can be derived with provided Airnode -[xpub](/reference/airnode/latest/concepts/airnode.md#xpub) with default -derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. -This command will most likely be used by a -[sponsor](/reference/airnode/latest/concepts/sponsor.md) to verify that the xpub -belongs to the Airnode before calling the -[derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Verifies that the `airnode-xpub` belongs to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode address can be derived with provided Airnode [xpub](/reference/airnode/latest/concepts/airnode.md#xpub) with default derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. This command will most likely be used by a [sponsor](/reference/airnode/latest/concepts/sponsor.md) to verify that the xpub belongs to the Airnode before calling the [derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) command. ::: code-group @@ -605,9 +460,7 @@ npx @api3/airnode-admin verify-airnode-xpub ^ ## Airnodes -Helper commands for a previously deployed Airnode. Some of these commands -connect to the AirnodeRrpV0.sol protocol contract where the signer must be the -Airnode wallet. +Helper commands for a previously deployed Airnode. Some of these commands connect to the AirnodeRrpV0.sol protocol contract where the signer must be the Airnode wallet. - [derive-airnode-xpub](/reference/airnode/latest/packages/admin-cli.md#derive-airnode-xpub) - [derive-endpoint-id](/reference/airnode/latest/packages/admin-cli.md#derive-endpoint-id) @@ -616,13 +469,7 @@ Airnode wallet. ### `derive-airnode-xpub` -Derives the Airnode extended public key -([xpub](/reference/airnode/latest/concepts/airnode.md#xpub)). This xpub must be -announced via off-chain channels because it will be needed to derive a -[sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) -address. See the -[derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Derives the Airnode extended public key ([xpub](/reference/airnode/latest/concepts/airnode.md#xpub)). This xpub must be announced via off-chain channels because it will be needed to derive a [sponsorWallet](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet) address. See the [derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `airnode-mnemonic`: The Airnode mnemonic for which the xpub is to be derived. @@ -640,15 +487,10 @@ npx @api3/airnode-admin derive-airnode-xpub --airnode-mnemonic "nature about sal ### `derive-endpoint-id` -Derives an -[endpointId](/reference/airnode/latest/deployment-files/config-json.md#triggers) -from the OIS title and the endpoint's name as described in the -[endpoint](/reference/airnode/latest/concepts/endpoint.md) documentation. Add -the `endpointId` to the config.json file (`triggers.rrp[n].endpointId`). +Derives an [endpointId](/reference/airnode/latest/deployment-files/config-json.md#triggers) from the OIS title and the endpoint's name as described in the [endpoint](/reference/airnode/latest/concepts/endpoint.md) documentation. Add the `endpointId` to the config.json file (`triggers.rrp[n].endpointId`). - `ois-title`: The title of the OIS from config.json (`ois.title`). -- `endpoint-name`: The name of the endpoint from config.json - (`triggers.rrp[n].endpointName`). +- `endpoint-name`: The name of the endpoint from config.json (`triggers.rrp[n].endpointName`). ::: code-group @@ -668,12 +510,7 @@ npx @api3/airnode-admin derive-endpoint-id ^ ### `generate-airnode-mnemonic` -Generates a unique mnemonic which can be used to create an -[airnode wallet](/reference/airnode/latest/concepts/airnode.md#mnemonic). In -addition to the mnemonic, this command will also display the corresponding -[airnode address](/reference/airnode/latest/concepts/airnode.md#airnodeaddress) -and its extended public key -([xpub](/reference/airnode/latest/concepts/airnode.md#xpub)). +Generates a unique mnemonic which can be used to create an [airnode wallet](/reference/airnode/latest/concepts/airnode.md#mnemonic). In addition to the mnemonic, this command will also display the corresponding [airnode address](/reference/airnode/latest/concepts/airnode.md#airnodeaddress) and its extended public key ([xpub](/reference/airnode/latest/concepts/airnode.md#xpub)). ```sh npx @api3/airnode-admin generate-airnode-mnemonic @@ -681,9 +518,7 @@ npx @api3/airnode-admin generate-airnode-mnemonic ### `generate-mnemonic` -Generates a unique mnemonic which can be used to create a wallet. In addition to -the mnemonic, this command will also display the corresponding default wallet -(path:m/44'/60'/0'/0/0) address. +Generates a unique mnemonic which can be used to create a wallet. In addition to the mnemonic, this command will also display the corresponding default wallet (path:m/44'/60'/0'/0/0) address. ```sh npx @api3/airnode-admin generate-mnemonic @@ -691,12 +526,7 @@ npx @api3/airnode-admin generate-mnemonic ### `derive-airnode-address` -Derives the -[airnode address](/reference/airnode/latest/concepts/airnode.md#airnodeaddress) -which is the identifier of the particular Airnode on chain. The address is the -default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this -identifier for many other admin CLI commands, such as -[derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address). +Derives the [airnode address](/reference/airnode/latest/concepts/airnode.md#airnodeaddress) which is the identifier of the particular Airnode on chain. The address is the default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this identifier for many other admin CLI commands, such as [derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address). - `airnode-mnemonic`: A mnemonic used to generate the airnode address. @@ -716,18 +546,11 @@ npx @api3/airnode-admin derive-airnode-address ^ ## RequesterAuthorizerWithAirnode -RequesterAuthorizerWithAirnode contract was written by API3 as an -[authorizer](/reference/airnode/latest/concepts/authorizers.md) contract that -can be used by any Airnode. Airnode owners can use this contract in addition to -authorizer contracts they have written themselves. +RequesterAuthorizerWithAirnode contract was written by API3 as an [authorizer](/reference/airnode/latest/concepts/authorizers.md) contract that can be used by any Airnode. Airnode owners can use this contract in addition to authorizer contracts they have written themselves. -This authorizer contract can whitelist -[requesters](/reference/airnode/latest/concepts/requester.md) where each Airnode -is administered by themselves. +This authorizer contract can whitelist [requesters](/reference/airnode/latest/concepts/requester.md) where each Airnode is administered by themselves. -These commands connect to the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract. +These commands connect to the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract. - [set-whitelist-expiration](/reference/airnode/latest/packages/admin-cli.md#set-whitelist-expiration) - [extend-whitelist-expiration](/reference/airnode/latest/packages/admin-cli.md#extend-whitelist-expiration) @@ -737,32 +560,20 @@ contract. ### `set-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration setter to set the -whitelisting expiration of a requester for the Airnode–endpoint pair. This can -hasten expiration in the case the new expiration timestamp is prior to a -previously set timestamp. +Called by the Airnode wallet or a whitelist expiration setter to set the whitelisting expiration of a requester for the Airnode–endpoint pair. This can hasten expiration in the case the new expiration timestamp is prior to a previously set timestamp. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. The mnemonic must be at least an Admin or - Airnode wallet. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -791,31 +602,20 @@ npx @api3/airnode-admin set-whitelist-expiration ^ ### `extend-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration extender to extend the -whitelist expiration of a requester for the Airnode–endpoint pair. This command -expects that the new expiration timestamp is later then the previously set -timestamp. +Called by the Airnode wallet or a whitelist expiration extender to extend the whitelist expiration of a requester for the Airnode–endpoint pair. This command expects that the new expiration timestamp is later then the previously set timestamp. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -844,34 +644,21 @@ npx @api3/airnode-admin extend-whitelist-expiration ^ ### `set-indefinite-whitelist-status` -Called by the Airnode wallet or an indefinite whitelister to whitelist a -requester indefinitely for the Airnode–endpoint pair. This command can be used -to make whitelisting permanent in cases where it is needed to allow requests -even beyond the expiration period. +Called by the Airnode wallet or an indefinite whitelister to whitelist a requester indefinitely for the Airnode–endpoint pair. This command can be used to make whitelisting permanent in cases where it is needed to allow requests even beyond the expiration period. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. The default address of - the mnemonic will be used unless a derivation-path is provided. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. The default address of the mnemonic will be used unless a derivation-path is provided. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. -- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be - whitelisted indefinitely or not. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. +- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be whitelisted indefinitely or not. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -900,17 +687,13 @@ npx @api3/airnode-admin set-indefinite-whitelist-status ^ ### `get-whitelist-status` -Called to get the detailed whitelist status of a requester for the -Airnode–endpoint pair. +Called to get the detailed whitelist status of a requester for the Airnode–endpoint pair. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. ::: code-group @@ -938,9 +721,7 @@ Called to check if a requester is whitelisted to use the Airnode–endpoint pair - `provider-url`: A valid blockchain provider URL. - `requester-authorizer-with-airnode`: The authorizer contract address. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/latest/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. @@ -968,8 +749,6 @@ npx @api3/airnode-admin is-requester-whitelisted ^ ## More Examples -You can find more examples in the -[test directory](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin/test) -of the `@api3-dao/airnode/package/admin` repo. +You can find more examples in the [test directory](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin/test) of the `@api3-dao/airnode/package/admin` repo. diff --git a/docs/reference/airnode/latest/packages/airnode-abi.md b/docs/reference/airnode/latest/packages/airnode-abi.md index dc80c131..5f35d29b 100644 --- a/docs/reference/airnode/latest/packages/airnode-abi.md +++ b/docs/reference/airnode/latest/packages/airnode-abi.md @@ -19,28 +19,15 @@ tags: # {{$frontmatter.title}} -The -[airnode-abi](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-abi) -package is a unique way to encode and decode parameters for use with Airnode. -Parameters are provided with encoding types, names and values. The types are -shortened and grouped with a version as the "header". The name/value pairs are -then grouped and encoded as the rest of the body. - -An advantage of encoding parameters this way is that parameters can be decoded -natively using the language(s) of the specific blockchain. In the case of EVM -blockchains, this means that parameters can be encoded as well as decoded in -Solidity (or Vyper), without any additional requirements. - -You can find additional documentation in -[Airnode ABI Specifications](/reference/airnode/latest/specifications/airnode-abi.md) -doc. +The [airnode-abi](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-abi) package is a unique way to encode and decode parameters for use with Airnode. Parameters are provided with encoding types, names and values. The types are shortened and grouped with a version as the "header". The name/value pairs are then grouped and encoded as the rest of the body. + +An advantage of encoding parameters this way is that parameters can be decoded natively using the language(s) of the specific blockchain. In the case of EVM blockchains, this means that parameters can be encoded as well as decoded in Solidity (or Vyper), without any additional requirements. + +You can find additional documentation in [Airnode ABI Specifications](/reference/airnode/latest/specifications/airnode-abi.md) doc. ## Installation -You can install -[@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) -with -[npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) +You can install [@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) with [npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) ```sh # npm @@ -53,16 +40,13 @@ npm install --save @api3/airnode-abi Accepts an array of objects with the following required keys: -1. `type` - The full list of accepted types can be found in the - [Airnode ABI](/reference/airnode/latest/specifications/airnode-abi.md#type-encodings) - specifications doc. +1. `type` - The full list of accepted types can be found in the [Airnode ABI](/reference/airnode/latest/specifications/airnode-abi.md#type-encodings) specifications doc. 2. `name` 3. `value` -It is important to note that numeric values (`int256` and `uint256`) should be -submitted as **strings** in order to preserve precision. +It is important to note that numeric values (`int256` and `uint256`) should be submitted as **strings** in order to preserve precision. ```ts import { encode } from '@api3/airnode-abi'; @@ -79,11 +63,9 @@ console.log(encodedData); ## `decode` -Returns an object where the keys are the "names" and the values are the "values" -from the initial encoding. +Returns an object where the keys are the "names" and the values are the "values" from the initial encoding. -It is important to note that `int256` and `uint256` will be decoded back to -strings. +It is important to note that `int256` and `uint256` will be decoded back to strings. ```ts import { decode } from '@api3/airnode-abi'; diff --git a/docs/reference/airnode/latest/packages/deployer.md b/docs/reference/airnode/latest/packages/deployer.md index 4a7bf09f..195b7583 100644 --- a/docs/reference/airnode/latest/packages/deployer.md +++ b/docs/reference/airnode/latest/packages/deployer.md @@ -19,22 +19,11 @@ tags: # {{$frontmatter.title}} -The -[airnode-deployer](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer) -package is used primarily by the -[Docker Images](/reference/airnode/latest/docker/). This CLI tool provides the -underlying commands used by the Docker images when deploying an Airnode. API -providers are strongly encouraged to use the -[Docker Images](/reference/airnode/latest/docker/) when deploying an Airnode and -not the deployer CLI commands. +The [airnode-deployer](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer) package is used primarily by the [Docker Images](/reference/airnode/latest/docker/). This CLI tool provides the underlying commands used by the Docker images when deploying an Airnode. API providers are strongly encouraged to use the [Docker Images](/reference/airnode/latest/docker/) when deploying an Airnode and not the deployer CLI commands. ## Usage -The deployer's commands can be run using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), -installing a global npm package or by manually building the airnode-deployer -package. Using npx is the simplest method to interact with the deployer manually -if you do not wish to use the Docker images. +The deployer's commands can be run using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), installing a global npm package or by manually building the airnode-deployer package. Using npx is the simplest method to interact with the deployer manually if you do not wish to use the Docker images. - [Using npx](/reference/airnode/latest/packages/deployer.md#using-npx) - [Global Package](/reference/airnode/latest/packages/deployer.md#global-package) @@ -42,9 +31,7 @@ if you do not wish to use the Docker images. ### Using npx -The airnode-deployer package can be run as an npm package using npx. This allows -you to run deployer commands without installing the deployer npm package or -having to manually build the airnode-deployer package yourself. +The airnode-deployer package can be run as an npm package using npx. This allows you to run deployer commands without installing the deployer npm package or having to manually build the airnode-deployer package yourself. ```sh npx @api3/airnode-deployer deploy \ @@ -117,27 +104,18 @@ cp config/secrets.env.example config/secrets.env ## Credentials -When using the `airnode-deployer` Docker image, AWS or GCP credentials are -loaded automatically. Conversely, when using the deployer CLI directly, you will -need to first load AWS or GCP credentials into the environment manually as -described below. +When using the `airnode-deployer` Docker image, AWS or GCP credentials are loaded automatically. Conversely, when using the deployer CLI directly, you will need to first load AWS or GCP credentials into the environment manually as described below. ### AWS Credentials For AWS, there are two options: -1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` - (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their - appropriate values. -2. Populate the AWS `credentials` file. See the AWS documentation for the - [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) - as well as its - [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). +1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their appropriate values. +2. Populate the AWS `credentials` file. See the AWS documentation for the [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) as well as its [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). ### GCP Credentials -Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of -the `gcp.json` credentials file. +Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the `gcp.json` credentials file. ## Commands @@ -150,33 +128,20 @@ the `gcp.json` credentials file. ### Airnode Deployment -When creating or updating an Airnode the `config.json` and `secrets.env` files -are needed. You can use the provided example -[config.json](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/config.example.json) -and -[secrets.env](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/secrets.example.env) -templates to get started quickly, but you will need to edit these with your own -API details and secrets. +When creating or updating an Airnode the `config.json` and `secrets.env` files are needed. You can use the provided example [config.json](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/config.example.json) and [secrets.env](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/secrets.example.env) templates to get started quickly, but you will need to edit these with your own API details and secrets. -Make sure `config.json` and `secrets.env` are available in the path for the -`--configuration` argument. +Make sure `config.json` and `secrets.env` are available in the path for the `--configuration` argument. #### deploy -When executed, the `deploy` command defaults to creating a `receipt.json` file -in the `config/` directory, although a different path can be specified using the -path and name with the `--receipt` argument. The receipt contains metadata about -the deployment and can be used to remove the Airnode. +When executed, the `deploy` command defaults to creating a `receipt.json` file in the `config/` directory, although a different path can be specified using the path and name with the `--receipt` argument. The receipt contains metadata about the deployment and can be used to remove the Airnode. -By default the deployer will save logs into the `config/logs/` directory. This -can be changed with the `--logs` argument. +By default the deployer will save logs into the `config/logs/` directory. This can be changed with the `--logs` argument. -If the deployment isn't successful, the command will try to automatically remove -deployed resources. You can disable this by running the deploy command with a -`--no-auto-remove` argument. +If the deployment isn't successful, the command will try to automatically remove deployed resources. You can disable this by running the deploy command with a `--no-auto-remove` argument. ```bash # Deploys an Airnode instance using the config.json and @@ -204,19 +169,15 @@ airnode-deployer deploy \ --logs config/logs/ ``` -See how [deploy](/reference/airnode/latest/docker/deployer-image.md#deploy) is -used via the AWS/GCP deployer image. +See how [deploy](/reference/airnode/latest/docker/deployer-image.md#deploy) is used via the AWS/GCP deployer image. ### Listing Airnodes -Once you've already deployed one or more Airnode, you can list your currently -deployed instances using the `list` command. +Once you've already deployed one or more Airnode, you can list your currently deployed instances using the `list` command. #### list -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ```bash # Lists deployed Airnode instances @@ -236,14 +197,11 @@ airnode-deployer list airnode-deployer list --cloud-providers gcp ``` -See how [list](/reference/airnode/latest/docker/deployer-image.md#list) is used -via the AWS/GCP deployer image. +See how [list](/reference/airnode/latest/docker/deployer-image.md#list) is used via the AWS/GCP deployer image. ### Fetching deployment information -You can use the `info` command to retrieve information about existing -deployments. The retrieved information include deployment's Airnode address, -stage, Airnode version and the update history. +You can use the `info` command to retrieve information about existing deployments. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. #### info @@ -263,8 +221,7 @@ Options: airnode-deployer info aws2c6ef2b3 ``` -See how [info](/reference/airnode/latest/docker/deployer-image.md#info) is used -via the AWS/GCP deployer image. +See how [info](/reference/airnode/latest/docker/deployer-image.md#info) is used via the AWS/GCP deployer image. ### Reverting to a previous version @@ -291,14 +248,11 @@ Options: airnode-deployer rollback aws808e2a22 5bbcd317 ``` -See how [rollback](/reference/airnode/latest/docker/deployer-image.md#rollback) -is used via the AWS/GCP deployer image. +See how [rollback](/reference/airnode/latest/docker/deployer-image.md#rollback) is used via the AWS/GCP deployer image. ### Fetching deployment files -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the `fetch-files` command to -retrieve them. +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the `fetch-files` command to retrieve them. #### fetch-files @@ -317,19 +271,14 @@ Options: airnode-deployer fetch-files aws2c6ef2b3 ``` -See how -[fetch-files](/reference/airnode/latest/docker/deployer-image.md#fetch-files) is -used via the AWS/GCP deployer image. +See how [fetch-files](/reference/airnode/latest/docker/deployer-image.md#fetch-files) is used via the AWS/GCP deployer image. ### Airnode Removal An Airnode can be removed in two different ways: -- **Best:** With `remove`, which uses the deployment ID found either in the - [deployment receipt file](/reference/airnode/latest/deployment-files/receipt-json.md) - or via the `list` command. -- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt - created when the Airnode was deployed. +- **Best:** With `remove`, which uses the deployment ID found either in the [deployment receipt file](/reference/airnode/latest/deployment-files/receipt-json.md) or via the `list` command. +- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt created when the Airnode was deployed. #### remove @@ -349,8 +298,7 @@ Options: airnode-deployer remove aws2c6ef2b3 ``` -See how [remove](/reference/airnode/latest/docker/deployer-image.md#remove) is -used via the AWS/GCP deployer image. +See how [remove](/reference/airnode/latest/docker/deployer-image.md#remove) is used via the AWS/GCP deployer image. #### remove-with-receipt @@ -373,8 +321,6 @@ airnode-deployer remove-with-receipt \ --logs config/logs/ ``` -See how -[remove-with-receipt](/reference/airnode/latest/docker/deployer-image.md#remove-with-receipt) -is used via the AWS/GCP deployer image. +See how [remove-with-receipt](/reference/airnode/latest/docker/deployer-image.md#remove-with-receipt) is used via the AWS/GCP deployer image. diff --git a/docs/reference/airnode/latest/packages/index.md b/docs/reference/airnode/latest/packages/index.md index 18261747..e673dab9 100644 --- a/docs/reference/airnode/latest/packages/index.md +++ b/docs/reference/airnode/latest/packages/index.md @@ -19,13 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode is a fully-serverless oracle node that is designed specifically for API -providers to operate their own oracles. Its code base is a monorepo managed -using [Lerna](https://github.com/lerna/lerna). The -[Airnode monorepo](https://github.com/api3dao/airnode/blob/v0.14/packages) has -several packages. Some of these packages are used by dApp developers and API -providers to interact with or to build Airnode. A few are simply used for -internal Airnode development. +Airnode is a fully-serverless oracle node that is designed specifically for API providers to operate their own oracles. Its code base is a monorepo managed using [Lerna](https://github.com/lerna/lerna). The [Airnode monorepo](https://github.com/api3dao/airnode/blob/v0.14/packages) has several packages. Some of these packages are used by dApp developers and API providers to interact with or to build Airnode. A few are simply used for internal Airnode development. - [airnode-adapter](/reference/airnode/latest/packages/adapter.md) - [airnode-admin](/reference/airnode/latest/packages/admin-cli.md) @@ -36,49 +30,30 @@ internal Airnode development. **Read about each package in the monorepo.** -Airnode packages are cross platform, available as npm packages or docker -containers. You should also be able to clone, build and use the packages on any -platform. However there is no guarantee that the development only features (e.g. -test or examples) will work out of the box. It is recommend to use UNIX based -systems for development. If you are using Windows, consider -[WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). +Airnode packages are cross platform, available as npm packages or docker containers. You should also be able to clone, build and use the packages on any platform. However there is no guarantee that the development only features (e.g. test or examples) will work out of the box. It is recommend to use UNIX based systems for development. If you are using Windows, consider [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). -- [airnode-adapter:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-adapter) - The module that makes an API call, processes the response and returns a single - value. +- [airnode-adapter:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-adapter) The module that makes an API call, processes the response and returns a single value. -- [airnode-admin:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin) - A package/CLI tool to interact with the Airnode contracts across chains. +- [airnode-admin:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-admin) A package/CLI tool to interact with the Airnode contracts across chains. -- [airnode-abi:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-abi) - Encoding and decoding utilities for Airnode according to the - [Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md). +- [airnode-abi:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-abi) Encoding and decoding utilities for Airnode according to the [Airnode ABI specifications](/reference/airnode/latest/specifications/airnode-abi.md). -- [airnode-deployer:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer) - Tools to automate Airnode deployment. +- [airnode-deployer:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer) Tools to automate Airnode deployment. -- [airnode-examples:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples) - A public list of examples showcasing the features of Airnode. +- [airnode-examples:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples) A public list of examples showcasing the features of Airnode. -- [airnode-node:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-node) - The node part of Airnode that allows for connecting multiple blockchains to - the rest of the world. +- [airnode-node:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-node) The node part of Airnode that allows for connecting multiple blockchains to the rest of the world. -- [airnode-operation:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-operation) - Development and testing utilities for the core parts of Airnode. +- [airnode-operation:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-operation) Development and testing utilities for the core parts of Airnode. -- [**airnode-protocol**:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol) - Contracts that implement Airnode RRP (request–response protocol). +- [**airnode-protocol**:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol) Contracts that implement Airnode RRP (request–response protocol). -- [airnode-validator:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-validator) - A package that can be used to validate Airnode configuration. +- [airnode-validator:](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-validator) A package that can be used to validate Airnode configuration. ## OIS -The `airnode-ois` monorepo package was removed from the Airnode repo and is now -in its own repo (`ois`) starting with Airnode `v0.8`. +The `airnode-ois` monorepo package was removed from the Airnode repo and is now in its own repo (`ois`) starting with Airnode `v0.8`. -- [ois:](https://github.com/api3dao/ois/tree/v2.3.2) Types for - [Oracle Integration Specification (OIS)](/reference/ois/latest/specification.md). +- [ois:](https://github.com/api3dao/ois/tree/v2.3.2) Types for [Oracle Integration Specification (OIS)](/reference/ois/latest/specification.md). diff --git a/docs/reference/airnode/latest/packages/validator.md b/docs/reference/airnode/latest/packages/validator.md index daf9b812..6e7e3c9b 100644 --- a/docs/reference/airnode/latest/packages/validator.md +++ b/docs/reference/airnode/latest/packages/validator.md @@ -19,26 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-validator](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-validator) -is used internally by the [Docker Images](/reference/airnode/latest/docker/) to -validate the -[configuration files](/reference/airnode/latest/understand/configuring.md) you -provide when deploying an Airnode. - -However, validator can also be used as a standalone package to verify the -correctness of the configuration files without deploying the Airnode. The -recommended way is to use the -[validator CLI](/reference/airnode/latest/packages/validator.md#cli-usage), but -for advanced use cases you can use the -[validator SDK](/reference/airnode/latest/packages/validator.md#sdk-usage). +The [airnode-validator](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-validator) is used internally by the [Docker Images](/reference/airnode/latest/docker/) to validate the [configuration files](/reference/airnode/latest/understand/configuring.md) you provide when deploying an Airnode. + +However, validator can also be used as a standalone package to verify the correctness of the configuration files without deploying the Airnode. The recommended way is to use the [validator CLI](/reference/airnode/latest/packages/validator.md#cli-usage), but for advanced use cases you can use the [validator SDK](/reference/airnode/latest/packages/validator.md#sdk-usage). ## CLI Usage -The simplest way to run the CLI is using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). -Alternatively, you can install the validator package as a dependency in your -project. +The simplest way to run the CLI is using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). Alternatively, you can install the validator package as a dependency in your project. ```sh npx @api3/airnode-validator --config "config.json" --secrets "secrets.env" @@ -56,8 +43,7 @@ npx airnode-validator --config "config.json" --secrets "secrets.env" ### Examples -Assuming the configurations files inside current working directory are valid, -executing: +Assuming the configurations files inside current working directory are valid, executing: ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "valid-secrets.env" @@ -69,8 +55,7 @@ yields: ✔ The configuration is valid ``` -When there is an error during validation, the command prints out the error and -fails with a non zero status code. +When there is an error during validation, the command prints out the error and fails with a non zero status code. ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "non-existent-secrets.env" @@ -84,26 +69,17 @@ yields: ## SDK Usage -The validator package contains an API that can be used to validate Airnode -configuration files programatically. +The validator package contains an API that can be used to validate Airnode configuration files programatically. The following functions can be used: -- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` and validates the interpolated configuration. Expects both `config` - and `secrets` to be JSON objects. -- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a - JSON object. -- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be - a JSON object. -- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be - a JSON object. -- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` but does not perform any validation afterwards. Use this function - only when you can guarantee that the configuration is valid. - -Validator has also full TypeScript support. All of these functions return a -typed object. +- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` and validates the interpolated configuration. Expects both `config` and `secrets` to be JSON objects. +- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a JSON object. +- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be a JSON object. +- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be a JSON object. +- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` but does not perform any validation afterwards. Use this function only when you can guarantee that the configuration is valid. + +Validator has also full TypeScript support. All of these functions return a typed object. ### Examples @@ -146,7 +122,6 @@ if (parseResult.success) { ## Build Manually -See the build instructions for the validator in the -[airnode package repository](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-validator). +See the build instructions for the validator in the [airnode package repository](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-validator). diff --git a/docs/reference/airnode/latest/specifications/airnode-abi.md b/docs/reference/airnode/latest/specifications/airnode-abi.md index bee6a87e..11e09085 100644 --- a/docs/reference/airnode/latest/specifications/airnode-abi.md +++ b/docs/reference/airnode/latest/specifications/airnode-abi.md @@ -19,39 +19,23 @@ tags: # {{$frontmatter.title}} -[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) -is used to encode different types of data while interacting with Ethereum -contracts. As a result, both Solidity and modules such as -[web3.js](https://web3js.readthedocs.io/) and -[ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality -as a first-class citizen. This makes using contract ABI for encoding API call -parameters a very attractive option. - -Although encoding API call parameters using contract ABI has many advantages, it -cannot be used for this purpose directly. Quoting from the -[Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): - -> The encoding is not self describing and thus requires a schema in order to -> decode. - -This means that when passing API call parameters (of type `bytes`), you would -also need to pass a list of the types for these parameters, which is cumbersome -and it is not clear how these types would be encoded. As a solution, Airnode -uses _Airnode ABI specifications_, an extension of contract ABI specifications -that includes a header that keeps the schema. +[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) is used to encode different types of data while interacting with Ethereum contracts. As a result, both Solidity and modules such as [web3.js](https://web3js.readthedocs.io/) and [ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality as a first-class citizen. This makes using contract ABI for encoding API call parameters a very attractive option. + +Although encoding API call parameters using contract ABI has many advantages, it cannot be used for this purpose directly. Quoting from the [Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): + +> The encoding is not self describing and thus requires a schema in order to decode. + +This means that when passing API call parameters (of type `bytes`), you would also need to pass a list of the types for these parameters, which is cumbersome and it is not clear how these types would be encoded. As a solution, Airnode uses _Airnode ABI specifications_, an extension of contract ABI specifications that includes a header that keeps the schema. ## Header -The Airnode ABI specifications header is of type `bytes32` and acts as the -schema (i.e., describes the types of the API call parameters). The header is -encoded in UTF-8 for ease of use. Here is an example: +The Airnode ABI specifications header is of type `bytes32` and acts as the schema (i.e., describes the types of the API call parameters). The header is encoded in UTF-8 for ease of use. Here is an example: ``` "1BSasbiuBa" ``` -The first character, `1`, represents the encoding version. Each following -character represents the type of an API call parameter. +The first character, `1`, represents the encoding version. Each following character represents the type of an API call parameter. ### Type encodings @@ -68,20 +52,11 @@ i: int256 f: bool ``` -Note that dynamically-sized types are represented with uppercase letters and -statically-sized types are represented with lowercase letters. Another thing to -notice is that `s` represents `string32`, but this is an artificial type and it -is not part of -[solidity types](https://docs.soliditylang.org/en/latest/types.html). This type -is instead represented on chain as `bytes32`. The reasons for this are explained -in depth in -[string32 details](/reference/airnode/latest/specifications/airnode-abi.md#string32) -section. +Note that dynamically-sized types are represented with uppercase letters and statically-sized types are represented with lowercase letters. Another thing to notice is that `s` represents `string32`, but this is an artificial type and it is not part of [solidity types](https://docs.soliditylang.org/en/latest/types.html). This type is instead represented on chain as `bytes32`. The reasons for this are explained in depth in [string32 details](/reference/airnode/latest/specifications/airnode-abi.md#string32) section. ## Encoding format -Airnode ABI specifications has the following encoding format (which is somewhat -similar to [SDS](https://github.com/antirez/sds)): +Airnode ABI specifications has the following encoding format (which is somewhat similar to [SDS](https://github.com/antirez/sds)): ``` [------------------------][-----------------------------------------] @@ -125,14 +100,11 @@ bytes memory parameters = abi.encode( ); ``` -Note that you do not need to add an external library to the contract, and -`abi.encode()` is fairly cheap in terms of gas usage (compared to alternative -encoding methods). +Note that you do not need to add an external library to the contract, and `abi.encode()` is fairly cheap in terms of gas usage (compared to alternative encoding methods). ## Example decoding -If you know the schema of the encoded parameters, then decode them on-chain. For -example, if the schema is `(bytes,string)`: +If you know the schema of the encoded parameters, then decode them on-chain. For example, if the schema is `(bytes,string)`: ```solidity ( @@ -142,17 +114,13 @@ example, if the schema is `(bytes,string)`: ) = abi.decode(parameters, (bytes32,bytes32,bytes,bytes32,string)); ``` -Note that this disregards the header and hard codes the schema into the code. It -is also possible to parse the header on-chain and decode accordingly, yet that -would be a lot more complex. +Note that this disregards the header and hard codes the schema into the code. It is also possible to parse the header on-chain and decode accordingly, yet that would be a lot more complex. ## Details ### `string32` -A parameter being of type `string32` (encoded as characted `s` in the ABI -specification schema header) implies that the parameter is UTF-8 encoded text. -For example, if the parameter is +A parameter being of type `string32` (encoded as characted `s` in the ABI specification schema header) implies that the parameter is UTF-8 encoded text. For example, if the parameter is ``` 0x68656c6c6f000000000000000000000000000000000000000000000000000000 @@ -164,9 +132,7 @@ Airnode will decode it as "hello" ``` -and feed that to the API, which is what the user would want to do in most cases. -This becomes a problem if the parameter is not encoded text, but for example a -hash such as: +and feed that to the API, which is what the user would want to do in most cases. This becomes a problem if the parameter is not encoded text, but for example a hash such as: ``` 0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71 @@ -179,15 +145,11 @@ If this hash is encoded as a `string32` type, Airnode will decode it as: !Õ$B˜±=/¡>q ``` -which is probably not what the user is looking for. For these use cases, the -user should use the -[`bytes32`](/reference/airnode/latest/specifications/airnode-abi.md#bytes32) -type instead. +which is probably not what the user is looking for. For these use cases, the user should use the [`bytes32`](/reference/airnode/latest/specifications/airnode-abi.md#bytes32) type instead. ### `bytes32` -To encode a `bytes32` hash on chain, use the `bytes32` type which is represented -by `b` in the ABI header schema. +To encode a `bytes32` hash on chain, use the `bytes32` type which is represented by `b` in the ABI header schema. ```solidity bytes memory parameters = abi.encode( @@ -202,46 +164,27 @@ When decoded by Airnode, the value would be the hash itself: "0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71" ``` -If you want to store 32 byte string values on chain, use the -[`string32`](/reference/airnode/latest/specifications/airnode-abi.md#string32) -type instead. +If you want to store 32 byte string values on chain, use the [`string32`](/reference/airnode/latest/specifications/airnode-abi.md#string32) type instead. ### `bool` -The `bool` type, encoded as character `f` using the ABI specification schema can -be used to encode a boolean value. The header symbol is `f`, because character -`b` was already reserved for bytes encodings. So we chose letter `f` as bool -values are commonly used to represent "boolean flags". +The `bool` type, encoded as character `f` using the ABI specification schema can be used to encode a boolean value. The header symbol is `f`, because character `b` was already reserved for bytes encodings. So we chose letter `f` as bool values are commonly used to represent "boolean flags". ### Omitted types -`array` and `tuple` are omitted because they are not suitable to be used as API -parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because -they are padded to 32 bytes by the ABI encoder anyway (meaning that the user -should simply typecast these to the 32-byte versions). +`array` and `tuple` are omitted because they are not suitable to be used as API parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because they are padded to 32 bytes by the ABI encoder anyway (meaning that the user should simply typecast these to the 32-byte versions). ### Size limit -The header can encode up to 31 parameters (and 1 byte is used to encode the -encoding version). This is far more than what would be needed in practice, and -thus is tolerated to avoid a more complex solution. +The header can encode up to 31 parameters (and 1 byte is used to encode the encoding version). This is far more than what would be needed in practice, and thus is tolerated to avoid a more complex solution. ### Padding -[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) -is used so that you can decode the values later on. This means that each -parameter will be padded with zeros to complete them to 32 bytes. Although this -padding increases gas costs, ABI encoding/decoding functions being cheap -balances this. Furthermore, the -[template](/reference/airnode/latest/concepts/template.md) pattern used in the -protocols allows for the referencing of these encoded parameters without -explicitly passing them in requests, making the increased cost induced by -padding irrelevant in most cases. +[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) is used so that you can decode the values later on. This means that each parameter will be padded with zeros to complete them to 32 bytes. Although this padding increases gas costs, ABI encoding/decoding functions being cheap balances this. Furthermore, the [template](/reference/airnode/latest/concepts/template.md) pattern used in the protocols allows for the referencing of these encoded parameters without explicitly passing them in requests, making the increased cost induced by padding irrelevant in most cases. ## `@api3/airnode-abi` -Encode and decode parameters with the -[airnode-abi](/reference/airnode/latest/packages/airnode-abi.md) package. +Encode and decode parameters with the [airnode-abi](/reference/airnode/latest/packages/airnode-abi.md) package. ```js import { encode } from '@api3/airnode-abi'; @@ -258,13 +201,6 @@ console.log('ENCODED:', encodedData); console.log('\nDECODED:', decoded); ``` -See the package doc -[airnode-abi](/reference/airnode/latest/packages/airnode-abi.md) for more -information on how to encode and decode with Airnode ABI off-chain. Also see -code samples in the -[examples](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples) -package. Lastly see the file -[request-utils.ts](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) -for example syntax on encoding parameters. +See the package doc [airnode-abi](/reference/airnode/latest/packages/airnode-abi.md) for more information on how to encode and decode with Airnode ABI off-chain. Also see code samples in the [examples](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples) package. Lastly see the file [request-utils.ts](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) for example syntax on encoding parameters. diff --git a/docs/reference/airnode/latest/specifications/ois.md b/docs/reference/airnode/latest/specifications/ois.md index 07cfa855..689d8d72 100644 --- a/docs/reference/airnode/latest/specifications/ois.md +++ b/docs/reference/airnode/latest/specifications/ois.md @@ -19,14 +19,8 @@ tags: # {{$frontmatter.title}} -The `ois` JSON object, in the `config.json` file that defines an Airnode, is an -integral part of an Airnode's understanding of an API's specification and its -endpoints. OIS provide a description of API endpoints and maps Airnode endpoints -to them. There can be more than one OIS object in the `config.json` file as -Airnode can serve endpoints from more than one API. - -Learn more about -[Oracle Integration Specifications (OIS)](/reference/ois/latest/) in its -versioned document set. +The `ois` JSON object, in the `config.json` file that defines an Airnode, is an integral part of an Airnode's understanding of an API's specification and its endpoints. OIS provide a description of API endpoints and maps Airnode endpoints to them. There can be more than one OIS object in the `config.json` file as Airnode can serve endpoints from more than one API. + +Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/latest/) in its versioned document set. diff --git a/docs/reference/airnode/latest/specifications/reserved-parameters.md b/docs/reference/airnode/latest/specifications/reserved-parameters.md index 3debd1a1..791533c0 100644 --- a/docs/reference/airnode/latest/specifications/reserved-parameters.md +++ b/docs/reference/airnode/latest/specifications/reserved-parameters.md @@ -19,10 +19,6 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an Airnode's defined endpoints in an -[Oracle Integration Specifications (OIS)](/reference/ois/latest/) object. They -do not map to operation parameters and are used by Airnode for special purposes. -See the [Reserved Parameters](/reference/ois/latest/reserved-parameters.md) doc -in the OIS document set for an in-depth explanation. +Reserved parameters are part of an Airnode's defined endpoints in an [Oracle Integration Specifications (OIS)](/reference/ois/latest/) object. They do not map to operation parameters and are used by Airnode for special purposes. See the [Reserved Parameters](/reference/ois/latest/reserved-parameters.md) doc in the OIS document set for an in-depth explanation. diff --git a/docs/reference/airnode/latest/understand/api-integration.md b/docs/reference/airnode/latest/understand/api-integration.md index f2af6684..25647ca1 100644 --- a/docs/reference/airnode/latest/understand/api-integration.md +++ b/docs/reference/airnode/latest/understand/api-integration.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -A successful integration of an API with an Airnode requires the mapping of each -other's interface. This is accomplished using an OIS -([Oracle Integration Specifications](/reference/ois/latest/specification.md)) -json object, found in the config.json file, designed to with three basic steps. +A successful integration of an API with an Airnode requires the mapping of each other's interface. This is accomplished using an OIS ([Oracle Integration Specifications](/reference/ois/latest/specification.md)) json object, found in the config.json file, designed to with three basic steps. 1. API operations are specified 1. Airnode endpoints are specified @@ -34,60 +31,36 @@ json object, found in the config.json file, designed to with three basic steps. > >

The OIS object in config.json contains mapping information of API operations to Airnode endpoint definitions.

-OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode -endpoints. When a requester contract calls one of the AirnodeRrpV0.sol -contract's request functions, such as `makeFullRequest(..., callData)`, the -callData is communicated to the off-chain Airnode which uses OIS mappings to -translate the callData into a valid HTTP request for the appropriate API -operation. +OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode endpoints. When a requester contract calls one of the AirnodeRrpV0.sol contract's request functions, such as `makeFullRequest(..., callData)`, the callData is communicated to the off-chain Airnode which uses OIS mappings to translate the callData into a valid HTTP request for the appropriate API operation. -OIS borrows formatting from -[OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). -If you have experience with OAS, OIS will seem familiar. +OIS borrows formatting from [OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). If you have experience with OAS, OIS will seem familiar. ::: info OAS -It is not recommended to refer to OAS for help while creating your OIS object. -OIS only borrows formatting practices from OAS. Everything needed to create an -OIS object is in these docs. +It is not recommended to refer to OAS for help while creating your OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: **Tips while reading ths page.** -- Open the [OIS template](/reference/ois/latest/template.md) in another browser - window to follow along. -- View an example of an Airnode - [config.json](/reference/airnode/latest/deployment-files/examples/config-json.md) - file. +- Open the [OIS template](/reference/ois/latest/template.md) in another browser window to follow along. +- View an example of an Airnode [config.json](/reference/airnode/latest/deployment-files/examples/config-json.md) file. ## OIS Template -OIS is a json object that is added to an Airnode's -[config.json](/reference/airnode/latest/deployment-files/templates/config-json.md) -file as the (`ois`) _key_, sometimes called a _field_. Try using the -[OIS template](/reference/ois/latest/template.md) to construct an OIS and add it -to the Airnode's config.json file later. +OIS is a json object that is added to an Airnode's [config.json](/reference/airnode/latest/deployment-files/templates/config-json.md) file as the (`ois`) _key_, sometimes called a _field_. Try using the [OIS template](/reference/ois/latest/template.md) to construct an OIS and add it to the Airnode's config.json file later. -In the OIS template, there are some fields that contain `{FILL_*}`. This means -that the value added is independent from other fields. On the other hand, if two -fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), -you must use the same value in them, because they are referencing each other. +In the OIS template, there are some fields that contain `{FILL_*}`. This means that the value added is independent from other fields. On the other hand, if two fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), you must use the same value in them, because they are referencing each other. -OIS uses a simplified version of the OAS. This means that if you have the -OpenAPI specifications of the API that you are going to integrate, you are about -80% done, because you can copy paste entire sections (but be sure to make the -necessary modifications to conform to the OIS format). +OIS uses a simplified version of the OAS. This means that if you have the OpenAPI specifications of the API that you are going to integrate, you are about 80% done, because you can copy paste entire sections (but be sure to make the necessary modifications to conform to the OIS format). -The remainder of this page will assume you do not have the OpenAPI -specifications of the API that you will be integrating. +The remainder of this page will assume you do not have the OpenAPI specifications of the API that you will be integrating. ## 1. Specify OIS Definitions -Start building an OIS by adding three descriptive fields to the root of the OIS -json object. +Start building an OIS by adding three descriptive fields to the root of the OIS json object. ```json { @@ -100,20 +73,15 @@ json object. ### oisFormat -A specific version of the -[OIS Specification](/reference/ois/latest/specification.md#_1-oisformat) to be -used. For Airnode `v0.14`, the proper OIS version is `2.3.0`. +A specific version of the [OIS Specification](/reference/ois/latest/specification.md#_1-oisformat) to be used. For Airnode `v0.14`, the proper OIS version is `2.3.0`. ### title -This is a unique title of the OIS. Note that an Airnode can be configured with -more than one OIS object and uses the title as the OIS identifier. +This is a unique title of the OIS. Note that an Airnode can be configured with more than one OIS object and uses the title as the OIS identifier. ### version -This is the version of the OIS which allows for version-control of the OIS -integration. It is recommended to use [semver](https://semver.org/) versioning. -The initial version could be `0.1.0`. +This is the version of the OIS which allows for version-control of the OIS integration. It is recommended to use [semver](https://semver.org/) versioning. The initial version could be `0.1.0`. @@ -134,15 +102,11 @@ The `apiSpecifications` field is used to describe the API and its operations. ### Servers -The first step of specifying an API is to enter its _baseURL_ in the -`apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed -in the `apiSpecifications.servers` array. A warning is raised during conversion -if servers has multiple elements. This baseURL will apply to all operations. +The first step of specifying an API is to enter its _baseURL_ in the `apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed in the `apiSpecifications.servers` array. A warning is raised during conversion if servers has multiple elements. This baseURL will apply to all operations. #### Choosing a Base URL -Consider the following full URL to execute an API operation that returns all -know tokens. +Consider the following full URL to execute an API operation that returns all know tokens. @@ -164,16 +128,11 @@ or > > **path:** `/data` -Because the call will be made to <`baseURL+path`> both will result in the same -full URL. +Because the call will be made to <`baseURL+path`> both will result in the same full URL. -Set the baseURL as the section of the full URL that you expect to be shared by -all operations. From the examples above it is recommended to use -`https://www.myapi.com`, in case additional paths starting with `/v2` get added -to the API in the future. As you can tell, API integration requires many -subjective choices, and is more art than science. +Set the baseURL as the section of the full URL that you expect to be shared by all operations. From the examples above it is recommended to use `https://www.myapi.com`, in case additional paths starting with `/v2` get added to the API in the future. As you can tell, API integration requires many subjective choices, and is more art than science. ```json "apiSpecifications": { @@ -188,20 +147,15 @@ subjective choices, and is more art than science. ### Paths -The _paths_ field defines all the API operations much like an OpenAPI -Specification file. +The _paths_ field defines all the API operations much like an OpenAPI Specification file. _What is an API operation?_ -> An API operation is specified as a unique combination of a _**path**_ and an -> HTTP _**method**_. `GET /token/{id}` +> An API operation is specified as a unique combination of a _**path**_ and an HTTP _**method**_. `GET /token/{id}` #### Operations -In the examples below, `GET` refers to an -[HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). -This implies that you could have another API operation that can be specified -using a different method but the same path. +In the examples below, `GET` refers to an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). This implies that you could have another API operation that can be specified using a different method but the same path. > path: /data > @@ -211,18 +165,11 @@ using a different method but the same path. > > method: POST -Therefore, a path is not enough to specify an API operation by itself, you must -also provide a method. If a new path is needed then it must be a new object in -paths with its own methods. Currently only the GET and POST methods are -supported by Airnode. +Therefore, a path is not enough to specify an API operation by itself, you must also provide a method. If a new path is needed then it must be a new object in paths with its own methods. Currently only the GET and POST methods are supported by Airnode. -With regards to the [OIS template](/reference/ois/latest/template.md), the name -of the element (denoted as `{FILL_PATH}`) should be replaced with the path -(e.g., `/data`). Similarly, `{FILL_METHOD}` should be replaced with the method -of the operation to integrate (e.g., `get`). The method must be lowercase. +With regards to the [OIS template](/reference/ois/latest/template.md), the name of the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., `/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the operation to integrate (e.g., `get`). The method must be lowercase. -The following example illustrates three operations, `GET /data`, `POST /data`, -`GET /tokens`. +The following example illustrates three operations, `GET /data`, `POST /data`, `GET /tokens`. ```json "paths": { @@ -244,27 +191,16 @@ The following example illustrates three operations, `GET /data`, `POST /data`, #### Parameters (operation) -After specifying the path and method of an API operation, the final step is to -specify its parameters. Each parameter is an object in the -`apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` -and `name`. `in` tells where the parameter goes in the HTTP request and `name` -tells the name that the parameter value will be sent under. Currently Airnode -supports the following parameter types for use with `in`. +After specifying the path and method of an API operation, the final step is to specify its parameters. Each parameter is an object in the `apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` and `name`. `in` tells where the parameter goes in the HTTP request and `name` tells the name that the parameter value will be sent under. Currently Airnode supports the following parameter types for use with `in`. - query - header - path - cookie -When integrating a POST method, define the body parameters with `in: query`. -Airnode will convert all `query` types into the `requestBody`. Note that only -the non-nested application/json content-type is supported. +When integrating a POST method, define the body parameters with `in: query`. Airnode will convert all `query` types into the `requestBody`. Note that only the non-nested application/json content-type is supported. -It is not necessary to specify all API operation parameters, but only the ones -the on-chain requester will need to be able to provide (see Airnode endpoint -[parameters](/reference/airnode/latest/understand/api-integration.md#parameters)), -and the ones needed to hard-code a value for (see Airnode endpoint -[fixed operation parameters](/reference/airnode/latest/understand/api-integration.md#fixedoperationparameters)). +It is not necessary to specify all API operation parameters, but only the ones the on-chain requester will need to be able to provide (see Airnode endpoint [parameters](/reference/airnode/latest/understand/api-integration.md#parameters)), and the ones needed to hard-code a value for (see Airnode endpoint [fixed operation parameters](/reference/airnode/latest/understand/api-integration.md#fixedoperationparameters)). ```json "paths": { @@ -287,8 +223,7 @@ and the ones needed to hard-code a value for (see Airnode endpoint _Example: Get a token_ -The `GET /token/{id}` returns a token using the token's `id` which is a `path` -parameter. +The `GET /token/{id}` returns a token using the token's `id` which is a `path` parameter. | Method | Path | in | name | | ------ | ----------- | ---- | ---- | @@ -296,11 +231,7 @@ parameter. _Example: Create a token_ -The `POST /token` operation accepts three parameters. The name and description -of the token are placed in the type `query` and will be moved by Airnode to the -requestBody upon calling the API operation. The third is a `header` parameter -that describes the Content-Type of the request such as `application/json` or -`application/x-www-form-urlencoded`. +The `POST /token` operation accepts three parameters. The name and description of the token are placed in the type `query` and will be moved by Airnode to the requestBody upon calling the API operation. The third is a `header` parameter that describes the Content-Type of the request such as `application/json` or `application/x-www-form-urlencoded`. | Method | Path | in | name | | ------ | ------ | ------ | ----------- | @@ -310,9 +241,7 @@ that describes the Content-Type of the request such as `application/json` or _Example: Get all tokens_ -The `GET /tokens` returns a list of all tokens. The list count can be limited -using the `limit' parameter which the API operation considers as optional since -it will not return an error if omitted. +The `GET /tokens` returns a list of all tokens. The list count can be limited using the `limit' parameter which the API operation considers as optional since it will not return an error if omitted. > `GET /tokens` returns all tokens. > @@ -326,66 +255,25 @@ it will not return an error if omitted. ## 3. Specifying Airnode Endpoints -An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It -maps to an API operation, but the nature of this mapping is customizable. It is -the integrator's job to define what this service is. - -For example, if an API operation returns an asset price given its ticker (e.g., -`BTC`), specify the endpoint such that the requester provides the ticker as a -parameter. The resulting endpoint would be a general one that returns prices for -any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price -will be returned (using -[fixed operation parameters](/reference/airnode/latest/understand/api-integration.md#fixedoperationparameters)), -which would make the endpoint a specific one that only returns the BTC price. - -The recommended endpoint definition pattern is to create an Airnode endpoint for -each API operation, and allow the requesters to provide all operation parameters -themselves. This results in optimal flexibility, and essentially allows the -requesters to use the entire API functionality on-chain. Normally, competitor -oracle integrations strive to hard-code as many API parameters as possible -because passing these parameters on-chain results in a gas cost overhead. -However, the Airnode protocol uses -[templates](/reference/airnode/latest/concepts/template.md) (not to be confused -with the OIS template used for this guide), which allow requesters to specify a -large number of endpoint parameters at no additional gas cost. - -Note that there are some cases where you may not want to map endpoints to API -operations one-to-one. For example, an API operation can have a `header` -parameter, `Accept`, that can take the values `application/json` or -`application/xml` to determine how to format the data that the API will respond -to the call. Airnode expects responses to be in JSON format, and thus -hard-coding this parameter as `JSON` would be more suitable than letting the -requester decide, as there is only one valid choice. Again, the integrator's job -is to be aware of these subtleties and use judgement. +An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It maps to an API operation, but the nature of this mapping is customizable. It is the integrator's job to define what this service is. + +For example, if an API operation returns an asset price given its ticker (e.g., `BTC`), specify the endpoint such that the requester provides the ticker as a parameter. The resulting endpoint would be a general one that returns prices for any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price will be returned (using [fixed operation parameters](/reference/airnode/latest/understand/api-integration.md#fixedoperationparameters)), which would make the endpoint a specific one that only returns the BTC price. + +The recommended endpoint definition pattern is to create an Airnode endpoint for each API operation, and allow the requesters to provide all operation parameters themselves. This results in optimal flexibility, and essentially allows the requesters to use the entire API functionality on-chain. Normally, competitor oracle integrations strive to hard-code as many API parameters as possible because passing these parameters on-chain results in a gas cost overhead. However, the Airnode protocol uses [templates](/reference/airnode/latest/concepts/template.md) (not to be confused with the OIS template used for this guide), which allow requesters to specify a large number of endpoint parameters at no additional gas cost. + +Note that there are some cases where you may not want to map endpoints to API operations one-to-one. For example, an API operation can have a `header` parameter, `Accept`, that can take the values `application/json` or `application/xml` to determine how to format the data that the API will respond to the call. Airnode expects responses to be in JSON format, and thus hard-coding this parameter as `JSON` would be more suitable than letting the requester decide, as there is only one valid choice. Again, the integrator's job is to be aware of these subtleties and use judgement. ### Endpoints array -The field `endpoints` is an array, with each row representing an Airnode -endpoint. The first field to fill in is `name`. Make sure that it is descriptive -and unique from other endpoint names. If you are integrating API operations to -Airnode endpoints one-to-one, using the API operation path as the endpoint name -is a decent choice (i.e., `/token`). Note that you would also add the method to -this name if there were multiple operations with different methods for a single -path (i.e., `GET/token`). +The field `endpoints` is an array, with each row representing an Airnode endpoint. The first field to fill in is `name`. Make sure that it is descriptive and unique from other endpoint names. If you are integrating API operations to Airnode endpoints one-to-one, using the API operation path as the endpoint name is a decent choice (i.e., `/token`). Note that you would also add the method to this name if there were multiple operations with different methods for a single path (i.e., `GET/token`). -The next step is to fill in `operation` object. Here, you need to enter the -`path` and `method` of an API operation you have defined in -`apiSpecifications.paths`, resulting in the Airnode endpoint calling the now -linked API operation. +The next step is to fill in `operation` object. Here, you need to enter the `path` and `method` of an API operation you have defined in `apiSpecifications.paths`, resulting in the Airnode endpoint calling the now linked API operation. #### fixedOperationParameters -It is not uncommon to hard-code API parameters (recall the `Accept` operation -parameter in the above example). Such hard-coded parameters are called -`fixedOperationParameters`. +It is not uncommon to hard-code API parameters (recall the `Accept` operation parameter in the above example). Such hard-coded parameters are called `fixedOperationParameters`. -In the OIS template there is a fixed operation parameter under -`endpoints[n].fixedOperationParameters`, and it refers to the first API -operation parameter. This means that whenever the Airnode receives a request for -this endpoint, the respective API call will be made with that API operation -parameter set to -endpoints[n].fixedOperationParameters[n].value. -The requester does not supply a value for `fixedOperationParameters`. +In the OIS template there is a fixed operation parameter under `endpoints[n].fixedOperationParameters`, and it refers to the first API operation parameter. This means that whenever the Airnode receives a request for this endpoint, the respective API call will be made with that API operation parameter set to endpoints[n].fixedOperationParameters[n].value. The requester does not supply a value for `fixedOperationParameters`. ```json "fixedOperationParameters": [ @@ -400,31 +288,17 @@ The requester does not supply a value for `fixedOperationParameters`. ``` -An Airnode endpoint can have multiple `fixedOperationParameters`. An API -operation parameter cannot be in both `endpoints[n].fixedOperationParameters` -and `endpoints[n].parameters`. +An Airnode endpoint can have multiple `fixedOperationParameters`. An API operation parameter cannot be in both `endpoints[n].fixedOperationParameters` and `endpoints[n].parameters`. #### reservedParameters -The requester can provide some parameters that are not mapped to API operation -parameters. These parameters are called "reserved parameters", and their names -start with an underscore. See the -[related OIS docs](/reference/ois/latest/specification.md#_5-4-reservedparameters) -for more information. +The requester can provide some parameters that are not mapped to API operation parameters. These parameters are called "reserved parameters", and their names start with an underscore. See the [related OIS docs](/reference/ois/latest/specification.md#_5-4-reservedparameters) for more information. -The current list of reserved parameters are `_type`, `_path`, `_times`, -`_gasPrice`, and `_minConfirmations`. See -[Reserved Parameters](/reference/ois/latest/reserved-parameters.md) in the OIS -document set to understand what each of these parameters are for. +The current list of reserved parameters are `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. See [Reserved Parameters](/reference/ois/latest/reserved-parameters.md) in the OIS document set to understand what each of these parameters are for. #### parameters -Airnode endpoint -[parameters](/reference/ois/latest/specification.md#_5-5-parameters) map to API -operation [parameters](/reference/ois/latest/specification.md#_4-2-1-parameters) -that the requester is allowed to provide values for. It refers to an API -operation through its field `operationParameter`. You can also provide `default` -values for endpoint parameters, though this is not recommended in most cases. +Airnode endpoint [parameters](/reference/ois/latest/specification.md#_5-5-parameters) map to API operation [parameters](/reference/ois/latest/specification.md#_4-2-1-parameters) that the requester is allowed to provide values for. It refers to an API operation through its field `operationParameter`. You can also provide `default` values for endpoint parameters, though this is not recommended in most cases. ```json // apiSpecifications.paths...parameters[1] @@ -460,27 +334,14 @@ Mapping between API parameters and endpoint parameters. │ │ ] ``` -Endpoint parameters have a `name` field, which does not have to be the same as -the API operation parameter that they map to. As a separate note, an Airnode -endpoint can have multiple parameters. +Endpoint parameters have a `name` field, which does not have to be the same as the API operation parameter that they map to. As a separate note, an Airnode endpoint can have multiple parameters. ## Conclusion -The API operations and Airnode endpoints are now specified. Each Airnode -endpoint maps to an API operation, and each Airnode endpoint parameter or -fixedOperationParameter maps to an API operation parameter. The resulting OIS -includes no user-specific information, which means that you can share it for -others to easily provide the same services (for example, to set up a third-party -oracle network). - -Note that there was some subjectivity while defining the Airnode endpoints. This -means that two different OISes can exist for the same exact API, differing based -on how the integrators designed the interface that the requester will use. -However, in most cases, one would simply map API operations to Airnode endpoints -directly, and let the requester provide all API operation parameters through the -Airnode endpoint parameters. - -Now that you have an OIS object, the next step is -[API Security](/reference/airnode/latest/understand/api-security.md). +The API operations and Airnode endpoints are now specified. Each Airnode endpoint maps to an API operation, and each Airnode endpoint parameter or fixedOperationParameter maps to an API operation parameter. The resulting OIS includes no user-specific information, which means that you can share it for others to easily provide the same services (for example, to set up a third-party oracle network). + +Note that there was some subjectivity while defining the Airnode endpoints. This means that two different OISes can exist for the same exact API, differing based on how the integrators designed the interface that the requester will use. However, in most cases, one would simply map API operations to Airnode endpoints directly, and let the requester provide all API operation parameters through the Airnode endpoint parameters. + +Now that you have an OIS object, the next step is [API Security](/reference/airnode/latest/understand/api-security.md). diff --git a/docs/reference/airnode/latest/understand/api-security.md b/docs/reference/airnode/latest/understand/api-security.md index f0add260..38011343 100644 --- a/docs/reference/airnode/latest/understand/api-security.md +++ b/docs/reference/airnode/latest/understand/api-security.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode can pass along security information (schemes) when making calls to API -operations. There are two groups of security schemes. +Airnode can pass along security information (schemes) when making calls to API operations. There are two groups of security schemes. - [Airnode Authentication](/reference/airnode/latest/concepts/airnode-auth.md) - [Relayed Meta Data Authentication](/reference/airnode/latest/concepts/relay-meta-auth.md) @@ -31,8 +30,7 @@ operations. There are two groups of security schemes. > 1.

The Airnode uses Airnode Authentication Security Schemes to authenticate itself to an API operation of which the values are known only by the Airnode.

> 2.

The Airnode uses Relayed Meta Data Security Schemes to forward known information from the requester's request to an API operation.

-Security schemes are declared by the required `type` property inside the -security scheme definition. The following security scheme types are supported. +Security schemes are declared by the required `type` property inside the security scheme definition. The following security scheme types are supported. - Airnode Authentication Security Schemes - apiKey @@ -46,22 +44,16 @@ security scheme definition. The following security scheme types are supported. - relaySponsorWalletAddress - relayRequestId -It is important to note that the security schemes in any given OIS object apply -to all endpoints/API operations in the OIS object. If different security schemes -are required by a mix of endpoints/API operations, then more than one OIS object -will be required grouping endpoint/API operations based on their security needs. +It is important to note that the security schemes in any given OIS object apply to all endpoints/API operations in the OIS object. If different security schemes are required by a mix of endpoints/API operations, then more than one OIS object will be required grouping endpoint/API operations based on their security needs. ## Airnode Authentication Security Schemes -An Airnode can use the following security scheme types to authenticate itself to -API operations. +An Airnode can use the following security scheme types to authenticate itself to API operations. - [apiKey](/reference/airnode/latest/understand/api-security.md#apikey) - [http](/reference/airnode/latest/understand/api-security.md#http) -A security scheme requires a unique name within the OIS object for which it -exists. This name groups the security scheme values for `in`, `type`, and` name` -as shown in the two code examples below. +A security scheme requires a unique name within the OIS object for which it exists. This name groups the security scheme values for `in`, `type`, and` name` as shown in the two code examples below. - `securitySchemes.` - `security.` @@ -69,18 +61,12 @@ as shown in the two code examples below. ### apiKey -The `apiKey` security scheme type allows you to define an API key the Airnode -will send to API operations. It is an object which consists of the following -fields: +The `apiKey` security scheme type allows you to define an API key the Airnode will send to API operations. It is an object which consists of the following fields: - `type` must be `apiKey` -- `in` can be one of the `query`, `header` or `cookie`. This value specifies how - the value will be sent to an API operation. When using the `query` option, the - API key will be sent in the request body for POST requests and in query string - for GET requests. +- `in` can be one of the `query`, `header` or `cookie`. This value specifies how the value will be sent to an API operation. When using the `query` option, the API key will be sent in the request body for POST requests and in query string for GET requests. -- `name` is the name of the API key that should be sent to an API. For example - "X-Api-Key". +- `name` is the name of the API key that should be sent to an API. For example "X-Api-Key". ```json "ois": [ @@ -108,11 +94,7 @@ fields: ] │ ``` -The value of the `apiKey` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `apiKey` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json "apiCredentials": [ │ @@ -126,11 +108,7 @@ file. ### http -The `http` security scheme type is used to define either a `basic` or `bearer` -authentication scheme. This security scheme will always be sent in the headers. -The security scheme value should be base64 encoded value "username:password" for -`basic` auth and the encoded token for `bearer` auth. It is an object which -consists of the following fields: +The `http` security scheme type is used to define either a `basic` or `bearer` authentication scheme. This security scheme will always be sent in the headers. The security scheme value should be base64 encoded value "username:password" for `basic` auth and the encoded token for `bearer` auth. It is an object which consists of the following fields: - `type` must be `http` - `scheme` is either `basic` or `bearer` @@ -144,11 +122,7 @@ consists of the following fields: } ``` -The value of the `http` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `http` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json { @@ -160,19 +134,13 @@ file. ::: info Authentication Tutorial -The -[authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates authentication. +The [authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) monorepo example demonstrates authentication. ::: ## Relayed Meta Data Security Schemes -In addition to authenticating itself, Airnode can "relay" security information -about a request to an API operation. This is different then the authorization of -requesters using -[Authorizers](/reference/airnode/latest/understand/apply-auth.md) to access the -Airnode. +In addition to authenticating itself, Airnode can "relay" security information about a request to an API operation. This is different then the authorization of requesters using [Authorizers](/reference/airnode/latest/understand/apply-auth.md) to access the Airnode. - [relayRequesterAddress](/reference/airnode/latest/understand/api-security.md#relayrequesteraddress) - [relayChainId](/reference/airnode/latest/understand/api-security.md#relaychainid) @@ -181,29 +149,19 @@ Airnode. - [relaySponsorWalletAddress](/reference/airnode/latest/understand/api-security.md#relaysponsorwalletaddress) - [relayRequestId](/reference/airnode/latest/understand/api-security.md#relayrequestid) -For relayed meta data security schemes do not provide any values in -[apiCredentials](/reference/airnode/latest/deployment-files/config-json.md#apicredentials) -as they are extracted from the request by Airnode. +For relayed meta data security schemes do not provide any values in [apiCredentials](/reference/airnode/latest/deployment-files/config-json.md#apicredentials) as they are extracted from the request by Airnode. -Note that Airnode relays this metadata to an API operation and does not perform -any additional processing logic. The API provider must implement any desired -logic in the API operation for any desired security checks. See -[Relayed Meta Data Authentication](/reference/airnode/latest/concepts/relay-meta-auth.md) -for overview of its usage. +Note that Airnode relays this metadata to an API operation and does not perform any additional processing logic. The API provider must implement any desired logic in the API operation for any desired security checks. See [Relayed Meta Data Authentication](/reference/airnode/latest/concepts/relay-meta-auth.md) for overview of its usage. ::: info Relay Metadata Tutorial -The -[relay-security-schemes](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates how to relay request metadata like chain ID and -sponsor address to the API endpoint. +The [relay-security-schemes](/guides/airnode/monorepo-examples.md) monorepo example demonstrates how to relay request metadata like chain ID and sponsor address to the API endpoint. ::: ### relayRequesterAddress -The `relayRequesterAddress` security scheme type instructs Airnode to forward -the [requester](/reference/airnode/latest/concepts/requester.md) address. +The `relayRequesterAddress` security scheme type instructs Airnode to forward the [requester](/reference/airnode/latest/concepts/requester.md) address. ```json { @@ -215,8 +173,7 @@ the [requester](/reference/airnode/latest/concepts/requester.md) address. ### relayChainId -The `relayChainId` security scheme type instructs Airnode to forward the chain's -ID. +The `relayChainId` security scheme type instructs Airnode to forward the chain's ID. ```json { @@ -228,8 +185,7 @@ ID. ### relayChainType -The `relayChainType` security scheme type instructs Airnode to forward the -chain's type. +The `relayChainType` security scheme type instructs Airnode to forward the chain's type. ```json { @@ -241,8 +197,7 @@ chain's type. ### relaySponsorAddress -The `relaySponsorAddress` security scheme type instructs Airnode to forward the -[sponsor address](/reference/airnode/latest/concepts/sponsor.md#sponsoraddress). +The `relaySponsorAddress` security scheme type instructs Airnode to forward the [sponsor address](/reference/airnode/latest/concepts/sponsor.md#sponsoraddress). ```json { @@ -254,9 +209,7 @@ The `relaySponsorAddress` security scheme type instructs Airnode to forward the ### relaySponsorWalletAddress -The `relaySponsorWalletAddress` security scheme type instructs Airnode to -forward the -[sponsor wallet address](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). +The `relaySponsorWalletAddress` security scheme type instructs Airnode to forward the [sponsor wallet address](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet). ```json { @@ -268,8 +221,7 @@ forward the ### relayRequestId -The `relayRequestId` security scheme type instructs Airnode to forward the -[id of the request](/reference/airnode/latest/concepts/request.md#requestid). +The `relayRequestId` security scheme type instructs Airnode to forward the [id of the request](/reference/airnode/latest/concepts/request.md#requestid). ```json { @@ -279,10 +231,7 @@ The `relayRequestId` security scheme type instructs Airnode to forward the } ``` -The following example shows how to set up relayed meta data to forward the -`relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that -unlike the Airnode authentication security scheme, no values are stored in -`apiCredentials` as Airnode passes these known values to the API operation. +The following example shows how to set up relayed meta data to forward the `relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that unlike the Airnode authentication security scheme, no values are stored in `apiCredentials` as Airnode passes these known values to the API operation. ```json "ois": [ @@ -318,29 +267,19 @@ unlike the Airnode authentication security scheme, no values are stored in ::: info Remember -The relayed meta data security schemes do not require a supplied value. Values -will be provided (relayed) by Airnode depending on the particular request. +The relayed meta data security schemes do not require a supplied value. Values will be provided (relayed) by Airnode depending on the particular request. ::: ## Example -OIS security is inspired by OAS security practices. This is implemented using -the security schemes and security field. All supported security schemes are -described in detail in the -[Airnode Authentication Security Schemes](/reference/airnode/latest/understand/api-security.md#airnode-authentication-security-schemes) -and -[Relayed Meta Data Security Schemes](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) -sections above. The following example is related to _Airnode Authentication -Security Schemes_. Working with security schemes can be described in three -steps. +OIS security is inspired by OAS security practices. This is implemented using the security schemes and security field. All supported security schemes are described in detail in the [Airnode Authentication Security Schemes](/reference/airnode/latest/understand/api-security.md#airnode-authentication-security-schemes) and [Relayed Meta Data Security Schemes](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) sections above. The following example is related to _Airnode Authentication Security Schemes_. Working with security schemes can be described in three steps. 1. [Define the security schemes for an OIS](/reference/airnode/latest/understand/api-security.md#step-1-define-the-security-schemes-for-an-ois) 2. [Turn on the defined security schemes](/reference/airnode/latest/understand/api-security.md#step-2-turn-on-the-defined-security-schemes) 3. [Specify the values for the defined security schemes](/reference/airnode/latest/understand/api-security.md#step-3-specify-the-values-for-the-defined-security-schemes) -Following is an example of a partial `config.json` which demonstrates the usage -of security scheme and security field. +Following is an example of a partial `config.json` which demonstrates the usage of security scheme and security field. ```json { @@ -377,60 +316,34 @@ of security scheme and security field. ### Step #1: Define the security schemes for an OIS -Use -ois[n].apiSpecifications.components.securitySchemes -to define the security schemes the API operation requires. Consider the partial -`config.json` above that declares a security scheme named `requiresXApiKey`. -This scheme declares that the API requires an API key that must exist in the -HTTP header named `X-api-key`. +Use ois[n].apiSpecifications.components.securitySchemes to define the security schemes the API operation requires. Consider the partial `config.json` above that declares a security scheme named `requiresXApiKey`. This scheme declares that the API requires an API key that must exist in the HTTP header named `X-api-key`. ### Step #2: Turn on the defined security schemes -When the scheme is defined, it is not turned on by default. You need to -explicitly list the security schemes you intend to use in the `security` field -located in `ois[n].apiSpecifications.security` object. The keys in this object -are the names of security schemes to be used. Use empty array (`[]`) as its -value. +When the scheme is defined, it is not turned on by default. You need to explicitly list the security schemes you intend to use in the `security` field located in `ois[n].apiSpecifications.security` object. The keys in this object are the names of security schemes to be used. Use empty array (`[]`) as its value. -_Be aware that this step seems like extra work since there is no reason to -define a security scheme that will not be used. However, Airnode may support -[more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) -logic in the future and using `[]` allows its implementation without a breaking -change._ +_Be aware that this step seems like extra work since there is no reason to define a security scheme that will not be used. However, Airnode may support [more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) logic in the future and using `[]` allows its implementation without a breaking change._ ### Step #3: Specify the values for the defined security schemes -After defining and turning on a security scheme, it may be unclear what provides -the value and how it is set. +After defining and turning on a security scheme, it may be unclear what provides the value and how it is set. -The authentication schemes are intended to be common for the whole OIS and set -by the API provider using `apiCredentials` which is part of `config.json`. The -`apiCredentials` is an array which specifies the values for all security schemes -in all OIS definitions. Each element of this array contains the following fields +The authentication schemes are intended to be common for the whole OIS and set by the API provider using `apiCredentials` which is part of `config.json`. The `apiCredentials` is an array which specifies the values for all security schemes in all OIS definitions. Each element of this array contains the following fields - `oisTitle` is the title of the OIS for the particular security scheme - `securitySchemeName` is the name of the security scheme -- `securitySchemeValue` is the actual value that should be used by Airnode when - making the API request. This value is usually a secret and it is recommended - to interpolate it from `secrets.env`. +- `securitySchemeValue` is the actual value that should be used by Airnode when making the API request. This value is usually a secret and it is recommended to interpolate it from `secrets.env`. ## Using Different Security Schemes -Currently, if you want different API operations to use different security -schemes they must be grouped in different OIS objects based on their common -security schemes. For example, your API has four operations, three require an -API key in the HTTP header, another (public `/ping` endpoint) requires no -security. +Currently, if you want different API operations to use different security schemes they must be grouped in different OIS objects based on their common security schemes. For example, your API has four operations, three require an API key in the HTTP header, another (public `/ping` endpoint) requires no security. -- The first three API operations might be in the `ois[0]` object with a security - scheme named _requiresXApiKey_ of type _apiKey_ as shown above. -- The /ping API operation would be in `ois[1]` which would not have any - `component.securitySchemes` and `security` would be an empty array. +- The first three API operations might be in the `ois[0]` object with a security scheme named _requiresXApiKey_ of type _apiKey_ as shown above. +- The /ping API operation would be in `ois[1]` which would not have any `component.securitySchemes` and `security` would be an empty array. ## Multiple Security Schemes -You can use multiple security schemes (e.g., an API key goes in the header, and -an additional secret goes in the query). +You can use multiple security schemes (e.g., an API key goes in the header, and an additional secret goes in the query). ```json // inside ois[n].apiSpecifications. @@ -456,7 +369,6 @@ an additional secret goes in the query). ## No Security -If the API you are integrating is publicly accessible, you can set both the -`security schemes` and `security` fields to empty objects. +If the API you are integrating is publicly accessible, you can set both the `security schemes` and `security` fields to empty objects. diff --git a/docs/reference/airnode/latest/understand/apply-auth.md b/docs/reference/airnode/latest/understand/apply-auth.md index 983bedc7..c22aca5a 100644 --- a/docs/reference/airnode/latest/understand/apply-auth.md +++ b/docs/reference/airnode/latest/understand/apply-auth.md @@ -19,51 +19,29 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using -[Authorizers](/reference/airnode/latest/concepts/authorizers.md). This method is -on-chain and requires some blockchain knowledge by an API provider. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizers](/reference/airnode/latest/concepts/authorizers.md). This method is on-chain and requires some blockchain knowledge by an API provider. ## What is an authorizer? -An [Authorizer](/reference/airnode/latest/concepts/authorizers.md) is a contract -which typically checks for a single condition ("has the requester made their -monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers -can be combined to enforce more complex policies. If any of the authorizers in -the list gives access, the request will considered to be authorized. From a -logical standpoint, the authorization outcomes get *OR*ed. +An [Authorizer](/reference/airnode/latest/concepts/authorizers.md) is a contract which typically checks for a single condition ("has the requester made their monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers can be combined to enforce more complex policies. If any of the authorizers in the list gives access, the request will considered to be authorized. From a logical standpoint, the authorization outcomes get *OR*ed. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: ## How to implement authorizers. -When you deploy your Airnode a receipt file is generated which contains the -Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use -`airnodeAddress` and an `endpointId` to make requests to your Airnode's -endpoints. However, rather than serve them publicly, you may want to: +When you deploy your Airnode a receipt file is generated which contains the Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use `airnodeAddress` and an `endpointId` to make requests to your Airnode's endpoints. However, rather than serve them publicly, you may want to: -- Only serve your own - [requester contracts](/reference/airnode/latest/developers/requesters-sponsors.md). +- Only serve your own [requester contracts](/reference/airnode/latest/developers/requesters-sponsors.md). - Only serve sponsors who have made a subscription payment. - Only serve sponsors who have gone through KYC. -The `chains[n].authorizers` object within `config.json` enables requests to be -authorized in a variety of ways and even across chains. Currently, the -authorizers include `requesterEndpointAuthorizers`, -`crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and -`crossChainRequesterAuthorizersWithErc721`. +The `chains[n].authorizers` object within `config.json` enables requests to be authorized in a variety of ways and even across chains. Currently, the authorizers include `requesterEndpointAuthorizers`, `crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and `crossChainRequesterAuthorizersWithErc721`. -Note that when all `chains[n].authorizers` values are empty arrays, all requests -are authorized, but still can be filtered by using -[Relayed Meta Data Security Schemes](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes). +Note that when all `chains[n].authorizers` values are empty arrays, all requests are authorized, but still can be filtered by using [Relayed Meta Data Security Schemes](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes). Below are examples of how to use the authorizers. @@ -122,23 +100,11 @@ Below are examples of how to use the authorizers. ## Using `RequesterAuthorizerWithAirnode` -A common use case for an authorizer is the -[RequesterAuthorizerWithAirnode](/reference/airnode/latest/concepts/authorizers.md#requesterauthorizerwithairnode) -authorizer contract developed for Airnode operators to use right out-of-the-box. -It allows the whitelisting of requester contracts (with or without expiration -timestamps) on a per endpoint basis. Endpoints are declared in the -`ois.endpoints` field of the `config.json` file. This is the most common use -case and can be implemented with the following steps: - -1. Add the RequesterAuthorizerWithAirnode - [authorizer contract address](/reference/airnode/latest/#requesterauthorizerwithairnode) - to the array `chains[n].authorizers.requesterEndpointAuthorizers`. -2. After your Airnode is deployed, call the Admin CLI command - [set-whitelist-expiration](/reference/airnode/latest/packages/admin-cli.md#set-whitelist-expiration) - to add the desired requester contract addresses to the whitelist maintained - by RequesterAuthorizerWithAirnode. - -Once implemented, only requester contract addresses you have added to -RequesterAuthorizerWithAirnode will have access to your Airnode. +A common use case for an authorizer is the [RequesterAuthorizerWithAirnode](/reference/airnode/latest/concepts/authorizers.md#requesterauthorizerwithairnode) authorizer contract developed for Airnode operators to use right out-of-the-box. It allows the whitelisting of requester contracts (with or without expiration timestamps) on a per endpoint basis. Endpoints are declared in the `ois.endpoints` field of the `config.json` file. This is the most common use case and can be implemented with the following steps: + +1. Add the RequesterAuthorizerWithAirnode [authorizer contract address](/reference/airnode/latest/#requesterauthorizerwithairnode) to the array `chains[n].authorizers.requesterEndpointAuthorizers`. +2. After your Airnode is deployed, call the Admin CLI command [set-whitelist-expiration](/reference/airnode/latest/packages/admin-cli.md#set-whitelist-expiration) to add the desired requester contract addresses to the whitelist maintained by RequesterAuthorizerWithAirnode. + +Once implemented, only requester contract addresses you have added to RequesterAuthorizerWithAirnode will have access to your Airnode. diff --git a/docs/reference/airnode/latest/understand/configuring.md b/docs/reference/airnode/latest/understand/configuring.md index 09da2f2f..031f08c5 100644 --- a/docs/reference/airnode/latest/understand/configuring.md +++ b/docs/reference/airnode/latest/understand/configuring.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -An Airnode is deployed or redeployed using configuration values from its -`config.json` and `secrets.env` files. The `config.json` specifies the -[Oracle Integration Specifications OIS](/reference/ois/latest/specification.md) -and other specific configuration details. The `secrets.env` file holds secrets, -such as API keys and chain provider URLs, which are referenced within the -config.json file using interpolation. +An Airnode is deployed or redeployed using configuration values from its `config.json` and `secrets.env` files. The `config.json` specifies the [Oracle Integration Specifications OIS](/reference/ois/latest/specification.md) and other specific configuration details. The `secrets.env` file holds secrets, such as API keys and chain provider URLs, which are referenced within the config.json file using interpolation. > > @@ -41,11 +36,7 @@ The following example files are useful while reading this doc. ## Creating `config.json` -Use the -[config.json template](/reference/airnode/latest/deployment-files/templates/config-json.md) -to build your own Airnode configuration file or alter the -[config.json example](/reference/airnode/latest/deployment-files/examples/config-json.md) -file. There are six root level fields in `config.json`. +Use the [config.json template](/reference/airnode/latest/deployment-files/templates/config-json.md) to build your own Airnode configuration file or alter the [config.json example](/reference/airnode/latest/deployment-files/examples/config-json.md) file. There are six root level fields in `config.json`. - [chains](/reference/airnode/latest/understand/configuring.md#chains) - [nodeSettings](/reference/airnode/latest/understand/configuring.md#nodesettings) @@ -56,15 +47,7 @@ file. There are six root level fields in `config.json`. ### chains -Each row in the `chains` array represents an Ethereum blockchain the Airnode -will serve as identified by the `id`. Currently Airnode only supports Ethereum -blockchains as denoted by `type: "evm"`. There are several supported -blockchains, see them in the -[Airnode contract addresses](/reference/airnode/latest/) doc. You can use -multiple chain providers for each chain and declare multiple chains each with -one of more chain providers. See -[Chains Providers](/reference/airnode/latest/concepts/chain-providers.md) in -_Concepts and Definitions_. +Each row in the `chains` array represents an Ethereum blockchain the Airnode will serve as identified by the `id`. Currently Airnode only supports Ethereum blockchains as denoted by `type: "evm"`. There are several supported blockchains, see them in the [Airnode contract addresses](/reference/airnode/latest/) doc. You can use multiple chain providers for each chain and declare multiple chains each with one of more chain providers. See [Chains Providers](/reference/airnode/latest/concepts/chain-providers.md) in _Concepts and Definitions_. Below is a simple chain array with a single chain provider. @@ -128,42 +111,26 @@ Below is a simple chain array with a single chain provider. ::: info Idiosyncrasies -See the dedicated -[Chain Idiosyncrasies](/reference/airnode/latest/chain-idiosyncrasies.md) -page for chain-specific configuration considerations. +See the dedicated [Chain Idiosyncrasies](/reference/airnode/latest/chain-idiosyncrasies.md) page for chain-specific configuration considerations. ::: #### Considerations: Gas Price Oracle -The gas price oracle strategies are applied in the order that they are listed. -Airnode supports four strategies: `latestBlockPercentileGasPrice`, -`providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and -`constantGasPrice`. The only required strategy is `constantGasPrice` and it is -recommended to place it as the last strategy in the list as it should be the -final fallback for the Airnode to use if all other strategies fail. For more -detail on these strategies, see the -[Gas Price Strategies](/reference/airnode/latest/concepts/gas-prices.md) page. +The gas price oracle strategies are applied in the order that they are listed. Airnode supports four strategies: `latestBlockPercentileGasPrice`, `providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and `constantGasPrice`. The only required strategy is `constantGasPrice` and it is recommended to place it as the last strategy in the list as it should be the final fallback for the Airnode to use if all other strategies fail. For more detail on these strategies, see the [Gas Price Strategies](/reference/airnode/latest/concepts/gas-prices.md) page. #### Considerations: Concurrency -If you set the `maxConcurrency` field to value X, then Airnode will guarantee -that: +If you set the `maxConcurrency` field to value X, then Airnode will guarantee that: - At most X api calls are made to the API -- At most X transactions (made by blockchain providers) will be made by the - blockchain providers of the respective chain +- At most X transactions (made by blockchain providers) will be made by the blockchain providers of the respective chain -When doing this, Airnode will calculate the total number of requests reported by -all blockchain providers. If this number exceeds the maximum concurrency limit, -Airnode will start processing the oldest request from the blockchain providers -until the number of processed requests reaches the limit. All other requests are -dropped and will be processed in the next Airnode run. +When doing this, Airnode will calculate the total number of requests reported by all blockchain providers. If this number exceeds the maximum concurrency limit, Airnode will start processing the oldest request from the blockchain providers until the number of processed requests reaches the limit. All other requests are dropped and will be processed in the next Airnode run. Note that this request dropping happens for each **chain** separately. -For example, if `maxConcurrency` is set to 5 and there are three providers (A, B -and C) and they reported the following requests: +For example, if `maxConcurrency` is set to 5 and there are three providers (A, B and C) and they reported the following requests: - A1, A2, A3, A4 and A5 - B1, B2 and B3 @@ -173,17 +140,13 @@ The above example results in the following requests: A1, A2, B1, B2, and C1. ::: warning -Note, that this limit only applies to the requests initiated on chain. For -example, requests initiated using HTTP gateway are not included in this limit. -Also note that, this limit is configured per chain and the limits of different -chains are unrelated to each other. +Note, that this limit only applies to the requests initiated on chain. For example, requests initiated using HTTP gateway are not included in this limit. Also note that, this limit is configured per chain and the limits of different chains are unrelated to each other. ::: #### References: `chains` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [authorizers](/reference/airnode/latest/deployment-files/config-json.md#authorizers) - [id](/reference/airnode/latest/deployment-files/config-json.md#id) @@ -233,26 +196,15 @@ The `nodeSettings` field holds node-specific (Airnode) configuration parameters. #### Considerations: Cloud Providers -Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are -supported cloud providers for hosting Airnode. Note that while many fields -within `nodeSettings` are required by both, there are some cloud provider -specific fields. For example, `cloudProvider.projectId` is only required with -GCP. Also note that not all cloud provider regions can be deployed to; see the -[cloudProvider.region reference](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider-region) -for more information. +Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are supported cloud providers for hosting Airnode. Note that while many fields within `nodeSettings` are required by both, there are some cloud provider specific fields. For example, `cloudProvider.projectId` is only required with GCP. Also note that not all cloud provider regions can be deployed to; see the [cloudProvider.region reference](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider-region) for more information. #### Considerations: Gateways -Airnode offers two gateways for accessing provider HTTP endpoints without using -the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information -on each of these see the -[HTTP Gateways](/reference/airnode/latest/understand/http-gateways.md) -documentation. Also note that that distinct API keys must be used for each. +Airnode offers two gateways for accessing provider HTTP endpoints without using the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information on each of these see the [HTTP Gateways](/reference/airnode/latest/understand/http-gateways.md) documentation. Also note that that distinct API keys must be used for each. #### References: `nodeSettings` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [cloudProvider](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider) - [cloudProvider.type](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider-type) @@ -279,15 +231,9 @@ Files section: ### triggers -The `triggers` field allow exposes Airnode endpoints from an OIS selectively for -the RRP protocol or via the HTTP gateway. For example, an OIS object may include -10 endpoints, but only two are desired for RRP and all 10 for the gateway. +The `triggers` field allow exposes Airnode endpoints from an OIS selectively for the RRP protocol or via the HTTP gateway. For example, an OIS object may include 10 endpoints, but only two are desired for RRP and all 10 for the gateway. -List the endpoints to serve with the request–response protocol (RRP) under -`triggers.rrp`. List the endpoints to serve with the HTTP gateway under -`triggers.http`. List the endpoints which can be used to get the signed data in -`triggers.httpSignedData`. In most cases create a trigger for each endpoint in -your OIS object. +List the endpoints to serve with the request–response protocol (RRP) under `triggers.rrp`. List the endpoints to serve with the HTTP gateway under `triggers.http`. List the endpoints which can be used to get the signed data in `triggers.httpSignedData`. In most cases create a trigger for each endpoint in your OIS object. ```json "triggers": { @@ -318,65 +264,38 @@ your OIS object. #### Considerations: triggers -The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived -from the `oisTitle` and `endpointName` using the CLI command -[derive-endpoint-id](/reference/airnode/latest/packages/admin-cli.md#derive-endpoint-id). -Remember that an Airnode's config.json file can have more than one OIS object -and that these endpoints can be triggers for `rrp`, `http`, and/or -`httpSignedData` as desired. +The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived from the `oisTitle` and `endpointName` using the CLI command [derive-endpoint-id](/reference/airnode/latest/packages/admin-cli.md#derive-endpoint-id). Remember that an Airnode's config.json file can have more than one OIS object and that these endpoints can be triggers for `rrp`, `http`, and/or `httpSignedData` as desired. #### Considerations: cached responses -When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API -responses on the local filesystem per request ID. This only applies to -blockchain requests. The flow is: +When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API responses on the local filesystem per request ID. This only applies to blockchain requests. The flow is: 1. A request is received from the Blockchain. 1. The Airnode does an HTTP/S call to a remote API based on the request. -1. [with caching enabled] Airnode stores the response on the local filesystem by - request ID. -1. Airnode then follows the usual process of extracting the response, - post-processing it and sending the response back on chain as a fulfillment - callback. -1. After all current requests are processed, Airnode then exits until the next - cycle (the next minute). -1. If during the next cycle, if the Airnode gets the same request and it isn't - fulfilled, it will try and fulfill the request again. Ordinarily, without - caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with - caching enabled it will fulfill the response using the cached API response - value. - -Clearance of the local filesystem cache is dependant on the environment Airnode -runs in. As a guideline: +1. [with caching enabled] Airnode stores the response on the local filesystem by request ID. +1. Airnode then follows the usual process of extracting the response, post-processing it and sending the response back on chain as a fulfillment callback. +1. After all current requests are processed, Airnode then exits until the next cycle (the next minute). +1. If during the next cycle, if the Airnode gets the same request and it isn't fulfilled, it will try and fulfill the request again. Ordinarily, without caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with caching enabled it will fulfill the response using the cached API response value. + +Clearance of the local filesystem cache is dependant on the environment Airnode runs in. As a guideline: - AWS Lambda persists for 2.5 hours. - Google Cloud persistence is completely arbitrary. - Docker persists as long as the container remains running. -If the local filesystem is cleared, the cache is lost and if a repeat request is -received after the cache has been cleared, Airnode will repeat the API call. -Airnode self-clears cached data after the data has reached 1 hour's age. +If the local filesystem is cleared, the cache is lost and if a repeat request is received after the cache has been cleared, Airnode will repeat the API call. Airnode self-clears cached data after the data has reached 1 hour's age. -Furthermore, as an example: "if an Airnode AWS Lambda environment/container" -(since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours -and Airnode gets a request, that request will only be cached until the container -resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. +Furthermore, as an example: "if an Airnode AWS Lambda environment/container" (since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours and Airnode gets a request, that request will only be cached until the container resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. -As described above, caching on serverless infrastructure is unreliable and if -request caching is mission critical, Airnode should be run in a Docker container -with a persistent `/tmp` directory. +As described above, caching on serverless infrastructure is unreliable and if request caching is mission critical, Airnode should be run in a Docker container with a persistent `/tmp` directory. -Caching is useful for non-idempotent API operations like random number -generators. Consider the following use-case: +Caching is useful for non-idempotent API operations like random number generators. Consider the following use-case: -> Random Numbers: in the absence of caching, a malicious blockchain provider can -> selectively block fulfillments containing numbers they don't like, allowing -> them to improve their odds of winning in a random-number betting game. +> Random Numbers: in the absence of caching, a malicious blockchain provider can selectively block fulfillments containing numbers they don't like, allowing them to improve their odds of winning in a random-number betting game. #### References: `triggers` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [rrp](/reference/airnode/latest/deployment-files/config-json.md#rrp) - [rrp[n].endpointId](/reference/airnode/latest/deployment-files/config-json.md#rrp-n-endpointid) @@ -394,13 +313,11 @@ Files section: ### templates -The templates field allows you to specify templates to be used to make template -requests. The array can be left empty if no templates will be used. +The templates field allows you to specify templates to be used to make template requests. The array can be left empty if no templates will be used. #### References: templates -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [templateId](/reference/airnode/latest/deployment-files/config-json.md#templateid) - [endpointId](/reference/airnode/latest/deployment-files/config-json.md#endpointid) @@ -408,23 +325,11 @@ Files section: ### ois -The `ois` field is a list OIS objects that Airnode will be serving. This means -that a single instance of an Airnode can serve multiple APIs. You can simply -copy paste OIS objects that you will be serving into the `ois` list. Use the -previous guide -[API Integration](/reference/airnode/latest/understand/api-integration.md) to -create an OIS object. The full specification is available in the -[Oracle Integration Specifications (OIS)](/reference/ois/latest/) documentation. +The `ois` field is a list OIS objects that Airnode will be serving. This means that a single instance of an Airnode can serve multiple APIs. You can simply copy paste OIS objects that you will be serving into the `ois` list. Use the previous guide [API Integration](/reference/airnode/latest/understand/api-integration.md) to create an OIS object. The full specification is available in the [Oracle Integration Specifications (OIS)](/reference/ois/latest/) documentation. ### apiCredentials -Each entry in `apiCredentials` maps to a security scheme defined in an OIS -(`ois[n].components.securitySchemes.{securitySchemeName}` and -`ois[n].security`), where `oisTitle` is the `title` field of the related OIS, -and `securitySchemeName` is the name of the respective security scheme. These -would be `myOisTitle` and `mySecurityScheme` in the example below. -`securitySchemeValue` is the value used for the authentication with the security -scheme (e.g., the API key). +Each entry in `apiCredentials` maps to a security scheme defined in an OIS (`ois[n].components.securitySchemes.{securitySchemeName}` and `ois[n].security`), where `oisTitle` is the `title` field of the related OIS, and `securitySchemeName` is the name of the respective security scheme. These would be `myOisTitle` and `mySecurityScheme` in the example below. `securitySchemeValue` is the value used for the authentication with the security scheme (e.g., the API key). If no security scheme is needed, leave the `apiCredentials` array empty. @@ -461,14 +366,11 @@ If no security scheme is needed, leave the `apiCredentials` array empty. #### Considerations: apiCredentials -Currently Airnode supports the following security scheme types when making API -calls: `apiKey` and `http`. For more detail, visit the previous section on -[API Security](/reference/airnode/latest/understand/api-security.md). +Currently Airnode supports the following security scheme types when making API calls: `apiKey` and `http`. For more detail, visit the previous section on [API Security](/reference/airnode/latest/understand/api-security.md). #### References: `apiCredentials` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [oisTitle](/reference/airnode/latest/deployment-files/config-json.md#oistitle) - [securitySchemeName](/reference/airnode/latest/deployment-files/config-json.md#securityschemename) @@ -476,10 +378,7 @@ Files section: ## Creating `secrets.env` -The `secrets.env` file contains values (secrets) such as blockchain provider -urls, chain provider urls, etc. These secrets are embedded in -[config.json](/reference/airnode/latest/deployment-files/config-json.md) using -interpolation. +The `secrets.env` file contains values (secrets) such as blockchain provider urls, chain provider urls, etc. These secrets are embedded in [config.json](/reference/airnode/latest/deployment-files/config-json.md) using interpolation. ```json // Sample interpolation value from config.json @@ -493,25 +392,15 @@ interpolation. HEARTBEAT_API_KEY="d714a900-3b9e-4e4d-8eae-756ef06a8836" ``` -Use the -[secrets.env](/reference/airnode/latest/deployment-files/templates/secrets-env.md) -template and refer to -[Reference > Deployment Files > secrets.env](/reference/airnode/latest/deployment-files/secrets-env.md) -as needed. +Use the [secrets.env](/reference/airnode/latest/deployment-files/templates/secrets-env.md) template and refer to [Reference > Deployment Files > secrets.env](/reference/airnode/latest/deployment-files/secrets-env.md) as needed. ## AWS setup (AWS deployment only) -When it is time to deploy the Airnode to AWS, the Docker -[deployer image](/reference/airnode/latest/docker/deployer-image.md) will need -the AWS credentials to build the node on AWS Lambda. +When it is time to deploy the Airnode to AWS, the Docker [deployer image](/reference/airnode/latest/docker/deployer-image.md) will need the AWS credentials to build the node on AWS Lambda. ### Creating `aws.env` (AWS only) -Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It -explains how to create an IAM user and get security credentials. Put them in the -`aws.env` file as shown below. See an -[example file](/reference/airnode/latest/deployment-files/templates/aws-env.md) -in the reference section. +Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It explains how to create an IAM user and get security credentials. Put them in the `aws.env` file as shown below. See an [example file](/reference/airnode/latest/deployment-files/templates/aws-env.md) in the reference section. - Variable names cannot contain dashes (-) or start with a number. @@ -522,46 +411,26 @@ AWS_SECRET_ACCESS_KEY=ABC7...89 ## GCP setup (GCP deployment only) -When it is time to deploy the Airnode to GCP, the Docker -[deployer image](/reference/airnode/latest/docker/deployer-image.md) will need -the GCP project ID to build the Airnode. +When it is time to deploy the Airnode to GCP, the Docker [deployer image](/reference/airnode/latest/docker/deployer-image.md) will need the GCP project ID to build the Airnode. ### Creating a GCP project -First -[create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) -under which will the Airnode be deployed. Once the project is created, insert -its -[projectId](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider) -into the `config.json` file. +First [create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) under which will the Airnode be deployed. Once the project is created, insert its [projectId](/reference/airnode/latest/deployment-files/config-json.md#cloudprovider) into the `config.json` file. ### Enable required API -In order for Airnode to deploy successfully, enable -[App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) -for the GCP project. After enabling it, wait a few minutes before the deployment -itself so the change will take place. +In order for Airnode to deploy successfully, enable [App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) for the GCP project. After enabling it, wait a few minutes before the deployment itself so the change will take place. ### Creating a Service Account -Create a new service account from the -[Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) -menu. Grant this service account access to the project by adding a role `Owner` -during the creation process. +Create a new service account from the [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) menu. Grant this service account access to the project by adding a role `Owner` during the creation process. -Once the account is created, add a new access key of type JSON for this account. -Download the key file as `gcp.json` into the root of your project. +Once the account is created, add a new access key of type JSON for this account. Download the key file as `gcp.json` into the root of your project. ## Summary -In this guide you created the `config.json`, `secrets.env` and obtained cloud -provider credentials required to deploy an Airnode to a cloud provider. Note -that `config.json` is user-specific and therefore it is not much use to others. +In this guide you created the `config.json`, `secrets.env` and obtained cloud provider credentials required to deploy an Airnode to a cloud provider. Note that `config.json` is user-specific and therefore it is not much use to others. -The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider -urls and security credentials, so they should be kept secret. Make sure that you -do not push your credentials to a repository or otherwise expose them as these -credentials can be used to gain access to your Airnode's private key, AWS -account or GCP account. +The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider urls and security credentials, so they should be kept secret. Make sure that you do not push your credentials to a repository or otherwise expose them as these credentials can be used to gain access to your Airnode's private key, AWS account or GCP account. diff --git a/docs/reference/airnode/latest/understand/deploying.md b/docs/reference/airnode/latest/understand/deploying.md index 48466ede..6d3d6e43 100644 --- a/docs/reference/airnode/latest/understand/deploying.md +++ b/docs/reference/airnode/latest/understand/deploying.md @@ -19,49 +19,21 @@ tags: # {{$frontmatter.title}} -After integrating an API -([API Integration](/reference/airnode/latest/understand/api-integration.md)) and -creating the configuration files -([Configuring Airnode](/reference/airnode/latest/understand/configuring.md)), -the next step is to deploy the Airnode. +After integrating an API ([API Integration](/reference/airnode/latest/understand/api-integration.md)) and creating the configuration files ([Configuring Airnode](/reference/airnode/latest/understand/configuring.md)), the next step is to deploy the Airnode. ## Deploy with Docker -The recommended way to deploy Airnode is by using the Docker -[deployer image](/reference/airnode/latest/docker/deployer-image.md). This image -is simply a wrapper around the -[deployer CLI](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer). -Try the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -tutorial if you wish to become familiar with the deployer image first. There are -also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a -[client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as -well as several repo based examples in the -[Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) -package. - -The deployer interacts with a cloud provider to deploy Airnode programmatically, -without requiring you to click through a lot of ever-changing graphical -interfaces. For it to do so, a cloud project setup and credentials are required -and was discussed in -[Configuring an Airnode](/reference/airnode/latest/understand/configuring.md#aws-setup-aws-deployment-only). -There is additional guidance in the AWS and GCP quick start tutorials mentioned -above. +The recommended way to deploy Airnode is by using the Docker [deployer image](/reference/airnode/latest/docker/deployer-image.md). This image is simply a wrapper around the [deployer CLI](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer). Try the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) tutorial if you wish to become familiar with the deployer image first. There are also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a [client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as well as several repo based examples in the [Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) package. + +The deployer interacts with a cloud provider to deploy Airnode programmatically, without requiring you to click through a lot of ever-changing graphical interfaces. For it to do so, a cloud project setup and credentials are required and was discussed in [Configuring an Airnode](/reference/airnode/latest/understand/configuring.md#aws-setup-aws-deployment-only). There is additional guidance in the AWS and GCP quick start tutorials mentioned above. ## Install Docker -The [deployer image](/reference/airnode/latest/docker/deployer-image.md) is -containerized as a Docker image. This will deploy the Airnode to the cloud -provider without the worry of installing dependencies and is the recommended way -to do a deployment. If you do not already have docker installed go to the -[Docker website](https://docs.docker.com/get-docker/) and install it. +The [deployer image](/reference/airnode/latest/docker/deployer-image.md) is containerized as a Docker image. This will deploy the Airnode to the cloud provider without the worry of installing dependencies and is the recommended way to do a deployment. If you do not already have docker installed go to the [Docker website](https://docs.docker.com/get-docker/) and install it. ## Deployment -At this point a project should resemble the following. The `config.json`, -`secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to -GCP) files should be ready to go. Other files and folders added to the project -are expected and are ignored by the deployer image. +At this point a project should resemble the following. The `config.json`, `secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to GCP) files should be ready to go. Other files and folders added to the project are expected and are ignored by the deployer image. ::: code-group @@ -84,13 +56,7 @@ my-airnode -From the root of the project directory run the Docker image command -[deploy](/reference/airnode/latest/docker/deployer-image.md#deploy) as shown -below to deploy the Airnode. When the deployment has completed a `receipt.json` -file will be written to the project directory, which is mounted to the -`/app/config` directory within the container. This file contains important -configuration information about the Airnode and is needed to remove the Airnode -should the need arise. +From the root of the project directory run the Docker image command [deploy](/reference/airnode/latest/docker/deployer-image.md#deploy) as shown below to deploy the Airnode. When the deployment has completed a `receipt.json` file will be written to the project directory, which is mounted to the `/app/config` directory within the container. This file contains important configuration information about the Airnode and is needed to remove the Airnode should the need arise.

@@ -114,10 +80,7 @@ docker run -it --rm ^ ### receipt.json -The `receipt.json` file is a product of a deployment attempt. It contains -Airnode configuration and deployment information and is used to remove the -Airnode. The field `success` is important in that it specifies whether the -deployment was successful or not. +The `receipt.json` file is a product of a deployment attempt. It contains Airnode configuration and deployment information and is used to remove the Airnode. The field `success` is important in that it specifies whether the deployment was successful or not. ```json { @@ -142,9 +105,7 @@ deployment was successful or not. ## Testing with HTTP Gateway -If you opted to enable the HTTP Gateway it can be used to test the Airnode while -bypassing the chain it was deployed to. There are examples that detail how to do -this. +If you opted to enable the HTTP Gateway it can be used to test the Airnode while bypassing the chain it was deployed to. There are examples that detail how to do this. - [HTTP Gateways](/reference/airnode/latest/understand/http-gateways.md#using-curl) - [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/#_5-test-the-airnode) @@ -153,15 +114,10 @@ this. ## Make an RRP request of the Airnode -Once the Airnode is deployed, see -[Calling an Airnode](/reference/airnode/latest/developers/index.md) to learn how -requests are made using the request-response protocol (RRP). +Once the Airnode is deployed, see [Calling an Airnode](/reference/airnode/latest/developers/index.md) to learn how requests are made using the request-response protocol (RRP). ## Removing the Airnode -If you would like to remove a deployed Airnode, see the Docker image commands -for [remove](/reference/airnode/latest/docker/deployer-image.md#remove) or -[remove-with-receipt](/reference/airnode/latest/docker/deployer-image.md#remove-with-receipt) -instructions. +If you would like to remove a deployed Airnode, see the Docker image commands for [remove](/reference/airnode/latest/docker/deployer-image.md#remove) or [remove-with-receipt](/reference/airnode/latest/docker/deployer-image.md#remove-with-receipt) instructions. diff --git a/docs/reference/airnode/latest/understand/heartbeat.md b/docs/reference/airnode/latest/understand/heartbeat.md index f37168e8..c088d228 100644 --- a/docs/reference/airnode/latest/understand/heartbeat.md +++ b/docs/reference/airnode/latest/understand/heartbeat.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -At the end of an Airnode's run (every minute), Airnode can make an HTTP POST -request to a specified URL. This is both to signal that the Airnode is alive and -working (useful especially right after the deployment) and also as a -notification every time it runs (self-operates). +At the end of an Airnode's run (every minute), Airnode can make an HTTP POST request to a specified URL. This is both to signal that the Airnode is alive and working (useful especially right after the deployment) and also as a notification every time it runs (self-operates). > > @@ -31,8 +28,7 @@ notification every time it runs (self-operates). > 3.

A response is sent to each request.

> 4.

Finally Airnode makes a request to the heartbeat URL (HTTP POST). This could be to an operation within the API Airnode supports or to any cloud REST endpoint such as a monitoring service.

-Turn on the optional heartbeat functionality by setting all fields in the -`config.json` section for `nodeSettings.heartbeat`. +Turn on the optional heartbeat functionality by setting all fields in the `config.json` section for `nodeSettings.heartbeat`. ```json{12-16} { @@ -95,8 +91,7 @@ The table below illustrates the parameters passed to the Heartbeat URL. | oev_gateway_url | body | string | | signature | body | string | -Below is an example of what is included in the request body. Note that -`airnode-heartbeat-api-key` can be found in the request header and not the body. +Below is an example of what is included in the request body. Note that `airnode-heartbeat-api-key` can be found in the request header and not the body. ```json { @@ -117,18 +112,13 @@ Below is an example of what is included in the request body. Note that The method by which the heartbeat payload is generated is as follows: -- An object is marshalled to JSON - this object contains multiple fields as - shown above. -- The Airnode's mnemonic (using the default EVM derivation path to derive a key) - is used to sign the payload. +- An object is marshalled to JSON - this object contains multiple fields as shown above. +- The Airnode's mnemonic (using the default EVM derivation path to derive a key) is used to sign the payload. - The payload and signature are included in a new object and marshalled to JSON. -The reason this nested JSON approach has been used is to prevent subtle -inconsistencies between JSON marshallers in different languages causing the -signature to not match the payload. +The reason this nested JSON approach has been used is to prevent subtle inconsistencies between JSON marshallers in different languages causing the signature to not match the payload. -The airnode's public key can be recovered from this signature and be used, -generally, to verify the authenticity of the payload. +The airnode's public key can be recovered from this signature and be used, generally, to verify the authenticity of the payload. The overall content to the heartbeat URL is as follows: diff --git a/docs/reference/airnode/latest/understand/http-gateways.md b/docs/reference/airnode/latest/understand/http-gateways.md index 6e0e07bb..dc8be423 100644 --- a/docs/reference/airnode/latest/understand/http-gateways.md +++ b/docs/reference/airnode/latest/understand/http-gateways.md @@ -19,35 +19,24 @@ tags: # {{$frontmatter.title}} -As part of the Airnode deployment you can decide to deploy two different HTTP -Gateways. +As part of the Airnode deployment you can decide to deploy two different HTTP Gateways. - HTTP Gateway: testing - HTTP Signed Data Gateway: production use ## Gateway Differences -Both gateways are setup identically. The differences are in their purpose and -response. +Both gateways are setup identically. The differences are in their purpose and response. > ### HTTP Gateway -The regular HTTP gateway is strictly for testing purposes. Using a simple tool -like CURL you can test that endpoints in the Airnode configuration are working -properly without accessing the blockchain. +The regular HTTP gateway is strictly for testing purposes. Using a simple tool like CURL you can test that endpoints in the Airnode configuration are working properly without accessing the blockchain. -In order to facilitate configuration and testing of parameters, HTTP gateway -requests have the following differences in handling when compared to blockchain -requests or requests to the HTTP signed data gateway: +In order to facilitate configuration and testing of parameters, HTTP gateway requests have the following differences in handling when compared to blockchain requests or requests to the HTTP signed data gateway: -1. When a request's API call is successful but then that response fails - extraction and encoding, data are still returned. This is in contrast to the - other types of requests for which only an error would be returned. The API - call response, after undergoing any - [post-processing](/reference/ois/latest/processing.md), will be present in - the `rawValue` field independent of encoding success or failure: +1. When a request's API call is successful but then that response fails extraction and encoding, data are still returned. This is in contrast to the other types of requests for which only an error would be returned. The API call response, after undergoing any [post-processing](/reference/ois/latest/processing.md), will be present in the `rawValue` field independent of encoding success or failure: ```json { @@ -55,29 +44,19 @@ requests or requests to the HTTP signed data gateway: } ``` -2. Reserved parameters are inaccessible in response pre/post processing. This is - only relevant if reserved parameters are being _modified_ in pre/post - processing (advanced use case). +2. Reserved parameters are inaccessible in response pre/post processing. This is only relevant if reserved parameters are being _modified_ in pre/post processing (advanced use case). ### HTTP Signed Data Gateway -The HTTP signed data gateway is used for production purposes. While it is -executed in a similar way as the HTTP gateway, its response is signed and does -not contain a `rawValue` field. This gateway is executed by an off-chain code -source that may in turn push data to a blockchain. +The HTTP signed data gateway is used for production purposes. While it is executed in a similar way as the HTTP gateway, its response is signed and does not contain a `rawValue` field. This gateway is executed by an off-chain code source that may in turn push data to a blockchain. ## Setup -Enable either gateway in the `config.json` file fields -`nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. +Enable either gateway in the `config.json` file fields `nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. - **enabled**: A boolean to enable/disable the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless function instance serving gateway requests. When - omitted, there is no maximum concurrency set. This field is ignored for - Airnode client gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless function instance serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -101,10 +80,7 @@ Enable either gateway in the `config.json` file fields }, ``` -Add the desired endpoints a gateway can respond to in the `triggers.http[n]` -and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need -to match. It could be practical to test all endpoints but only serve certain -endpoints using the HTTP signed data gateway or via RRP. +Add the desired endpoints a gateway can respond to in the `triggers.http[n]` and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need to match. It could be practical to test all endpoints but only serve certain endpoints using the HTTP signed data gateway or via RRP. ```json // in config.json @@ -134,50 +110,28 @@ endpoints using the HTTP signed data gateway or via RRP. ## Gateway URLs -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URLs should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URLs should be kept secret. -The gateway URLs are also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/latest/understand/heartbeat.md) to a specified -heartbeat URL. +The gateway URLs are also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/latest/understand/heartbeat.md) to a specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated for each gateway (when enabled) when Airnode is -deployed. The URL including, the secret `UUID` path parameter, is displayed on -the terminal at the end of an Airnode deployment using the -[Docker image](/reference/airnode/latest/docker/deployer-image.md). +A gateway URL is generated for each gateway (when enabled) when Airnode is deployed. The URL including, the secret `UUID` path parameter, is displayed on the terminal at the end of an Airnode deployment using the [Docker image](/reference/airnode/latest/docker/deployer-image.md). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for both gateways, which is exposed on the host machine. -Doing so will make the gateways API accessible like a regular web server running -on the machine. Each gateway has a separate endpoint as shown below. Note the -`PORT` which is exposed as part of the Airnode client container. See the -[Airnode client usage](/reference/airnode/latest/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for both gateways, which is exposed on the host machine. Doing so will make the gateways API accessible like a regular web server running on the machine. Each gateway has a separate endpoint as shown below. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/latest/docker/client-image.md#usage) for more details. -- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Gateway -- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Signed Data Gateway +- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Gateway +- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Signed Data Gateway ## Using CURL -In order to execute an endpoint served by either gateway, the following are -required as part of the CURL call. +In order to execute an endpoint served by either gateway, the following are required as part of the CURL call. -- Make a POST request with the `endpointId` as a path parameter. An `endpointId` - can found in config.json under `triggers.http.endpointId` or - `triggers.httpSignedData.endpointId`. +- Make a POST request with the `endpointId` as a path parameter. An `endpointId` can found in config.json under `triggers.http.endpointId` or `triggers.httpSignedData.endpointId`. - Add the `Content-Type` header, set to `application/json`. - Place the parameters/encodedParameters in the request body. @@ -192,15 +146,11 @@ required as part of the CURL call. | \* parameters
HTTP Gateway
| body | `-d '{"parameters": {"param1": "myValue", "param2": 5}}'` | | \* encodedParameters
HTTP Signed Data Gateway
| body | `-d '{"encodedParameters": "0x3173737300....000"}'` | -\* Parameters for the gateways are named differently. The HTTP signed data -gateway requires that the `encodedParameters` be encoded using -[Airnode ABI](/reference/airnode/latest/specifications/airnode-abi.md). +\* Parameters for the gateways are named differently. The HTTP signed data gateway requires that the `encodedParameters` be encoded using [Airnode ABI](/reference/airnode/latest/specifications/airnode-abi.md). ### Request -Replace `` in the examples below with the URL displayed in the -terminal at the end of an Airnode deployment using a -[Docker image](/reference/airnode/latest/docker/). +Replace `` in the examples below with the URL displayed in the terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/latest/docker/). ::: code-group diff --git a/docs/reference/airnode/latest/understand/index.md b/docs/reference/airnode/latest/understand/index.md index 6ba4a427..957c84d5 100644 --- a/docs/reference/airnode/latest/understand/index.md +++ b/docs/reference/airnode/latest/understand/index.md @@ -19,17 +19,11 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that pushes off-chain API data on-chain via data -feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs -off-chain as a background component of the API3 ecosystem. **Understanding -Airnode** is a progression of pages that provides a detailed understanding of -the capabilities and functionality of Airnode. +Airnode is a first-party oracle that pushes off-chain API data on-chain via data feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs off-chain as a background component of the API3 ecosystem. **Understanding Airnode** is a progression of pages that provides a detailed understanding of the capabilities and functionality of Airnode. ## Project Folder -A typical Airnode project folder contains files used to define the Airnode. Show -below are typical project folders for each of AWS, GCP, and container -deployments. +A typical Airnode project folder contains files used to define the Airnode. Show below are typical project folders for each of AWS, GCP, and container deployments. ::: code-group @@ -55,12 +49,7 @@ my-airnode ::: code-group -Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the -files in the -[Templates](/reference/airnode/latest/deployment-files/templates/config-json.md) -as an aid to create all but the `gcp.json` files. Also see the -[Examples](/reference/airnode/latest/deployment-files/examples/config-json.md) -for demonstration purposes. +Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the files in the [Templates](/reference/airnode/latest/deployment-files/templates/config-json.md) as an aid to create all but the `gcp.json` files. Also see the [Examples](/reference/airnode/latest/deployment-files/examples/config-json.md) for demonstration purposes. ## Configuration files @@ -69,57 +58,40 @@ for demonstration purposes. - `aws.env`: AWS credentials. - `gcp.json`: GCP project information. -The diagrams below depict the configuration files needed for a successful -deployment of an Airnode to AWS, GCP, and a Docker Container. +The diagrams below depict the configuration files needed for a successful deployment of an Airnode to AWS, GCP, and a Docker Container. ### AWS -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **aws.env**: Contains AWS credentials required by the Docker deployer image. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### GCP -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **gcp.json**: GCP project file. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### Container -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. -3. **client image**: The Docker client image that contains the Airnode and runs - with the provided configuration. +3. **client image**: The Docker client image that contains the Airnode and runs with the provided configuration. ## Deploying -There are two ways to deploy and run an Airnode. The most popular is with a -cloud provider such as AWS or GCP. Use the Docker -[Airnode Deployer Image](/reference/airnode/latest/docker/deployer-image.md) for -these type of deployments. - -The second method is to run a containerized Airnode hosted internally or with a -cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker -[Airnode Client Image](/reference/airnode/latest/docker/client-image.md) for -this type of deployment. - -Try the guide AWS -[Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) -as a quick introduction to an Airnode deployment. Also be sure to visit -[ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an -Airnode. +There are two ways to deploy and run an Airnode. The most popular is with a cloud provider such as AWS or GCP. Use the Docker [Airnode Deployer Image](/reference/airnode/latest/docker/deployer-image.md) for these type of deployments. + +The second method is to run a containerized Airnode hosted internally or with a cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker [Airnode Client Image](/reference/airnode/latest/docker/client-image.md) for this type of deployment. + +Try the guide AWS [Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) as a quick introduction to an Airnode deployment. Also be sure to visit [ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an Airnode. diff --git a/docs/reference/airnode/latest/understand/monitor.md b/docs/reference/airnode/latest/understand/monitor.md index 252ec03a..cc0fec56 100644 --- a/docs/reference/airnode/latest/understand/monitor.md +++ b/docs/reference/airnode/latest/understand/monitor.md @@ -19,43 +19,24 @@ tags: # {{$frontmatter.title}} -Airnode logs or log groups are named similarly in AWS and GCP and include the -following hyphen-separated components: `airnode`, ``, -``, and ``, for example, -`airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages -or request types and the logs they contain are as follows: - -- `startCoordinator`: Logs for chain provider initialization and request - fetching +Airnode logs or log groups are named similarly in AWS and GCP and include the following hyphen-separated components: `airnode`, ``, ``, and ``, for example, `airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages or request types and the logs they contain are as follows: + +- `startCoordinator`: Logs for chain provider initialization and request fetching - `run`: Logs of API calls and withdrawals originating from blockchain requests -- `httpReq`: Logs for - [HTTP gateway requests](/reference/airnode/latest/understand/http-gateways.md#http-gateway) -- `httpSignedReq`: Logs for - [HTTP signed data gateway requests](/reference/airnode/latest/understand/http-gateways.md) -- `signOevReq`: Logs for - [OEV gateway requests](/reference/airnode/latest/understand/oev-gateway.md) +- `httpReq`: Logs for [HTTP gateway requests](/reference/airnode/latest/understand/http-gateways.md#http-gateway) +- `httpSignedReq`: Logs for [HTTP signed data gateway requests](/reference/airnode/latest/understand/http-gateways.md) +- `signOevReq`: Logs for [OEV gateway requests](/reference/airnode/latest/understand/oev-gateway.md) ### AWS -Airnode logs are available in -[CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. -Note that for the HTTP gateways, AWS generates a unique `requestId` for each -request. These should not be confused with the `requestId` of a request -originating from a blockchain. +Airnode logs are available in [CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. Note that for the HTTP gateways, AWS generates a unique `requestId` for each request. These should not be confused with the `requestId` of a request originating from a blockchain. ### GCP -Airnode logs are available in the -[Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to -query or stream logs by the "Cloud Function" Resource Type and then by "Function -Name" in order to view a specific request type or Airnode cycle stage. +Airnode logs are available in the [Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to query or stream logs by the "Cloud Function" Resource Type and then by "Function Name" in order to view a specific request type or Airnode cycle stage. ## Local Airnode Client -Running the `airnode-client` Docker image will output container logs to the -command line. These logs are also available through the Docker interface e.g. -under Containers within Docker Desktop. See the Docker -[client image](/reference/airnode/latest/docker/client-image.md) for more -information. +Running the `airnode-client` Docker image will output container logs to the command line. These logs are also available through the Docker interface e.g. under Containers within Docker Desktop. See the Docker [client image](/reference/airnode/latest/docker/client-image.md) for more information. diff --git a/docs/reference/airnode/latest/understand/oev-gateway.md b/docs/reference/airnode/latest/understand/oev-gateway.md index eb6d7dd2..459932da 100644 --- a/docs/reference/airnode/latest/understand/oev-gateway.md +++ b/docs/reference/airnode/latest/understand/oev-gateway.md @@ -19,23 +19,15 @@ tags: # {{$frontmatter.title}} -OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The -data is signed by the Airnode so that only the searcher who won the auction can -use it to update the data feed. You can learn more about OEV at -https://api3.org. +OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The data is signed by the Airnode so that only the searcher who won the auction can use it to update the data feed. You can learn more about OEV at https://api3.org. ## Setup -Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` -section. +Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` section. - **enabled**: A boolean to enable/disable for the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless functions serving gateway requests. When omitted, - there is no maximum concurrency set. This field is ignored for Airnode client - gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless functions serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -56,44 +48,25 @@ section. ## Gateway URL -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URL should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URL should be kept secret. -The gateway URL is also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/latest/understand/heartbeat.md) to your specified -heartbeat URL. +The gateway URL is also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/latest/understand/heartbeat.md) to your specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated when Airnode is deployed. You can see the URLs -including the secret `UUID` path parameter, displayed on your terminal at the -end of an Airnode deployment using a -[Docker image](/reference/airnode/latest/docker/). +A gateway URL is generated when Airnode is deployed. You can see the URLs including the secret `UUID` path parameter, displayed on your terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/latest/docker/). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for the gateway, which is exposed on the host machine. -Doing so will make the gateway API accessible like a regular web server running -on the machine. Note the `PORT` which is exposed as part of the Airnode client -container. See the -[Airnode client usage](/reference/airnode/latest/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for the gateway, which is exposed on the host machine. Doing so will make the gateway API accessible like a regular web server running on the machine. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/latest/docker/client-image.md#usage) for more details. -- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - - Gateway URL for the OEV Gateway +- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - Gateway URL for the OEV Gateway ## Usage -In order to execute the processing on the gateway, it needs to receive a -properly constructed HTTP request: +In order to execute the processing on the gateway, it needs to receive a properly constructed HTTP request: - It must be a `POST` request - It must contain a `Content-Type` header, set to `application/json`. @@ -134,8 +107,7 @@ where: - `updateId` - Auction update ID. - `bidderAddress` - Blockchain address of the winning searcher. - `bidAmount` - Bid amount that won the auction. -- `beacons` - A list of beacon data to be signed. It can contain two types: full - beacon data, only beacon metadata +- `beacons` - A list of beacon data to be signed. It can contain two types: full beacon data, only beacon metadata - `airnodeAddress` - Airnode address identifying a beacon - `templateId` - Template ID identifying a beacon - `signedData` - The signed beacon data received from signed data gateway. @@ -177,8 +149,6 @@ curl --location '' \ ] ``` -The gateway will return a list of signatures. There is a signature for each -beacon within the data feed that is served by the given Airnode, returned in the -same order as they are specified in the request body. +The gateway will return a list of signatures. There is a signature for each beacon within the data feed that is served by the given Airnode, returned in the same order as they are specified in the request body. diff --git a/docs/reference/airnode/latest/understand/using-authorizations.md b/docs/reference/airnode/latest/understand/using-authorizations.md index ff283a38..8bd163a9 100644 --- a/docs/reference/airnode/latest/understand/using-authorizations.md +++ b/docs/reference/airnode/latest/understand/using-authorizations.md @@ -19,39 +19,22 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using -[Authorizations](/reference/airnode/latest/concepts/authorizations.md). This -method is off-chain and requires no blockchain knowledge by an API provider. It -is different than -[Authorizers](/reference/airnode/latest/concepts/authorizers.md) which is an -on-chain auth scheme. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizations](/reference/airnode/latest/concepts/authorizations.md). This method is off-chain and requires no blockchain knowledge by an API provider. It is different than [Authorizers](/reference/airnode/latest/concepts/authorizers.md) which is an on-chain auth scheme. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/latest/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: -Authorizations use scheme types that hard-code access to an Airnode's endpoints -in the same file that defines the Airnode, its `config.json` file. These -hard-coded values are endpointId/address pairs that the Airnode will use to -allow access to its endpoints by requesters (smart contracts). +Authorizations use scheme types that hard-code access to an Airnode's endpoints in the same file that defines the Airnode, its `config.json` file. These hard-coded values are endpointId/address pairs that the Airnode will use to allow access to its endpoints by requesters (smart contracts). -Nothing in _authorizers_ can supersede permissions granted by _authorizations_ -as the latter takes precedence. -Currently there is only one _authorizations_ scheme type, -`requesterEndpointAuthorizations`. +Nothing in _authorizers_ can supersede permissions granted by _authorizations_ as the latter takes precedence. +Currently there is only one _authorizations_ scheme type, `requesterEndpointAuthorizations`. ## requesterEndpointAuthorizations -Currently `requesterEndpointAuthorizations` is the only scheme type available -for _authorizations_. It defines a list of endpointIds each with a array of -requester addresses that can access them. +Currently `requesterEndpointAuthorizations` is the only scheme type available for _authorizations_. It defines a list of endpointIds each with a array of requester addresses that can access them. ```json { diff --git a/docs/reference/airnode/latest/versions.md b/docs/reference/airnode/latest/versions.md index 96c718dd..dfd02f7b 100644 --- a/docs/reference/airnode/latest/versions.md +++ b/docs/reference/airnode/latest/versions.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The latest version of Airnode is `v0.14.x`. See -[releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for -all Airnode versions. Below is a list of Airnode versions included in this -documentation website. Each can be accessed via the Airnode selector at the top -of the left sidebar under Reference. +The latest version of Airnode is `v0.14.x`. See [releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for all Airnode versions. Below is a list of Airnode versions included in this documentation website. Each can be accessed via the Airnode selector at the top of the left sidebar under Reference. | | | ------- | @@ -34,9 +30,7 @@ of the left sidebar under Reference. ## Other Versions -Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their -documentation is available at -[https://old-docs.api3.org](https://old-docs.api3.org). +Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their documentation is available at [https://old-docs.api3.org](https://old-docs.api3.org). | | | --------------------------------------------------------- | diff --git a/docs/reference/airnode/next/chain-idiosyncrasies.md b/docs/reference/airnode/next/chain-idiosyncrasies.md index 08dc95c5..aedae5ac 100644 --- a/docs/reference/airnode/next/chain-idiosyncrasies.md +++ b/docs/reference/airnode/next/chain-idiosyncrasies.md @@ -19,60 +19,28 @@ tags: # {{$frontmatter.title}} -Differences in chain design inevitably lead to some unique chain-specific -considerations. Below are idiosyncrasies we have identified, though it may not -be comprehensive and we are interested in hearing if you encounter others. +Differences in chain design inevitably lead to some unique chain-specific considerations. Below are idiosyncrasies we have identified, though it may not be comprehensive and we are interested in hearing if you encounter others. ## config.json - `chains` field -The idiosyncrasies below relate to the `chains` field of `config.json` discussed -in -[Configuring Airnode](/reference/airnode/next/understand/configuring.md#chains) -and -[Deployment Files](/reference/airnode/next/deployment-files/config-json.md#chains) -section. +The idiosyncrasies below relate to the `chains` field of `config.json` discussed in [Configuring Airnode](/reference/airnode/next/understand/configuring.md#chains) and [Deployment Files](/reference/airnode/next/deployment-files/config-json.md#chains) section. ### Avalanche -Gas prices on Avalanche mainnet are often underestimated when getting `type 0` -estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error -manifests as the `maxFeePerGas` being set to less than the block -`baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set -`recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. +Gas prices on Avalanche mainnet are often underestimated when getting `type 0` estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error manifests as the `maxFeePerGas` being set to less than the block `baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set `recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. ### Arbitrum -Execution costs on Arbitrum are calculated slightly differently than Ethereum, -which impacts the gas required to fulfill requests. To account for this, it is -recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when -using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is -optional, so if it is not specified, Airnode will attempt to estimate the -appropriate gas limit automatically. Read more about -[ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. +Execution costs on Arbitrum are calculated slightly differently than Ethereum, which impacts the gas required to fulfill requests. To account for this, it is recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. Read more about [ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. ### Metis -On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is -recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that -`fulfillmentGasLimit` is optional, so if it is not specified, Airnode will -attempt to estimate the appropriate gas limit automatically. +On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. ### Optimism -Using `type 0` transaction types is recommended over `type 2` so the use of -`providerRecommendedEip1559GasPrice` is discouraged. - -As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, -which are -[accounted for separately](https://docs.optimism.io/stack/transactions/fees). To -cover the L1 data fee when a sponsor requests a -[withdrawal](/reference/airnode/next/concepts/sponsor.md#withdrawals), an amount -has to be subtracted from the funds returned to the sponsor. The -`withdrawalRemainder` parameter has been introduced specifically for this -reason, though the value required will differ between Optimism mainnet and -testnet due to differences in L1 gas fees. For Optimism testnet, a -`withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a -value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover -an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. +Using `type 0` transaction types is recommended over `type 2` so the use of `providerRecommendedEip1559GasPrice` is discouraged. + +As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, which are [accounted for separately](https://docs.optimism.io/stack/transactions/fees). To cover the L1 data fee when a sponsor requests a [withdrawal](/reference/airnode/next/concepts/sponsor.md#withdrawals), an amount has to be subtracted from the funds returned to the sponsor. The `withdrawalRemainder` parameter has been introduced specifically for this reason, though the value required will differ between Optimism mainnet and testnet due to differences in L1 gas fees. For Optimism testnet, a `withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. diff --git a/docs/reference/airnode/next/cloud-resources.md b/docs/reference/airnode/next/cloud-resources.md index a5421bf2..4476de15 100644 --- a/docs/reference/airnode/next/cloud-resources.md +++ b/docs/reference/airnode/next/cloud-resources.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain -resources to fully operate and supports most regions. +When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain resources to fully operate and supports most regions. ## Resources diff --git a/docs/reference/airnode/next/concepts/airnode-auth.md b/docs/reference/airnode/next/concepts/airnode-auth.md index 6be3f028..332f2e63 100644 --- a/docs/reference/airnode/next/concepts/airnode-auth.md +++ b/docs/reference/airnode/next/concepts/airnode-auth.md @@ -19,40 +19,24 @@ tags: # {{$frontmatter.title}} -API providers can instruct Airnode to authenticate requests to their endpoints. -This is done by setting up a security scheme in the config.json file for their -Airnode. Airnode supports three methods of authentication from the OpenAPI -specification. +API providers can instruct Airnode to authenticate requests to their endpoints. This is done by setting up a security scheme in the config.json file for their Airnode. Airnode supports three methods of authentication from the OpenAPI specification. > -[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) -uses the term **security scheme** for authentication and authorization schemes. -Airnode only uses standard OAS defined authentication schemes to identify itself -to API endpoints. Airnode supports two types of authentication, `http` and -`apiKey`. +[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) uses the term **security scheme** for authentication and authorization schemes. Airnode only uses standard OAS defined authentication schemes to identify itself to API endpoints. Airnode supports two types of authentication, `http` and `apiKey`. -- HTTP authentication schemes (using the `Authorization` header) supported by - Airnode: +- HTTP authentication schemes (using the `Authorization` header) supported by Airnode: - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) - [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) -- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in - the request header, cookie in header or query string +- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in the request header, cookie in header or query string -How Airnode sends the authentication data is explained in the sections **Basic, -Bearer and API Key** below. +How Airnode sends the authentication data is explained in the sections **Basic, Bearer and API Key** below. ## Basic -Basic authentication is a simple authentication scheme built into the HTTP -protocol. The Authorization request header contains the Base64-encoded username -and password, separated by a colon. When handling the request, the server -decodes the login details and checks if the user can access the requested -content. +Basic authentication is a simple authentication scheme built into the HTTP protocol. The Authorization request header contains the Base64-encoded username and password, separated by a colon. When handling the request, the server decodes the login details and checks if the user can access the requested content. -The header field is in the form of `Authorization: Basic ` where -`credentials` is the Base64 encoding of a username and password joined by a -single colon (`airnode:airnode-password`). +The header field is in the form of `Authorization: Basic ` where `credentials` is the Base64 encoding of a username and password joined by a single colon (`airnode:airnode-password`). `Authorization: Basic ` @@ -63,10 +47,7 @@ curl -H "Authorization: Basic YW5kZXJzb25AZ21haWwuY29tOjEyM215cGFzc3dvcmQ=" \ ## Bearer -Bearer authentication (also called token authentication) is an HTTP -authentication scheme that involves security tokens called bearer tokens. The -API provider supplies a token used by Airnode to authenticate itself to API -endpoints. +Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The API provider supplies a token used by Airnode to authenticate itself to API endpoints. The header field is in the form of `Authorization: Bearer `. @@ -77,9 +58,7 @@ curl -H "Authorization: Bearer RZ8Y65TG" \ ## API Key -Some APIs use an `apiKey` for authentication. The API provider supplies an -`apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can -send the `apiKey` three ways. +Some APIs use an `apiKey` for authentication. The API provider supplies an `apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can send the `apiKey` three ways. ```sh # In the query string. diff --git a/docs/reference/airnode/next/concepts/airnode.md b/docs/reference/airnode/next/concepts/airnode.md index 836e95fd..0be12f87 100644 --- a/docs/reference/airnode/next/concepts/airnode.md +++ b/docs/reference/airnode/next/concepts/airnode.md @@ -19,37 +19,17 @@ tags: # {{$frontmatter.title}} -Airnode is a serverless oracle node implemented with a "set and forget" -philosophy. Airnode is flexible in that it can move API provider data on-chain -for multiple purposes. The most important of which are data feeds -([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in -response to dApp direct requests for API provider data -([RRP](/reference/airnode/next/developers/)). +Airnode is a serverless oracle node implemented with a "set and forget" philosophy. Airnode is flexible in that it can move API provider data on-chain for multiple purposes. The most important of which are data feeds ([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in response to dApp direct requests for API provider data ([RRP](/reference/airnode/next/developers/)). ## Airnode sources data to dAPIs -An Airnode supplies API provider data to beacons from API providers. These -beacons are the underlying data source for data feeds known as dAPIs. +An Airnode supplies API provider data to beacons from API providers. These beacons are the underlying data source for data feeds known as dAPIs. -API providers, owners of first-party Airnodes, store data feed values on-chain -as individual beacons that in are turn sourced by the -[Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) -contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). -Airnode has an internal mechanism that looks for a deviation in the value of API -provider's API operations. This mechanism updates beacons on-chain as needed. +API providers, owners of first-party Airnodes, store data feed values on-chain as individual beacons that in are turn sourced by the [Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). Airnode has an internal mechanism that looks for a deviation in the value of API provider's API operations. This mechanism updates beacons on-chain as needed. ## Airnode processes RRP requests -An Airnode is capable of serving the data from one or more APIs directly to -[requesters](/reference/airnode/next/concepts/requester.md) (which are on-chain -smart contracts) that request data served by a particular Airnode. This is done -using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 -protocol is designed to be flexible and is meant to serve a variety of use -cases. See the the -[Calling Airnode (RRP)](/reference/airnode/next/developers/index.md) for more -details on how an RRP request is made. Also see the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples/contracts) -for potential design patterns. +An Airnode is capable of serving the data from one or more APIs directly to [requesters](/reference/airnode/next/concepts/requester.md) (which are on-chain smart contracts) that request data served by a particular Airnode. This is done using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 protocol is designed to be flexible and is meant to serve a variety of use cases. See the the [Calling Airnode (RRP)](/reference/airnode/next/developers/index.md) for more details on how an RRP request is made. Also see the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples/contracts) for potential design patterns. diff --git a/docs/reference/airnode/next/deployment-files/templates/aws-env.md b/docs/reference/airnode/next/deployment-files/templates/aws-env.md index d4e77a1e..a081e57e 100644 --- a/docs/reference/airnode/next/deployment-files/templates/aws-env.md +++ b/docs/reference/airnode/next/deployment-files/templates/aws-env.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -The `aws.env` contains AWS credentials from an IAM user. These credentials are -used by the Docker -[deployer image](/reference/airnode/next/docker/deployer-image.md) to deploy an -Airnode to AWS. For more details, see the full description of the -[aws.env](/reference/airnode/next/deployment-files/templates/aws-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `aws.env` contains AWS credentials from an IAM user. These credentials are used by the Docker [deployer image](/reference/airnode/next/docker/deployer-image.md) to deploy an Airnode to AWS. For more details, see the full description of the [aws.env](/reference/airnode/next/deployment-files/templates/aws-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AWS_ACCESS_KEY_ID= diff --git a/docs/reference/airnode/next/deployment-files/templates/config-json.md b/docs/reference/airnode/next/deployment-files/templates/config-json.md index e0d01872..e3156309 100644 --- a/docs/reference/airnode/next/deployment-files/templates/config-json.md +++ b/docs/reference/airnode/next/deployment-files/templates/config-json.md @@ -19,33 +19,23 @@ tags: # {{$frontmatter.title}} -A template for an Airnode's configuration file. Below are notations to help -explain contents of the template. +A template for an Airnode's configuration file. Below are notations to help explain contents of the template. -- `, , `: The value added is independent from - other fields and a value is needed unless otherwise indicated. These values - are not considered secret unless you want them to be. +- `, , `: The value added is independent from other fields and a value is needed unless otherwise indicated. These values are not considered secret unless you want them to be. -- ``: If two fields contain the same - expression, use the same value in them because they are referencing each - other. Usually these are not considered to be secret. +- ``: If two fields contain the same expression, use the same value in them because they are referencing each other. Usually these are not considered to be secret. -- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to - `secrets.env` though it is not required. +- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to `secrets.env` though it is not required. Consider the following relationships. - `ois[0].title` is related to `triggers.rrp[0].oisTitle`. -- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to - ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in -- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to - ois[0].endpoints[0].parameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to ois[0].endpoints[0].parameters[0].operationParameter.in -See -[config.json](/reference/airnode/next/deployment-files/templates/config-json.md) -as a reference while building a config.json file. +See [config.json](/reference/airnode/next/deployment-files/templates/config-json.md) as a reference while building a config.json file. ```json { diff --git a/docs/reference/airnode/next/deployment-files/templates/ois-json.md b/docs/reference/airnode/next/deployment-files/templates/ois-json.md index 66be3a96..29f33988 100644 --- a/docs/reference/airnode/next/deployment-files/templates/ois-json.md +++ b/docs/reference/airnode/next/deployment-files/templates/ois-json.md @@ -19,11 +19,6 @@ tags: # {{$frontmatter.title}} -An [OIS (Oracle Integration Specifications)](/reference/ois/next/) JSON object -is part of an Airnode's -[config.json](/reference/airnode/next/deployment-files/templates/config-json.md) -file. There can be more than one OIS object in the `config.json` file that -defines an Airnode. See the [OIS Template](/reference/ois/next/template.md) in -the OIS document set. +An [OIS (Oracle Integration Specifications)](/reference/ois/next/) JSON object is part of an Airnode's [config.json](/reference/airnode/next/deployment-files/templates/config-json.md) file. There can be more than one OIS object in the `config.json` file that defines an Airnode. See the [OIS Template](/reference/ois/next/template.md) in the OIS document set. diff --git a/docs/reference/airnode/next/deployment-files/templates/secrets-env.md b/docs/reference/airnode/next/deployment-files/templates/secrets-env.md index 3f09c6e6..012b4cd7 100644 --- a/docs/reference/airnode/next/deployment-files/templates/secrets-env.md +++ b/docs/reference/airnode/next/deployment-files/templates/secrets-env.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The `secrets.env` contains the secrets that the respective Airnode deployments -will need. All variables defined in a `secrets.env` can be interpolated inside -`config.json`. For more details, see the full description of the -[secrets.env](/reference/airnode/next/deployment-files/secrets-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `secrets.env` contains the secrets that the respective Airnode deployments will need. All variables defined in a `secrets.env` can be interpolated inside `config.json`. For more details, see the full description of the [secrets.env](/reference/airnode/next/deployment-files/secrets-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AIRNODE_WALLET_MNEMONIC="" diff --git a/docs/reference/airnode/next/developers/fees.md b/docs/reference/airnode/next/developers/fees.md index 741c5446..b18e2ecb 100644 --- a/docs/reference/airnode/next/developers/fees.md +++ b/docs/reference/airnode/next/developers/fees.md @@ -19,18 +19,11 @@ tags: # {{$frontmatter.title}} -There are some one-time setup/maintenance costs and some ongoing costs of -calling an Airnode. The Airnode protocol is designed in a way that the requester -assumes all gas costs, including the request fulfillment (response) -transactions. +There are some one-time setup/maintenance costs and some ongoing costs of calling an Airnode. The Airnode protocol is designed in a way that the requester assumes all gas costs, including the request fulfillment (response) transactions. ## Sponsors -Fees are encountered when a sponsor engages in setup activity such as sponsoring -a requester. These are per call transaction gas costs and are relatively small. -The funds come from the wallet mnemonic that the sponsor supplies when calling -certain [admin commands](/reference/airnode/next/packages/admin-cli.md) as shown -below. +Fees are encountered when a sponsor engages in setup activity such as sponsoring a requester. These are per call transaction gas costs and are relatively small. The funds come from the wallet mnemonic that the sponsor supplies when calling certain [admin commands](/reference/airnode/next/packages/admin-cli.md) as shown below. - [sponsor-requester](/reference/airnode/next/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/next/packages/admin-cli.md#unsponsor-requester) @@ -39,32 +32,18 @@ below. ## Airnodes -The fees take the form of transaction gas costs. These are applied when funding -a requester's sponsor wallet for an Airnode and when executing the Airnode in -response to a request. +The fees take the form of transaction gas costs. These are applied when funding a requester's sponsor wallet for an Airnode and when executing the Airnode in response to a request. -- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is - funded manually by a sponsor using their preferred wallet management tool such - as MetaMask. +- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is funded manually by a sponsor using their preferred wallet management tool such as MetaMask. -- [Calling](/reference/airnode/next/developers/index.md) an Airnode: Transaction - gas fees are withdrawn from the sponsor wallet related to the Airnode being - called by a sponsored requester. +- [Calling](/reference/airnode/next/developers/index.md) an Airnode: Transaction gas fees are withdrawn from the sponsor wallet related to the Airnode being called by a sponsored requester. -Learn more about [sponsor wallets](/reference/airnode/next/concepts/sponsor.md) -in the reference section. +Learn more about [sponsor wallets](/reference/airnode/next/concepts/sponsor.md) in the reference section. ## API Provider Fees -Some API providers charge a subscription fee for access to their data. This is a -typical practice and usually requires the requester to create an account on the -provider's website and then subscribe to a level of service offered. These types -of services are usually billed monthly and can be based on an annual rate to -save costs. The subscription (even if free) will most likely involve the use of -a security scheme such as an API key that must be used to access the data. See -[Calling an Airnode](/reference/airnode/next/developers/index.md) to learn more -on how to pass the security credentials to an Airnode. +Some API providers charge a subscription fee for access to their data. This is a typical practice and usually requires the requester to create an account on the provider's website and then subscribe to a level of service offered. These types of services are usually billed monthly and can be based on an annual rate to save costs. The subscription (even if free) will most likely involve the use of a security scheme such as an API key that must be used to access the data. See [Calling an Airnode](/reference/airnode/next/developers/index.md) to learn more on how to pass the security credentials to an Airnode. diff --git a/docs/reference/airnode/next/developers/index.md b/docs/reference/airnode/next/developers/index.md index 95d74874..08380499 100644 --- a/docs/reference/airnode/next/developers/index.md +++ b/docs/reference/airnode/next/developers/index.md @@ -19,47 +19,22 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that can push off-chain API data to an on-chain -contract. While dApp developers will find -[dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the -most useful aspect of an Airnode's capabilities, there is the option for -developers to access Airnode data using its request-response protocol (RRP). The -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract facilitates RRP and is designed to be flexible and is meant to -serve a variety of use cases. See the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples/contracts) -for potential design patterns. +Airnode is a first-party oracle that can push off-chain API data to an on-chain contract. While dApp developers will find [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the most useful aspect of an Airnode's capabilities, there is the option for developers to access Airnode data using its request-response protocol (RRP). The [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract facilitates RRP and is designed to be flexible and is meant to serve a variety of use cases. See the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples/contracts) for potential design patterns. ## It starts with a requester -A requester is a smart contract that can trigger an Airnode RRP request. To do -so, the requester needs to be sponsored and make the request using a matching -sponsor wallet. See -[Requesters and Sponsors](/reference/airnode/next/developers/requesters-sponsors.md) -on how to sponsor a requester and derive the sponsor wallet. +A requester is a smart contract that can trigger an Airnode RRP request. To do so, the requester needs to be sponsored and make the request using a matching sponsor wallet. See [Requesters and Sponsors](/reference/airnode/next/developers/requesters-sponsors.md) on how to sponsor a requester and derive the sponsor wallet. ## A simplified understanding -In the diagram below, any typical smart contract is called a requester if it -makes a request of Airnode's RRP protocol. It makes a request to the on-chain -RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event -logs. The off-chain Airnode then accesses the event logs, gets the API data and -performs a callback to the requester. +In the diagram below, any typical smart contract is called a requester if it makes a request of Airnode's RRP protocol. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event logs. The off-chain Airnode then accesses the event logs, gets the API data and performs a callback to the requester. In summary, the requester will do two things. -- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol - contract, which returns a - [`requestId`](/reference/airnode/next/concepts/request.md#requestid). -- Add a `myFulfill()` function (call it what you like) to your requester where - the off-chain Airnode can send the requested data when ready. The data - includes the same `requestId` as the one returned at the time of making the - request. +- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol contract, which returns a [`requestId`](/reference/airnode/next/concepts/request.md#requestid). +- Add a `myFulfill()` function (call it what you like) to your requester where the off-chain Airnode can send the requested data when ready. The data includes the same `requestId` as the one returned at the time of making the request. -In the diagram below a requester makes a request to the on-chain RRP protocol -contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its -run cycle the off-chain Airnode accesses the event logs, gets the requested data -from the the API provider, then performs a callback to the requester. +In the diagram below a requester makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its run cycle the off-chain Airnode accesses the event logs, gets the requested data from the the API provider, then performs a callback to the requester. > > @@ -68,19 +43,13 @@ from the the API provider, then performs a callback to the requester. > 3.

Airnode gathers response data from the API specified in the request.

> 4.

Airnode performs a callback to a named function myFulfill() in myContract.sol via the AirnodeRrpV0.sol function fulfill() with the requested data and the requestId.

-See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn -how to make a RRP request of an Airnode. +See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn how to make a RRP request of an Airnode. ## A deeper dive -This section, through its detailed illustration, builds on the previous section -([A simplified understanding](/reference/airnode/next/developers/index.md#a-simplified-understanding)) -in an attempt to further illustrate and explain the mechanics of how an Airnode -response to a request made by a requester. +This section, through its detailed illustration, builds on the previous section ([A simplified understanding](/reference/airnode/next/developers/index.md#a-simplified-understanding)) in an attempt to further illustrate and explain the mechanics of how an Airnode response to a request made by a requester. -Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") -deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain -**protocol contract** AirnodeRrpV0.sol. +Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain **protocol contract** AirnodeRrpV0.sol. > > diff --git a/docs/reference/airnode/next/developers/requesters-sponsors.md b/docs/reference/airnode/next/developers/requesters-sponsors.md index 52243f5a..9623c982 100644 --- a/docs/reference/airnode/next/developers/requesters-sponsors.md +++ b/docs/reference/airnode/next/developers/requesters-sponsors.md @@ -19,143 +19,80 @@ tags: # {{$frontmatter.title}} -As a dApp developer it helps to understand what a **requester** is and what a -**sponsor** does. They are both important parts of the Airnode ecosystem. This -doc will further define them and walk you through the process of sponsoring a -requester and deriving a sponsor wallet using the admin CLI commands. +As a dApp developer it helps to understand what a **requester** is and what a **sponsor** does. They are both important parts of the Airnode ecosystem. This doc will further define them and walk you through the process of sponsoring a requester and deriving a sponsor wallet using the admin CLI commands. ## What is a Requester? -The term [requester](/reference/airnode/next/concepts/requester.md) is important -to remember. When requester is mentioned, the reference is to your smart -contract that makes a request of an Airnode. +The term [requester](/reference/airnode/next/concepts/requester.md) is important to remember. When requester is mentioned, the reference is to your smart contract that makes a request of an Airnode. > -As an example see the `myContract.sol` contract in the diagram within the -[Overview](/reference/airnode/next/concepts/) doc, it is a requester. +As an example see the `myContract.sol` contract in the diagram within the [Overview](/reference/airnode/next/concepts/) doc, it is a requester. ## What is a Sponsor? -Equally important is the term -[sponsor](/reference/airnode/next/concepts/sponsor.md). A sponsor is an entity -such as yourself, an organization, etc. Sponsors create relationships between -requesters and Airnodes. +Equally important is the term [sponsor](/reference/airnode/next/concepts/sponsor.md). A sponsor is an entity such as yourself, an organization, etc. Sponsors create relationships between requesters and Airnodes. ### Sponsor's Requester/Airnode Relationships -As a sponsor you will use the public address from an account within a mnemonic -you own to "**sponsor a requester**" and then use the public address (known as a -[sponsorAddress](/reference/airnode/next/concepts/sponsor.md#sponsoraddress)) to -"**derive a -[sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet)**" -for an Airnode. This action creates a relationship between a sponsor's requester -and a particular Airnode. You do this because a sponsor is the entity that pays -for the fulfillment of a request, the gas costs the Airnode will incur. These -costs will be withdrawn from the `sponsorWallet` of the Airnode when the -requester calls it. +As a sponsor you will use the public address from an account within a mnemonic you own to "**sponsor a requester**" and then use the public address (known as a [sponsorAddress](/reference/airnode/next/concepts/sponsor.md#sponsoraddress)) to "**derive a [sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet)**" for an Airnode. This action creates a relationship between a sponsor's requester and a particular Airnode. You do this because a sponsor is the entity that pays for the fulfillment of a request, the gas costs the Airnode will incur. These costs will be withdrawn from the `sponsorWallet` of the Airnode when the requester calls it. ::: info sponsorAddress -A [sponsorAddress](/reference/airnode/next/concepts/sponsor.md#sponsoraddress) -is a public address of an account from a mnemonic, usually the default account. -Rather than the default account another account from the mnemonic can be used. -The `sponsorAddress` is used to uniquely identify a sponsor. +A [sponsorAddress](/reference/airnode/next/concepts/sponsor.md#sponsoraddress) is a public address of an account from a mnemonic, usually the default account. Rather than the default account another account from the mnemonic can be used. The `sponsorAddress` is used to uniquely identify a sponsor. ::: -1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester - with the Admin CLI. The CLI will use the default address of the mnemonic - passed as the `sponsorAddress` for the sponsorship unless another account is - specified. +1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester with the Admin CLI. The CLI will use the default address of the mnemonic passed as the `sponsorAddress` for the sponsorship unless another account is specified. -2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the - `sponsorAddress`. +2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the `sponsorAddress`. 3. The requester can now make requests of the Airnode. > -In the above diagram it is possible to use the same sponsorAddress -`(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is -possible to sponsor more than one requester with the same `sponsorAddress`. -However it is important to remember that all requesters can now access all the -Airnodes regardless if they need to. There is no harm in this scenario. +In the above diagram it is possible to use the same sponsorAddress `(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is possible to sponsor more than one requester with the same `sponsorAddress`. However it is important to remember that all requesters can now access all the Airnodes regardless if they need to. There is no harm in this scenario. ### Advanced Scenarios - **Two requesters, one Airnode, one sponsorWallet**: - Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) - would access the same Airnode using a single sponsorWallet derived by the - `sponsorAddress`. + Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) would access the same Airnode using a single sponsorWallet derived by the `sponsorAddress`. - **Two requesters, one Airnode, two sponsorWallets**: - Sponsor two different requesters each with a different `sponsorAddress` (e.g., - `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you - can derive two separate sponsorWallets for the same Airnode. Now each - requester will deplete funds from a separate Airnode sponsorWallet when using - the Airnode. + Sponsor two different requesters each with a different `sponsorAddress` (e.g., `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you can derive two separate sponsorWallets for the same Airnode. Now each requester will deplete funds from a separate Airnode sponsorWallet when using the Airnode. - **One requester, two Airnodes, two sponsorWallets**: - A requester can make requests from two different Airnodes. Sponsor the - requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of - two the Airnodes, using the `sponsorAddress`. Despite the fact that the - sponsorWallet for each Airnode was derived with the same `sponsorAddress` the - sponsorWallets are different since they are derived using the airnode's xpub - plus the `sponsorAddress`. The sponsor must fund both wallets separately using - the unique `sponsorWallet` address of the two sponsorWallets. + A requester can make requests from two different Airnodes. Sponsor the requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of two the Airnodes, using the `sponsorAddress`. Despite the fact that the sponsorWallet for each Airnode was derived with the same `sponsorAddress` the sponsorWallets are different since they are derived using the airnode's xpub plus the `sponsorAddress`. The sponsor must fund both wallets separately using the unique `sponsorWallet` address of the two sponsorWallets. ### Things to Remember -When you sponsor a requester with a `sponsorAddress` you are giving it -permission to use the sponsorWallet (associated with a Airnode) that was derived -using the same `sponsorAddress`. +When you sponsor a requester with a `sponsorAddress` you are giving it permission to use the sponsorWallet (associated with a Airnode) that was derived using the same `sponsorAddress`. -When the requester makes a request to the Airnode, the Airnode will use funds -from the corresponding sponsorWallet to pay gas costs in response to the -request. Therefore the sponsor pays for the fulfillment of the request. +When the requester makes a request to the Airnode, the Airnode will use funds from the corresponding sponsorWallet to pay gas costs in response to the request. Therefore the sponsor pays for the fulfillment of the request. -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/next/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/next/developers/fees.md#api-provider-fees). ## Admin CLI Commands -There are several sponsor and requester related commands in the -[Admin CLI Commands](/reference/airnode/next/packages/admin-cli.md) package. You -can also see a list of available commands using -`npx @api3/airnode-admin --help`. +There are several sponsor and requester related commands in the [Admin CLI Commands](/reference/airnode/next/packages/admin-cli.md) package. You can also see a list of available commands using `npx @api3/airnode-admin --help`. -In the next two sections of this doc you will use two commands from the -`@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor -wallet_. +In the next two sections of this doc you will use two commands from the `@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor wallet_. -1. [sponsor-requester](/reference/airnode/next/packages/admin-cli.md#sponsor-requester) - sponsors a requester. -2. [derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address)creates - a sponsor wallet associated with an Airnode. +1. [sponsor-requester](/reference/airnode/next/packages/admin-cli.md#sponsor-requester) sponsors a requester. +2. [derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address)creates a sponsor wallet associated with an Airnode. ## How to Sponsor a Requester -To sponsor a requester execute the `sponsor-requester` command using the -parameters detailed in the list below. Your requester should already be deployed -on-chain. This command has transaction gas costs. +To sponsor a requester execute the `sponsor-requester` command using the parameters detailed in the list below. Your requester should already be deployed on-chain. This command has transaction gas costs. -- `providerURL`: A blockchain provider URL (such as Infura) with providerID for - the desired network. -- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to - derive the sponsorAddress from the default address. The sponsorAddress will be - needed to derive a sponsorWallet for an Airnode. +- `providerURL`: A blockchain provider URL (such as Infura) with providerID for the desired network. +- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to derive the sponsorAddress from the default address. The sponsorAddress will be needed to derive a sponsorWallet for an Airnode. - `requester-address`: Address of the requester contract. -- `derivation-path (optional)` (_not used in the example below_): Selects an - alternate account to use from the mnemonic rather than the default account. +- `derivation-path (optional)` (_not used in the example below_): Selects an alternate account to use from the mnemonic rather than the default account. -Executing the command -[sponsor-requester](/reference/airnode/next/packages/admin-cli.md#sponsor-requester) -will sponsor a requester and returns the requesterAddress and sponsorAddress. +Executing the command [sponsor-requester](/reference/airnode/next/packages/admin-cli.md#sponsor-requester) will sponsor a requester and returns the requesterAddress and sponsorAddress. ::: code-group @@ -181,27 +118,15 @@ npx @api3/airnode-admin sponsor-requester ^ ## How to Derive a Sponsor Wallet -To use a particular Airnode you must _derive a sponsorWallet_. Once the -sponsorWallet is created it must be funded using the public address -(`sponsorWallet` address) returned by the command -`derive-sponsor-wallet-address`. Each Airnode keeps a separate list of -individual sponsorWallets that can access the Airnode. Learn more about a -[sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). +To use a particular Airnode you must _derive a sponsorWallet_. Once the sponsorWallet is created it must be funded using the public address (`sponsorWallet` address) returned by the command `derive-sponsor-wallet-address`. Each Airnode keeps a separate list of individual sponsorWallets that can access the Airnode. Learn more about a [sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). -To derive a sponsorWallet for an Airnode execute the -[derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) -command using the parameters detailed in the list below. There are no -transaction gas costs to do so. +To derive a sponsorWallet for an Airnode execute the [derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) command using the parameters detailed in the list below. There are no transaction gas costs to do so. -- `airnode-xpub`: The extended public address of the Airnode for path - m/44'/60'/0'. +- `airnode-xpub`: The extended public address of the Airnode for path m/44'/60'/0'. - `airnode-address`: The public address of the desired Airnode. -- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) - owned by a sponsor. Usually the sponsorAddress is the one returned when - sponsoring a requester. +- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) owned by a sponsor. Usually the sponsorAddress is the one returned when sponsoring a requester. -The command `derive-sponsor-wallet-address` will return the public address -(`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. +The command `derive-sponsor-wallet-address` will return the public address (`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. ::: code-group @@ -225,22 +150,15 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ::: -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/next/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/next/developers/fees.md#api-provider-fees). -If you forget the public address (`sponsorWallet` address) of the sponsorWallet -simply run `derive-sponsor-wallet-address` again. Since the wallet already -exists for the airnodeAddress/sponsorAddress pair it will just return the -address. +If you forget the public address (`sponsorWallet` address) of the sponsorWallet simply run `derive-sponsor-wallet-address` again. Since the wallet already exists for the airnodeAddress/sponsorAddress pair it will just return the address. ## Record Keeping -During and after sponsoring requesters and deriving a sponsorWallet there are a -few things to keep track of. +During and after sponsoring requesters and deriving a sponsorWallet there are a few things to keep track of. | Item | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -248,11 +166,6 @@ few things to keep track of. | sponsor address | The public address of an account derived from a sponsor's mnemonic when sponsoring a requester. Record which `sponsorAddress` was used to create a sponsorWallet for each Airnode. | | sponsor wallet address | Record the `sponsorWallet` address of the sponsorWallet derived for an Airnode. For each Airnode you have derived a sponsorWallet, the Airnode keeps the private key and returns the public address (`sponsorWallet` address) which is used to fund the sponsorWallet. | -You can acquire the public address (`sponsorWallet` address) of a sponsorWallet -later, if you lose it, by running the command `derive-sponsor-wallet-address` -again. Since the sponsorWallet was already created for the -`sponsorAddress/airnodeAddress` pair, the command will only return the public -address for the wallet. However you must use the same `sponsorAddress` used when -the wallet was first created or a new sponsorWallet will be created. +You can acquire the public address (`sponsorWallet` address) of a sponsorWallet later, if you lose it, by running the command `derive-sponsor-wallet-address` again. Since the sponsorWallet was already created for the `sponsorAddress/airnodeAddress` pair, the command will only return the public address for the wallet. However you must use the same `sponsorAddress` used when the wallet was first created or a new sponsorWallet will be created. diff --git a/docs/reference/airnode/next/developers/using-templates.md b/docs/reference/airnode/next/developers/using-templates.md index 36ccc0a5..0c90a0f8 100644 --- a/docs/reference/airnode/next/developers/using-templates.md +++ b/docs/reference/airnode/next/developers/using-templates.md @@ -19,15 +19,7 @@ tags: # {{$frontmatter.title}} -A request to an Airnode can have many parameters. It is very common for -requester contracts (e.g., a data feed) to make repeated requests with the exact -same parameters. In such instances, it is wasteful to pass all of these -parameters repeatedly. Templates are used to hold a set of parameter values -on-chain that can be used repeatedly when calling -the`makeTemplateRequest()`function in -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). -Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester -pass`templateId`which identifies a template. +A request to an Airnode can have many parameters. It is very common for requester contracts (e.g., a data feed) to make repeated requests with the exact same parameters. In such instances, it is wasteful to pass all of these parameters repeatedly. Templates are used to hold a set of parameter values on-chain that can be used repeatedly when calling the`makeTemplateRequest()`function in [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester pass`templateId`which identifies a template. ```solidity function makeTemplateRequest( @@ -40,10 +32,7 @@ function makeTemplateRequest( ) external override returns (bytes32 requestId) { ``` -When a template is used to make a request, both the parameters encoded in -parameters of the template and parameters provided at request-time (if any) will -be used by the Airnode. In case the two include a parameter with the same name, -the one provided at request-time will be used. +When a template is used to make a request, both the parameters encoded in parameters of the template and parameters provided at request-time (if any) will be used by the Airnode. In case the two include a parameter with the same name, the one provided at request-time will be used. The structure of a template, as shown below, is simple. @@ -59,10 +48,6 @@ struct Template { } ``` -See the guide -[Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn -how to create and use a template. Also visit the -[coingecko-template](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples/integrations/coingecko-template) -monorepo example demonstrates template requests. +See the guide [Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn how to create and use a template. Also visit the [coingecko-template](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples/integrations/coingecko-template) monorepo example demonstrates template requests. diff --git a/docs/reference/airnode/next/developers/verify-airnode-addresses.md b/docs/reference/airnode/next/developers/verify-airnode-addresses.md index 8b9d7b92..aff619b6 100644 --- a/docs/reference/airnode/next/developers/verify-airnode-addresses.md +++ b/docs/reference/airnode/next/developers/verify-airnode-addresses.md @@ -19,18 +19,9 @@ tags: # {{$frontmatter.title}} -An Airnode is owned and operated by an API provider. Every Airnode has a unique -on-chain -[`airnodeAddress`](/reference/airnode/next/concepts/airnode.md#airnodeaddress) -created and known by its API provider. API providers normally announce their -Airnode addresses in the form of a DNS `TXT` record within their DNS -registration, which also serves to prove ownership. An API provider's Airnode -address is the same for all chains. - -The key for the `TXT` record is `chainapi-verification-keys` and is an array of -Airnode addresses owned by the API provider. Below is an example of the Airnode -for -[dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). +An Airnode is owned and operated by an API provider. Every Airnode has a unique on-chain [`airnodeAddress`](/reference/airnode/next/concepts/airnode.md#airnodeaddress) created and known by its API provider. API providers normally announce their Airnode addresses in the form of a DNS `TXT` record within their DNS registration, which also serves to prove ownership. An API provider's Airnode address is the same for all chains. + +The key for the `TXT` record is `chainapi-verification-keys` and is an array of Airnode addresses owned by the API provider. Below is an example of the Airnode for [dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). ![dxfeed-txt-record](../assets/images/txt-record-dxfeed.png) @@ -56,5 +47,4 @@ The following list of links go to the DNS lookup at DigitalOcean. - [Kaiko](https://www.digitalocean.com/community/tools/dns?domain=kaiko.io#TXT-Records) - [NewChangeFX](https://www.digitalocean.com/community/tools/dns?domain=newchangefx.com#TXT-Records) - [Nodary](https://www.digitalocean.com/community/tools/dns?domain=nodary.io#TXT-Records) -- [twelvedata](https://www.digitalocean.com/community/tools/dns?domain=twelvedata.com#TXT-Records) - +- [twelvedata](https://www.digitalocean.com/community/tools/dns?domain=twelvedata.com#TXT-Records) diff --git a/docs/reference/airnode/next/docker/admin-cli-image.md b/docs/reference/airnode/next/docker/admin-cli-image.md index 1bb6b9f1..04210f55 100644 --- a/docs/reference/airnode/next/docker/admin-cli-image.md +++ b/docs/reference/airnode/next/docker/admin-cli-image.md @@ -22,24 +22,15 @@ tags: -Use the admin CLI image as an alternative method to execute -[Admin CLI](/reference/airnode/next/packages/admin-cli.md) using npx. Either -method will achieve the same results. The image forgoes downloading the admin -CLI package each time a command is executed using npx. +Use the admin CLI image as an alternative method to execute [Admin CLI](/reference/airnode/next/packages/admin-cli.md) using npx. Either method will achieve the same results. The image forgoes downloading the admin CLI package each time a command is executed using npx. -If you want to build the admin CLI image from the source yourself, you can find -the -[image built instructions](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin/docker) -in the Airnode repository. +If you want to build the admin CLI image from the source yourself, you can find the [image built instructions](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin/docker) in the Airnode repository. -Additional information about the -[admin CLI image](/reference/airnode/next/packages/admin-cli.md#using-docker) is -available in the admin CLI commands doc. +Additional information about the [admin CLI image](/reference/airnode/next/packages/admin-cli.md#using-docker) is available in the admin CLI commands doc. ## Usage -The following example shows the difference between using the docker image versus -npx when executing the `get-sponsor-status` admin CLI command. +The following example shows the difference between using the docker image versus npx when executing the `get-sponsor-status` admin CLI command. ```sh #npx diff --git a/docs/reference/airnode/next/docker/client-image.md b/docs/reference/airnode/next/docker/client-image.md index 2eaae444..e4aa5bfd 100644 --- a/docs/reference/airnode/next/docker/client-image.md +++ b/docs/reference/airnode/next/docker/client-image.md @@ -19,29 +19,17 @@ tags: # {{$frontmatter.title}} -Usually the Airnode is deployed on a serverless platform using the -[deployer](/reference/airnode/next/docker/deployer-image.md). However, there is -another option which is to run the Airnode in a docker container on your machine -locally, on premise or cloud hosted. +Usually the Airnode is deployed on a serverless platform using the [deployer](/reference/airnode/next/docker/deployer-image.md). However, there is another option which is to run the Airnode in a docker container on your machine locally, on premise or cloud hosted. -A docker client image has been published on -[Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build -the container from the source yourself, you can find the image and built -instructions in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-node/docker). +A docker client image has been published on [Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build the container from the source yourself, you can find the image and built instructions in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-node/docker). ## Configuration -The Airnode needs two configuration files for its run: `config.json` and -`secrets.env`. These files need to be passed to the Docker container via -volumes. +The Airnode needs two configuration files for its run: `config.json` and `secrets.env`. These files need to be passed to the Docker container via volumes. -The Docker container looks for configuration files mounted internally in the -`/app/config` directory. +The Docker container looks for configuration files mounted internally in the `/app/config` directory. -Your current working directory should contain the configuration files above and -you bind it to the `/app/config` directory for the docker using the `--volume` -parameter. +Your current working directory should contain the configuration files above and you bind it to the `/app/config` directory for the docker using the `--volume` parameter. ::: code-group @@ -73,8 +61,7 @@ $ docker run --volume %cd%:/config:/app/config ... ## Usage -Example directory structure and commands for running the Airnode Docker -container. The below commands are run from the depicted directory. +Example directory structure and commands for running the Airnode Docker container. The below commands are run from the depicted directory. ### Running Airnode @@ -105,18 +92,11 @@ docker run ^ ::: -> If you want to connect Airnode to a blockchain running on localhost, you need -> to make the blockchain accessible from within the docker itself. If you use -> docker for linux you can use `--network="host"` parameter. If you are using -> Docker Desktop (on any platform), connect to -> `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See -> [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). +> If you want to connect Airnode to a blockchain running on localhost, you need to make the blockchain accessible from within the docker itself. If you use docker for linux you can use `--network="host"` parameter. If you are using Docker Desktop (on any platform), connect to `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). ### Checking Airnode logs -Logs will be output to the console after running the above command. If you -decide to run Airnode in detached mode with `--detach`, you need to use the -`logs` command, optionally with `--follow`, to access the logs. +Logs will be output to the console after running the above command. If you decide to run Airnode in detached mode with `--detach`, you need to use the `logs` command, optionally with `--follow`, to access the logs. ```bash docker logs airnode diff --git a/docs/reference/airnode/next/docker/deployer-image.md b/docs/reference/airnode/next/docker/deployer-image.md index d0fb0d1a..f7fc5434 100644 --- a/docs/reference/airnode/next/docker/deployer-image.md +++ b/docs/reference/airnode/next/docker/deployer-image.md @@ -19,26 +19,17 @@ tags: # {{$frontmatter.title}} -Use the deployer image to deploy or remove an Airnode with a cloud provider such -as AWS. The simplest way is to use the pre-built packages. If you would rather -build the images yourself see the -[README](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer/docker) -in the deployer package. +Use the deployer image to deploy or remove an Airnode with a cloud provider such as AWS. The simplest way is to use the pre-built packages. If you would rather build the images yourself see the [README](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer/docker) in the deployer package. ::: info Quick Deploy Demos -See the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -guides to quickly deploy and remove a preconfigured Airnode using the deployer -image. +See the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guides to quickly deploy and remove a preconfigured Airnode using the deployer image. ::: ## Configuration Files -The files `config.json` and `secrets.env` are used to configure the Airnode. The -`aws.env` and `gcp.json` files are used to define environment information the -deployer uses to connect to these cloud providers. +The files `config.json` and `secrets.env` are used to configure the Airnode. The `aws.env` and `gcp.json` files are used to define environment information the deployer uses to connect to these cloud providers. ``` my-airnode @@ -50,22 +41,15 @@ my-airnode ## Cloud Provider Credentials -In order to deploy Airnode to a serverless cloud provider, you need to provide -cloud provider credentials to the Airnode deployer image. The deployer image -currently supports deploying to AWS and GCP. For AWS deployment, see the -[AWS Setup](/reference/airnode/next/understand/configuring.md#aws-setup-aws-deployment-only) -and for GCP deployment, see the -[GCP Setup](/reference/airnode/next/understand/configuring.md#gcp-setup-gcp-deployment-only). +In order to deploy Airnode to a serverless cloud provider, you need to provide cloud provider credentials to the Airnode deployer image. The deployer image currently supports deploying to AWS and GCP. For AWS deployment, see the [AWS Setup](/reference/airnode/next/understand/configuring.md#aws-setup-aws-deployment-only) and for GCP deployment, see the [GCP Setup](/reference/airnode/next/understand/configuring.md#gcp-setup-gcp-deployment-only). ## Deployer Logs -The deployer saves log files by default into the `config/logs/` direcotry, but -this can be changed by passing a `--logs` argument to the command. +The deployer saves log files by default into the `config/logs/` direcotry, but this can be changed by passing a `--logs` argument to the command. ## Deployer Image Commands -Commands are similar for AWS and GCP. Any differences between AWS and GCP are -noted where they exist. +Commands are similar for AWS and GCP. Any differences between AWS and GCP are noted where they exist. - `deploy` - `list` @@ -77,22 +61,16 @@ noted where they exist. ### `deploy` -The [deploy](/reference/airnode/next/packages/deployer.md#deploy) command will -create the Airnode with a cloud provider or update it if it already exists. -Three files are needed to run the deploy command. +The [deploy](/reference/airnode/next/packages/deployer.md#deploy) command will create the Airnode with a cloud provider or update it if it already exists. Three files are needed to run the deploy command. - config.json - secrets.env - aws.env (AWS only) - gcp.json (GCP only) -See -[Deploying an Airnode](/reference/airnode/next/understand/deploying.md#deploy-with-docker) -for deployment commands specific to various operating systems and cloud -providers. +See [Deploying an Airnode](/reference/airnode/next/understand/deploying.md#deploy-with-docker) for deployment commands specific to various operating systems and cloud providers. -Note that a `receipt.json` file will be created upon completion. It contains -some deployment information and is used to remove the Airnode. +Note that a `receipt.json` file will be created upon completion. It contains some deployment information and is used to remove the Airnode. @@ -120,24 +98,14 @@ docker run -it --rm ^ #### Re-deployments -A unique deployment is defined by the value of -[nodeSetting.stage](/reference/airnode/next/deployment-files/config-json.md#stage). -If you deploy again, using the same `nodeSetting.stage` value, then you are -re-deploying or updating the previous deployment. +A unique deployment is defined by the value of [nodeSetting.stage](/reference/airnode/next/deployment-files/config-json.md#stage). If you deploy again, using the same `nodeSetting.stage` value, then you are re-deploying or updating the previous deployment. -By default the deployer will attempt to remove the Airnode should either a -deployment or re-deployment fail. But if either fails (and -[--auto-remove](/reference/airnode/next/packages/deployer.md#deploy) is false) -then the Airnode will not be removed, however it could be left in an unstable -state. You can alter the `deploy` command to change this behavior using the -following. +By default the deployer will attempt to remove the Airnode should either a deployment or re-deployment fail. But if either fails (and [--auto-remove](/reference/airnode/next/packages/deployer.md#deploy) is false) then the Airnode will not be removed, however it could be left in an unstable state. You can alter the `deploy` command to change this behavior using the following. - `--auto-remove true|false`: defaults to true - `--no-auto-remove` -Auto removal is usually recommended for development deployments. For production -deployments, consider changing the value of `nodeSetting.stage` to create a new -deployment and follow-up by removing the previous deployment. +Auto removal is usually recommended for development deployments. For production deployments, consider changing the value of `nodeSetting.stage` to create a new deployment and follow-up by removing the previous deployment. Use the following example to avoid the automatic removal of the Airnode. @@ -150,12 +118,7 @@ api3/airnode-deployer:0.15.0 deploy --auto-remove false ### `list` -Once one or more Airnodes were deployed using the -[deploy](/reference/airnode/next/docker/deployer-image.md#deploy) command above, -the [list](/reference/airnode/next/packages/deployer.md#list) command can be -used to list currently deployed Airnodes. Files for cloud provider -authentication are needed for the command to run correctly: `aws.env` (for AWS) -and/or `gcp.json` (for GCP). +Once one or more Airnodes were deployed using the [deploy](/reference/airnode/next/docker/deployer-image.md#deploy) command above, the [list](/reference/airnode/next/packages/deployer.md#list) command can be used to list currently deployed Airnodes. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -174,9 +137,7 @@ docker run -it --rm ^ ::: -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ::: code-group @@ -197,14 +158,7 @@ docker run -it --rm ^ ### `info` -Retrieve more information about a deployment with the -[info](/reference/airnode/next/packages/deployer.md#info) command. Use the -deployment ID from the -[list](/reference/airnode/next/docker/deployer-image.md#list) command above to -request information about a specific deployment. The retrieved information -include deployment's Airnode address, stage, Airnode version and the update -history. Files for cloud provider authentication are needed for the command to -run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). +Retrieve more information about a deployment with the [info](/reference/airnode/next/packages/deployer.md#info) command. Use the deployment ID from the [list](/reference/airnode/next/docker/deployer-image.md#list) command above to request information about a specific deployment. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -225,17 +179,7 @@ docker run -it --rm ^ ### `rollback` -To revert to a previous version of a deployment, use the -[rollback](/reference/airnode/next/packages/deployer.md#rollback) command. -Provide the deployment ID from the -[list](/reference/airnode/next/docker/deployer-image.md#list) command above to -specify which deployment will be changed. Also provide the desired version ID -from the [info](/reference/airnode/next/docker/deployer-image.md#info) command -above to revert to. The -[rollback](/reference/airnode/next/packages/deployer.md#rollback) command will -then fetch the configuration files of the specified version and deploy the -version using its configuration. Check this with the -[info](/reference/airnode/next/docker/deployer-image.md#info) command above. +To revert to a previous version of a deployment, use the [rollback](/reference/airnode/next/packages/deployer.md#rollback) command. Provide the deployment ID from the [list](/reference/airnode/next/docker/deployer-image.md#list) command above to specify which deployment will be changed. Also provide the desired version ID from the [info](/reference/airnode/next/docker/deployer-image.md#info) command above to revert to. The [rollback](/reference/airnode/next/packages/deployer.md#rollback) command will then fetch the configuration files of the specified version and deploy the version using its configuration. Check this with the [info](/reference/airnode/next/docker/deployer-image.md#info) command above. ::: code-group @@ -256,23 +200,7 @@ docker run -it --rm ^ ### `fetch-files` -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the -[fetch-files](/reference/airnode/next/packages/deployer.md#fetch-files) command -to retrieve them. You need to provide the deployment ID from the -[list](/reference/airnode/next/docker/deployer-image.md#list) command above to -specify the desired deployment. By default, the files from the latest version of -this deployment are fetched. Alternatively, you can additionally provide a -deployment version ID from the -[info](/reference/airnode/next/docker/deployer-image.md#info) command above to -specify the desired deployment version. By default, the archive with the files -is stored in the `config` directory **within the Docker container** that is, in -the example below, mapped to your current working directory. You can change the -output directory by providing an `--output-dir` option specifying a different -directory instead. Don't forget to add a mapping for the new output directory so -you'll be able to access the files. Files for cloud provider authentication are -needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for -GCP). +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the [fetch-files](/reference/airnode/next/packages/deployer.md#fetch-files) command to retrieve them. You need to provide the deployment ID from the [list](/reference/airnode/next/docker/deployer-image.md#list) command above to specify the desired deployment. By default, the files from the latest version of this deployment are fetched. Alternatively, you can additionally provide a deployment version ID from the [info](/reference/airnode/next/docker/deployer-image.md#info) command above to specify the desired deployment version. By default, the archive with the files is stored in the `config` directory **within the Docker container** that is, in the example below, mapped to your current working directory. You can change the output directory by providing an `--output-dir` option specifying a different directory instead. Don't forget to add a mapping for the new output directory so you'll be able to access the files. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -293,16 +221,7 @@ docker run -it --rm ^ ### `remove` -A deployed Airnode can be removed via the -[remove](/reference/airnode/next/packages/deployer.md#remove) command. To remove -Airnode, use the deployment ID from the -[list](/reference/airnode/next/docker/deployer-image.md#list) command above. -Airnode's update history, that can be seen by the -[info](/reference/airnode/next/docker/deployer-image.md#info) command, will be -removed as well. Files for cloud provider authentication are needed for the -command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is -the recommended way to remove a deployment, but an alternative is the -`remove-with-receipt` command. +A deployed Airnode can be removed via the [remove](/reference/airnode/next/packages/deployer.md#remove) command. To remove Airnode, use the deployment ID from the [list](/reference/airnode/next/docker/deployer-image.md#list) command above. Airnode's update history, that can be seen by the [info](/reference/airnode/next/docker/deployer-image.md#info) command, will be removed as well. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is the recommended way to remove a deployment, but an alternative is the `remove-with-receipt` command. ::: code-group @@ -323,12 +242,7 @@ docker run -it --rm ^ ### `remove-with-receipt` -When an Airnode was deployed using the `deploy` command, a `receipt.json` file -was created. This file is used to remove the Airnode. The -[remove-with-receipt](/reference/airnode/next/packages/deployer.md#remove-with-receipt) -command is identical for AWS and GCP. Files for cloud provider authentication -are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` -(for GCP). +When an Airnode was deployed using the `deploy` command, a `receipt.json` file was created. This file is used to remove the Airnode. The [remove-with-receipt](/reference/airnode/next/packages/deployer.md#remove-with-receipt) command is identical for AWS and GCP. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -349,22 +263,11 @@ docker run -it --rm ^ ## Manual Removal -Optionally you can remove an Airnode manually though it is highly recommended -that you do so using the deployer image's `remove-with-receipt` or `remove` -commands. When removing manually, you will need the Airnode's deployment ID, -`deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., -`production`). They can be found in the -[receipt.json](/reference/airnode/next/deployment-files/receipt-json.md) file -generated when deploying the Airnode. These are included in the element name of -AWS and GCP deployed features. Airnode has a presence in several areas of both -AWS and GCP as listed below. +Optionally you can remove an Airnode manually though it is highly recommended that you do so using the deployer image's `remove-with-receipt` or `remove` commands. When removing manually, you will need the Airnode's deployment ID, `deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., `production`). They can be found in the [receipt.json](/reference/airnode/next/deployment-files/receipt-json.md) file generated when deploying the Airnode. These are included in the element name of AWS and GCP deployed features. Airnode has a presence in several areas of both AWS and GCP as listed below. ::: danger Remember -Only delete elements of a feature with the `deploymentId` and `stage` name -contained in the element's name. There can be more than one Airnode. Example: -(airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the -deploymentId and `production` is the stage name. +Only delete elements of a feature with the `deploymentId` and `stage` name contained in the element's name. There can be more than one Airnode. Example: (airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the deploymentId and `production` is the stage name. ::: @@ -376,7 +279,6 @@ deploymentId and `production` is the stage name. -Learn more about AWS or GCP resources that Airnode uses in the -[Cloud Resources](/reference/airnode/next/cloud-resources.md) doc. +Learn more about AWS or GCP resources that Airnode uses in the [Cloud Resources](/reference/airnode/next/cloud-resources.md) doc. diff --git a/docs/reference/airnode/next/docker/index.md b/docs/reference/airnode/next/docker/index.md index 2096e2fa..9a2409cf 100644 --- a/docs/reference/airnode/next/docker/index.md +++ b/docs/reference/airnode/next/docker/index.md @@ -19,31 +19,19 @@ tags: # {{$frontmatter.title}} -Using Docker is the easiest way to both deploy an Airnode to a cloud provider -and to run an Airnode locally. There are two Docker images: the Airnode deployer -image and the Airnode client image. +Using Docker is the easiest way to both deploy an Airnode to a cloud provider and to run an Airnode locally. There are two Docker images: the Airnode deployer image and the Airnode client image. -There is also a docker image wrapping the admin CLI package, as an alternative -to using `npx`. +There is also a docker image wrapping the admin CLI package, as an alternative to using `npx`. -To use these images first install [Docker](https://docs.docker.com/get-docker/) -if it is not present on your system. +To use these images first install [Docker](https://docs.docker.com/get-docker/) if it is not present on your system. -If using a Linux distribution that enforces Selinux policies, allow the Docker -images access to the host directory by -[creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). +If using a Linux distribution that enforces Selinux policies, allow the Docker images access to the host directory by [creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). -- The [deployer image](/reference/airnode/next/docker/deployer-image.md) deploys - the node in the form of serverless functions to a serverless cloud provider - (e.g. AWS Lambda). +- The [deployer image](/reference/airnode/next/docker/deployer-image.md) deploys the node in the form of serverless functions to a serverless cloud provider (e.g. AWS Lambda). -- The [client image](/reference/airnode/next/docker/client-image.md) is the node - itself, containerized. The container can be run locally or deployed to a cloud - hosting service (e.g. AWS EC2 or Lightsail). +- The [client image](/reference/airnode/next/docker/client-image.md) is the node itself, containerized. The container can be run locally or deployed to a cloud hosting service (e.g. AWS EC2 or Lightsail). -- The [admin CLI image](/reference/airnode/next/docker/admin-cli-image.md) wraps - the admin CLI package in a docker image to provide an alternative usage option - to the Admin CLI commands (npx). +- The [admin CLI image](/reference/airnode/next/docker/admin-cli-image.md) wraps the admin CLI package in a docker image to provide an alternative usage option to the Admin CLI commands (npx). ## DockerHub diff --git a/docs/reference/airnode/next/index.md b/docs/reference/airnode/next/index.md index 9ace2c1b..d2161784 100644 --- a/docs/reference/airnode/next/index.md +++ b/docs/reference/airnode/next/index.md @@ -19,17 +19,9 @@ tags: # {{$frontmatter.title}} -Use the contract addresses listed in the tables below to interact with Airnode -on EVM-compatible blockchains. Additional addresses will be added as contracts -are deployed, but feel free to -[submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a -new deployment. - -The contract addresses listed below are sourced from the Airnode monorepo -[airnode-protocol](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-protocol) -and can be found in its -[deployments](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-protocol/deployments) -directory. +Use the contract addresses listed in the tables below to interact with Airnode on EVM-compatible blockchains. Additional addresses will be added as contracts are deployed, but feel free to [submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a new deployment. + +The contract addresses listed below are sourced from the Airnode monorepo [airnode-protocol](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-protocol) and can be found in its [deployments](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-protocol/deployments) directory. ## AirnodeRrpV0 diff --git a/docs/reference/airnode/next/migration.md b/docs/reference/airnode/next/migration.md index 0834e1ac..ba5c37bb 100644 --- a/docs/reference/airnode/next/migration.md +++ b/docs/reference/airnode/next/migration.md @@ -19,13 +19,11 @@ tags: # {{$frontmatter.title}} -This document describes changes to `config.json` as well as to user facing -services related to Airnode, such as airnode-deployer, airnode-admin, etc. +This document describes changes to `config.json` as well as to user facing services related to Airnode, such as airnode-deployer, airnode-admin, etc. ## Changes to `config.json` -The following assumes a valid v0.13 `config.json` file. All changes listed below -must be implemented in order to migrate to Airnode v0.14.1. +The following assumes a valid v0.13 `config.json` file. All changes listed below must be implemented in order to migrate to Airnode v0.14.1. 1. `nodeSettings.nodeVersion` @@ -51,22 +49,16 @@ Updated to "2.3.2". ## Breaking changes outside of `config.json` -The following are not expected to have an impact on users, but are listed here -for completeness. +The following are not expected to have an impact on users, but are listed here for completeness. - The OEV interface has changed in the following ways: - `api3ServerV1` has replaced `dapiServerAddress` - `templateId` has replaced `endpointId` and `encodedParameters` -- `chainNames` and `networks` are no longer exported from `references.json` of - `airnode-protocol`. +- `chainNames` and `networks` are no longer exported from `references.json` of `airnode-protocol`. - Support for `boba-avalanche` has been removed as the chain has shut down. ## New features and fixes -- In conjunction with OIS v2.3.2, there is now a version 2 of pre-processing and - post-processing. More details can be found in the - [OIS reference](/reference/ois/latest/processing.md#v2). +- In conjunction with OIS v2.3.2, there is now a version 2 of pre-processing and post-processing. More details can be found in the [OIS reference](/reference/ois/latest/processing.md#v2). - OEV gateway AWS lambda memory has been increased from 256 MB to 2048 MB -- Airnode protocol contracts have been deployed on LightLink, LightLink Goerli - Testnet, and Blast Sepolia Testnet chains. You can find the addresses on the - [Contracts page](/reference/airnode/next/index.md). +- Airnode protocol contracts have been deployed on LightLink, LightLink Goerli Testnet, and Blast Sepolia Testnet chains. You can find the addresses on the [Contracts page](/reference/airnode/next/index.md). diff --git a/docs/reference/airnode/next/packages/adapter.md b/docs/reference/airnode/next/packages/adapter.md index fabf7dca..9643d46e 100644 --- a/docs/reference/airnode/next/packages/adapter.md +++ b/docs/reference/airnode/next/packages/adapter.md @@ -19,55 +19,36 @@ tags: # {{$frontmatter.title}} -The -[airnode-adapter](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-adapter) -package has multiple responsibilities. It is used for building requests from an -[Oracle Integration Specification (OIS)](/reference/ois/next/), executing them, -parsing the responses, but also converting and encoding them for on chain use. +The [airnode-adapter](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-adapter) package has multiple responsibilities. It is used for building requests from an [Oracle Integration Specification (OIS)](/reference/ois/next/), executing them, parsing the responses, but also converting and encoding them for on chain use. -It is an internal dependency of Airnode, but can also be used standalone as an -API. +It is an internal dependency of Airnode, but can also be used standalone as an API. ## Installation -You can install `@api3/airnode-adapter` by adding it to the `package.json` file -in your project. +You can install `@api3/airnode-adapter` by adding it to the `package.json` file in your project. ```sh npm install --save @api3/airnode-adapter ``` -You shouldn't need to use the adapter package directly. However, you might want -to use its API to double check the conversion or encoding behavior for which you -can install this package and verify your assumptions. +You shouldn't need to use the adapter package directly. However, you might want to use its API to double check the conversion or encoding behavior for which you can install this package and verify your assumptions. ## Conversion -While the adapter package has many responsibilities, many of those can be -treated as implementation details. On the other hand, there are a few important -behaviors to be noted when converting the response values based on the target -type and making the response transaction on chain. +While the adapter package has many responsibilities, many of those can be treated as implementation details. On the other hand, there are a few important behaviors to be noted when converting the response values based on the target type and making the response transaction on chain. Altogether, the response cycle consists of multiple steps 1. A successful API call is made and Airnode receives a response value. -2. The value to be converted is extracted from the response using the - [\_path](/reference/ois/next/reserved-parameters.md#path) from the OIS - object. -3. This extracted value is converted to the target type. Conversions are - performed internally by the `castValue(value, type)` function. -4. The converted value is encoded to the native solidity type based on the - [\_type](/reference/ois/next/reserved-parameters.md#type) from the OIS - object. Encoding is performed internally by the `encodeValue(value, type)` - function. +2. The value to be converted is extracted from the response using the [\_path](/reference/ois/next/reserved-parameters.md#path) from the OIS object. +3. This extracted value is converted to the target type. Conversions are performed internally by the `castValue(value, type)` function. +4. The converted value is encoded to the native solidity type based on the [\_type](/reference/ois/next/reserved-parameters.md#type) from the OIS object. Encoding is performed internally by the `encodeValue(value, type)` function. -If any of the steps above fail, an error is thrown. This will fail the given API -request and the error reason can be found in the logs. +If any of the steps above fail, an error is thrown. This will fail the given API request and the error reason can be found in the logs. -The rest of this section covers the conversion logic for all of the supported -types. +The rest of this section covers the conversion logic for all of the supported types. ### `int256` or `uint256` @@ -86,8 +67,7 @@ const ERROR_VALUES = [ ]; ``` -There are a few special strings and boolean values that are convertible to -`int256` or `uint256`: +There are a few special strings and boolean values that are convertible to `int256` or `uint256`: ```ts const SPECIAL_INT_VALUES = [false, 'false', true, 'true']; @@ -97,11 +77,7 @@ console.log(values); // [0, 0, 1, 1]; ``` -Number strings and numbers will attempt to be converted to -[BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be -multiplied by the value of the -[\_times](/reference/ois/next/reserved-parameters.md#times) parameter if it is -present. +Number strings and numbers will attempt to be converted to [BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be multiplied by the value of the [\_times](/reference/ois/next/reserved-parameters.md#times) parameter if it is present. ```ts const VALID_INT_VALUES = ['123.456', 7777]; @@ -111,17 +87,11 @@ console.log(values); // [new BigNumber(123.456), new BigNumber(7777)]; ``` -Conversion for `int256` and `uint256` is the same - this means that `-123` can -be converted to `uint256`. However, an error will be thrown while encoding. +Conversion for `int256` and `uint256` is the same - this means that `-123` can be converted to `uint256`. However, an error will be thrown while encoding. :::warning Flooring -Beware that any floating point number will be **floored**. This is necessary, -because floating point numbers are not valid in solidity. To mitigate precision -loss, you can use the -[`_times`](/reference/ois/next/reserved-parameters.md#times) parameter that is -sufficiently large. For example, if the API response is a USD currency, you -might want to use `_times: "100"` to convert the value to cents. +Beware that any floating point number will be **floored**. This is necessary, because floating point numbers are not valid in solidity. To mitigate precision loss, you can use the [`_times`](/reference/ois/next/reserved-parameters.md#times) parameter that is sufficiently large. For example, if the API response is a USD currency, you might want to use `_times: "100"` to convert the value to cents. ::: @@ -144,17 +114,9 @@ All other values are converted to `true`. ### `bytes32` -There is no conversion for `bytes32` - the value is expected to be a valid hex -string representing the encoded 32 bytes value. This means that the encoding -**must** be implemented on the API side. If you want to delegate the encoding to -Airnode, see the documentation for -[`string32`](/reference/airnode/next/packages/adapter.md#string32). +There is no conversion for `bytes32` - the value is expected to be a valid hex string representing the encoded 32 bytes value. This means that the encoding **must** be implemented on the API side. If you want to delegate the encoding to Airnode, see the documentation for [`string32`](/reference/airnode/next/packages/adapter.md#string32). -For example, let's say the API wants to encode the following string -`simple string` with length 13. Its encoding is -0x73696d706c6520737472696e6700000000000000000000000000000000000000. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. +For example, let's say the API wants to encode the following string `simple string` with length 13. Its encoding is 0x73696d706c6520737472696e6700000000000000000000000000000000000000. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. You can use [ethers](https://docs.ethers.io/v5/) to encode these on the API side @@ -166,29 +128,16 @@ console.log(encoded); // 0x73696d706c6520737472696e67000000000000000000000000000 ### `address` -There is no conversion for `address` - the value is expected to be a string -representing a valid address. Valid examples are: +There is no conversion for `address` - the value is expected to be a string representing a valid address. Valid examples are: -- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) - of an address. -- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - - all lowercase address. +- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) of an address. +- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - all lowercase address. ### `bytes` -There is no conversion for `bytes` - the value is expected to be a valid hex -string representing the encoded value. This means that the encoding to bytes -**must** be implemented on the API side. If you want to send a string, see the -documentation for -[`string`](/reference/airnode/next/packages/adapter.md#string). +There is no conversion for `bytes` - the value is expected to be a valid hex string representing the encoded value. This means that the encoding to bytes **must** be implemented on the API side. If you want to send a string, see the documentation for [`string`](/reference/airnode/next/packages/adapter.md#string). -For example, let's say the API wants to encode the following string -`this is an example string that is a bit longer`. Its encoding is -0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these -on the API side. +For example, let's say the API wants to encode the following string `this is an example string that is a bit longer`. Its encoding is 0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these on the API side. ```js const value = 'this is an example string that is a bit longer'; @@ -198,9 +147,7 @@ console.log(encodedValue); // 0x7468697320697320616e206578616d706c6520737472696e ### `string` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. All other values will be converted to -`string` and before encoded on chain using the `string` type. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. All other values will be converted to `string` and before encoded on chain using the `string` type. ```js const values = [ @@ -220,20 +167,11 @@ const mappedValues = values.map((v) => { ### `string32` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. -However, there is one exception, if the stringified value contains more than 31 -characters it will be **trimmed down** to only the first 31 characters during -conversion. +However, there is one exception, if the stringified value contains more than 31 characters it will be **trimmed down** to only the first 31 characters during conversion. -For example, if the API response is the following string -`this is an example string that is a bit longer` with length 46. It will be -first trimmed to 31 characters, string `this is an example string that ` and -afterwards converted to -0x7468697320697320616e206578616d706c6520737472696e6720746861742000. -Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using -the following snippet +For example, if the API response is the following string `this is an example string that is a bit longer` with length 46. It will be first trimmed to 31 characters, string `this is an example string that ` and afterwards converted to 0x7468697320697320616e206578616d706c6520737472696e6720746861742000. Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using the following snippet ```js const encoded = @@ -244,17 +182,11 @@ console.log(decoded); // "this is an example string that " ### Arrays -Conversion of arrays depends on the primitive type. All values of the array (or -nested array) will be converted according to the rules of the primitive type. +Conversion of arrays depends on the primitive type. All values of the array (or nested array) will be converted according to the rules of the primitive type. For example: -- `int256[]` - has primitive type `int256`. All elements of this array follow - the [`int256`](/reference/airnode/next/packages/adapter.md#int256-or-uint256) - rules. -- `string32[7][][5]` - is a multidimensional array, where some dimensions are - fixed and some not. This is irrelevant though, and all the elements are - converted based on - [`string32`](/reference/airnode/next/packages/adapter.md#string32) rules. +- `int256[]` - has primitive type `int256`. All elements of this array follow the [`int256`](/reference/airnode/next/packages/adapter.md#int256-or-uint256) rules. +- `string32[7][][5]` - is a multidimensional array, where some dimensions are fixed and some not. This is irrelevant though, and all the elements are converted based on [`string32`](/reference/airnode/next/packages/adapter.md#string32) rules. diff --git a/docs/reference/airnode/next/packages/admin-cli.md b/docs/reference/airnode/next/packages/admin-cli.md index 70102cb0..b342fe45 100644 --- a/docs/reference/airnode/next/packages/admin-cli.md +++ b/docs/reference/airnode/next/packages/admin-cli.md @@ -19,54 +19,26 @@ tags: # {{$frontmatter.title}} -Use the -[airnode-admin](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin) -Admin CLI tool to interact with Airnode across blockchains. There are commands -for both developers (dApp) and API providers. Developers can sponsor -[requester](/reference/airnode/next/concepts/requester.md) contracts and derive -[sponsorWallets](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) for -Airnodes. API providers can build -[Airnodes](/reference/airnode/next/concepts/airnode.md) that serve their API -data to requester contracts. +Use the [airnode-admin](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin) Admin CLI tool to interact with Airnode across blockchains. There are commands for both developers (dApp) and API providers. Developers can sponsor [requester](/reference/airnode/next/concepts/requester.md) contracts and derive [sponsorWallets](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) for Airnodes. API providers can build [Airnodes](/reference/airnode/next/concepts/airnode.md) that serve their API data to requester contracts. ::: warning Transaction Gas Costs -Some commands will incur transaction fees. These are per call transaction gas -costs and are relatively small. See the -[Developer Fees](/reference/airnode/next/developers/fees.md) -doc. +Some commands will incur transaction fees. These are per call transaction gas costs and are relatively small. See the [Developer Fees](/reference/airnode/next/developers/fees.md) doc. ::: -Almost all commands require you to provide a blockchain `providerUrl`. Following -are just two examples of many possibilities. See the -[Chain Providers](/reference/airnode/next/concepts/chain-providers.md) doc for -more information. +Almost all commands require you to provide a blockchain `providerUrl`. Following are just two examples of many possibilities. See the [Chain Providers](/reference/airnode/next/concepts/chain-providers.md) doc for more information. - `https://eth-goerli.gateway.pokt.network/v1/lb/` - `https://sepolia.infura.io/v3/` -The CLI connects to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -or the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract, which addresses are derived from the current chain. You can optionally -specify the contract addresses yourself by providing optional -`airnode-rrp-address` or `requester-authorizer-with-airnode` command argument -with the address of the deployed contract on your targeted chain. - -Commands that require `mnemonic` will make an on-chain transaction. The -application will derive the account from the mnemonic with default ethereum -derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional -parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet -that is associated with the mnemonic is funded on the target chain. The -application will not exit until the transaction is confirmed. +The CLI connects to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) or the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract, which addresses are derived from the current chain. You can optionally specify the contract addresses yourself by providing optional `airnode-rrp-address` or `requester-authorizer-with-airnode` command argument with the address of the deployed contract on your targeted chain. + +Commands that require `mnemonic` will make an on-chain transaction. The application will derive the account from the mnemonic with default ethereum derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet that is associated with the mnemonic is funded on the target chain. The application will not exit until the transaction is confirmed. ### Using transaction overrides -CLI commands also support the following transaction overrides as optional -arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and -`max-priority-fee` (EIP-1559 transactions) and `nonce`. +CLI commands also support the following transaction overrides as optional arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and `max-priority-fee` (EIP-1559 transactions) and `nonce`. ### Default transaction overrides @@ -115,9 +87,7 @@ docker run api3/airnode-admin:0.15.0 $COMMAND --help ## SDK -You can also use the package programmatically. The SDK exports respective -functions for all CLI commands as well as helper functions for obtaining the -contract instance on the targeted chain. +You can also use the package programmatically. The SDK exports respective functions for all CLI commands as well as helper functions for obtaining the contract instance on the targeted chain. ```js import { sponsorRequester, getAirnodeRrpWithSigner } from '@api3/airnode-admin'; @@ -133,9 +103,7 @@ const airnodeRrp = await getAirnodeRrpWithSigner( const requester = await sponsorRequester(airnodeRrp, requester); ``` -If you plan to use multiple commands it might be tedious to pass the contract -instance to every function call. For this reason there is also class based -`AdminSdk` which you initialize with `AirnodeRrp` contract only once. +If you plan to use multiple commands it might be tedious to pass the contract instance to every function call. For this reason there is also class based `AdminSdk` which you initialize with `AirnodeRrp` contract only once. ```js import { AdminSdk } from '@api3/airnode-admin'; @@ -157,14 +125,11 @@ const requester = await adminSdk.sponsorRequester(requester); adminSdk.airnodeRrp = airnodeRrp.connect(someOtherWallet); ``` -The SDK will also provide TS typings out of the box. Please, refer to the -implementation for more details. +The SDK will also provide TS typings out of the box. Please, refer to the implementation for more details. ### Using transaction overrides -You can also use transaction overrides to customize gas limits and fee settings. -The SDK simply passes the overrides parameter to the contract method so you can -use any overrides supported by the ethers library. +You can also use transaction overrides to customize gas limits and fee settings. The SDK simply passes the overrides parameter to the contract method so you can use any overrides supported by the ethers library. ```js import { ethers } from 'ethers'; @@ -188,14 +153,7 @@ const requester = await adminSdk.sponsorRequester(requester, overrides); ## Sponsors -Commands related to a [sponsor's](/reference/airnode/next/concepts/sponsor.md) -relationships between -[requesters](/reference/airnode/next/concepts/requester.md) and -[sponsorWallets](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) as -well as [templates](/reference/airnode/next/concepts/template.md) used by a -sponsor's requesters. Some of these commands connect to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract where the signer is sponsor account. +Commands related to a [sponsor's](/reference/airnode/next/concepts/sponsor.md) relationships between [requesters](/reference/airnode/next/concepts/requester.md) and [sponsorWallets](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) as well as [templates](/reference/airnode/next/concepts/template.md) used by a sponsor's requesters. Some of these commands connect to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract where the signer is sponsor account. - [sponsor-requester](/reference/airnode/next/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/next/packages/admin-cli.md#unsponsor-requester) @@ -210,39 +168,19 @@ protocol contract where the signer is sponsor account. ### `sponsor-requester` -[Sponsors](/reference/airnode/next/concepts/sponsor.md) a -[requester](/reference/airnode/next/concepts/requester.md) contract so that its -requests can be fulfilled by the -[sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) of an -Airnode. The account derived from the `mnemonic` you provide must belong to the -sponsor. +[Sponsors](/reference/airnode/next/concepts/sponsor.md) a [requester](/reference/airnode/next/concepts/requester.md) contract so that its requests can be fulfilled by the [sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) of an Airnode. The account derived from the `mnemonic` you provide must belong to the sponsor. -Sponsoring a requester and using the returned `sponsorAddress` to derive a -`sponsorWallet` for an Airnode creates a -[relationship](/reference/airnode/next/concepts/sponsor.md) between the -requester and the Airnode, see the -[`derive-sponsor-wallet-address`](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Sponsoring a requester and using the returned `sponsorAddress` to derive a `sponsorWallet` for an Airnode creates a [relationship](/reference/airnode/next/concepts/sponsor.md) between the requester and the Airnode, see the [`derive-sponsor-wallet-address`](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a - `sponsorAddress` as the default account of the mnemonic unless a - `derivation-path` is specified. It's also used to pay gas costs from the - mnemonic's default account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a `sponsorAddress` as the default account of the mnemonic unless a `derivation-path` is specified. It's also used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to sponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. If this parameter is not provided, it will be deduced from - the current chain. If there is no RRP address found for the given chain an - error is thrown. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. If this parameter is not provided, it will be deduced from the current chain. If there is no RRP address found for the given chain an error is thrown. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -265,29 +203,17 @@ npx @api3/airnode-admin sponsor-requester ^ ### `unsponsor-requester` -Removes the sponsorship of a -[requester](/reference/airnode/next/concepts/requester.md) contract so that its -requests can no longer be fulfilled by the -[sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). The -account derived from the `mnemonic` you provide here has to belong to the -sponsor. +Removes the sponsorship of a [requester](/reference/airnode/next/concepts/requester.md) contract so that its requests can no longer be fulfilled by the [sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). The account derived from the `mnemonic` you provide here has to belong to the sponsor. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used - to sponsor the requester. Used to pay gas costs from the mnemonic's default - account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used to sponsor the requester. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to unsponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -310,17 +236,12 @@ npx @api3/airnode-admin unsponsor-requester ^ ### `get-sponsor-status` -Returns the sponsor status for a given -[sponsor](/reference/airnode/next/concepts/sponsor.md) and -[requester](/reference/airnode/next/concepts/requester.md) (`true` if sponsored, -`false` otherwise). +Returns the sponsor status for a given [sponsor](/reference/airnode/next/concepts/sponsor.md) and [requester](/reference/airnode/next/concepts/requester.md) (`true` if sponsored, `false` otherwise). - `provider-url`: A valid blockchain provider URL. -- `sponsor-address`: The `sponsorAddress` returned when the requester was - sponsored. +- `sponsor-address`: The `sponsorAddress` returned when the requester was sponsored. - `requester-address`: The requester contract address. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -342,16 +263,9 @@ npx @api3/airnode-admin get-sponsor-status ^ ### `derive-sponsor-wallet-address` -Derives the address of the wallet designated by an Airnode for a -[sponsor](/reference/airnode/next/concepts/sponsor.md), which is called the -[sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). This -command will error if `airnode-xpub` does not belong to the HDNode with the path -`m/44'/60'/0'` of the Airnode wallet. See the -[`derive-airnode-xpub`](/reference/airnode/next/packages/admin-cli.md#derive-airnode-xpub) -command. +Derives the address of the wallet designated by an Airnode for a [sponsor](/reference/airnode/next/concepts/sponsor.md), which is called the [sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). This command will error if `airnode-xpub` does not belong to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. See the [`derive-airnode-xpub`](/reference/airnode/next/packages/admin-cli.md#derive-airnode-xpub) command. -- `airnode-xpub`: The extended public address of the Airnode for path - `m/44'/60'/0'`. +- `airnode-xpub`: The extended public address of the Airnode for path `m/44'/60'/0'`. - `airnode-address`: The public address of the Airnode. - `sponsor-address`: The address of the sponsor account. @@ -375,27 +289,17 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ### `create-template` -Reads a file, uses its contents to create a -[template](/reference/airnode/next/concepts/template.md) and returns a -`template-id`. Also see -[Using Templates](/reference/airnode/next/developers/using-templates.md) for an -example template file. +Reads a file, uses its contents to create a [template](/reference/airnode/next/concepts/template.md) and returns a `template-id`. Also see [Using Templates](/reference/airnode/next/developers/using-templates.md) for an example template file. - `provider-url`: A valid blockchain provider URL. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `template-file-path`: Path to the template file to create on-chain. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -418,20 +322,11 @@ npx @api3/airnode-admin create-template ^ ### `create-inline-template` -It is possible to inline Airnode templates inside config.json in a `templates` -section. These templates need to be published on chain, but inlining them inside -config provides more clarity which templates can be used for template requests -and also saves a blockchain call . +It is possible to inline Airnode templates inside config.json in a `templates` section. These templates need to be published on chain, but inlining them inside config provides more clarity which templates can be used for template requests and also saves a blockchain call . -The command reads a template file, uses its contents to create a -[template](/reference/airnode/next/concepts/template.md) and returns the data -necessary to inline the template inside config. See -[Using Templates](/reference/airnode/next/developers/using-templates.md) for an -example template file. +The command reads a template file, uses its contents to create a [template](/reference/airnode/next/concepts/template.md) and returns the data necessary to inline the template inside config. See [Using Templates](/reference/airnode/next/developers/using-templates.md) for an example template file. -This command does **not** create a template on chain. Be sure to use the -[create-template](/reference/airnode/next/packages/admin-cli.md#create-template) -command on chain before making template requests. +This command does **not** create a template on chain. Be sure to use the [create-template](/reference/airnode/next/packages/admin-cli.md#create-template) command on chain before making template requests. - `template-file-path`: Path to the template file to create on-chain. @@ -451,13 +346,11 @@ npx @api3/airnode-admin create-inline-template ^ ### `get-template` -Returns the [template](/reference/airnode/next/concepts/template.md) for the -given `template-id`. +Returns the [template](/reference/airnode/next/concepts/template.md) for the given `template-id`. - `provider-url`: A valid blockchain provider URL. - `template-id`: The id of a template to return. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -477,50 +370,28 @@ npx @api3/airnode-admin get-template ^ ### `request-withdrawal` -Requests a [withdrawal](/reference/airnode/next/concepts/sponsor.md#withdrawals) -from a -[sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) -managed by an Airnode. +Requests a [withdrawal](/reference/airnode/next/concepts/sponsor.md#withdrawals) from a [sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) managed by an Airnode. -The funds will be returned to the account derived from the `sponsor-mnemonic`. -This account must belong to a -[sponsor](/reference/airnode/next/concepts/sponsor.md) for the specified -[sponsor wallet address](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) -in the command. +The funds will be returned to the account derived from the `sponsor-mnemonic`. This account must belong to a [sponsor](/reference/airnode/next/concepts/sponsor.md) for the specified [sponsor wallet address](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) in the command. -After the request is made, it needs to be fulfilled by Airnode, so the return -value of this command is only a `withdrawal-request-id` which you can use to -call -[check-withdrawal-request](/reference/airnode/next/packages/admin-cli.md#check-withdrawal-request) -to see whether the request was processed or not. +After the request is made, it needs to be fulfilled by Airnode, so the return value of this command is only a `withdrawal-request-id` which you can use to call [check-withdrawal-request](/reference/airnode/next/packages/admin-cli.md#check-withdrawal-request) to see whether the request was processed or not. ::: warning Withdrawal Priority -Airnode will drop any pending API calls associated with a `sponsorWallet` once a -withdrawal is requested. +Airnode will drop any pending API calls associated with a `sponsorWallet` once a withdrawal is requested. ::: - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from - the mnemonic's default account unless a `derivation-path` is specified. - Withdrawn funds will be added to this mnemonic's default address unless a - `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. Withdrawn funds will be added to this mnemonic's default address unless a `derivation-path` is specified. - `airnode-address`: The public address of the Airnode. -- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw - from. This address was returned by the `derive-sponsor-wallet-address` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)` : The destination address of the `mnemonic` - parameter to add the withdrawn funds to if the default address is not desired. +- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw from. This address was returned by the `derive-sponsor-wallet-address` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)` : The destination address of the `mnemonic` parameter to add the withdrawn funds to if the default address is not desired. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -545,17 +416,11 @@ npx @api3/airnode-admin request-withdrawal ^ ### `check-withdrawal-request` -Checks the status of the -[withdrawal](/reference/airnode/next/concepts/sponsor.md#withdrawals) request -with the given `withdrawal-request-id` from the -[request withdrawal command](/reference/airnode/next/packages/admin-cli.md#request-withdrawal) -above. +Checks the status of the [withdrawal](/reference/airnode/next/concepts/sponsor.md#withdrawals) request with the given `withdrawal-request-id` from the [request withdrawal command](/reference/airnode/next/packages/admin-cli.md#request-withdrawal) above. - `provider-url`: A valid blockchain provider URL. -- `withdrawal-request-id`: This id was returned by the `request-withdrawal` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `withdrawal-request-id`: This id was returned by the `request-withdrawal` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -575,16 +440,7 @@ npx @api3/airnode-admin check-withdrawal-request ^ ### `verify-airnode-xpub` -Verifies that the `airnode-xpub` belongs to the HDNode with the path -`m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode -address can be derived with provided Airnode -[xpub](/reference/airnode/next/concepts/airnode.md#xpub) with default derivation -path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. This command -will most likely be used by a -[sponsor](/reference/airnode/next/concepts/sponsor.md) to verify that the xpub -belongs to the Airnode before calling the -[derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Verifies that the `airnode-xpub` belongs to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode address can be derived with provided Airnode [xpub](/reference/airnode/next/concepts/airnode.md#xpub) with default derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. This command will most likely be used by a [sponsor](/reference/airnode/next/concepts/sponsor.md) to verify that the xpub belongs to the Airnode before calling the [derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) command. ::: code-group @@ -604,9 +460,7 @@ npx @api3/airnode-admin verify-airnode-xpub ^ ## Airnodes -Helper commands for a previously deployed Airnode. Some of these commands -connect to the AirnodeRrpV0.sol protocol contract where the signer must be the -Airnode wallet. +Helper commands for a previously deployed Airnode. Some of these commands connect to the AirnodeRrpV0.sol protocol contract where the signer must be the Airnode wallet. - [derive-airnode-xpub](/reference/airnode/next/packages/admin-cli.md#derive-airnode-xpub) - [derive-endpoint-id](/reference/airnode/next/packages/admin-cli.md#derive-endpoint-id) @@ -615,13 +469,7 @@ Airnode wallet. ### `derive-airnode-xpub` -Derives the Airnode extended public key -([xpub](/reference/airnode/next/concepts/airnode.md#xpub)). This xpub must be -announced via off-chain channels because it will be needed to derive a -[sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) -address. See the -[derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Derives the Airnode extended public key ([xpub](/reference/airnode/next/concepts/airnode.md#xpub)). This xpub must be announced via off-chain channels because it will be needed to derive a [sponsorWallet](/reference/airnode/next/concepts/sponsor.md#sponsorwallet) address. See the [derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `airnode-mnemonic`: The Airnode mnemonic for which the xpub is to be derived. @@ -639,15 +487,10 @@ npx @api3/airnode-admin derive-airnode-xpub --airnode-mnemonic "nature about sal ### `derive-endpoint-id` -Derives an -[endpointId](/reference/airnode/next/deployment-files/config-json.md#triggers) -from the OIS title and the endpoint's name as described in the -[endpoint](/reference/airnode/next/concepts/endpoint.md) documentation. Add the -`endpointId` to the config.json file (`triggers.rrp[n].endpointId`). +Derives an [endpointId](/reference/airnode/next/deployment-files/config-json.md#triggers) from the OIS title and the endpoint's name as described in the [endpoint](/reference/airnode/next/concepts/endpoint.md) documentation. Add the `endpointId` to the config.json file (`triggers.rrp[n].endpointId`). - `ois-title`: The title of the OIS from config.json (`ois.title`). -- `endpoint-name`: The name of the endpoint from config.json - (`triggers.rrp[n].endpointName`). +- `endpoint-name`: The name of the endpoint from config.json (`triggers.rrp[n].endpointName`). ::: code-group @@ -667,12 +510,7 @@ npx @api3/airnode-admin derive-endpoint-id ^ ### `generate-airnode-mnemonic` -Generates a unique mnemonic which can be used to create an -[airnode wallet](/reference/airnode/next/concepts/airnode.md#mnemonic). In -addition to the mnemonic, this command will also display the corresponding -[airnode address](/reference/airnode/next/concepts/airnode.md#airnodeaddress) -and its extended public key -([xpub](/reference/airnode/next/concepts/airnode.md#xpub)). +Generates a unique mnemonic which can be used to create an [airnode wallet](/reference/airnode/next/concepts/airnode.md#mnemonic). In addition to the mnemonic, this command will also display the corresponding [airnode address](/reference/airnode/next/concepts/airnode.md#airnodeaddress) and its extended public key ([xpub](/reference/airnode/next/concepts/airnode.md#xpub)). ```sh npx @api3/airnode-admin generate-airnode-mnemonic @@ -680,9 +518,7 @@ npx @api3/airnode-admin generate-airnode-mnemonic ### `generate-mnemonic` -Generates a unique mnemonic which can be used to create a wallet. In addition to -the mnemonic, this command will also display the corresponding default wallet -(path:m/44'/60'/0'/0/0) address. +Generates a unique mnemonic which can be used to create a wallet. In addition to the mnemonic, this command will also display the corresponding default wallet (path:m/44'/60'/0'/0/0) address. ```sh npx @api3/airnode-admin generate-mnemonic @@ -690,12 +526,7 @@ npx @api3/airnode-admin generate-mnemonic ### `derive-airnode-address` -Derives the -[airnode address](/reference/airnode/next/concepts/airnode.md#airnodeaddress) -which is the identifier of the particular Airnode on chain. The address is the -default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this -identifier for many other admin CLI commands, such as -[derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address). +Derives the [airnode address](/reference/airnode/next/concepts/airnode.md#airnodeaddress) which is the identifier of the particular Airnode on chain. The address is the default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this identifier for many other admin CLI commands, such as [derive-sponsor-wallet-address](/reference/airnode/next/packages/admin-cli.md#derive-sponsor-wallet-address). - `airnode-mnemonic`: A mnemonic used to generate the airnode address. @@ -715,18 +546,11 @@ npx @api3/airnode-admin derive-airnode-address ^ ## RequesterAuthorizerWithAirnode -RequesterAuthorizerWithAirnode contract was written by API3 as an -[authorizer](/reference/airnode/next/concepts/authorizers.md) contract that can -be used by any Airnode. Airnode owners can use this contract in addition to -authorizer contracts they have written themselves. +RequesterAuthorizerWithAirnode contract was written by API3 as an [authorizer](/reference/airnode/next/concepts/authorizers.md) contract that can be used by any Airnode. Airnode owners can use this contract in addition to authorizer contracts they have written themselves. -This authorizer contract can whitelist -[requesters](/reference/airnode/next/concepts/requester.md) where each Airnode -is administered by themselves. +This authorizer contract can whitelist [requesters](/reference/airnode/next/concepts/requester.md) where each Airnode is administered by themselves. -These commands connect to the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract. +These commands connect to the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract. - [set-whitelist-expiration](/reference/airnode/next/packages/admin-cli.md#set-whitelist-expiration) - [extend-whitelist-expiration](/reference/airnode/next/packages/admin-cli.md#extend-whitelist-expiration) @@ -736,32 +560,20 @@ contract. ### `set-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration setter to set the -whitelisting expiration of a requester for the Airnode–endpoint pair. This can -hasten expiration in the case the new expiration timestamp is prior to a -previously set timestamp. +Called by the Airnode wallet or a whitelist expiration setter to set the whitelisting expiration of a requester for the Airnode–endpoint pair. This can hasten expiration in the case the new expiration timestamp is prior to a previously set timestamp. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. The mnemonic must be at least an Admin or - Airnode wallet. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -790,31 +602,20 @@ npx @api3/airnode-admin set-whitelist-expiration ^ ### `extend-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration extender to extend the -whitelist expiration of a requester for the Airnode–endpoint pair. This command -expects that the new expiration timestamp is later then the previously set -timestamp. +Called by the Airnode wallet or a whitelist expiration extender to extend the whitelist expiration of a requester for the Airnode–endpoint pair. This command expects that the new expiration timestamp is later then the previously set timestamp. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -843,34 +644,21 @@ npx @api3/airnode-admin extend-whitelist-expiration ^ ### `set-indefinite-whitelist-status` -Called by the Airnode wallet or an indefinite whitelister to whitelist a -requester indefinitely for the Airnode–endpoint pair. This command can be used -to make whitelisting permanent in cases where it is needed to allow requests -even beyond the expiration period. +Called by the Airnode wallet or an indefinite whitelister to whitelist a requester indefinitely for the Airnode–endpoint pair. This command can be used to make whitelisting permanent in cases where it is needed to allow requests even beyond the expiration period. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. The default address of - the mnemonic will be used unless a derivation-path is provided. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. The default address of the mnemonic will be used unless a derivation-path is provided. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. -- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be - whitelisted indefinitely or not. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. +- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be whitelisted indefinitely or not. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -899,17 +687,13 @@ npx @api3/airnode-admin set-indefinite-whitelist-status ^ ### `get-whitelist-status` -Called to get the detailed whitelist status of a requester for the -Airnode–endpoint pair. +Called to get the detailed whitelist status of a requester for the Airnode–endpoint pair. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. ::: code-group @@ -937,9 +721,7 @@ Called to check if a requester is whitelisted to use the Airnode–endpoint pair - `provider-url`: A valid blockchain provider URL. - `requester-authorizer-with-airnode`: The authorizer contract address. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/next/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. @@ -967,8 +749,6 @@ npx @api3/airnode-admin is-requester-whitelisted ^ ## More Examples -You can find more examples in the -[test directory](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin/test) -of the `@api3-dao/airnode/package/admin` repo. +You can find more examples in the [test directory](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin/test) of the `@api3-dao/airnode/package/admin` repo. diff --git a/docs/reference/airnode/next/packages/airnode-abi.md b/docs/reference/airnode/next/packages/airnode-abi.md index 4f9e5035..14c6aee9 100644 --- a/docs/reference/airnode/next/packages/airnode-abi.md +++ b/docs/reference/airnode/next/packages/airnode-abi.md @@ -19,28 +19,15 @@ tags: # {{$frontmatter.title}} -The -[airnode-abi](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-abi) -package is a unique way to encode and decode parameters for use with Airnode. -Parameters are provided with encoding types, names and values. The types are -shortened and grouped with a version as the "header". The name/value pairs are -then grouped and encoded as the rest of the body. - -An advantage of encoding parameters this way is that parameters can be decoded -natively using the language(s) of the specific blockchain. In the case of EVM -blockchains, this means that parameters can be encoded as well as decoded in -Solidity (or Vyper), without any additional requirements. - -You can find additional documentation in -[Airnode ABI Specifications](/reference/airnode/next/specifications/airnode-abi.md) -doc. +The [airnode-abi](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-abi) package is a unique way to encode and decode parameters for use with Airnode. Parameters are provided with encoding types, names and values. The types are shortened and grouped with a version as the "header". The name/value pairs are then grouped and encoded as the rest of the body. + +An advantage of encoding parameters this way is that parameters can be decoded natively using the language(s) of the specific blockchain. In the case of EVM blockchains, this means that parameters can be encoded as well as decoded in Solidity (or Vyper), without any additional requirements. + +You can find additional documentation in [Airnode ABI Specifications](/reference/airnode/next/specifications/airnode-abi.md) doc. ## Installation -You can install -[@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) -with -[npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) +You can install [@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) with [npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) ```sh # npm @@ -53,16 +40,13 @@ npm install --save @api3/airnode-abi Accepts an array of objects with the following required keys: -1. `type` - The full list of accepted types can be found in the - [Airnode ABI](/reference/airnode/next/specifications/airnode-abi.md#type-encodings) - specifications doc. +1. `type` - The full list of accepted types can be found in the [Airnode ABI](/reference/airnode/next/specifications/airnode-abi.md#type-encodings) specifications doc. 2. `name` 3. `value` -It is important to note that numeric values (`int256` and `uint256`) should be -submitted as **strings** in order to preserve precision. +It is important to note that numeric values (`int256` and `uint256`) should be submitted as **strings** in order to preserve precision. ```ts import { encode } from '@api3/airnode-abi'; @@ -79,11 +63,9 @@ console.log(encodedData); ## `decode` -Returns an object where the keys are the "names" and the values are the "values" -from the initial encoding. +Returns an object where the keys are the "names" and the values are the "values" from the initial encoding. -It is important to note that `int256` and `uint256` will be decoded back to -strings. +It is important to note that `int256` and `uint256` will be decoded back to strings. ```ts import { decode } from '@api3/airnode-abi'; diff --git a/docs/reference/airnode/next/packages/deployer.md b/docs/reference/airnode/next/packages/deployer.md index c355df0c..4fb44a64 100644 --- a/docs/reference/airnode/next/packages/deployer.md +++ b/docs/reference/airnode/next/packages/deployer.md @@ -19,22 +19,11 @@ tags: # {{$frontmatter.title}} -The -[airnode-deployer](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer) -package is used primarily by the -[Docker Images](/reference/airnode/next/docker/). This CLI tool provides the -underlying commands used by the Docker images when deploying an Airnode. API -providers are strongly encouraged to use the -[Docker Images](/reference/airnode/next/docker/) when deploying an Airnode and -not the deployer CLI commands. +The [airnode-deployer](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer) package is used primarily by the [Docker Images](/reference/airnode/next/docker/). This CLI tool provides the underlying commands used by the Docker images when deploying an Airnode. API providers are strongly encouraged to use the [Docker Images](/reference/airnode/next/docker/) when deploying an Airnode and not the deployer CLI commands. ## Usage -The deployer's commands can be run using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), -installing a global npm package or by manually building the airnode-deployer -package. Using npx is the simplest method to interact with the deployer manually -if you do not wish to use the Docker images. +The deployer's commands can be run using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), installing a global npm package or by manually building the airnode-deployer package. Using npx is the simplest method to interact with the deployer manually if you do not wish to use the Docker images. - [Using npx](/reference/airnode/next/packages/deployer.md#using-npx) - [Global Package](/reference/airnode/next/packages/deployer.md#global-package) @@ -42,9 +31,7 @@ if you do not wish to use the Docker images. ### Using npx -The airnode-deployer package can be run as an npm package using npx. This allows -you to run deployer commands without installing the deployer npm package or -having to manually build the airnode-deployer package yourself. +The airnode-deployer package can be run as an npm package using npx. This allows you to run deployer commands without installing the deployer npm package or having to manually build the airnode-deployer package yourself. ```sh npx @api3/airnode-deployer deploy \ @@ -117,27 +104,18 @@ cp config/secrets.env.example config/secrets.env ## Credentials -When using the `airnode-deployer` Docker image, AWS or GCP credentials are -loaded automatically. Conversely, when using the deployer CLI directly, you will -need to first load AWS or GCP credentials into the environment manually as -described below. +When using the `airnode-deployer` Docker image, AWS or GCP credentials are loaded automatically. Conversely, when using the deployer CLI directly, you will need to first load AWS or GCP credentials into the environment manually as described below. ### AWS Credentials For AWS, there are two options: -1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` - (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their - appropriate values. -2. Populate the AWS `credentials` file. See the AWS documentation for the - [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) - as well as its - [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). +1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their appropriate values. +2. Populate the AWS `credentials` file. See the AWS documentation for the [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) as well as its [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). ### GCP Credentials -Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of -the `gcp.json` credentials file. +Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the `gcp.json` credentials file. ## Commands @@ -150,33 +128,20 @@ the `gcp.json` credentials file. ### Airnode Deployment -When creating or updating an Airnode the `config.json` and `secrets.env` files -are needed. You can use the provided example -[config.json](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/config.example.json) -and -[secrets.env](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/secrets.example.env) -templates to get started quickly, but you will need to edit these with your own -API details and secrets. +When creating or updating an Airnode the `config.json` and `secrets.env` files are needed. You can use the provided example [config.json](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/config.example.json) and [secrets.env](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-deployer/config/secrets.example.env) templates to get started quickly, but you will need to edit these with your own API details and secrets. -Make sure `config.json` and `secrets.env` are available in the path for the -`--configuration` argument. +Make sure `config.json` and `secrets.env` are available in the path for the `--configuration` argument. #### deploy -When executed, the `deploy` command defaults to creating a `receipt.json` file -in the `config/` directory, although a different path can be specified using the -path and name with the `--receipt` argument. The receipt contains metadata about -the deployment and can be used to remove the Airnode. +When executed, the `deploy` command defaults to creating a `receipt.json` file in the `config/` directory, although a different path can be specified using the path and name with the `--receipt` argument. The receipt contains metadata about the deployment and can be used to remove the Airnode. -By default the deployer will save logs into the `config/logs/` directory. This -can be changed with the `--logs` argument. +By default the deployer will save logs into the `config/logs/` directory. This can be changed with the `--logs` argument. -If the deployment isn't successful, the command will try to automatically remove -deployed resources. You can disable this by running the deploy command with a -`--no-auto-remove` argument. +If the deployment isn't successful, the command will try to automatically remove deployed resources. You can disable this by running the deploy command with a `--no-auto-remove` argument. ```bash # Deploys an Airnode instance using the config.json and @@ -204,19 +169,15 @@ airnode-deployer deploy \ --logs config/logs/ ``` -See how [deploy](/reference/airnode/next/docker/deployer-image.md#deploy) is -used via the AWS/GCP deployer image. +See how [deploy](/reference/airnode/next/docker/deployer-image.md#deploy) is used via the AWS/GCP deployer image. ### Listing Airnodes -Once you've already deployed one or more Airnode, you can list your currently -deployed instances using the `list` command. +Once you've already deployed one or more Airnode, you can list your currently deployed instances using the `list` command. #### list -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ```bash # Lists deployed Airnode instances @@ -236,14 +197,11 @@ airnode-deployer list airnode-deployer list --cloud-providers gcp ``` -See how [list](/reference/airnode/next/docker/deployer-image.md#list) is used -via the AWS/GCP deployer image. +See how [list](/reference/airnode/next/docker/deployer-image.md#list) is used via the AWS/GCP deployer image. ### Fetching deployment information -You can use the `info` command to retrieve information about existing -deployments. The retrieved information include deployment's Airnode address, -stage, Airnode version and the update history. +You can use the `info` command to retrieve information about existing deployments. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. #### info @@ -263,8 +221,7 @@ Options: airnode-deployer info aws2c6ef2b3 ``` -See how [info](/reference/airnode/next/docker/deployer-image.md#info) is used -via the AWS/GCP deployer image. +See how [info](/reference/airnode/next/docker/deployer-image.md#info) is used via the AWS/GCP deployer image. ### Reverting to a previous version @@ -291,14 +248,11 @@ Options: airnode-deployer rollback aws808e2a22 5bbcd317 ``` -See how [rollback](/reference/airnode/next/docker/deployer-image.md#rollback) is -used via the AWS/GCP deployer image. +See how [rollback](/reference/airnode/next/docker/deployer-image.md#rollback) is used via the AWS/GCP deployer image. ### Fetching deployment files -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the `fetch-files` command to -retrieve them. +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the `fetch-files` command to retrieve them. #### fetch-files @@ -317,19 +271,14 @@ Options: airnode-deployer fetch-files aws2c6ef2b3 ``` -See how -[fetch-files](/reference/airnode/next/docker/deployer-image.md#fetch-files) is -used via the AWS/GCP deployer image. +See how [fetch-files](/reference/airnode/next/docker/deployer-image.md#fetch-files) is used via the AWS/GCP deployer image. ### Airnode Removal An Airnode can be removed in two different ways: -- **Best:** With `remove`, which uses the deployment ID found either in the - [deployment receipt file](/reference/airnode/next/deployment-files/receipt-json.md) - or via the `list` command. -- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt - created when the Airnode was deployed. +- **Best:** With `remove`, which uses the deployment ID found either in the [deployment receipt file](/reference/airnode/next/deployment-files/receipt-json.md) or via the `list` command. +- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt created when the Airnode was deployed. #### remove @@ -349,8 +298,7 @@ Options: airnode-deployer remove aws2c6ef2b3 ``` -See how [remove](/reference/airnode/next/docker/deployer-image.md#remove) is -used via the AWS/GCP deployer image. +See how [remove](/reference/airnode/next/docker/deployer-image.md#remove) is used via the AWS/GCP deployer image. #### remove-with-receipt @@ -373,8 +321,6 @@ airnode-deployer remove-with-receipt \ --logs config/logs/ ``` -See how -[remove-with-receipt](/reference/airnode/next/docker/deployer-image.md#remove-with-receipt) -is used via the AWS/GCP deployer image. +See how [remove-with-receipt](/reference/airnode/next/docker/deployer-image.md#remove-with-receipt) is used via the AWS/GCP deployer image. diff --git a/docs/reference/airnode/next/packages/index.md b/docs/reference/airnode/next/packages/index.md index 8dfcade7..870842a2 100644 --- a/docs/reference/airnode/next/packages/index.md +++ b/docs/reference/airnode/next/packages/index.md @@ -19,13 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode is a fully-serverless oracle node that is designed specifically for API -providers to operate their own oracles. Its code base is a monorepo managed -using [Lerna](https://github.com/lerna/lerna). The -[Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.14/packages) has -several packages. Some of these packages are used by dApp developers and API -providers to interact with or to build Airnode. A few are simply used for -internal Airnode development. +Airnode is a fully-serverless oracle node that is designed specifically for API providers to operate their own oracles. Its code base is a monorepo managed using [Lerna](https://github.com/lerna/lerna). The [Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.14/packages) has several packages. Some of these packages are used by dApp developers and API providers to interact with or to build Airnode. A few are simply used for internal Airnode development. - [airnode-adapter](/reference/airnode/next/packages/adapter.md) - [airnode-admin](/reference/airnode/next/packages/admin-cli.md) @@ -36,49 +30,30 @@ internal Airnode development. **Read about each package in the monorepo.** -Airnode packages are cross platform, available as npm packages or docker -containers. You should also be able to clone, build and use the packages on any -platform. However there is no guarantee that the development only features (e.g. -test or examples) will work out of the box. It is recommend to use UNIX based -systems for development. If you are using Windows, consider -[WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). +Airnode packages are cross platform, available as npm packages or docker containers. You should also be able to clone, build and use the packages on any platform. However there is no guarantee that the development only features (e.g. test or examples) will work out of the box. It is recommend to use UNIX based systems for development. If you are using Windows, consider [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). -- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-adapter) - The module that makes an API call, processes the response and returns a single - value. +- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-adapter) The module that makes an API call, processes the response and returns a single value. -- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin) - A package/CLI tool to interact with the Airnode contracts across chains. +- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-admin) A package/CLI tool to interact with the Airnode contracts across chains. -- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-abi) - Encoding and decoding utilities for Airnode according to the - [Airnode ABI specifications](/reference/airnode/next/specifications/airnode-abi.md). +- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-abi) Encoding and decoding utilities for Airnode according to the [Airnode ABI specifications](/reference/airnode/next/specifications/airnode-abi.md). -- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer) - Tools to automate Airnode deployment. +- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer) Tools to automate Airnode deployment. -- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) - A public list of examples showcasing the features of Airnode. +- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) A public list of examples showcasing the features of Airnode. -- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-node) - The node part of Airnode that allows for connecting multiple blockchains to - the rest of the world. +- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-node) The node part of Airnode that allows for connecting multiple blockchains to the rest of the world. -- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-operation) - Development and testing utilities for the core parts of Airnode. +- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-operation) Development and testing utilities for the core parts of Airnode. -- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-protocol) - Contracts that implement Airnode RRP (request–response protocol). +- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-protocol) Contracts that implement Airnode RRP (request–response protocol). -- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-validator) - A package that can be used to validate Airnode configuration. +- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-validator) A package that can be used to validate Airnode configuration. ## OIS -The `airnode-ois` monorepo package was removed from the Airnode repo and is now -in its own repo (`ois`) starting with Airnode `v0.8`. +The `airnode-ois` monorepo package was removed from the Airnode repo and is now in its own repo (`ois`) starting with Airnode `v0.8`. -- [ois:](https://github.com/api3dao/ois/tree/v2.3.2) Types for - [Oracle Integration Specification (OIS)](/reference/ois/next/specification.md). +- [ois:](https://github.com/api3dao/ois/tree/v2.3.2) Types for [Oracle Integration Specification (OIS)](/reference/ois/next/specification.md). diff --git a/docs/reference/airnode/next/packages/validator.md b/docs/reference/airnode/next/packages/validator.md index 8342b95e..d2eb03cd 100644 --- a/docs/reference/airnode/next/packages/validator.md +++ b/docs/reference/airnode/next/packages/validator.md @@ -19,26 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-validator](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-validator) -is used internally by the [Docker Images](/reference/airnode/next/docker/) to -validate the -[configuration files](/reference/airnode/next/understand/configuring.md) you -provide when deploying an Airnode. - -However, validator can also be used as a standalone package to verify the -correctness of the configuration files without deploying the Airnode. The -recommended way is to use the -[validator CLI](/reference/airnode/next/packages/validator.md#cli-usage), but -for advanced use cases you can use the -[validator SDK](/reference/airnode/next/packages/validator.md#sdk-usage). +The [airnode-validator](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-validator) is used internally by the [Docker Images](/reference/airnode/next/docker/) to validate the [configuration files](/reference/airnode/next/understand/configuring.md) you provide when deploying an Airnode. + +However, validator can also be used as a standalone package to verify the correctness of the configuration files without deploying the Airnode. The recommended way is to use the [validator CLI](/reference/airnode/next/packages/validator.md#cli-usage), but for advanced use cases you can use the [validator SDK](/reference/airnode/next/packages/validator.md#sdk-usage). ## CLI Usage -The simplest way to run the CLI is using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). -Alternatively, you can install the validator package as a dependency in your -project. +The simplest way to run the CLI is using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). Alternatively, you can install the validator package as a dependency in your project. ```sh npx @api3/airnode-validator --config "config.json" --secrets "secrets.env" @@ -56,8 +43,7 @@ npx airnode-validator --config "config.json" --secrets "secrets.env" ### Examples -Assuming the configurations files inside current working directory are valid, -executing: +Assuming the configurations files inside current working directory are valid, executing: ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "valid-secrets.env" @@ -69,8 +55,7 @@ yields: ✔ The configuration is valid ``` -When there is an error during validation, the command prints out the error and -fails with a non zero status code. +When there is an error during validation, the command prints out the error and fails with a non zero status code. ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "non-existent-secrets.env" @@ -84,26 +69,17 @@ yields: ## SDK Usage -The validator package contains an API that can be used to validate Airnode -configuration files programatically. +The validator package contains an API that can be used to validate Airnode configuration files programatically. The following functions can be used: -- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` and validates the interpolated configuration. Expects both `config` - and `secrets` to be JSON objects. -- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a - JSON object. -- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be - a JSON object. -- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be - a JSON object. -- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` but does not perform any validation afterwards. Use this function - only when you can guarantee that the configuration is valid. - -Validator has also full TypeScript support. All of these functions return a -typed object. +- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` and validates the interpolated configuration. Expects both `config` and `secrets` to be JSON objects. +- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a JSON object. +- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be a JSON object. +- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be a JSON object. +- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` but does not perform any validation afterwards. Use this function only when you can guarantee that the configuration is valid. + +Validator has also full TypeScript support. All of these functions return a typed object. ### Examples @@ -146,7 +122,6 @@ if (parseResult.success) { ## Build Manually -See the build instructions for the validator in the -[airnode package repository](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-validator). +See the build instructions for the validator in the [airnode package repository](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-validator). diff --git a/docs/reference/airnode/next/specifications/airnode-abi.md b/docs/reference/airnode/next/specifications/airnode-abi.md index eb25b2e2..cc271088 100644 --- a/docs/reference/airnode/next/specifications/airnode-abi.md +++ b/docs/reference/airnode/next/specifications/airnode-abi.md @@ -19,39 +19,23 @@ tags: # {{$frontmatter.title}} -[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) -is used to encode different types of data while interacting with Ethereum -contracts. As a result, both Solidity and modules such as -[web3.js](https://web3js.readthedocs.io/) and -[ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality -as a first-class citizen. This makes using contract ABI for encoding API call -parameters a very attractive option. - -Although encoding API call parameters using contract ABI has many advantages, it -cannot be used for this purpose directly. Quoting from the -[Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): - -> The encoding is not self describing and thus requires a schema in order to -> decode. - -This means that when passing API call parameters (of type `bytes`), you would -also need to pass a list of the types for these parameters, which is cumbersome -and it is not clear how these types would be encoded. As a solution, Airnode -uses _Airnode ABI specifications_, an extension of contract ABI specifications -that includes a header that keeps the schema. +[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) is used to encode different types of data while interacting with Ethereum contracts. As a result, both Solidity and modules such as [web3.js](https://web3js.readthedocs.io/) and [ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality as a first-class citizen. This makes using contract ABI for encoding API call parameters a very attractive option. + +Although encoding API call parameters using contract ABI has many advantages, it cannot be used for this purpose directly. Quoting from the [Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): + +> The encoding is not self describing and thus requires a schema in order to decode. + +This means that when passing API call parameters (of type `bytes`), you would also need to pass a list of the types for these parameters, which is cumbersome and it is not clear how these types would be encoded. As a solution, Airnode uses _Airnode ABI specifications_, an extension of contract ABI specifications that includes a header that keeps the schema. ## Header -The Airnode ABI specifications header is of type `bytes32` and acts as the -schema (i.e., describes the types of the API call parameters). The header is -encoded in UTF-8 for ease of use. Here is an example: +The Airnode ABI specifications header is of type `bytes32` and acts as the schema (i.e., describes the types of the API call parameters). The header is encoded in UTF-8 for ease of use. Here is an example: ``` "1BSasbiuBa" ``` -The first character, `1`, represents the encoding version. Each following -character represents the type of an API call parameter. +The first character, `1`, represents the encoding version. Each following character represents the type of an API call parameter. ### Type encodings @@ -68,20 +52,11 @@ i: int256 f: bool ``` -Note that dynamically-sized types are represented with uppercase letters and -statically-sized types are represented with lowercase letters. Another thing to -notice is that `s` represents `string32`, but this is an artificial type and it -is not part of -[solidity types](https://docs.soliditylang.org/en/latest/types.html). This type -is instead represented on chain as `bytes32`. The reasons for this are explained -in depth in -[string32 details](/reference/airnode/next/specifications/airnode-abi.md#string32) -section. +Note that dynamically-sized types are represented with uppercase letters and statically-sized types are represented with lowercase letters. Another thing to notice is that `s` represents `string32`, but this is an artificial type and it is not part of [solidity types](https://docs.soliditylang.org/en/latest/types.html). This type is instead represented on chain as `bytes32`. The reasons for this are explained in depth in [string32 details](/reference/airnode/next/specifications/airnode-abi.md#string32) section. ## Encoding format -Airnode ABI specifications has the following encoding format (which is somewhat -similar to [SDS](https://github.com/antirez/sds)): +Airnode ABI specifications has the following encoding format (which is somewhat similar to [SDS](https://github.com/antirez/sds)): ``` [------------------------][-----------------------------------------] @@ -125,14 +100,11 @@ bytes memory parameters = abi.encode( ); ``` -Note that you do not need to add an external library to the contract, and -`abi.encode()` is fairly cheap in terms of gas usage (compared to alternative -encoding methods). +Note that you do not need to add an external library to the contract, and `abi.encode()` is fairly cheap in terms of gas usage (compared to alternative encoding methods). ## Example decoding -If you know the schema of the encoded parameters, then decode them on-chain. For -example, if the schema is `(bytes,string)`: +If you know the schema of the encoded parameters, then decode them on-chain. For example, if the schema is `(bytes,string)`: ```solidity ( @@ -142,17 +114,13 @@ example, if the schema is `(bytes,string)`: ) = abi.decode(parameters, (bytes32,bytes32,bytes,bytes32,string)); ``` -Note that this disregards the header and hard codes the schema into the code. It -is also possible to parse the header on-chain and decode accordingly, yet that -would be a lot more complex. +Note that this disregards the header and hard codes the schema into the code. It is also possible to parse the header on-chain and decode accordingly, yet that would be a lot more complex. ## Details ### `string32` -A parameter being of type `string32` (encoded as characted `s` in the ABI -specification schema header) implies that the parameter is UTF-8 encoded text. -For example, if the parameter is +A parameter being of type `string32` (encoded as characted `s` in the ABI specification schema header) implies that the parameter is UTF-8 encoded text. For example, if the parameter is ``` 0x68656c6c6f000000000000000000000000000000000000000000000000000000 @@ -164,9 +132,7 @@ Airnode will decode it as "hello" ``` -and feed that to the API, which is what the user would want to do in most cases. -This becomes a problem if the parameter is not encoded text, but for example a -hash such as: +and feed that to the API, which is what the user would want to do in most cases. This becomes a problem if the parameter is not encoded text, but for example a hash such as: ``` 0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71 @@ -179,15 +145,11 @@ If this hash is encoded as a `string32` type, Airnode will decode it as: !Õ$B˜±=/¡>q ``` -which is probably not what the user is looking for. For these use cases, the -user should use the -[`bytes32`](/reference/airnode/next/specifications/airnode-abi.md#bytes32) type -instead. +which is probably not what the user is looking for. For these use cases, the user should use the [`bytes32`](/reference/airnode/next/specifications/airnode-abi.md#bytes32) type instead. ### `bytes32` -To encode a `bytes32` hash on chain, use the `bytes32` type which is represented -by `b` in the ABI header schema. +To encode a `bytes32` hash on chain, use the `bytes32` type which is represented by `b` in the ABI header schema. ```solidity bytes memory parameters = abi.encode( @@ -202,46 +164,27 @@ When decoded by Airnode, the value would be the hash itself: "0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71" ``` -If you want to store 32 byte string values on chain, use the -[`string32`](/reference/airnode/next/specifications/airnode-abi.md#string32) -type instead. +If you want to store 32 byte string values on chain, use the [`string32`](/reference/airnode/next/specifications/airnode-abi.md#string32) type instead. ### `bool` -The `bool` type, encoded as character `f` using the ABI specification schema can -be used to encode a boolean value. The header symbol is `f`, because character -`b` was already reserved for bytes encodings. So we chose letter `f` as bool -values are commonly used to represent "boolean flags". +The `bool` type, encoded as character `f` using the ABI specification schema can be used to encode a boolean value. The header symbol is `f`, because character `b` was already reserved for bytes encodings. So we chose letter `f` as bool values are commonly used to represent "boolean flags". ### Omitted types -`array` and `tuple` are omitted because they are not suitable to be used as API -parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because -they are padded to 32 bytes by the ABI encoder anyway (meaning that the user -should simply typecast these to the 32-byte versions). +`array` and `tuple` are omitted because they are not suitable to be used as API parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because they are padded to 32 bytes by the ABI encoder anyway (meaning that the user should simply typecast these to the 32-byte versions). ### Size limit -The header can encode up to 31 parameters (and 1 byte is used to encode the -encoding version). This is far more than what would be needed in practice, and -thus is tolerated to avoid a more complex solution. +The header can encode up to 31 parameters (and 1 byte is used to encode the encoding version). This is far more than what would be needed in practice, and thus is tolerated to avoid a more complex solution. ### Padding -[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) -is used so that you can decode the values later on. This means that each -parameter will be padded with zeros to complete them to 32 bytes. Although this -padding increases gas costs, ABI encoding/decoding functions being cheap -balances this. Furthermore, the -[template](/reference/airnode/next/concepts/template.md) pattern used in the -protocols allows for the referencing of these encoded parameters without -explicitly passing them in requests, making the increased cost induced by -padding irrelevant in most cases. +[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) is used so that you can decode the values later on. This means that each parameter will be padded with zeros to complete them to 32 bytes. Although this padding increases gas costs, ABI encoding/decoding functions being cheap balances this. Furthermore, the [template](/reference/airnode/next/concepts/template.md) pattern used in the protocols allows for the referencing of these encoded parameters without explicitly passing them in requests, making the increased cost induced by padding irrelevant in most cases. ## `@api3/airnode-abi` -Encode and decode parameters with the -[airnode-abi](/reference/airnode/next/packages/airnode-abi.md) package. +Encode and decode parameters with the [airnode-abi](/reference/airnode/next/packages/airnode-abi.md) package. ```js import { encode } from '@api3/airnode-abi'; @@ -258,13 +201,6 @@ console.log('ENCODED:', encodedData); console.log('\nDECODED:', decoded); ``` -See the package doc -[airnode-abi](/reference/airnode/next/packages/airnode-abi.md) for more -information on how to encode and decode with Airnode ABI off-chain. Also see -code samples in the -[examples](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) -package. Lastly see the file -[request-utils.ts](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) -for example syntax on encoding parameters. +See the package doc [airnode-abi](/reference/airnode/next/packages/airnode-abi.md) for more information on how to encode and decode with Airnode ABI off-chain. Also see code samples in the [examples](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) package. Lastly see the file [request-utils.ts](https://github.com/api3dao/airnode/blob/v0.14/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) for example syntax on encoding parameters. diff --git a/docs/reference/airnode/next/specifications/ois.md b/docs/reference/airnode/next/specifications/ois.md index 82f7d18a..1d6f1ff3 100644 --- a/docs/reference/airnode/next/specifications/ois.md +++ b/docs/reference/airnode/next/specifications/ois.md @@ -19,13 +19,8 @@ tags: # {{$frontmatter.title}} -The `ois` JSON object, in the `config.json` file that defines an Airnode, is an -integral part of an Airnode's understanding of an API's specification and its -endpoints. OIS provide a description of API endpoints and maps Airnode endpoints -to them. There can be more than one OIS object in the `config.json` file as -Airnode can serve endpoints from more than one API. - -Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/next/) -in its versioned document set. +The `ois` JSON object, in the `config.json` file that defines an Airnode, is an integral part of an Airnode's understanding of an API's specification and its endpoints. OIS provide a description of API endpoints and maps Airnode endpoints to them. There can be more than one OIS object in the `config.json` file as Airnode can serve endpoints from more than one API. + +Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/next/) in its versioned document set. diff --git a/docs/reference/airnode/next/specifications/reserved-parameters.md b/docs/reference/airnode/next/specifications/reserved-parameters.md index d9e04571..e44d0208 100644 --- a/docs/reference/airnode/next/specifications/reserved-parameters.md +++ b/docs/reference/airnode/next/specifications/reserved-parameters.md @@ -19,10 +19,6 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an Airnode's defined endpoints in an -[Oracle Integration Specifications (OIS)](/reference/ois/next/) object. They do -not map to operation parameters and are used by Airnode for special purposes. -See the [Reserved Parameters](/reference/ois/next/reserved-parameters.md) doc in -the OIS document set for an in-depth explanation. +Reserved parameters are part of an Airnode's defined endpoints in an [Oracle Integration Specifications (OIS)](/reference/ois/next/) object. They do not map to operation parameters and are used by Airnode for special purposes. See the [Reserved Parameters](/reference/ois/next/reserved-parameters.md) doc in the OIS document set for an in-depth explanation. diff --git a/docs/reference/airnode/next/understand/api-integration.md b/docs/reference/airnode/next/understand/api-integration.md index b6878976..004e414c 100644 --- a/docs/reference/airnode/next/understand/api-integration.md +++ b/docs/reference/airnode/next/understand/api-integration.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -A successful integration of an API with an Airnode requires the mapping of each -other's interface. This is accomplished using an OIS -([Oracle Integration Specifications](/reference/ois/next/specification.md)) json -object, found in the config.json file, designed to with three basic steps. +A successful integration of an API with an Airnode requires the mapping of each other's interface. This is accomplished using an OIS ([Oracle Integration Specifications](/reference/ois/next/specification.md)) json object, found in the config.json file, designed to with three basic steps. 1. API operations are specified 1. Airnode endpoints are specified @@ -34,60 +31,36 @@ object, found in the config.json file, designed to with three basic steps. > >

The OIS object in config.json contains mapping information of API operations to Airnode endpoint definitions.

-OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode -endpoints. When a requester contract calls one of the AirnodeRrpV0.sol -contract's request functions, such as `makeFullRequest(..., callData)`, the -callData is communicated to the off-chain Airnode which uses OIS mappings to -translate the callData into a valid HTTP request for the appropriate API -operation. +OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode endpoints. When a requester contract calls one of the AirnodeRrpV0.sol contract's request functions, such as `makeFullRequest(..., callData)`, the callData is communicated to the off-chain Airnode which uses OIS mappings to translate the callData into a valid HTTP request for the appropriate API operation. -OIS borrows formatting from -[OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). -If you have experience with OAS, OIS will seem familiar. +OIS borrows formatting from [OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). If you have experience with OAS, OIS will seem familiar. ::: info OAS -It is not recommended to refer to OAS for help while creating your OIS object. -OIS only borrows formatting practices from OAS. Everything needed to create an -OIS object is in these docs. +It is not recommended to refer to OAS for help while creating your OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: **Tips while reading ths page.** -- Open the [OIS template](/reference/ois/next/template.md) in another browser - window to follow along. -- View an example of an Airnode - [config.json](/reference/airnode/next/deployment-files/examples/config-json.md) - file. +- Open the [OIS template](/reference/ois/next/template.md) in another browser window to follow along. +- View an example of an Airnode [config.json](/reference/airnode/next/deployment-files/examples/config-json.md) file. ## OIS Template -OIS is a json object that is added to an Airnode's -[config.json](/reference/airnode/next/deployment-files/templates/config-json.md) -file as the (`ois`) _key_, sometimes called a _field_. Try using the -[OIS template](/reference/ois/next/template.md) to construct an OIS and add it -to the Airnode's config.json file later. +OIS is a json object that is added to an Airnode's [config.json](/reference/airnode/next/deployment-files/templates/config-json.md) file as the (`ois`) _key_, sometimes called a _field_. Try using the [OIS template](/reference/ois/next/template.md) to construct an OIS and add it to the Airnode's config.json file later. -In the OIS template, there are some fields that contain `{FILL_*}`. This means -that the value added is independent from other fields. On the other hand, if two -fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), -you must use the same value in them, because they are referencing each other. +In the OIS template, there are some fields that contain `{FILL_*}`. This means that the value added is independent from other fields. On the other hand, if two fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), you must use the same value in them, because they are referencing each other. -OIS uses a simplified version of the OAS. This means that if you have the -OpenAPI specifications of the API that you are going to integrate, you are about -80% done, because you can copy paste entire sections (but be sure to make the -necessary modifications to conform to the OIS format). +OIS uses a simplified version of the OAS. This means that if you have the OpenAPI specifications of the API that you are going to integrate, you are about 80% done, because you can copy paste entire sections (but be sure to make the necessary modifications to conform to the OIS format). -The remainder of this page will assume you do not have the OpenAPI -specifications of the API that you will be integrating. +The remainder of this page will assume you do not have the OpenAPI specifications of the API that you will be integrating. ## 1. Specify OIS Definitions -Start building an OIS by adding three descriptive fields to the root of the OIS -json object. +Start building an OIS by adding three descriptive fields to the root of the OIS json object. ```json { @@ -100,20 +73,15 @@ json object. ### oisFormat -A specific version of the -[OIS Specification](/reference/ois/next/specification.md#_1-oisformat) to be -used. For Airnode `v0.14`, the proper OIS version is `2.3.0`. +A specific version of the [OIS Specification](/reference/ois/next/specification.md#_1-oisformat) to be used. For Airnode `v0.14`, the proper OIS version is `2.3.0`. ### title -This is a unique title of the OIS. Note that an Airnode can be configured with -more than one OIS object and uses the title as the OIS identifier. +This is a unique title of the OIS. Note that an Airnode can be configured with more than one OIS object and uses the title as the OIS identifier. ### version -This is the version of the OIS which allows for version-control of the OIS -integration. It is recommended to use [semver](https://semver.org/) versioning. -The initial version could be `0.1.0`. +This is the version of the OIS which allows for version-control of the OIS integration. It is recommended to use [semver](https://semver.org/) versioning. The initial version could be `0.1.0`. @@ -134,15 +102,11 @@ The `apiSpecifications` field is used to describe the API and its operations. ### Servers -The first step of specifying an API is to enter its _baseURL_ in the -`apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed -in the `apiSpecifications.servers` array. A warning is raised during conversion -if servers has multiple elements. This baseURL will apply to all operations. +The first step of specifying an API is to enter its _baseURL_ in the `apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed in the `apiSpecifications.servers` array. A warning is raised during conversion if servers has multiple elements. This baseURL will apply to all operations. #### Choosing a Base URL -Consider the following full URL to execute an API operation that returns all -know tokens. +Consider the following full URL to execute an API operation that returns all know tokens. @@ -164,16 +128,11 @@ or > > **path:** `/data` -Because the call will be made to <`baseURL+path`> both will result in the same -full URL. +Because the call will be made to <`baseURL+path`> both will result in the same full URL. -Set the baseURL as the section of the full URL that you expect to be shared by -all operations. From the examples above it is recommended to use -`https://www.myapi.com`, in case additional paths starting with `/v2` get added -to the API in the future. As you can tell, API integration requires many -subjective choices, and is more art than science. +Set the baseURL as the section of the full URL that you expect to be shared by all operations. From the examples above it is recommended to use `https://www.myapi.com`, in case additional paths starting with `/v2` get added to the API in the future. As you can tell, API integration requires many subjective choices, and is more art than science. ```json "apiSpecifications": { @@ -188,20 +147,15 @@ subjective choices, and is more art than science. ### Paths -The _paths_ field defines all the API operations much like an OpenAPI -Specification file. +The _paths_ field defines all the API operations much like an OpenAPI Specification file. _What is an API operation?_ -> An API operation is specified as a unique combination of a _**path**_ and an -> HTTP _**method**_. `GET /token/{id}` +> An API operation is specified as a unique combination of a _**path**_ and an HTTP _**method**_. `GET /token/{id}` #### Operations -In the examples below, `GET` refers to an -[HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). -This implies that you could have another API operation that can be specified -using a different method but the same path. +In the examples below, `GET` refers to an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). This implies that you could have another API operation that can be specified using a different method but the same path. > path: /data > @@ -211,18 +165,11 @@ using a different method but the same path. > > method: POST -Therefore, a path is not enough to specify an API operation by itself, you must -also provide a method. If a new path is needed then it must be a new object in -paths with its own methods. Currently only the GET and POST methods are -supported by Airnode. +Therefore, a path is not enough to specify an API operation by itself, you must also provide a method. If a new path is needed then it must be a new object in paths with its own methods. Currently only the GET and POST methods are supported by Airnode. -With regards to the [OIS template](/reference/ois/next/template.md), the name of -the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., -`/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the -operation to integrate (e.g., `get`). The method must be lowercase. +With regards to the [OIS template](/reference/ois/next/template.md), the name of the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., `/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the operation to integrate (e.g., `get`). The method must be lowercase. -The following example illustrates three operations, `GET /data`, `POST /data`, -`GET /tokens`. +The following example illustrates three operations, `GET /data`, `POST /data`, `GET /tokens`. ```json "paths": { @@ -244,27 +191,16 @@ The following example illustrates three operations, `GET /data`, `POST /data`, #### Parameters (operation) -After specifying the path and method of an API operation, the final step is to -specify its parameters. Each parameter is an object in the -`apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` -and `name`. `in` tells where the parameter goes in the HTTP request and `name` -tells the name that the parameter value will be sent under. Currently Airnode -supports the following parameter types for use with `in`. +After specifying the path and method of an API operation, the final step is to specify its parameters. Each parameter is an object in the `apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` and `name`. `in` tells where the parameter goes in the HTTP request and `name` tells the name that the parameter value will be sent under. Currently Airnode supports the following parameter types for use with `in`. - query - header - path - cookie -When integrating a POST method, define the body parameters with `in: query`. -Airnode will convert all `query` types into the `requestBody`. Note that only -the non-nested application/json content-type is supported. +When integrating a POST method, define the body parameters with `in: query`. Airnode will convert all `query` types into the `requestBody`. Note that only the non-nested application/json content-type is supported. -It is not necessary to specify all API operation parameters, but only the ones -the on-chain requester will need to be able to provide (see Airnode endpoint -[parameters](/reference/airnode/next/understand/api-integration.md#parameters)), -and the ones needed to hard-code a value for (see Airnode endpoint -[fixed operation parameters](/reference/airnode/next/understand/api-integration.md#fixedoperationparameters)). +It is not necessary to specify all API operation parameters, but only the ones the on-chain requester will need to be able to provide (see Airnode endpoint [parameters](/reference/airnode/next/understand/api-integration.md#parameters)), and the ones needed to hard-code a value for (see Airnode endpoint [fixed operation parameters](/reference/airnode/next/understand/api-integration.md#fixedoperationparameters)). ```json "paths": { @@ -287,8 +223,7 @@ and the ones needed to hard-code a value for (see Airnode endpoint _Example: Get a token_ -The `GET /token/{id}` returns a token using the token's `id` which is a `path` -parameter. +The `GET /token/{id}` returns a token using the token's `id` which is a `path` parameter. | Method | Path | in | name | | ------ | ----------- | ---- | ---- | @@ -296,11 +231,7 @@ parameter. _Example: Create a token_ -The `POST /token` operation accepts three parameters. The name and description -of the token are placed in the type `query` and will be moved by Airnode to the -requestBody upon calling the API operation. The third is a `header` parameter -that describes the Content-Type of the request such as `application/json` or -`application/x-www-form-urlencoded`. +The `POST /token` operation accepts three parameters. The name and description of the token are placed in the type `query` and will be moved by Airnode to the requestBody upon calling the API operation. The third is a `header` parameter that describes the Content-Type of the request such as `application/json` or `application/x-www-form-urlencoded`. | Method | Path | in | name | | ------ | ------ | ------ | ----------- | @@ -310,9 +241,7 @@ that describes the Content-Type of the request such as `application/json` or _Example: Get all tokens_ -The `GET /tokens` returns a list of all tokens. The list count can be limited -using the `limit' parameter which the API operation considers as optional since -it will not return an error if omitted. +The `GET /tokens` returns a list of all tokens. The list count can be limited using the `limit' parameter which the API operation considers as optional since it will not return an error if omitted. > `GET /tokens` returns all tokens. > @@ -326,66 +255,25 @@ it will not return an error if omitted. ## 3. Specifying Airnode Endpoints -An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It -maps to an API operation, but the nature of this mapping is customizable. It is -the integrator's job to define what this service is. - -For example, if an API operation returns an asset price given its ticker (e.g., -`BTC`), specify the endpoint such that the requester provides the ticker as a -parameter. The resulting endpoint would be a general one that returns prices for -any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price -will be returned (using -[fixed operation parameters](/reference/airnode/next/understand/api-integration.md#fixedoperationparameters)), -which would make the endpoint a specific one that only returns the BTC price. - -The recommended endpoint definition pattern is to create an Airnode endpoint for -each API operation, and allow the requesters to provide all operation parameters -themselves. This results in optimal flexibility, and essentially allows the -requesters to use the entire API functionality on-chain. Normally, competitor -oracle integrations strive to hard-code as many API parameters as possible -because passing these parameters on-chain results in a gas cost overhead. -However, the Airnode protocol uses -[templates](/reference/airnode/next/concepts/template.md) (not to be confused -with the OIS template used for this guide), which allow requesters to specify a -large number of endpoint parameters at no additional gas cost. - -Note that there are some cases where you may not want to map endpoints to API -operations one-to-one. For example, an API operation can have a `header` -parameter, `Accept`, that can take the values `application/json` or -`application/xml` to determine how to format the data that the API will respond -to the call. Airnode expects responses to be in JSON format, and thus -hard-coding this parameter as `JSON` would be more suitable than letting the -requester decide, as there is only one valid choice. Again, the integrator's job -is to be aware of these subtleties and use judgement. +An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It maps to an API operation, but the nature of this mapping is customizable. It is the integrator's job to define what this service is. + +For example, if an API operation returns an asset price given its ticker (e.g., `BTC`), specify the endpoint such that the requester provides the ticker as a parameter. The resulting endpoint would be a general one that returns prices for any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price will be returned (using [fixed operation parameters](/reference/airnode/next/understand/api-integration.md#fixedoperationparameters)), which would make the endpoint a specific one that only returns the BTC price. + +The recommended endpoint definition pattern is to create an Airnode endpoint for each API operation, and allow the requesters to provide all operation parameters themselves. This results in optimal flexibility, and essentially allows the requesters to use the entire API functionality on-chain. Normally, competitor oracle integrations strive to hard-code as many API parameters as possible because passing these parameters on-chain results in a gas cost overhead. However, the Airnode protocol uses [templates](/reference/airnode/next/concepts/template.md) (not to be confused with the OIS template used for this guide), which allow requesters to specify a large number of endpoint parameters at no additional gas cost. + +Note that there are some cases where you may not want to map endpoints to API operations one-to-one. For example, an API operation can have a `header` parameter, `Accept`, that can take the values `application/json` or `application/xml` to determine how to format the data that the API will respond to the call. Airnode expects responses to be in JSON format, and thus hard-coding this parameter as `JSON` would be more suitable than letting the requester decide, as there is only one valid choice. Again, the integrator's job is to be aware of these subtleties and use judgement. ### Endpoints array -The field `endpoints` is an array, with each row representing an Airnode -endpoint. The first field to fill in is `name`. Make sure that it is descriptive -and unique from other endpoint names. If you are integrating API operations to -Airnode endpoints one-to-one, using the API operation path as the endpoint name -is a decent choice (i.e., `/token`). Note that you would also add the method to -this name if there were multiple operations with different methods for a single -path (i.e., `GET/token`). +The field `endpoints` is an array, with each row representing an Airnode endpoint. The first field to fill in is `name`. Make sure that it is descriptive and unique from other endpoint names. If you are integrating API operations to Airnode endpoints one-to-one, using the API operation path as the endpoint name is a decent choice (i.e., `/token`). Note that you would also add the method to this name if there were multiple operations with different methods for a single path (i.e., `GET/token`). -The next step is to fill in `operation` object. Here, you need to enter the -`path` and `method` of an API operation you have defined in -`apiSpecifications.paths`, resulting in the Airnode endpoint calling the now -linked API operation. +The next step is to fill in `operation` object. Here, you need to enter the `path` and `method` of an API operation you have defined in `apiSpecifications.paths`, resulting in the Airnode endpoint calling the now linked API operation. #### fixedOperationParameters -It is not uncommon to hard-code API parameters (recall the `Accept` operation -parameter in the above example). Such hard-coded parameters are called -`fixedOperationParameters`. +It is not uncommon to hard-code API parameters (recall the `Accept` operation parameter in the above example). Such hard-coded parameters are called `fixedOperationParameters`. -In the OIS template there is a fixed operation parameter under -`endpoints[n].fixedOperationParameters`, and it refers to the first API -operation parameter. This means that whenever the Airnode receives a request for -this endpoint, the respective API call will be made with that API operation -parameter set to -endpoints[n].fixedOperationParameters[n].value. -The requester does not supply a value for `fixedOperationParameters`. +In the OIS template there is a fixed operation parameter under `endpoints[n].fixedOperationParameters`, and it refers to the first API operation parameter. This means that whenever the Airnode receives a request for this endpoint, the respective API call will be made with that API operation parameter set to endpoints[n].fixedOperationParameters[n].value. The requester does not supply a value for `fixedOperationParameters`. ```json "fixedOperationParameters": [ @@ -400,31 +288,17 @@ The requester does not supply a value for `fixedOperationParameters`. ``` -An Airnode endpoint can have multiple `fixedOperationParameters`. An API -operation parameter cannot be in both `endpoints[n].fixedOperationParameters` -and `endpoints[n].parameters`. +An Airnode endpoint can have multiple `fixedOperationParameters`. An API operation parameter cannot be in both `endpoints[n].fixedOperationParameters` and `endpoints[n].parameters`. #### reservedParameters -The requester can provide some parameters that are not mapped to API operation -parameters. These parameters are called "reserved parameters", and their names -start with an underscore. See the -[related OIS docs](/reference/ois/next/specification.md#_5-4-reservedparameters) -for more information. +The requester can provide some parameters that are not mapped to API operation parameters. These parameters are called "reserved parameters", and their names start with an underscore. See the [related OIS docs](/reference/ois/next/specification.md#_5-4-reservedparameters) for more information. -The current list of reserved parameters are `_type`, `_path`, `_times`, -`_gasPrice`, and `_minConfirmations`. See -[Reserved Parameters](/reference/ois/next/reserved-parameters.md) in the OIS -document set to understand what each of these parameters are for. +The current list of reserved parameters are `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. See [Reserved Parameters](/reference/ois/next/reserved-parameters.md) in the OIS document set to understand what each of these parameters are for. #### parameters -Airnode endpoint -[parameters](/reference/ois/next/specification.md#_5-5-parameters) map to API -operation [parameters](/reference/ois/next/specification.md#_4-2-1-parameters) -that the requester is allowed to provide values for. It refers to an API -operation through its field `operationParameter`. You can also provide `default` -values for endpoint parameters, though this is not recommended in most cases. +Airnode endpoint [parameters](/reference/ois/next/specification.md#_5-5-parameters) map to API operation [parameters](/reference/ois/next/specification.md#_4-2-1-parameters) that the requester is allowed to provide values for. It refers to an API operation through its field `operationParameter`. You can also provide `default` values for endpoint parameters, though this is not recommended in most cases. ```json // apiSpecifications.paths...parameters[1] @@ -460,27 +334,14 @@ Mapping between API parameters and endpoint parameters. │ │ ] ``` -Endpoint parameters have a `name` field, which does not have to be the same as -the API operation parameter that they map to. As a separate note, an Airnode -endpoint can have multiple parameters. +Endpoint parameters have a `name` field, which does not have to be the same as the API operation parameter that they map to. As a separate note, an Airnode endpoint can have multiple parameters. ## Conclusion -The API operations and Airnode endpoints are now specified. Each Airnode -endpoint maps to an API operation, and each Airnode endpoint parameter or -fixedOperationParameter maps to an API operation parameter. The resulting OIS -includes no user-specific information, which means that you can share it for -others to easily provide the same services (for example, to set up a third-party -oracle network). - -Note that there was some subjectivity while defining the Airnode endpoints. This -means that two different OISes can exist for the same exact API, differing based -on how the integrators designed the interface that the requester will use. -However, in most cases, one would simply map API operations to Airnode endpoints -directly, and let the requester provide all API operation parameters through the -Airnode endpoint parameters. - -Now that you have an OIS object, the next step is -[API Security](/reference/airnode/next/understand/api-security.md). +The API operations and Airnode endpoints are now specified. Each Airnode endpoint maps to an API operation, and each Airnode endpoint parameter or fixedOperationParameter maps to an API operation parameter. The resulting OIS includes no user-specific information, which means that you can share it for others to easily provide the same services (for example, to set up a third-party oracle network). + +Note that there was some subjectivity while defining the Airnode endpoints. This means that two different OISes can exist for the same exact API, differing based on how the integrators designed the interface that the requester will use. However, in most cases, one would simply map API operations to Airnode endpoints directly, and let the requester provide all API operation parameters through the Airnode endpoint parameters. + +Now that you have an OIS object, the next step is [API Security](/reference/airnode/next/understand/api-security.md). diff --git a/docs/reference/airnode/next/understand/api-security.md b/docs/reference/airnode/next/understand/api-security.md index ef0e9e30..82e1f505 100644 --- a/docs/reference/airnode/next/understand/api-security.md +++ b/docs/reference/airnode/next/understand/api-security.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode can pass along security information (schemes) when making calls to API -operations. There are two groups of security schemes. +Airnode can pass along security information (schemes) when making calls to API operations. There are two groups of security schemes. - [Airnode Authentication](/reference/airnode/next/concepts/airnode-auth.md) - [Relayed Meta Data Authentication](/reference/airnode/next/concepts/relay-meta-auth.md) @@ -31,8 +30,7 @@ operations. There are two groups of security schemes. > 1.

The Airnode uses Airnode Authentication Security Schemes to authenticate itself to an API operation of which the values are known only by the Airnode.

> 2.

The Airnode uses Relayed Meta Data Security Schemes to forward known information from the requester's request to an API operation.

-Security schemes are declared by the required `type` property inside the -security scheme definition. The following security scheme types are supported. +Security schemes are declared by the required `type` property inside the security scheme definition. The following security scheme types are supported. - Airnode Authentication Security Schemes - apiKey @@ -46,22 +44,16 @@ security scheme definition. The following security scheme types are supported. - relaySponsorWalletAddress - relayRequestId -It is important to note that the security schemes in any given OIS object apply -to all endpoints/API operations in the OIS object. If different security schemes -are required by a mix of endpoints/API operations, then more than one OIS object -will be required grouping endpoint/API operations based on their security needs. +It is important to note that the security schemes in any given OIS object apply to all endpoints/API operations in the OIS object. If different security schemes are required by a mix of endpoints/API operations, then more than one OIS object will be required grouping endpoint/API operations based on their security needs. ## Airnode Authentication Security Schemes -An Airnode can use the following security scheme types to authenticate itself to -API operations. +An Airnode can use the following security scheme types to authenticate itself to API operations. - [apiKey](/reference/airnode/next/understand/api-security.md#apikey) - [http](/reference/airnode/next/understand/api-security.md#http) -A security scheme requires a unique name within the OIS object for which it -exists. This name groups the security scheme values for `in`, `type`, and` name` -as shown in the two code examples below. +A security scheme requires a unique name within the OIS object for which it exists. This name groups the security scheme values for `in`, `type`, and` name` as shown in the two code examples below. - `securitySchemes.` - `security.` @@ -69,18 +61,12 @@ as shown in the two code examples below. ### apiKey -The `apiKey` security scheme type allows you to define an API key the Airnode -will send to API operations. It is an object which consists of the following -fields: +The `apiKey` security scheme type allows you to define an API key the Airnode will send to API operations. It is an object which consists of the following fields: - `type` must be `apiKey` -- `in` can be one of the `query`, `header` or `cookie`. This value specifies how - the value will be sent to an API operation. When using the `query` option, the - API key will be sent in the request body for POST requests and in query string - for GET requests. +- `in` can be one of the `query`, `header` or `cookie`. This value specifies how the value will be sent to an API operation. When using the `query` option, the API key will be sent in the request body for POST requests and in query string for GET requests. -- `name` is the name of the API key that should be sent to an API. For example - "X-Api-Key". +- `name` is the name of the API key that should be sent to an API. For example "X-Api-Key". ```json "ois": [ @@ -108,11 +94,7 @@ fields: ] │ ``` -The value of the `apiKey` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `apiKey` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json "apiCredentials": [ │ @@ -126,11 +108,7 @@ file. ### http -The `http` security scheme type is used to define either a `basic` or `bearer` -authentication scheme. This security scheme will always be sent in the headers. -The security scheme value should be base64 encoded value "username:password" for -`basic` auth and the encoded token for `bearer` auth. It is an object which -consists of the following fields: +The `http` security scheme type is used to define either a `basic` or `bearer` authentication scheme. This security scheme will always be sent in the headers. The security scheme value should be base64 encoded value "username:password" for `basic` auth and the encoded token for `bearer` auth. It is an object which consists of the following fields: - `type` must be `http` - `scheme` is either `basic` or `bearer` @@ -144,11 +122,7 @@ consists of the following fields: } ``` -The value of the `http` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `http` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json { @@ -160,18 +134,13 @@ file. ::: info Authentication Tutorial -The -[authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates authentication. +The [authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) monorepo example demonstrates authentication. ::: ## Relayed Meta Data Security Schemes -In addition to authenticating itself, Airnode can "relay" security information -about a request to an API operation. This is different then the authorization of -requesters using [Authorizers](/reference/airnode/next/understand/apply-auth.md) -to access the Airnode. +In addition to authenticating itself, Airnode can "relay" security information about a request to an API operation. This is different then the authorization of requesters using [Authorizers](/reference/airnode/next/understand/apply-auth.md) to access the Airnode. - [relayRequesterAddress](/reference/airnode/next/understand/api-security.md#relayrequesteraddress) - [relayChainId](/reference/airnode/next/understand/api-security.md#relaychainid) @@ -180,29 +149,19 @@ to access the Airnode. - [relaySponsorWalletAddress](/reference/airnode/next/understand/api-security.md#relaysponsorwalletaddress) - [relayRequestId](/reference/airnode/next/understand/api-security.md#relayrequestid) -For relayed meta data security schemes do not provide any values in -[apiCredentials](/reference/airnode/next/deployment-files/config-json.md#apicredentials) -as they are extracted from the request by Airnode. +For relayed meta data security schemes do not provide any values in [apiCredentials](/reference/airnode/next/deployment-files/config-json.md#apicredentials) as they are extracted from the request by Airnode. -Note that Airnode relays this metadata to an API operation and does not perform -any additional processing logic. The API provider must implement any desired -logic in the API operation for any desired security checks. See -[Relayed Meta Data Authentication](/reference/airnode/next/concepts/relay-meta-auth.md) -for overview of its usage. +Note that Airnode relays this metadata to an API operation and does not perform any additional processing logic. The API provider must implement any desired logic in the API operation for any desired security checks. See [Relayed Meta Data Authentication](/reference/airnode/next/concepts/relay-meta-auth.md) for overview of its usage. ::: info Relay Metadata Tutorial -The -[relay-security-schemes](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates how to relay request metadata like chain ID and -sponsor address to the API endpoint. +The [relay-security-schemes](/guides/airnode/monorepo-examples.md) monorepo example demonstrates how to relay request metadata like chain ID and sponsor address to the API endpoint. ::: ### relayRequesterAddress -The `relayRequesterAddress` security scheme type instructs Airnode to forward -the [requester](/reference/airnode/next/concepts/requester.md) address. +The `relayRequesterAddress` security scheme type instructs Airnode to forward the [requester](/reference/airnode/next/concepts/requester.md) address. ```json { @@ -214,8 +173,7 @@ the [requester](/reference/airnode/next/concepts/requester.md) address. ### relayChainId -The `relayChainId` security scheme type instructs Airnode to forward the chain's -ID. +The `relayChainId` security scheme type instructs Airnode to forward the chain's ID. ```json { @@ -227,8 +185,7 @@ ID. ### relayChainType -The `relayChainType` security scheme type instructs Airnode to forward the -chain's type. +The `relayChainType` security scheme type instructs Airnode to forward the chain's type. ```json { @@ -240,8 +197,7 @@ chain's type. ### relaySponsorAddress -The `relaySponsorAddress` security scheme type instructs Airnode to forward the -[sponsor address](/reference/airnode/next/concepts/sponsor.md#sponsoraddress). +The `relaySponsorAddress` security scheme type instructs Airnode to forward the [sponsor address](/reference/airnode/next/concepts/sponsor.md#sponsoraddress). ```json { @@ -253,9 +209,7 @@ The `relaySponsorAddress` security scheme type instructs Airnode to forward the ### relaySponsorWalletAddress -The `relaySponsorWalletAddress` security scheme type instructs Airnode to -forward the -[sponsor wallet address](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). +The `relaySponsorWalletAddress` security scheme type instructs Airnode to forward the [sponsor wallet address](/reference/airnode/next/concepts/sponsor.md#sponsorwallet). ```json { @@ -267,8 +221,7 @@ forward the ### relayRequestId -The `relayRequestId` security scheme type instructs Airnode to forward the -[id of the request](/reference/airnode/next/concepts/request.md#requestid). +The `relayRequestId` security scheme type instructs Airnode to forward the [id of the request](/reference/airnode/next/concepts/request.md#requestid). ```json { @@ -278,10 +231,7 @@ The `relayRequestId` security scheme type instructs Airnode to forward the } ``` -The following example shows how to set up relayed meta data to forward the -`relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that -unlike the Airnode authentication security scheme, no values are stored in -`apiCredentials` as Airnode passes these known values to the API operation. +The following example shows how to set up relayed meta data to forward the `relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that unlike the Airnode authentication security scheme, no values are stored in `apiCredentials` as Airnode passes these known values to the API operation. ```json "ois": [ @@ -317,29 +267,19 @@ unlike the Airnode authentication security scheme, no values are stored in ::: info Remember -The relayed meta data security schemes do not require a supplied value. Values -will be provided (relayed) by Airnode depending on the particular request. +The relayed meta data security schemes do not require a supplied value. Values will be provided (relayed) by Airnode depending on the particular request. ::: ## Example -OIS security is inspired by OAS security practices. This is implemented using -the security schemes and security field. All supported security schemes are -described in detail in the -[Airnode Authentication Security Schemes](/reference/airnode/next/understand/api-security.md#airnode-authentication-security-schemes) -and -[Relayed Meta Data Security Schemes](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes) -sections above. The following example is related to _Airnode Authentication -Security Schemes_. Working with security schemes can be described in three -steps. +OIS security is inspired by OAS security practices. This is implemented using the security schemes and security field. All supported security schemes are described in detail in the [Airnode Authentication Security Schemes](/reference/airnode/next/understand/api-security.md#airnode-authentication-security-schemes) and [Relayed Meta Data Security Schemes](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes) sections above. The following example is related to _Airnode Authentication Security Schemes_. Working with security schemes can be described in three steps. 1. [Define the security schemes for an OIS](/reference/airnode/next/understand/api-security.md#step-1-define-the-security-schemes-for-an-ois) 2. [Turn on the defined security schemes](/reference/airnode/next/understand/api-security.md#step-2-turn-on-the-defined-security-schemes) 3. [Specify the values for the defined security schemes](/reference/airnode/next/understand/api-security.md#step-3-specify-the-values-for-the-defined-security-schemes) -Following is an example of a partial `config.json` which demonstrates the usage -of security scheme and security field. +Following is an example of a partial `config.json` which demonstrates the usage of security scheme and security field. ```json { @@ -376,60 +316,34 @@ of security scheme and security field. ### Step #1: Define the security schemes for an OIS -Use -ois[n].apiSpecifications.components.securitySchemes -to define the security schemes the API operation requires. Consider the partial -`config.json` above that declares a security scheme named `requiresXApiKey`. -This scheme declares that the API requires an API key that must exist in the -HTTP header named `X-api-key`. +Use ois[n].apiSpecifications.components.securitySchemes to define the security schemes the API operation requires. Consider the partial `config.json` above that declares a security scheme named `requiresXApiKey`. This scheme declares that the API requires an API key that must exist in the HTTP header named `X-api-key`. ### Step #2: Turn on the defined security schemes -When the scheme is defined, it is not turned on by default. You need to -explicitly list the security schemes you intend to use in the `security` field -located in `ois[n].apiSpecifications.security` object. The keys in this object -are the names of security schemes to be used. Use empty array (`[]`) as its -value. +When the scheme is defined, it is not turned on by default. You need to explicitly list the security schemes you intend to use in the `security` field located in `ois[n].apiSpecifications.security` object. The keys in this object are the names of security schemes to be used. Use empty array (`[]`) as its value. -_Be aware that this step seems like extra work since there is no reason to -define a security scheme that will not be used. However, Airnode may support -[more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) -logic in the future and using `[]` allows its implementation without a breaking -change._ +_Be aware that this step seems like extra work since there is no reason to define a security scheme that will not be used. However, Airnode may support [more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) logic in the future and using `[]` allows its implementation without a breaking change._ ### Step #3: Specify the values for the defined security schemes -After defining and turning on a security scheme, it may be unclear what provides -the value and how it is set. +After defining and turning on a security scheme, it may be unclear what provides the value and how it is set. -The authentication schemes are intended to be common for the whole OIS and set -by the API provider using `apiCredentials` which is part of `config.json`. The -`apiCredentials` is an array which specifies the values for all security schemes -in all OIS definitions. Each element of this array contains the following fields +The authentication schemes are intended to be common for the whole OIS and set by the API provider using `apiCredentials` which is part of `config.json`. The `apiCredentials` is an array which specifies the values for all security schemes in all OIS definitions. Each element of this array contains the following fields - `oisTitle` is the title of the OIS for the particular security scheme - `securitySchemeName` is the name of the security scheme -- `securitySchemeValue` is the actual value that should be used by Airnode when - making the API request. This value is usually a secret and it is recommended - to interpolate it from `secrets.env`. +- `securitySchemeValue` is the actual value that should be used by Airnode when making the API request. This value is usually a secret and it is recommended to interpolate it from `secrets.env`. ## Using Different Security Schemes -Currently, if you want different API operations to use different security -schemes they must be grouped in different OIS objects based on their common -security schemes. For example, your API has four operations, three require an -API key in the HTTP header, another (public `/ping` endpoint) requires no -security. +Currently, if you want different API operations to use different security schemes they must be grouped in different OIS objects based on their common security schemes. For example, your API has four operations, three require an API key in the HTTP header, another (public `/ping` endpoint) requires no security. -- The first three API operations might be in the `ois[0]` object with a security - scheme named _requiresXApiKey_ of type _apiKey_ as shown above. -- The /ping API operation would be in `ois[1]` which would not have any - `component.securitySchemes` and `security` would be an empty array. +- The first three API operations might be in the `ois[0]` object with a security scheme named _requiresXApiKey_ of type _apiKey_ as shown above. +- The /ping API operation would be in `ois[1]` which would not have any `component.securitySchemes` and `security` would be an empty array. ## Multiple Security Schemes -You can use multiple security schemes (e.g., an API key goes in the header, and -an additional secret goes in the query). +You can use multiple security schemes (e.g., an API key goes in the header, and an additional secret goes in the query). ```json // inside ois[n].apiSpecifications. @@ -455,7 +369,6 @@ an additional secret goes in the query). ## No Security -If the API you are integrating is publicly accessible, you can set both the -`security schemes` and `security` fields to empty objects. +If the API you are integrating is publicly accessible, you can set both the `security schemes` and `security` fields to empty objects. diff --git a/docs/reference/airnode/next/understand/apply-auth.md b/docs/reference/airnode/next/understand/apply-auth.md index 89095b9c..48340c49 100644 --- a/docs/reference/airnode/next/understand/apply-auth.md +++ b/docs/reference/airnode/next/understand/apply-auth.md @@ -19,51 +19,29 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using [Authorizers](/reference/airnode/next/concepts/authorizers.md). -This method is on-chain and requires some blockchain knowledge by an API -provider. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizers](/reference/airnode/next/concepts/authorizers.md). This method is on-chain and requires some blockchain knowledge by an API provider. ## What is an authorizer? -An [Authorizer](/reference/airnode/next/concepts/authorizers.md) is a contract -which typically checks for a single condition ("has the requester made their -monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers -can be combined to enforce more complex policies. If any of the authorizers in -the list gives access, the request will considered to be authorized. From a -logical standpoint, the authorization outcomes get *OR*ed. +An [Authorizer](/reference/airnode/next/concepts/authorizers.md) is a contract which typically checks for a single condition ("has the requester made their monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers can be combined to enforce more complex policies. If any of the authorizers in the list gives access, the request will considered to be authorized. From a logical standpoint, the authorization outcomes get *OR*ed. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: ## How to implement authorizers. -When you deploy your Airnode a receipt file is generated which contains the -Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use -`airnodeAddress` and an `endpointId` to make requests to your Airnode's -endpoints. However, rather than serve them publicly, you may want to: +When you deploy your Airnode a receipt file is generated which contains the Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use `airnodeAddress` and an `endpointId` to make requests to your Airnode's endpoints. However, rather than serve them publicly, you may want to: -- Only serve your own - [requester contracts](/reference/airnode/next/developers/requesters-sponsors.md). +- Only serve your own [requester contracts](/reference/airnode/next/developers/requesters-sponsors.md). - Only serve sponsors who have made a subscription payment. - Only serve sponsors who have gone through KYC. -The `chains[n].authorizers` object within `config.json` enables requests to be -authorized in a variety of ways and even across chains. Currently, the -authorizers include `requesterEndpointAuthorizers`, -`crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and -`crossChainRequesterAuthorizersWithErc721`. +The `chains[n].authorizers` object within `config.json` enables requests to be authorized in a variety of ways and even across chains. Currently, the authorizers include `requesterEndpointAuthorizers`, `crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and `crossChainRequesterAuthorizersWithErc721`. -Note that when all `chains[n].authorizers` values are empty arrays, all requests -are authorized, but still can be filtered by using -[Relayed Meta Data Security Schemes](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes). +Note that when all `chains[n].authorizers` values are empty arrays, all requests are authorized, but still can be filtered by using [Relayed Meta Data Security Schemes](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes). Below are examples of how to use the authorizers. @@ -122,23 +100,11 @@ Below are examples of how to use the authorizers. ## Using `RequesterAuthorizerWithAirnode` -A common use case for an authorizer is the -[RequesterAuthorizerWithAirnode](/reference/airnode/next/concepts/authorizers.md#requesterauthorizerwithairnode) -authorizer contract developed for Airnode operators to use right out-of-the-box. -It allows the whitelisting of requester contracts (with or without expiration -timestamps) on a per endpoint basis. Endpoints are declared in the -`ois.endpoints` field of the `config.json` file. This is the most common use -case and can be implemented with the following steps: - -1. Add the RequesterAuthorizerWithAirnode - [authorizer contract address](/reference/airnode/next/#requesterauthorizerwithairnode) - to the array `chains[n].authorizers.requesterEndpointAuthorizers`. -2. After your Airnode is deployed, call the Admin CLI command - [set-whitelist-expiration](/reference/airnode/next/packages/admin-cli.md#set-whitelist-expiration) - to add the desired requester contract addresses to the whitelist maintained - by RequesterAuthorizerWithAirnode. - -Once implemented, only requester contract addresses you have added to -RequesterAuthorizerWithAirnode will have access to your Airnode. +A common use case for an authorizer is the [RequesterAuthorizerWithAirnode](/reference/airnode/next/concepts/authorizers.md#requesterauthorizerwithairnode) authorizer contract developed for Airnode operators to use right out-of-the-box. It allows the whitelisting of requester contracts (with or without expiration timestamps) on a per endpoint basis. Endpoints are declared in the `ois.endpoints` field of the `config.json` file. This is the most common use case and can be implemented with the following steps: + +1. Add the RequesterAuthorizerWithAirnode [authorizer contract address](/reference/airnode/next/#requesterauthorizerwithairnode) to the array `chains[n].authorizers.requesterEndpointAuthorizers`. +2. After your Airnode is deployed, call the Admin CLI command [set-whitelist-expiration](/reference/airnode/next/packages/admin-cli.md#set-whitelist-expiration) to add the desired requester contract addresses to the whitelist maintained by RequesterAuthorizerWithAirnode. + +Once implemented, only requester contract addresses you have added to RequesterAuthorizerWithAirnode will have access to your Airnode. diff --git a/docs/reference/airnode/next/understand/configuring.md b/docs/reference/airnode/next/understand/configuring.md index 94a8e847..2a2e8d9d 100644 --- a/docs/reference/airnode/next/understand/configuring.md +++ b/docs/reference/airnode/next/understand/configuring.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -An Airnode is deployed or redeployed using configuration values from its -`config.json` and `secrets.env` files. The `config.json` specifies the -[Oracle Integration Specifications OIS](/reference/ois/next/specification.md) -and other specific configuration details. The `secrets.env` file holds secrets, -such as API keys and chain provider URLs, which are referenced within the -config.json file using interpolation. +An Airnode is deployed or redeployed using configuration values from its `config.json` and `secrets.env` files. The `config.json` specifies the [Oracle Integration Specifications OIS](/reference/ois/next/specification.md) and other specific configuration details. The `secrets.env` file holds secrets, such as API keys and chain provider URLs, which are referenced within the config.json file using interpolation. > > @@ -41,11 +36,7 @@ The following example files are useful while reading this doc. ## Creating `config.json` -Use the -[config.json template](/reference/airnode/next/deployment-files/templates/config-json.md) -to build your own Airnode configuration file or alter the -[config.json example](/reference/airnode/next/deployment-files/examples/config-json.md) -file. There are six root level fields in `config.json`. +Use the [config.json template](/reference/airnode/next/deployment-files/templates/config-json.md) to build your own Airnode configuration file or alter the [config.json example](/reference/airnode/next/deployment-files/examples/config-json.md) file. There are six root level fields in `config.json`. - [chains](/reference/airnode/next/understand/configuring.md#chains) - [nodeSettings](/reference/airnode/next/understand/configuring.md#nodesettings) @@ -56,15 +47,7 @@ file. There are six root level fields in `config.json`. ### chains -Each row in the `chains` array represents an Ethereum blockchain the Airnode -will serve as identified by the `id`. Currently Airnode only supports Ethereum -blockchains as denoted by `type: "evm"`. There are several supported -blockchains, see them in the -[Airnode contract addresses](/reference/airnode/next/) doc. You can use multiple -chain providers for each chain and declare multiple chains each with one of more -chain providers. See -[Chains Providers](/reference/airnode/next/concepts/chain-providers.md) in -_Concepts and Definitions_. +Each row in the `chains` array represents an Ethereum blockchain the Airnode will serve as identified by the `id`. Currently Airnode only supports Ethereum blockchains as denoted by `type: "evm"`. There are several supported blockchains, see them in the [Airnode contract addresses](/reference/airnode/next/) doc. You can use multiple chain providers for each chain and declare multiple chains each with one of more chain providers. See [Chains Providers](/reference/airnode/next/concepts/chain-providers.md) in _Concepts and Definitions_. Below is a simple chain array with a single chain provider. @@ -128,42 +111,26 @@ Below is a simple chain array with a single chain provider. ::: info Idiosyncrasies -See the dedicated -[Chain Idiosyncrasies](/reference/airnode/next/chain-idiosyncrasies.md) -page for chain-specific configuration considerations. +See the dedicated [Chain Idiosyncrasies](/reference/airnode/next/chain-idiosyncrasies.md) page for chain-specific configuration considerations. ::: #### Considerations: Gas Price Oracle -The gas price oracle strategies are applied in the order that they are listed. -Airnode supports four strategies: `latestBlockPercentileGasPrice`, -`providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and -`constantGasPrice`. The only required strategy is `constantGasPrice` and it is -recommended to place it as the last strategy in the list as it should be the -final fallback for the Airnode to use if all other strategies fail. For more -detail on these strategies, see the -[Gas Price Strategies](/reference/airnode/next/concepts/gas-prices.md) page. +The gas price oracle strategies are applied in the order that they are listed. Airnode supports four strategies: `latestBlockPercentileGasPrice`, `providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and `constantGasPrice`. The only required strategy is `constantGasPrice` and it is recommended to place it as the last strategy in the list as it should be the final fallback for the Airnode to use if all other strategies fail. For more detail on these strategies, see the [Gas Price Strategies](/reference/airnode/next/concepts/gas-prices.md) page. #### Considerations: Concurrency -If you set the `maxConcurrency` field to value X, then Airnode will guarantee -that: +If you set the `maxConcurrency` field to value X, then Airnode will guarantee that: - At most X api calls are made to the API -- At most X transactions (made by blockchain providers) will be made by the - blockchain providers of the respective chain +- At most X transactions (made by blockchain providers) will be made by the blockchain providers of the respective chain -When doing this, Airnode will calculate the total number of requests reported by -all blockchain providers. If this number exceeds the maximum concurrency limit, -Airnode will start processing the oldest request from the blockchain providers -until the number of processed requests reaches the limit. All other requests are -dropped and will be processed in the next Airnode run. +When doing this, Airnode will calculate the total number of requests reported by all blockchain providers. If this number exceeds the maximum concurrency limit, Airnode will start processing the oldest request from the blockchain providers until the number of processed requests reaches the limit. All other requests are dropped and will be processed in the next Airnode run. Note that this request dropping happens for each **chain** separately. -For example, if `maxConcurrency` is set to 5 and there are three providers (A, B -and C) and they reported the following requests: +For example, if `maxConcurrency` is set to 5 and there are three providers (A, B and C) and they reported the following requests: - A1, A2, A3, A4 and A5 - B1, B2 and B3 @@ -173,17 +140,13 @@ The above example results in the following requests: A1, A2, B1, B2, and C1. ::: warning -Note, that this limit only applies to the requests initiated on chain. For -example, requests initiated using HTTP gateway are not included in this limit. -Also note that, this limit is configured per chain and the limits of different -chains are unrelated to each other. +Note, that this limit only applies to the requests initiated on chain. For example, requests initiated using HTTP gateway are not included in this limit. Also note that, this limit is configured per chain and the limits of different chains are unrelated to each other. ::: #### References: `chains` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [authorizers](/reference/airnode/next/deployment-files/config-json.md#authorizers) - [id](/reference/airnode/next/deployment-files/config-json.md#id) @@ -233,26 +196,15 @@ The `nodeSettings` field holds node-specific (Airnode) configuration parameters. #### Considerations: Cloud Providers -Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are -supported cloud providers for hosting Airnode. Note that while many fields -within `nodeSettings` are required by both, there are some cloud provider -specific fields. For example, `cloudProvider.projectId` is only required with -GCP. Also note that not all cloud provider regions can be deployed to; see the -[cloudProvider.region reference](/reference/airnode/next/deployment-files/config-json.md#cloudprovider-region) -for more information. +Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are supported cloud providers for hosting Airnode. Note that while many fields within `nodeSettings` are required by both, there are some cloud provider specific fields. For example, `cloudProvider.projectId` is only required with GCP. Also note that not all cloud provider regions can be deployed to; see the [cloudProvider.region reference](/reference/airnode/next/deployment-files/config-json.md#cloudprovider-region) for more information. #### Considerations: Gateways -Airnode offers two gateways for accessing provider HTTP endpoints without using -the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information -on each of these see the -[HTTP Gateways](/reference/airnode/next/understand/http-gateways.md) -documentation. Also note that that distinct API keys must be used for each. +Airnode offers two gateways for accessing provider HTTP endpoints without using the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information on each of these see the [HTTP Gateways](/reference/airnode/next/understand/http-gateways.md) documentation. Also note that that distinct API keys must be used for each. #### References: `nodeSettings` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [cloudProvider](/reference/airnode/next/deployment-files/config-json.md#cloudprovider) - [cloudProvider.type](/reference/airnode/next/deployment-files/config-json.md#cloudprovider-type) @@ -279,15 +231,9 @@ Files section: ### triggers -The `triggers` field allow exposes Airnode endpoints from an OIS selectively for -the RRP protocol or via the HTTP gateway. For example, an OIS object may include -10 endpoints, but only two are desired for RRP and all 10 for the gateway. +The `triggers` field allow exposes Airnode endpoints from an OIS selectively for the RRP protocol or via the HTTP gateway. For example, an OIS object may include 10 endpoints, but only two are desired for RRP and all 10 for the gateway. -List the endpoints to serve with the request–response protocol (RRP) under -`triggers.rrp`. List the endpoints to serve with the HTTP gateway under -`triggers.http`. List the endpoints which can be used to get the signed data in -`triggers.httpSignedData`. In most cases create a trigger for each endpoint in -your OIS object. +List the endpoints to serve with the request–response protocol (RRP) under `triggers.rrp`. List the endpoints to serve with the HTTP gateway under `triggers.http`. List the endpoints which can be used to get the signed data in `triggers.httpSignedData`. In most cases create a trigger for each endpoint in your OIS object. ```json "triggers": { @@ -318,65 +264,38 @@ your OIS object. #### Considerations: triggers -The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived -from the `oisTitle` and `endpointName` using the CLI command -[derive-endpoint-id](/reference/airnode/next/packages/admin-cli.md#derive-endpoint-id). -Remember that an Airnode's config.json file can have more than one OIS object -and that these endpoints can be triggers for `rrp`, `http`, and/or -`httpSignedData` as desired. +The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived from the `oisTitle` and `endpointName` using the CLI command [derive-endpoint-id](/reference/airnode/next/packages/admin-cli.md#derive-endpoint-id). Remember that an Airnode's config.json file can have more than one OIS object and that these endpoints can be triggers for `rrp`, `http`, and/or `httpSignedData` as desired. #### Considerations: cached responses -When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API -responses on the local filesystem per request ID. This only applies to -blockchain requests. The flow is: +When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API responses on the local filesystem per request ID. This only applies to blockchain requests. The flow is: 1. A request is received from the Blockchain. 1. The Airnode does an HTTP/S call to a remote API based on the request. -1. [with caching enabled] Airnode stores the response on the local filesystem by - request ID. -1. Airnode then follows the usual process of extracting the response, - post-processing it and sending the response back on chain as a fulfillment - callback. -1. After all current requests are processed, Airnode then exits until the next - cycle (the next minute). -1. If during the next cycle, if the Airnode gets the same request and it isn't - fulfilled, it will try and fulfill the request again. Ordinarily, without - caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with - caching enabled it will fulfill the response using the cached API response - value. - -Clearance of the local filesystem cache is dependant on the environment Airnode -runs in. As a guideline: +1. [with caching enabled] Airnode stores the response on the local filesystem by request ID. +1. Airnode then follows the usual process of extracting the response, post-processing it and sending the response back on chain as a fulfillment callback. +1. After all current requests are processed, Airnode then exits until the next cycle (the next minute). +1. If during the next cycle, if the Airnode gets the same request and it isn't fulfilled, it will try and fulfill the request again. Ordinarily, without caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with caching enabled it will fulfill the response using the cached API response value. + +Clearance of the local filesystem cache is dependant on the environment Airnode runs in. As a guideline: - AWS Lambda persists for 2.5 hours. - Google Cloud persistence is completely arbitrary. - Docker persists as long as the container remains running. -If the local filesystem is cleared, the cache is lost and if a repeat request is -received after the cache has been cleared, Airnode will repeat the API call. -Airnode self-clears cached data after the data has reached 1 hour's age. +If the local filesystem is cleared, the cache is lost and if a repeat request is received after the cache has been cleared, Airnode will repeat the API call. Airnode self-clears cached data after the data has reached 1 hour's age. -Furthermore, as an example: "if an Airnode AWS Lambda environment/container" -(since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours -and Airnode gets a request, that request will only be cached until the container -resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. +Furthermore, as an example: "if an Airnode AWS Lambda environment/container" (since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours and Airnode gets a request, that request will only be cached until the container resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. -As described above, caching on serverless infrastructure is unreliable and if -request caching is mission critical, Airnode should be run in a Docker container -with a persistent `/tmp` directory. +As described above, caching on serverless infrastructure is unreliable and if request caching is mission critical, Airnode should be run in a Docker container with a persistent `/tmp` directory. -Caching is useful for non-idempotent API operations like random number -generators. Consider the following use-case: +Caching is useful for non-idempotent API operations like random number generators. Consider the following use-case: -> Random Numbers: in the absence of caching, a malicious blockchain provider can -> selectively block fulfillments containing numbers they don't like, allowing -> them to improve their odds of winning in a random-number betting game. +> Random Numbers: in the absence of caching, a malicious blockchain provider can selectively block fulfillments containing numbers they don't like, allowing them to improve their odds of winning in a random-number betting game. #### References: `triggers` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [rrp](/reference/airnode/next/deployment-files/config-json.md#rrp) - [rrp[n].endpointId](/reference/airnode/next/deployment-files/config-json.md#rrp-n-endpointid) @@ -394,13 +313,11 @@ Files section: ### templates -The templates field allows you to specify templates to be used to make template -requests. The array can be left empty if no templates will be used. +The templates field allows you to specify templates to be used to make template requests. The array can be left empty if no templates will be used. #### References: templates -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [templateId](/reference/airnode/next/deployment-files/config-json.md#templateid) - [endpointId](/reference/airnode/next/deployment-files/config-json.md#endpointid) @@ -408,23 +325,11 @@ Files section: ### ois -The `ois` field is a list OIS objects that Airnode will be serving. This means -that a single instance of an Airnode can serve multiple APIs. You can simply -copy paste OIS objects that you will be serving into the `ois` list. Use the -previous guide -[API Integration](/reference/airnode/next/understand/api-integration.md) to -create an OIS object. The full specification is available in the -[Oracle Integration Specifications (OIS)](/reference/ois/next/) documentation. +The `ois` field is a list OIS objects that Airnode will be serving. This means that a single instance of an Airnode can serve multiple APIs. You can simply copy paste OIS objects that you will be serving into the `ois` list. Use the previous guide [API Integration](/reference/airnode/next/understand/api-integration.md) to create an OIS object. The full specification is available in the [Oracle Integration Specifications (OIS)](/reference/ois/next/) documentation. ### apiCredentials -Each entry in `apiCredentials` maps to a security scheme defined in an OIS -(`ois[n].components.securitySchemes.{securitySchemeName}` and -`ois[n].security`), where `oisTitle` is the `title` field of the related OIS, -and `securitySchemeName` is the name of the respective security scheme. These -would be `myOisTitle` and `mySecurityScheme` in the example below. -`securitySchemeValue` is the value used for the authentication with the security -scheme (e.g., the API key). +Each entry in `apiCredentials` maps to a security scheme defined in an OIS (`ois[n].components.securitySchemes.{securitySchemeName}` and `ois[n].security`), where `oisTitle` is the `title` field of the related OIS, and `securitySchemeName` is the name of the respective security scheme. These would be `myOisTitle` and `mySecurityScheme` in the example below. `securitySchemeValue` is the value used for the authentication with the security scheme (e.g., the API key). If no security scheme is needed, leave the `apiCredentials` array empty. @@ -461,14 +366,11 @@ If no security scheme is needed, leave the `apiCredentials` array empty. #### Considerations: apiCredentials -Currently Airnode supports the following security scheme types when making API -calls: `apiKey` and `http`. For more detail, visit the previous section on -[API Security](/reference/airnode/next/understand/api-security.md). +Currently Airnode supports the following security scheme types when making API calls: `apiKey` and `http`. For more detail, visit the previous section on [API Security](/reference/airnode/next/understand/api-security.md). #### References: `apiCredentials` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [oisTitle](/reference/airnode/next/deployment-files/config-json.md#oistitle) - [securitySchemeName](/reference/airnode/next/deployment-files/config-json.md#securityschemename) @@ -476,10 +378,7 @@ Files section: ## Creating `secrets.env` -The `secrets.env` file contains values (secrets) such as blockchain provider -urls, chain provider urls, etc. These secrets are embedded in -[config.json](/reference/airnode/next/deployment-files/config-json.md) using -interpolation. +The `secrets.env` file contains values (secrets) such as blockchain provider urls, chain provider urls, etc. These secrets are embedded in [config.json](/reference/airnode/next/deployment-files/config-json.md) using interpolation. ```json // Sample interpolation value from config.json @@ -493,25 +392,15 @@ interpolation. HEARTBEAT_API_KEY="d714a900-3b9e-4e4d-8eae-756ef06a8836" ``` -Use the -[secrets.env](/reference/airnode/next/deployment-files/templates/secrets-env.md) -template and refer to -[Reference > Deployment Files > secrets.env](/reference/airnode/next/deployment-files/secrets-env.md) -as needed. +Use the [secrets.env](/reference/airnode/next/deployment-files/templates/secrets-env.md) template and refer to [Reference > Deployment Files > secrets.env](/reference/airnode/next/deployment-files/secrets-env.md) as needed. ## AWS setup (AWS deployment only) -When it is time to deploy the Airnode to AWS, the Docker -[deployer image](/reference/airnode/next/docker/deployer-image.md) will need the -AWS credentials to build the node on AWS Lambda. +When it is time to deploy the Airnode to AWS, the Docker [deployer image](/reference/airnode/next/docker/deployer-image.md) will need the AWS credentials to build the node on AWS Lambda. ### Creating `aws.env` (AWS only) -Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It -explains how to create an IAM user and get security credentials. Put them in the -`aws.env` file as shown below. See an -[example file](/reference/airnode/next/deployment-files/templates/aws-env.md) in -the reference section. +Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It explains how to create an IAM user and get security credentials. Put them in the `aws.env` file as shown below. See an [example file](/reference/airnode/next/deployment-files/templates/aws-env.md) in the reference section. - Variable names cannot contain dashes (-) or start with a number. @@ -522,46 +411,26 @@ AWS_SECRET_ACCESS_KEY=ABC7...89 ## GCP setup (GCP deployment only) -When it is time to deploy the Airnode to GCP, the Docker -[deployer image](/reference/airnode/next/docker/deployer-image.md) will need the -GCP project ID to build the Airnode. +When it is time to deploy the Airnode to GCP, the Docker [deployer image](/reference/airnode/next/docker/deployer-image.md) will need the GCP project ID to build the Airnode. ### Creating a GCP project -First -[create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) -under which will the Airnode be deployed. Once the project is created, insert -its -[projectId](/reference/airnode/next/deployment-files/config-json.md#cloudprovider) -into the `config.json` file. +First [create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) under which will the Airnode be deployed. Once the project is created, insert its [projectId](/reference/airnode/next/deployment-files/config-json.md#cloudprovider) into the `config.json` file. ### Enable required API -In order for Airnode to deploy successfully, enable -[App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) -for the GCP project. After enabling it, wait a few minutes before the deployment -itself so the change will take place. +In order for Airnode to deploy successfully, enable [App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) for the GCP project. After enabling it, wait a few minutes before the deployment itself so the change will take place. ### Creating a Service Account -Create a new service account from the -[Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) -menu. Grant this service account access to the project by adding a role `Owner` -during the creation process. +Create a new service account from the [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) menu. Grant this service account access to the project by adding a role `Owner` during the creation process. -Once the account is created, add a new access key of type JSON for this account. -Download the key file as `gcp.json` into the root of your project. +Once the account is created, add a new access key of type JSON for this account. Download the key file as `gcp.json` into the root of your project. ## Summary -In this guide you created the `config.json`, `secrets.env` and obtained cloud -provider credentials required to deploy an Airnode to a cloud provider. Note -that `config.json` is user-specific and therefore it is not much use to others. +In this guide you created the `config.json`, `secrets.env` and obtained cloud provider credentials required to deploy an Airnode to a cloud provider. Note that `config.json` is user-specific and therefore it is not much use to others. -The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider -urls and security credentials, so they should be kept secret. Make sure that you -do not push your credentials to a repository or otherwise expose them as these -credentials can be used to gain access to your Airnode's private key, AWS -account or GCP account. +The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider urls and security credentials, so they should be kept secret. Make sure that you do not push your credentials to a repository or otherwise expose them as these credentials can be used to gain access to your Airnode's private key, AWS account or GCP account. diff --git a/docs/reference/airnode/next/understand/deploying.md b/docs/reference/airnode/next/understand/deploying.md index 71f8e88d..cd8a7646 100644 --- a/docs/reference/airnode/next/understand/deploying.md +++ b/docs/reference/airnode/next/understand/deploying.md @@ -19,49 +19,21 @@ tags: # {{$frontmatter.title}} -After integrating an API -([API Integration](/reference/airnode/next/understand/api-integration.md)) and -creating the configuration files -([Configuring Airnode](/reference/airnode/next/understand/configuring.md)), the -next step is to deploy the Airnode. +After integrating an API ([API Integration](/reference/airnode/next/understand/api-integration.md)) and creating the configuration files ([Configuring Airnode](/reference/airnode/next/understand/configuring.md)), the next step is to deploy the Airnode. ## Deploy with Docker -The recommended way to deploy Airnode is by using the Docker -[deployer image](/reference/airnode/next/docker/deployer-image.md). This image -is simply a wrapper around the -[deployer CLI](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer). -Try the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -tutorial if you wish to become familiar with the deployer image first. There are -also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a -[client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as -well as several repo based examples in the -[Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) -package. - -The deployer interacts with a cloud provider to deploy Airnode programmatically, -without requiring you to click through a lot of ever-changing graphical -interfaces. For it to do so, a cloud project setup and credentials are required -and was discussed in -[Configuring an Airnode](/reference/airnode/next/understand/configuring.md#aws-setup-aws-deployment-only). -There is additional guidance in the AWS and GCP quick start tutorials mentioned -above. +The recommended way to deploy Airnode is by using the Docker [deployer image](/reference/airnode/next/docker/deployer-image.md). This image is simply a wrapper around the [deployer CLI](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-deployer). Try the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) tutorial if you wish to become familiar with the deployer image first. There are also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a [client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as well as several repo based examples in the [Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.14/packages/airnode-examples) package. + +The deployer interacts with a cloud provider to deploy Airnode programmatically, without requiring you to click through a lot of ever-changing graphical interfaces. For it to do so, a cloud project setup and credentials are required and was discussed in [Configuring an Airnode](/reference/airnode/next/understand/configuring.md#aws-setup-aws-deployment-only). There is additional guidance in the AWS and GCP quick start tutorials mentioned above. ## Install Docker -The [deployer image](/reference/airnode/next/docker/deployer-image.md) is -containerized as a Docker image. This will deploy the Airnode to the cloud -provider without the worry of installing dependencies and is the recommended way -to do a deployment. If you do not already have docker installed go to the -[Docker website](https://docs.docker.com/get-docker/) and install it. +The [deployer image](/reference/airnode/next/docker/deployer-image.md) is containerized as a Docker image. This will deploy the Airnode to the cloud provider without the worry of installing dependencies and is the recommended way to do a deployment. If you do not already have docker installed go to the [Docker website](https://docs.docker.com/get-docker/) and install it. ## Deployment -At this point a project should resemble the following. The `config.json`, -`secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to -GCP) files should be ready to go. Other files and folders added to the project -are expected and are ignored by the deployer image. +At this point a project should resemble the following. The `config.json`, `secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to GCP) files should be ready to go. Other files and folders added to the project are expected and are ignored by the deployer image. ::: code-group @@ -84,13 +56,7 @@ my-airnode -From the root of the project directory run the Docker image command -[deploy](/reference/airnode/next/docker/deployer-image.md#deploy) as shown below -to deploy the Airnode. When the deployment has completed a `receipt.json` file -will be written to the project directory, which is mounted to the `/app/config` -directory within the container. This file contains important configuration -information about the Airnode and is needed to remove the Airnode should the -need arise. +From the root of the project directory run the Docker image command [deploy](/reference/airnode/next/docker/deployer-image.md#deploy) as shown below to deploy the Airnode. When the deployment has completed a `receipt.json` file will be written to the project directory, which is mounted to the `/app/config` directory within the container. This file contains important configuration information about the Airnode and is needed to remove the Airnode should the need arise.

@@ -114,10 +80,7 @@ docker run -it --rm ^ ### receipt.json -The `receipt.json` file is a product of a deployment attempt. It contains -Airnode configuration and deployment information and is used to remove the -Airnode. The field `success` is important in that it specifies whether the -deployment was successful or not. +The `receipt.json` file is a product of a deployment attempt. It contains Airnode configuration and deployment information and is used to remove the Airnode. The field `success` is important in that it specifies whether the deployment was successful or not. ```json { @@ -142,9 +105,7 @@ deployment was successful or not. ## Testing with HTTP Gateway -If you opted to enable the HTTP Gateway it can be used to test the Airnode while -bypassing the chain it was deployed to. There are examples that detail how to do -this. +If you opted to enable the HTTP Gateway it can be used to test the Airnode while bypassing the chain it was deployed to. There are examples that detail how to do this. - [HTTP Gateways](/reference/airnode/next/understand/http-gateways.md#using-curl) - [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/#_5-test-the-airnode) @@ -153,15 +114,10 @@ this. ## Make an RRP request of the Airnode -Once the Airnode is deployed, see -[Calling an Airnode](/reference/airnode/next/developers/index.md) to learn how -requests are made using the request-response protocol (RRP). +Once the Airnode is deployed, see [Calling an Airnode](/reference/airnode/next/developers/index.md) to learn how requests are made using the request-response protocol (RRP). ## Removing the Airnode -If you would like to remove a deployed Airnode, see the Docker image commands -for [remove](/reference/airnode/next/docker/deployer-image.md#remove) or -[remove-with-receipt](/reference/airnode/next/docker/deployer-image.md#remove-with-receipt) -instructions. +If you would like to remove a deployed Airnode, see the Docker image commands for [remove](/reference/airnode/next/docker/deployer-image.md#remove) or [remove-with-receipt](/reference/airnode/next/docker/deployer-image.md#remove-with-receipt) instructions. diff --git a/docs/reference/airnode/next/understand/heartbeat.md b/docs/reference/airnode/next/understand/heartbeat.md index b91309a3..51781580 100644 --- a/docs/reference/airnode/next/understand/heartbeat.md +++ b/docs/reference/airnode/next/understand/heartbeat.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -At the end of an Airnode's run (every minute), Airnode can make an HTTP POST -request to a specified URL. This is both to signal that the Airnode is alive and -working (useful especially right after the deployment) and also as a -notification every time it runs (self-operates). +At the end of an Airnode's run (every minute), Airnode can make an HTTP POST request to a specified URL. This is both to signal that the Airnode is alive and working (useful especially right after the deployment) and also as a notification every time it runs (self-operates). > > @@ -31,8 +28,7 @@ notification every time it runs (self-operates). > 3.

A response is sent to each request.

> 4.

Finally Airnode makes a request to the heartbeat URL (HTTP POST). This could be to an operation within the API Airnode supports or to any cloud REST endpoint such as a monitoring service.

-Turn on the optional heartbeat functionality by setting all fields in the -`config.json` section for `nodeSettings.heartbeat`. +Turn on the optional heartbeat functionality by setting all fields in the `config.json` section for `nodeSettings.heartbeat`. ```json{12-16} { @@ -95,8 +91,7 @@ The table below illustrates the parameters passed to the Heartbeat URL. | oev_gateway_url | body | string | | signature | body | string | -Below is an example of what is included in the request body. Note that -`airnode-heartbeat-api-key` can be found in the request header and not the body. +Below is an example of what is included in the request body. Note that `airnode-heartbeat-api-key` can be found in the request header and not the body. ```json { @@ -117,18 +112,13 @@ Below is an example of what is included in the request body. Note that The method by which the heartbeat payload is generated is as follows: -- An object is marshalled to JSON - this object contains multiple fields as - shown above. -- The Airnode's mnemonic (using the default EVM derivation path to derive a key) - is used to sign the payload. +- An object is marshalled to JSON - this object contains multiple fields as shown above. +- The Airnode's mnemonic (using the default EVM derivation path to derive a key) is used to sign the payload. - The payload and signature are included in a new object and marshalled to JSON. -The reason this nested JSON approach has been used is to prevent subtle -inconsistencies between JSON marshallers in different languages causing the -signature to not match the payload. +The reason this nested JSON approach has been used is to prevent subtle inconsistencies between JSON marshallers in different languages causing the signature to not match the payload. -The airnode's public key can be recovered from this signature and be used, -generally, to verify the authenticity of the payload. +The airnode's public key can be recovered from this signature and be used, generally, to verify the authenticity of the payload. The overall content to the heartbeat URL is as follows: diff --git a/docs/reference/airnode/next/understand/http-gateways.md b/docs/reference/airnode/next/understand/http-gateways.md index c1dad7bb..8a68163c 100644 --- a/docs/reference/airnode/next/understand/http-gateways.md +++ b/docs/reference/airnode/next/understand/http-gateways.md @@ -19,35 +19,24 @@ tags: # {{$frontmatter.title}} -As part of the Airnode deployment you can decide to deploy two different HTTP -Gateways. +As part of the Airnode deployment you can decide to deploy two different HTTP Gateways. - HTTP Gateway: testing - HTTP Signed Data Gateway: production use ## Gateway Differences -Both gateways are setup identically. The differences are in their purpose and -response. +Both gateways are setup identically. The differences are in their purpose and response. > ### HTTP Gateway -The regular HTTP gateway is strictly for testing purposes. Using a simple tool -like CURL you can test that endpoints in the Airnode configuration are working -properly without accessing the blockchain. +The regular HTTP gateway is strictly for testing purposes. Using a simple tool like CURL you can test that endpoints in the Airnode configuration are working properly without accessing the blockchain. -In order to facilitate configuration and testing of parameters, HTTP gateway -requests have the following differences in handling when compared to blockchain -requests or requests to the HTTP signed data gateway: +In order to facilitate configuration and testing of parameters, HTTP gateway requests have the following differences in handling when compared to blockchain requests or requests to the HTTP signed data gateway: -1. When a request's API call is successful but then that response fails - extraction and encoding, data are still returned. This is in contrast to the - other types of requests for which only an error would be returned. The API - call response, after undergoing any - [post-processing](/reference/ois/next/processing.md), will be present in the - `rawValue` field independent of encoding success or failure: +1. When a request's API call is successful but then that response fails extraction and encoding, data are still returned. This is in contrast to the other types of requests for which only an error would be returned. The API call response, after undergoing any [post-processing](/reference/ois/next/processing.md), will be present in the `rawValue` field independent of encoding success or failure: ```json { @@ -55,29 +44,19 @@ requests or requests to the HTTP signed data gateway: } ``` -2. Reserved parameters are inaccessible in response pre/post processing. This is - only relevant if reserved parameters are being _modified_ in pre/post - processing (advanced use case). +2. Reserved parameters are inaccessible in response pre/post processing. This is only relevant if reserved parameters are being _modified_ in pre/post processing (advanced use case). ### HTTP Signed Data Gateway -The HTTP signed data gateway is used for production purposes. While it is -executed in a similar way as the HTTP gateway, its response is signed and does -not contain a `rawValue` field. This gateway is executed by an off-chain code -source that may in turn push data to a blockchain. +The HTTP signed data gateway is used for production purposes. While it is executed in a similar way as the HTTP gateway, its response is signed and does not contain a `rawValue` field. This gateway is executed by an off-chain code source that may in turn push data to a blockchain. ## Setup -Enable either gateway in the `config.json` file fields -`nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. +Enable either gateway in the `config.json` file fields `nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. - **enabled**: A boolean to enable/disable the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless function instance serving gateway requests. When - omitted, there is no maximum concurrency set. This field is ignored for - Airnode client gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless function instance serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -101,10 +80,7 @@ Enable either gateway in the `config.json` file fields }, ``` -Add the desired endpoints a gateway can respond to in the `triggers.http[n]` -and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need -to match. It could be practical to test all endpoints but only serve certain -endpoints using the HTTP signed data gateway or via RRP. +Add the desired endpoints a gateway can respond to in the `triggers.http[n]` and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need to match. It could be practical to test all endpoints but only serve certain endpoints using the HTTP signed data gateway or via RRP. ```json // in config.json @@ -134,50 +110,28 @@ endpoints using the HTTP signed data gateway or via RRP. ## Gateway URLs -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URLs should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URLs should be kept secret. -The gateway URLs are also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/next/understand/heartbeat.md) to a specified -heartbeat URL. +The gateway URLs are also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/next/understand/heartbeat.md) to a specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated for each gateway (when enabled) when Airnode is -deployed. The URL including, the secret `UUID` path parameter, is displayed on -the terminal at the end of an Airnode deployment using the -[Docker image](/reference/airnode/next/docker/deployer-image.md). +A gateway URL is generated for each gateway (when enabled) when Airnode is deployed. The URL including, the secret `UUID` path parameter, is displayed on the terminal at the end of an Airnode deployment using the [Docker image](/reference/airnode/next/docker/deployer-image.md). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for both gateways, which is exposed on the host machine. -Doing so will make the gateways API accessible like a regular web server running -on the machine. Each gateway has a separate endpoint as shown below. Note the -`PORT` which is exposed as part of the Airnode client container. See the -[Airnode client usage](/reference/airnode/next/docker/client-image.md#usage) for -more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for both gateways, which is exposed on the host machine. Doing so will make the gateways API accessible like a regular web server running on the machine. Each gateway has a separate endpoint as shown below. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/next/docker/client-image.md#usage) for more details. -- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Gateway -- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Signed Data Gateway +- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Gateway +- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Signed Data Gateway ## Using CURL -In order to execute an endpoint served by either gateway, the following are -required as part of the CURL call. +In order to execute an endpoint served by either gateway, the following are required as part of the CURL call. -- Make a POST request with the `endpointId` as a path parameter. An `endpointId` - can found in config.json under `triggers.http.endpointId` or - `triggers.httpSignedData.endpointId`. +- Make a POST request with the `endpointId` as a path parameter. An `endpointId` can found in config.json under `triggers.http.endpointId` or `triggers.httpSignedData.endpointId`. - Add the `Content-Type` header, set to `application/json`. - Place the parameters/encodedParameters in the request body. @@ -192,15 +146,11 @@ required as part of the CURL call. | \* parameters
HTTP Gateway
| body | `-d '{"parameters": {"param1": "myValue", "param2": 5}}'` | | \* encodedParameters
HTTP Signed Data Gateway
| body | `-d '{"encodedParameters": "0x3173737300....000"}'` | -\* Parameters for the gateways are named differently. The HTTP signed data -gateway requires that the `encodedParameters` be encoded using -[Airnode ABI](/reference/airnode/next/specifications/airnode-abi.md). +\* Parameters for the gateways are named differently. The HTTP signed data gateway requires that the `encodedParameters` be encoded using [Airnode ABI](/reference/airnode/next/specifications/airnode-abi.md). ### Request -Replace `` in the examples below with the URL displayed in the -terminal at the end of an Airnode deployment using a -[Docker image](/reference/airnode/next/docker/). +Replace `` in the examples below with the URL displayed in the terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/next/docker/). ::: code-group diff --git a/docs/reference/airnode/next/understand/index.md b/docs/reference/airnode/next/understand/index.md index 7ae3d97e..6cdc2f25 100644 --- a/docs/reference/airnode/next/understand/index.md +++ b/docs/reference/airnode/next/understand/index.md @@ -19,17 +19,11 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that pushes off-chain API data on-chain via data -feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs -off-chain as a background component of the API3 ecosystem. **Understanding -Airnode** is a progression of pages that provides a detailed understanding of -the capabilities and functionality of Airnode. +Airnode is a first-party oracle that pushes off-chain API data on-chain via data feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs off-chain as a background component of the API3 ecosystem. **Understanding Airnode** is a progression of pages that provides a detailed understanding of the capabilities and functionality of Airnode. ## Project Folder -A typical Airnode project folder contains files used to define the Airnode. Show -below are typical project folders for each of AWS, GCP, and container -deployments. +A typical Airnode project folder contains files used to define the Airnode. Show below are typical project folders for each of AWS, GCP, and container deployments. ::: code-group @@ -55,12 +49,7 @@ my-airnode ::: code-group -Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the -files in the -[Templates](/reference/airnode/next/deployment-files/templates/config-json.md) -as an aid to create all but the `gcp.json` files. Also see the -[Examples](/reference/airnode/next/deployment-files/examples/config-json.md) for -demonstration purposes. +Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the files in the [Templates](/reference/airnode/next/deployment-files/templates/config-json.md) as an aid to create all but the `gcp.json` files. Also see the [Examples](/reference/airnode/next/deployment-files/examples/config-json.md) for demonstration purposes. ## Configuration files @@ -69,57 +58,40 @@ demonstration purposes. - `aws.env`: AWS credentials. - `gcp.json`: GCP project information. -The diagrams below depict the configuration files needed for a successful -deployment of an Airnode to AWS, GCP, and a Docker Container. +The diagrams below depict the configuration files needed for a successful deployment of an Airnode to AWS, GCP, and a Docker Container. ### AWS -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **aws.env**: Contains AWS credentials required by the Docker deployer image. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### GCP -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **gcp.json**: GCP project file. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### Container -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. -3. **client image**: The Docker client image that contains the Airnode and runs - with the provided configuration. +3. **client image**: The Docker client image that contains the Airnode and runs with the provided configuration. ## Deploying -There are two ways to deploy and run an Airnode. The most popular is with a -cloud provider such as AWS or GCP. Use the Docker -[Airnode Deployer Image](/reference/airnode/next/docker/deployer-image.md) for -these type of deployments. - -The second method is to run a containerized Airnode hosted internally or with a -cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker -[Airnode Client Image](/reference/airnode/next/docker/client-image.md) for this -type of deployment. - -Try the guide AWS -[Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) -as a quick introduction to an Airnode deployment. Also be sure to visit -[ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an -Airnode. +There are two ways to deploy and run an Airnode. The most popular is with a cloud provider such as AWS or GCP. Use the Docker [Airnode Deployer Image](/reference/airnode/next/docker/deployer-image.md) for these type of deployments. + +The second method is to run a containerized Airnode hosted internally or with a cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker [Airnode Client Image](/reference/airnode/next/docker/client-image.md) for this type of deployment. + +Try the guide AWS [Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) as a quick introduction to an Airnode deployment. Also be sure to visit [ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an Airnode. diff --git a/docs/reference/airnode/next/understand/monitor.md b/docs/reference/airnode/next/understand/monitor.md index 036ee411..a8d61bc6 100644 --- a/docs/reference/airnode/next/understand/monitor.md +++ b/docs/reference/airnode/next/understand/monitor.md @@ -19,43 +19,24 @@ tags: # {{$frontmatter.title}} -Airnode logs or log groups are named similarly in AWS and GCP and include the -following hyphen-separated components: `airnode`, ``, -``, and ``, for example, -`airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages -or request types and the logs they contain are as follows: - -- `startCoordinator`: Logs for chain provider initialization and request - fetching +Airnode logs or log groups are named similarly in AWS and GCP and include the following hyphen-separated components: `airnode`, ``, ``, and ``, for example, `airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages or request types and the logs they contain are as follows: + +- `startCoordinator`: Logs for chain provider initialization and request fetching - `run`: Logs of API calls and withdrawals originating from blockchain requests -- `httpReq`: Logs for - [HTTP gateway requests](/reference/airnode/next/understand/http-gateways.md#http-gateway) -- `httpSignedReq`: Logs for - [HTTP signed data gateway requests](/reference/airnode/next/understand/http-gateways.md) -- `signOevReq`: Logs for - [OEV gateway requests](/reference/airnode/next/understand/oev-gateway.md) +- `httpReq`: Logs for [HTTP gateway requests](/reference/airnode/next/understand/http-gateways.md#http-gateway) +- `httpSignedReq`: Logs for [HTTP signed data gateway requests](/reference/airnode/next/understand/http-gateways.md) +- `signOevReq`: Logs for [OEV gateway requests](/reference/airnode/next/understand/oev-gateway.md) ### AWS -Airnode logs are available in -[CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. -Note that for the HTTP gateways, AWS generates a unique `requestId` for each -request. These should not be confused with the `requestId` of a request -originating from a blockchain. +Airnode logs are available in [CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. Note that for the HTTP gateways, AWS generates a unique `requestId` for each request. These should not be confused with the `requestId` of a request originating from a blockchain. ### GCP -Airnode logs are available in the -[Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to -query or stream logs by the "Cloud Function" Resource Type and then by "Function -Name" in order to view a specific request type or Airnode cycle stage. +Airnode logs are available in the [Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to query or stream logs by the "Cloud Function" Resource Type and then by "Function Name" in order to view a specific request type or Airnode cycle stage. ## Local Airnode Client -Running the `airnode-client` Docker image will output container logs to the -command line. These logs are also available through the Docker interface e.g. -under Containers within Docker Desktop. See the Docker -[client image](/reference/airnode/next/docker/client-image.md) for more -information. +Running the `airnode-client` Docker image will output container logs to the command line. These logs are also available through the Docker interface e.g. under Containers within Docker Desktop. See the Docker [client image](/reference/airnode/next/docker/client-image.md) for more information. diff --git a/docs/reference/airnode/next/understand/oev-gateway.md b/docs/reference/airnode/next/understand/oev-gateway.md index 5d398a1c..6e428113 100644 --- a/docs/reference/airnode/next/understand/oev-gateway.md +++ b/docs/reference/airnode/next/understand/oev-gateway.md @@ -19,23 +19,15 @@ tags: # {{$frontmatter.title}} -OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The -data is signed by the Airnode so that only the searcher who won the auction can -use it to update the data feed. You can learn more about OEV at -https://api3.org. +OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The data is signed by the Airnode so that only the searcher who won the auction can use it to update the data feed. You can learn more about OEV at https://api3.org. ## Setup -Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` -section. +Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` section. - **enabled**: A boolean to enable/disable for the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless functions serving gateway requests. When omitted, - there is no maximum concurrency set. This field is ignored for Airnode client - gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless functions serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -56,44 +48,25 @@ section. ## Gateway URL -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URL should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URL should be kept secret. -The gateway URL is also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/next/understand/heartbeat.md) to your specified -heartbeat URL. +The gateway URL is also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/next/understand/heartbeat.md) to your specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated when Airnode is deployed. You can see the URLs -including the secret `UUID` path parameter, displayed on your terminal at the -end of an Airnode deployment using a -[Docker image](/reference/airnode/next/docker/). +A gateway URL is generated when Airnode is deployed. You can see the URLs including the secret `UUID` path parameter, displayed on your terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/next/docker/). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for the gateway, which is exposed on the host machine. -Doing so will make the gateway API accessible like a regular web server running -on the machine. Note the `PORT` which is exposed as part of the Airnode client -container. See the -[Airnode client usage](/reference/airnode/next/docker/client-image.md#usage) for -more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for the gateway, which is exposed on the host machine. Doing so will make the gateway API accessible like a regular web server running on the machine. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/next/docker/client-image.md#usage) for more details. -- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - - Gateway URL for the OEV Gateway +- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - Gateway URL for the OEV Gateway ## Usage -In order to execute the processing on the gateway, it needs to receive a -properly constructed HTTP request: +In order to execute the processing on the gateway, it needs to receive a properly constructed HTTP request: - It must be a `POST` request - It must contain a `Content-Type` header, set to `application/json`. @@ -134,8 +107,7 @@ where: - `updateId` - Auction update ID. - `bidderAddress` - Blockchain address of the winning searcher. - `bidAmount` - Bid amount that won the auction. -- `beacons` - A list of beacon data to be signed. It can contain two types: full - beacon data, only beacon metadata +- `beacons` - A list of beacon data to be signed. It can contain two types: full beacon data, only beacon metadata - `airnodeAddress` - Airnode address identifying a beacon - `templateId` - Template ID identifying a beacon - `signedData` - The signed beacon data received from signed data gateway. @@ -177,8 +149,6 @@ curl --location '' \ ] ``` -The gateway will return a list of signatures. There is a signature for each -beacon within the data feed that is served by the given Airnode, returned in the -same order as they are specified in the request body. +The gateway will return a list of signatures. There is a signature for each beacon within the data feed that is served by the given Airnode, returned in the same order as they are specified in the request body. diff --git a/docs/reference/airnode/next/understand/using-authorizations.md b/docs/reference/airnode/next/understand/using-authorizations.md index c73e8b6a..94d161db 100644 --- a/docs/reference/airnode/next/understand/using-authorizations.md +++ b/docs/reference/airnode/next/understand/using-authorizations.md @@ -19,38 +19,22 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using -[Authorizations](/reference/airnode/next/concepts/authorizations.md). This -method is off-chain and requires no blockchain knowledge by an API provider. It -is different than [Authorizers](/reference/airnode/next/concepts/authorizers.md) -which is an on-chain auth scheme. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizations](/reference/airnode/next/concepts/authorizations.md). This method is off-chain and requires no blockchain knowledge by an API provider. It is different than [Authorizers](/reference/airnode/next/concepts/authorizers.md) which is an on-chain auth scheme. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/next/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: -Authorizations use scheme types that hard-code access to an Airnode's endpoints -in the same file that defines the Airnode, its `config.json` file. These -hard-coded values are endpointId/address pairs that the Airnode will use to -allow access to its endpoints by requesters (smart contracts). +Authorizations use scheme types that hard-code access to an Airnode's endpoints in the same file that defines the Airnode, its `config.json` file. These hard-coded values are endpointId/address pairs that the Airnode will use to allow access to its endpoints by requesters (smart contracts). -Nothing in _authorizers_ can supersede permissions granted by _authorizations_ -as the latter takes precedence. -Currently there is only one _authorizations_ scheme type, -`requesterEndpointAuthorizations`. +Nothing in _authorizers_ can supersede permissions granted by _authorizations_ as the latter takes precedence. +Currently there is only one _authorizations_ scheme type, `requesterEndpointAuthorizations`. ## requesterEndpointAuthorizations -Currently `requesterEndpointAuthorizations` is the only scheme type available -for _authorizations_. It defines a list of endpointIds each with a array of -requester addresses that can access them. +Currently `requesterEndpointAuthorizations` is the only scheme type available for _authorizations_. It defines a list of endpointIds each with a array of requester addresses that can access them. ```json { diff --git a/docs/reference/airnode/next/versions.md b/docs/reference/airnode/next/versions.md index 0ef8993f..ea3d15e9 100644 --- a/docs/reference/airnode/next/versions.md +++ b/docs/reference/airnode/next/versions.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The latest version of Airnode is `v0.15.x`. See -[releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for -all Airnode versions. Below is a list of Airnode versions included in this -documentation website. Each can be accessed via the Airnode selector at the top -of the left sidebar under Reference. +The latest version of Airnode is `v0.15.x`. See [releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for all Airnode versions. Below is a list of Airnode versions included in this documentation website. Each can be accessed via the Airnode selector at the top of the left sidebar under Reference. | | | ------- | @@ -35,9 +31,7 @@ of the left sidebar under Reference. ## Other Versions -Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their -documentation is available at -[https://old-docs.api3.org](https://old-docs.api3.org). +Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their documentation is available at [https://old-docs.api3.org](https://old-docs.api3.org). | | | --------------------------------------------------------- | diff --git a/docs/reference/airnode/v0.11/chain-idiosyncrasies.md b/docs/reference/airnode/v0.11/chain-idiosyncrasies.md index 1683f584..712698f2 100644 --- a/docs/reference/airnode/v0.11/chain-idiosyncrasies.md +++ b/docs/reference/airnode/v0.11/chain-idiosyncrasies.md @@ -19,56 +19,28 @@ tags: # {{$frontmatter.title}} -Differences in chain design inevitably lead to some unique chain-specific -considerations. Below are idiosyncrasies we have identified, though it may not -be comprehensive and we are interested in hearing if you encounter others. +Differences in chain design inevitably lead to some unique chain-specific considerations. Below are idiosyncrasies we have identified, though it may not be comprehensive and we are interested in hearing if you encounter others. ## config.json - `chains` field -The idiosyncrasies below relate to the `chains` field of `config.json` discussed -in -[Configuring Airnode](/reference/airnode/v0.11/understand/configuring.md#chains) -and -[Deployment Files](/reference/airnode/v0.11/deployment-files/config-json.md#chains) -section. +The idiosyncrasies below relate to the `chains` field of `config.json` discussed in [Configuring Airnode](/reference/airnode/v0.11/understand/configuring.md#chains) and [Deployment Files](/reference/airnode/v0.11/deployment-files/config-json.md#chains) section. ### Avalanche -Gas prices on Avalanche mainnet are often underestimated when getting `type 0` -estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error -manifests as the `maxFeePerGas` being set to less than the block -`baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set -`recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. +Gas prices on Avalanche mainnet are often underestimated when getting `type 0` estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error manifests as the `maxFeePerGas` being set to less than the block `baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set `recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. ### Arbitrum -Execution costs on Arbitrum are calculated slightly differently than Ethereum, -which impacts the gas required to fulfill requests. To account for this, it is -recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when -using both Arbitrum mainnet and testnet. Read more about -[ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. +Execution costs on Arbitrum are calculated slightly differently than Ethereum, which impacts the gas required to fulfill requests. To account for this, it is recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when using both Arbitrum mainnet and testnet. Read more about [ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. ### Metis -On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is -recommended to use a `fulfillmentGasLimit` of at least `5000000`. +On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is recommended to use a `fulfillmentGasLimit` of at least `5000000`. ### Optimism -Using `type 0` transaction types is recommended over `type 2` so the use of -`providerRecommendedEip1559GasPrice` is discouraged. - -As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, -which are -[accounted for separately](https://docs.optimism.io/stack/transactions/fees)). -To cover the L1 data fee when a sponsor requests a -[withdrawal](/reference/airnode/v0.11/concepts/sponsor.md#withdrawals), an -amount has to be subtracted from the funds returned to the sponsor. The -`withdrawalRemainder` parameter has been introduced specifically for this -reason, though the value required will differ between Optimism mainnet and -testnet due to differences in L1 gas fees. For Optimism testnet, a -`withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a -value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover -an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. +Using `type 0` transaction types is recommended over `type 2` so the use of `providerRecommendedEip1559GasPrice` is discouraged. + +As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, which are [accounted for separately](https://docs.optimism.io/stack/transactions/fees)). To cover the L1 data fee when a sponsor requests a [withdrawal](/reference/airnode/v0.11/concepts/sponsor.md#withdrawals), an amount has to be subtracted from the funds returned to the sponsor. The `withdrawalRemainder` parameter has been introduced specifically for this reason, though the value required will differ between Optimism mainnet and testnet due to differences in L1 gas fees. For Optimism testnet, a `withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. diff --git a/docs/reference/airnode/v0.11/cloud-resources.md b/docs/reference/airnode/v0.11/cloud-resources.md index d42019ab..6689a19c 100644 --- a/docs/reference/airnode/v0.11/cloud-resources.md +++ b/docs/reference/airnode/v0.11/cloud-resources.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain -resources to fully operate and supports most regions. +When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain resources to fully operate and supports most regions. ## Resources diff --git a/docs/reference/airnode/v0.11/concepts/airnode-auth.md b/docs/reference/airnode/v0.11/concepts/airnode-auth.md index eadc8c86..3d3d184d 100644 --- a/docs/reference/airnode/v0.11/concepts/airnode-auth.md +++ b/docs/reference/airnode/v0.11/concepts/airnode-auth.md @@ -19,40 +19,24 @@ tags: # {{$frontmatter.title}} -API providers can instruct Airnode to authenticate requests to their endpoints. -This is done by setting up a security scheme in the config.json file for their -Airnode. Airnode supports three methods of authentication from the OpenAPI -specification. +API providers can instruct Airnode to authenticate requests to their endpoints. This is done by setting up a security scheme in the config.json file for their Airnode. Airnode supports three methods of authentication from the OpenAPI specification. > -[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) -uses the term **security scheme** for authentication and authorization schemes. -Airnode only uses standard OAS defined authentication schemes to identify itself -to API endpoints. Airnode supports two types of authentication, `http` and -`apiKey`. +[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) uses the term **security scheme** for authentication and authorization schemes. Airnode only uses standard OAS defined authentication schemes to identify itself to API endpoints. Airnode supports two types of authentication, `http` and `apiKey`. -- HTTP authentication schemes (using the `Authorization` header) supported by - Airnode: +- HTTP authentication schemes (using the `Authorization` header) supported by Airnode: - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) - [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) -- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in - the request header, cookie in header or query string +- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in the request header, cookie in header or query string -How Airnode sends the authentication data is explained in the sections **Basic, -Bearer and API Key** below. +How Airnode sends the authentication data is explained in the sections **Basic, Bearer and API Key** below. ## Basic -Basic authentication is a simple authentication scheme built into the HTTP -protocol. The Authorization request header contains the Base64-encoded username -and password, separated by a colon. When handling the request, the server -decodes the login details and checks if the user can access the requested -content. +Basic authentication is a simple authentication scheme built into the HTTP protocol. The Authorization request header contains the Base64-encoded username and password, separated by a colon. When handling the request, the server decodes the login details and checks if the user can access the requested content. -The header field is in the form of `Authorization: Basic ` where -`credentials` is the Base64 encoding of a username and password joined by a -single colon (`airnode:airnode-password`). +The header field is in the form of `Authorization: Basic ` where `credentials` is the Base64 encoding of a username and password joined by a single colon (`airnode:airnode-password`). `Authorization: Basic ` @@ -63,10 +47,7 @@ curl -H "Authorization: Basic YW5kZXJzb25AZ21haWwuY29tOjEyM215cGFzc3dvcmQ=" \ ## Bearer -Bearer authentication (also called token authentication) is an HTTP -authentication scheme that involves security tokens called bearer tokens. The -API provider supplies a token used by Airnode to authenticate itself to API -endpoints. +Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The API provider supplies a token used by Airnode to authenticate itself to API endpoints. The header field is in the form of `Authorization: Bearer `. @@ -77,9 +58,7 @@ curl -H "Authorization: Bearer RZ8Y65TG" \ ## API Key -Some APIs use an `apiKey` for authentication. The API provider supplies an -`apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can -send the `apiKey` three ways. +Some APIs use an `apiKey` for authentication. The API provider supplies an `apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can send the `apiKey` three ways. ```sh # In the query string. diff --git a/docs/reference/airnode/v0.11/concepts/airnode.md b/docs/reference/airnode/v0.11/concepts/airnode.md index e7e93079..a4cf80ba 100644 --- a/docs/reference/airnode/v0.11/concepts/airnode.md +++ b/docs/reference/airnode/v0.11/concepts/airnode.md @@ -19,37 +19,17 @@ tags: # {{$frontmatter.title}} -Airnode is a serverless oracle node implemented with a "set and forget" -philosophy. Airnode is flexible in that it can move API provider data on-chain -for multiple purposes. The most important of which are data feeds -([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in -response to dApp direct requests for API provider data -([RRP](/reference/airnode/v0.11/developers/)). +Airnode is a serverless oracle node implemented with a "set and forget" philosophy. Airnode is flexible in that it can move API provider data on-chain for multiple purposes. The most important of which are data feeds ([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in response to dApp direct requests for API provider data ([RRP](/reference/airnode/v0.11/developers/)). ## Airnode sources data to dAPIs -An Airnode supplies API provider data to beacons from API providers. These -beacons are the underlying data source for data feeds known as dAPIs. +An Airnode supplies API provider data to beacons from API providers. These beacons are the underlying data source for data feeds known as dAPIs. -API providers, owners of first-party Airnodes, store data feed values on-chain -as individual beacons that in are turn sourced by the -[Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) -contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). -Airnode has an internal mechanism that looks for a deviation in the value of API -provider's API operations. This mechanism updates beacons on-chain as needed. +API providers, owners of first-party Airnodes, store data feed values on-chain as individual beacons that in are turn sourced by the [Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). Airnode has an internal mechanism that looks for a deviation in the value of API provider's API operations. This mechanism updates beacons on-chain as needed. ## Airnode processes RRP requests -An Airnode is capable of serving the data from one or more APIs directly to -[requesters](/reference/airnode/v0.11/concepts/requester.md) (which are on-chain -smart contracts) that request data served by a particular Airnode. This is done -using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 -protocol is designed to be flexible and is meant to serve a variety of use -cases. See the the -[Calling Airnode (RRP)](/reference/airnode/v0.11/developers/index.md) for more -details on how an RRP request is made. Also see the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/contracts) -for potential design patterns. +An Airnode is capable of serving the data from one or more APIs directly to [requesters](/reference/airnode/v0.11/concepts/requester.md) (which are on-chain smart contracts) that request data served by a particular Airnode. This is done using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 protocol is designed to be flexible and is meant to serve a variety of use cases. See the the [Calling Airnode (RRP)](/reference/airnode/v0.11/developers/index.md) for more details on how an RRP request is made. Also see the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/contracts) for potential design patterns. diff --git a/docs/reference/airnode/v0.11/deployment-files/templates/aws-env.md b/docs/reference/airnode/v0.11/deployment-files/templates/aws-env.md index e788a927..d15b55fd 100644 --- a/docs/reference/airnode/v0.11/deployment-files/templates/aws-env.md +++ b/docs/reference/airnode/v0.11/deployment-files/templates/aws-env.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -The `aws.env` contains AWS credentials from an IAM user. These credentials are -used by the Docker -[deployer image](/reference/airnode/v0.11/docker/deployer-image.md) to deploy an -Airnode to AWS. For more details, see the full description of the -[aws.env](/reference/airnode/v0.11/deployment-files/templates/aws-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `aws.env` contains AWS credentials from an IAM user. These credentials are used by the Docker [deployer image](/reference/airnode/v0.11/docker/deployer-image.md) to deploy an Airnode to AWS. For more details, see the full description of the [aws.env](/reference/airnode/v0.11/deployment-files/templates/aws-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AWS_ACCESS_KEY_ID= diff --git a/docs/reference/airnode/v0.11/deployment-files/templates/config-json.md b/docs/reference/airnode/v0.11/deployment-files/templates/config-json.md index 8b750361..baa5088d 100644 --- a/docs/reference/airnode/v0.11/deployment-files/templates/config-json.md +++ b/docs/reference/airnode/v0.11/deployment-files/templates/config-json.md @@ -19,33 +19,23 @@ tags: # {{$frontmatter.title}} -A template for an Airnode's configuration file. Below are notations to help -explain contents of the template. +A template for an Airnode's configuration file. Below are notations to help explain contents of the template. -- `, , `: The value added is independent from - other fields and a value is needed unless otherwise indicated. These values - are not considered secret unless you want them to be. +- `, , `: The value added is independent from other fields and a value is needed unless otherwise indicated. These values are not considered secret unless you want them to be. -- ``: If two fields contain the same - expression, use the same value in them because they are referencing each - other. Usually these are not considered to be secret. +- ``: If two fields contain the same expression, use the same value in them because they are referencing each other. Usually these are not considered to be secret. -- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to - `secrets.env` though it is not required. +- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to `secrets.env` though it is not required. Consider the following relationships. - `ois[0].title` is related to `triggers.rrp[0].oisTitle`. -- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to - ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in -- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to - ois[0].endpoints[0].parameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to ois[0].endpoints[0].parameters[0].operationParameter.in -See -[config.json](/reference/airnode/v0.11/deployment-files/templates/config-json.md) -as a reference while building a config.json file. +See [config.json](/reference/airnode/v0.11/deployment-files/templates/config-json.md) as a reference while building a config.json file. ```json { diff --git a/docs/reference/airnode/v0.11/deployment-files/templates/ois-json.md b/docs/reference/airnode/v0.11/deployment-files/templates/ois-json.md index 7ee522d2..9db50510 100644 --- a/docs/reference/airnode/v0.11/deployment-files/templates/ois-json.md +++ b/docs/reference/airnode/v0.11/deployment-files/templates/ois-json.md @@ -19,11 +19,6 @@ tags: # {{$frontmatter.title}} -An [OIS (Oracle Integration Specifications)](/reference/ois/2.1/) JSON object is -part of an Airnode's -[config.json](/reference/airnode/v0.11/deployment-files/templates/config-json.md) -file. There can be more than one OIS object in the `config.json` file that -defines an Airnode. See the [OIS Template](/reference/ois/2.1/template.md) in -the OIS document set. +An [OIS (Oracle Integration Specifications)](/reference/ois/2.1/) JSON object is part of an Airnode's [config.json](/reference/airnode/v0.11/deployment-files/templates/config-json.md) file. There can be more than one OIS object in the `config.json` file that defines an Airnode. See the [OIS Template](/reference/ois/2.1/template.md) in the OIS document set. diff --git a/docs/reference/airnode/v0.11/deployment-files/templates/secrets-env.md b/docs/reference/airnode/v0.11/deployment-files/templates/secrets-env.md index e27a208c..c3ad2a2b 100644 --- a/docs/reference/airnode/v0.11/deployment-files/templates/secrets-env.md +++ b/docs/reference/airnode/v0.11/deployment-files/templates/secrets-env.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The `secrets.env` contains the secrets that the respective Airnode deployments -will need. All variables defined in a `secrets.env` can be interpolated inside -`config.json`. For more details, see the full description of the -[secrets.env](/reference/airnode/v0.11/deployment-files/secrets-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `secrets.env` contains the secrets that the respective Airnode deployments will need. All variables defined in a `secrets.env` can be interpolated inside `config.json`. For more details, see the full description of the [secrets.env](/reference/airnode/v0.11/deployment-files/secrets-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AIRNODE_WALLET_MNEMONIC="" diff --git a/docs/reference/airnode/v0.11/developers/fees.md b/docs/reference/airnode/v0.11/developers/fees.md index c4be5acc..a5c01c87 100644 --- a/docs/reference/airnode/v0.11/developers/fees.md +++ b/docs/reference/airnode/v0.11/developers/fees.md @@ -19,18 +19,11 @@ tags: # {{$frontmatter.title}} -There are some one-time setup/maintenance costs and some ongoing costs of -calling an Airnode. The Airnode protocol is designed in a way that the requester -assumes all gas costs, including the request fulfillment (response) -transactions. +There are some one-time setup/maintenance costs and some ongoing costs of calling an Airnode. The Airnode protocol is designed in a way that the requester assumes all gas costs, including the request fulfillment (response) transactions. ## Sponsors -Fees are encountered when a sponsor engages in setup activity such as sponsoring -a requester. These are per call transaction gas costs and are relatively small. -The funds come from the wallet mnemonic that the sponsor supplies when calling -certain [admin commands](/reference/airnode/v0.11/packages/admin-cli.md) as -shown below. +Fees are encountered when a sponsor engages in setup activity such as sponsoring a requester. These are per call transaction gas costs and are relatively small. The funds come from the wallet mnemonic that the sponsor supplies when calling certain [admin commands](/reference/airnode/v0.11/packages/admin-cli.md) as shown below. - [sponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#unsponsor-requester) @@ -39,32 +32,18 @@ shown below. ## Airnodes -The fees take the form of transaction gas costs. These are applied when funding -a requester's sponsor wallet for an Airnode and when executing the Airnode in -response to a request. +The fees take the form of transaction gas costs. These are applied when funding a requester's sponsor wallet for an Airnode and when executing the Airnode in response to a request. -- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is - funded manually by a sponsor using their preferred wallet management tool such - as MetaMask. +- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is funded manually by a sponsor using their preferred wallet management tool such as MetaMask. -- [Calling](/reference/airnode/v0.11/developers/index.md) an Airnode: - Transaction gas fees are withdrawn from the sponsor wallet related to the - Airnode being called by a sponsored requester. +- [Calling](/reference/airnode/v0.11/developers/index.md) an Airnode: Transaction gas fees are withdrawn from the sponsor wallet related to the Airnode being called by a sponsored requester. -Learn more about [sponsor wallets](/reference/airnode/v0.11/concepts/sponsor.md) -in the reference section. +Learn more about [sponsor wallets](/reference/airnode/v0.11/concepts/sponsor.md) in the reference section. ## API Provider Fees -Some API providers charge a subscription fee for access to their data. This is a -typical practice and usually requires the requester to create an account on the -provider's website and then subscribe to a level of service offered. These types -of services are usually billed monthly and can be based on an annual rate to -save costs. The subscription (even if free) will most likely involve the use of -a security scheme such as an API key that must be used to access the data. See -[Calling an Airnode](/reference/airnode/v0.11/developers/index.md) to learn more -on how to pass the security credentials to an Airnode. +Some API providers charge a subscription fee for access to their data. This is a typical practice and usually requires the requester to create an account on the provider's website and then subscribe to a level of service offered. These types of services are usually billed monthly and can be based on an annual rate to save costs. The subscription (even if free) will most likely involve the use of a security scheme such as an API key that must be used to access the data. See [Calling an Airnode](/reference/airnode/v0.11/developers/index.md) to learn more on how to pass the security credentials to an Airnode. diff --git a/docs/reference/airnode/v0.11/developers/index.md b/docs/reference/airnode/v0.11/developers/index.md index 7880a76e..cf134ab9 100644 --- a/docs/reference/airnode/v0.11/developers/index.md +++ b/docs/reference/airnode/v0.11/developers/index.md @@ -19,47 +19,22 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that can push off-chain API data to an on-chain -contract. While dApp developers will find -[dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the -most useful aspect of an Airnode's capabilities, there is the option for -developers to access Airnode data using its request-response protocol (RRP). The -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/master/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract facilitates RRP and is designed to be flexible and is meant to -serve a variety of use cases. See the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/contracts) -for potential design patterns. +Airnode is a first-party oracle that can push off-chain API data to an on-chain contract. While dApp developers will find [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the most useful aspect of an Airnode's capabilities, there is the option for developers to access Airnode data using its request-response protocol (RRP). The [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/master/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract facilitates RRP and is designed to be flexible and is meant to serve a variety of use cases. See the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/contracts) for potential design patterns. ## It starts with a requester -A requester is a smart contract that can trigger an Airnode RRP request. To do -so, the requester needs to be sponsored and make the request using a matching -sponsor wallet. See -[Requesters and Sponsors](/reference/airnode/v0.11/developers/requesters-sponsors.md) -on how to sponsor a requester and derive the sponsor wallet. +A requester is a smart contract that can trigger an Airnode RRP request. To do so, the requester needs to be sponsored and make the request using a matching sponsor wallet. See [Requesters and Sponsors](/reference/airnode/v0.11/developers/requesters-sponsors.md) on how to sponsor a requester and derive the sponsor wallet. ## A simplified understanding -In the diagram below, any typical smart contract is called a requester if it -makes a request of Airnode's RRP protocol. It makes a request to the on-chain -RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event -logs. The off-chain Airnode then accesses the event logs, gets the API data and -performs a callback to the requester. +In the diagram below, any typical smart contract is called a requester if it makes a request of Airnode's RRP protocol. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event logs. The off-chain Airnode then accesses the event logs, gets the API data and performs a callback to the requester. In summary, the requester will do two things. -- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol - contract, which returns a - [`requestId`](/reference/airnode/v0.11/concepts/request.md#requestid). -- Add a `myFulfill()` function (call it what you like) to your requester where - the off-chain Airnode can send the requested data when ready. The data - includes the same `requestId` as the one returned at the time of making the - request. +- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol contract, which returns a [`requestId`](/reference/airnode/v0.11/concepts/request.md#requestid). +- Add a `myFulfill()` function (call it what you like) to your requester where the off-chain Airnode can send the requested data when ready. The data includes the same `requestId` as the one returned at the time of making the request. -In the diagram below a requester makes a request to the on-chain RRP protocol -contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its -run cycle the off-chain Airnode accesses the event logs, gets the requested data -from the the API provider, then performs a callback to the requester. +In the diagram below a requester makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its run cycle the off-chain Airnode accesses the event logs, gets the requested data from the the API provider, then performs a callback to the requester. > > @@ -68,19 +43,13 @@ from the the API provider, then performs a callback to the requester. > 3.

Airnode gathers response data from the API specified in the request.

> 4.

Airnode performs a callback to a named function myFulfill() in myContract.sol via the AirnodeRrpV0.sol function fulfill() with the requested data and the requestId.

-See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn -how to make a RRP request of an Airnode. +See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn how to make a RRP request of an Airnode. ## A deeper dive -This section, through its detailed illustration, builds on the previous section -([A simplified understanding](/reference/airnode/v0.11/developers/index.md#a-simplified-understanding)) -in an attempt to further illustrate and explain the mechanics of how an Airnode -response to a request made by a requester. +This section, through its detailed illustration, builds on the previous section ([A simplified understanding](/reference/airnode/v0.11/developers/index.md#a-simplified-understanding)) in an attempt to further illustrate and explain the mechanics of how an Airnode response to a request made by a requester. -Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") -deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain -**protocol contract** AirnodeRrpV0.sol. +Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain **protocol contract** AirnodeRrpV0.sol. > > diff --git a/docs/reference/airnode/v0.11/developers/requesters-sponsors.md b/docs/reference/airnode/v0.11/developers/requesters-sponsors.md index a5906243..36ea15b9 100644 --- a/docs/reference/airnode/v0.11/developers/requesters-sponsors.md +++ b/docs/reference/airnode/v0.11/developers/requesters-sponsors.md @@ -19,143 +19,80 @@ tags: # {{$frontmatter.title}} -As a dApp developer it helps to understand what a **requester** is and what a -**sponsor** does. They are both important parts of the Airnode ecosystem. This -doc will further define them and walk you through the process of sponsoring a -requester and deriving a sponsor wallet using the admin CLI commands. +As a dApp developer it helps to understand what a **requester** is and what a **sponsor** does. They are both important parts of the Airnode ecosystem. This doc will further define them and walk you through the process of sponsoring a requester and deriving a sponsor wallet using the admin CLI commands. ## What is a Requester? -The term [requester](/reference/airnode/v0.11/concepts/requester.md) is -important to remember. When requester is mentioned, the reference is to your -smart contract that makes a request of an Airnode. +The term [requester](/reference/airnode/v0.11/concepts/requester.md) is important to remember. When requester is mentioned, the reference is to your smart contract that makes a request of an Airnode. > -As an example see the `myContract.sol` contract in the diagram within the -[Overview](/reference/airnode/v0.11/concepts/) doc, it is a requester. +As an example see the `myContract.sol` contract in the diagram within the [Overview](/reference/airnode/v0.11/concepts/) doc, it is a requester. ## What is a Sponsor? -Equally important is the term -[sponsor](/reference/airnode/v0.11/concepts/sponsor.md). A sponsor is an entity -such as yourself, an organization, etc. Sponsors create relationships between -requesters and Airnodes. +Equally important is the term [sponsor](/reference/airnode/v0.11/concepts/sponsor.md). A sponsor is an entity such as yourself, an organization, etc. Sponsors create relationships between requesters and Airnodes. ### Sponsor's Requester/Airnode Relationships -As a sponsor you will use the public address from an account within a mnemonic -you own to "**sponsor a requester**" and then use the public address (known as a -[sponsorAddress](/reference/airnode/v0.11/concepts/sponsor.md#sponsoraddress)) -to "**derive a -[sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet)**" -for an Airnode. This action creates a relationship between a sponsor's requester -and a particular Airnode. You do this because a sponsor is the entity that pays -for the fulfillment of a request, the gas costs the Airnode will incur. These -costs will be withdrawn from the `sponsorWallet` of the Airnode when the -requester calls it. +As a sponsor you will use the public address from an account within a mnemonic you own to "**sponsor a requester**" and then use the public address (known as a [sponsorAddress](/reference/airnode/v0.11/concepts/sponsor.md#sponsoraddress)) to "**derive a [sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet)**" for an Airnode. This action creates a relationship between a sponsor's requester and a particular Airnode. You do this because a sponsor is the entity that pays for the fulfillment of a request, the gas costs the Airnode will incur. These costs will be withdrawn from the `sponsorWallet` of the Airnode when the requester calls it. ::: info sponsorAddress -A [sponsorAddress](/reference/airnode/v0.11/concepts/sponsor.md#sponsoraddress) -is a public address of an account from a mnemonic, usually the default account. -Rather than the default account another account from the mnemonic can be used. -The `sponsorAddress` is used to uniquely identify a sponsor. +A [sponsorAddress](/reference/airnode/v0.11/concepts/sponsor.md#sponsoraddress) is a public address of an account from a mnemonic, usually the default account. Rather than the default account another account from the mnemonic can be used. The `sponsorAddress` is used to uniquely identify a sponsor. ::: -1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester - with the Admin CLI. The CLI will use the default address of the mnemonic - passed as the `sponsorAddress` for the sponsorship unless another account is - specified. +1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester with the Admin CLI. The CLI will use the default address of the mnemonic passed as the `sponsorAddress` for the sponsorship unless another account is specified. -2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the - `sponsorAddress`. +2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the `sponsorAddress`. 3. The requester can now make requests of the Airnode. > -In the above diagram it is possible to use the same sponsorAddress -`(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is -possible to sponsor more than one requester with the same `sponsorAddress`. -However it is important to remember that all requesters can now access all the -Airnodes regardless if they need to. There is no harm in this scenario. +In the above diagram it is possible to use the same sponsorAddress `(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is possible to sponsor more than one requester with the same `sponsorAddress`. However it is important to remember that all requesters can now access all the Airnodes regardless if they need to. There is no harm in this scenario. ### Advanced Scenarios - **Two requesters, one Airnode, one sponsorWallet**: - Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) - would access the same Airnode using a single sponsorWallet derived by the - `sponsorAddress`. + Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) would access the same Airnode using a single sponsorWallet derived by the `sponsorAddress`. - **Two requesters, one Airnode, two sponsorWallets**: - Sponsor two different requesters each with a different `sponsorAddress` (e.g., - `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you - can derive two separate sponsorWallets for the same Airnode. Now each - requester will deplete funds from a separate Airnode sponsorWallet when using - the Airnode. + Sponsor two different requesters each with a different `sponsorAddress` (e.g., `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you can derive two separate sponsorWallets for the same Airnode. Now each requester will deplete funds from a separate Airnode sponsorWallet when using the Airnode. - **One requester, two Airnodes, two sponsorWallets**: - A requester can make requests from two different Airnodes. Sponsor the - requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of - two the Airnodes, using the `sponsorAddress`. Despite the fact that the - sponsorWallet for each Airnode was derived with the same `sponsorAddress` the - sponsorWallets are different since they are derived using the airnode's xpub - plus the `sponsorAddress`. The sponsor must fund both wallets separately using - the unique `sponsorWallet` address of the two sponsorWallets. + A requester can make requests from two different Airnodes. Sponsor the requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of two the Airnodes, using the `sponsorAddress`. Despite the fact that the sponsorWallet for each Airnode was derived with the same `sponsorAddress` the sponsorWallets are different since they are derived using the airnode's xpub plus the `sponsorAddress`. The sponsor must fund both wallets separately using the unique `sponsorWallet` address of the two sponsorWallets. ### Things to Remember -When you sponsor a requester with a `sponsorAddress` you are giving it -permission to use the sponsorWallet (associated with a Airnode) that was derived -using the same `sponsorAddress`. +When you sponsor a requester with a `sponsorAddress` you are giving it permission to use the sponsorWallet (associated with a Airnode) that was derived using the same `sponsorAddress`. -When the requester makes a request to the Airnode, the Airnode will use funds -from the corresponding sponsorWallet to pay gas costs in response to the -request. Therefore the sponsor pays for the fulfillment of the request. +When the requester makes a request to the Airnode, the Airnode will use funds from the corresponding sponsorWallet to pay gas costs in response to the request. Therefore the sponsor pays for the fulfillment of the request. -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/v0.11/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/v0.11/developers/fees.md#api-provider-fees). ## Admin CLI Commands -There are several sponsor and requester related commands in the -[Admin CLI Commands](/reference/airnode/v0.11/packages/admin-cli.md) package. -You can also see a list of available commands using -`npx @api3/airnode-admin --help`. +There are several sponsor and requester related commands in the [Admin CLI Commands](/reference/airnode/v0.11/packages/admin-cli.md) package. You can also see a list of available commands using `npx @api3/airnode-admin --help`. -In the next two sections of this doc you will use two commands from the -`@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor -wallet_. +In the next two sections of this doc you will use two commands from the `@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor wallet_. -1. [sponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#sponsor-requester) - sponsors a requester. -2. [derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address)creates - a sponsor wallet associated with an Airnode. +1. [sponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#sponsor-requester) sponsors a requester. +2. [derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address)creates a sponsor wallet associated with an Airnode. ## How to Sponsor a Requester -To sponsor a requester execute the `sponsor-requester` command using the -parameters detailed in the list below. Your requester should already be deployed -on-chain. This command has transaction gas costs. +To sponsor a requester execute the `sponsor-requester` command using the parameters detailed in the list below. Your requester should already be deployed on-chain. This command has transaction gas costs. -- `providerURL`: A blockchain provider URL (such as Infura) with providerID for - the desired network. -- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to - derive the sponsorAddress from the default address. The sponsorAddress will be - needed to derive a sponsorWallet for an Airnode. +- `providerURL`: A blockchain provider URL (such as Infura) with providerID for the desired network. +- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to derive the sponsorAddress from the default address. The sponsorAddress will be needed to derive a sponsorWallet for an Airnode. - `requester-address`: Address of the requester contract. -- `derivation-path (optional)` (_not used in the example below_): Selects an - alternate account to use from the mnemonic rather than the default account. +- `derivation-path (optional)` (_not used in the example below_): Selects an alternate account to use from the mnemonic rather than the default account. -Executing the command -[sponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#sponsor-requester) -will sponsor a requester and returns the requesterAddress and sponsorAddress. +Executing the command [sponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#sponsor-requester) will sponsor a requester and returns the requesterAddress and sponsorAddress. ::: code-group @@ -181,27 +118,15 @@ npx @api3/airnode-admin sponsor-requester ^ ## How to Derive a Sponsor Wallet -To use a particular Airnode you must _derive a sponsorWallet_. Once the -sponsorWallet is created it must be funded using the public address -(`sponsorWallet` address) returned by the command -`derive-sponsor-wallet-address`. Each Airnode keeps a separate list of -individual sponsorWallets that can access the Airnode. Learn more about a -[sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). +To use a particular Airnode you must _derive a sponsorWallet_. Once the sponsorWallet is created it must be funded using the public address (`sponsorWallet` address) returned by the command `derive-sponsor-wallet-address`. Each Airnode keeps a separate list of individual sponsorWallets that can access the Airnode. Learn more about a [sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). -To derive a sponsorWallet for an Airnode execute the -[derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) -command using the parameters detailed in the list below. There are no -transaction gas costs to do so. +To derive a sponsorWallet for an Airnode execute the [derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) command using the parameters detailed in the list below. There are no transaction gas costs to do so. -- `airnode-xpub`: The extended public address of the Airnode for path - m/44'/60'/0'. +- `airnode-xpub`: The extended public address of the Airnode for path m/44'/60'/0'. - `airnode-address`: The public address of the desired Airnode. -- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) - owned by a sponsor. Usually the sponsorAddress is the one returned when - sponsoring a requester. +- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) owned by a sponsor. Usually the sponsorAddress is the one returned when sponsoring a requester. -The command `derive-sponsor-wallet-address` will return the public address -(`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. +The command `derive-sponsor-wallet-address` will return the public address (`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. ::: code-group @@ -225,22 +150,15 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ::: -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/v0.11/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/v0.11/developers/fees.md#api-provider-fees). -If you forget the public address (`sponsorWallet` address) of the sponsorWallet -simply run `derive-sponsor-wallet-address` again. Since the wallet already -exists for the airnodeAddress/sponsorAddress pair it will just return the -address. +If you forget the public address (`sponsorWallet` address) of the sponsorWallet simply run `derive-sponsor-wallet-address` again. Since the wallet already exists for the airnodeAddress/sponsorAddress pair it will just return the address. ## Record Keeping -During and after sponsoring requesters and deriving a sponsorWallet there are a -few things to keep track of. +During and after sponsoring requesters and deriving a sponsorWallet there are a few things to keep track of. | Item | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -248,11 +166,6 @@ few things to keep track of. | sponsor address | The public address of an account derived from a sponsor's mnemonic when sponsoring a requester. Record which `sponsorAddress` was used to create a sponsorWallet for each Airnode. | | sponsor wallet address | Record the `sponsorWallet` address of the sponsorWallet derived for an Airnode. For each Airnode you have derived a sponsorWallet, the Airnode keeps the private key and returns the public address (`sponsorWallet` address) which is used to fund the sponsorWallet. | -You can acquire the public address (`sponsorWallet` address) of a sponsorWallet -later, if you lose it, by running the command `derive-sponsor-wallet-address` -again. Since the sponsorWallet was already created for the -`sponsorAddress/airnodeAddress` pair, the command will only return the public -address for the wallet. However you must use the same `sponsorAddress` used when -the wallet was first created or a new sponsorWallet will be created. +You can acquire the public address (`sponsorWallet` address) of a sponsorWallet later, if you lose it, by running the command `derive-sponsor-wallet-address` again. Since the sponsorWallet was already created for the `sponsorAddress/airnodeAddress` pair, the command will only return the public address for the wallet. However you must use the same `sponsorAddress` used when the wallet was first created or a new sponsorWallet will be created. diff --git a/docs/reference/airnode/v0.11/developers/using-templates.md b/docs/reference/airnode/v0.11/developers/using-templates.md index 2c2ad8ea..9ac56876 100644 --- a/docs/reference/airnode/v0.11/developers/using-templates.md +++ b/docs/reference/airnode/v0.11/developers/using-templates.md @@ -19,15 +19,7 @@ tags: # {{$frontmatter.title}} -A request to an Airnode can have many parameters. It is very common for -requester contracts (e.g., a data feed) to make repeated requests with the exact -same parameters. In such instances, it is wasteful to pass all of these -parameters repeatedly. Templates are used to hold a set of parameter values -on-chain that can be used repeatedly when calling -the`makeTemplateRequest()`function in -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). -Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester -pass`templateId`which identifies a template. +A request to an Airnode can have many parameters. It is very common for requester contracts (e.g., a data feed) to make repeated requests with the exact same parameters. In such instances, it is wasteful to pass all of these parameters repeatedly. Templates are used to hold a set of parameter values on-chain that can be used repeatedly when calling the`makeTemplateRequest()`function in [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester pass`templateId`which identifies a template. ```solidity function makeTemplateRequest( @@ -40,10 +32,7 @@ function makeTemplateRequest( ) external override returns (bytes32 requestId) { ``` -When a template is used to make a request, both the parameters encoded in -parameters of the template and parameters provided at request-time (if any) will -be used by the Airnode. In case the two include a parameter with the same name, -the one provided at request-time will be used. +When a template is used to make a request, both the parameters encoded in parameters of the template and parameters provided at request-time (if any) will be used by the Airnode. In case the two include a parameter with the same name, the one provided at request-time will be used. The structure of a template, as shown below, is simple. @@ -59,10 +48,6 @@ struct Template { } ``` -See the guide -[Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn -how to create and use a template. Also visit the -[coingecko-template](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-template) -monorepo example demonstrates template requests. +See the guide [Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn how to create and use a template. Also visit the [coingecko-template](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations/coingecko-template) monorepo example demonstrates template requests. diff --git a/docs/reference/airnode/v0.11/developers/verify-airnode-addresses.md b/docs/reference/airnode/v0.11/developers/verify-airnode-addresses.md index b00583dc..0dbb1f8c 100644 --- a/docs/reference/airnode/v0.11/developers/verify-airnode-addresses.md +++ b/docs/reference/airnode/v0.11/developers/verify-airnode-addresses.md @@ -19,18 +19,9 @@ tags: # {{$frontmatter.title}} -An Airnode is owned and operated by an API provider. Every Airnode has a unique -on-chain -[`airnodeAddress`](/reference/airnode/v0.11/concepts/airnode.md#airnodeaddress) -created and known by its API provider. API providers normally announce their -Airnode addresses in the form of a DNS `TXT` record within their DNS -registration, which also serves to prove ownership. An API provider's Airnode -address is the same for all chains. - -The key for the `TXT` record is `chainapi-verification-keys` and is an array of -Airnode addresses owned by the API provider. Below is an example of the Airnode -for -[dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). +An Airnode is owned and operated by an API provider. Every Airnode has a unique on-chain [`airnodeAddress`](/reference/airnode/v0.11/concepts/airnode.md#airnodeaddress) created and known by its API provider. API providers normally announce their Airnode addresses in the form of a DNS `TXT` record within their DNS registration, which also serves to prove ownership. An API provider's Airnode address is the same for all chains. + +The key for the `TXT` record is `chainapi-verification-keys` and is an array of Airnode addresses owned by the API provider. Below is an example of the Airnode for [dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). ![dxfeed-txt-record](../assets/images/txt-record-dxfeed.png) diff --git a/docs/reference/airnode/v0.11/docker/admin-cli-image.md b/docs/reference/airnode/v0.11/docker/admin-cli-image.md index bc3e6a3f..c0132d80 100644 --- a/docs/reference/airnode/v0.11/docker/admin-cli-image.md +++ b/docs/reference/airnode/v0.11/docker/admin-cli-image.md @@ -22,24 +22,15 @@ tags: -Use the admin CLI image as an alternative method to execute -[Admin CLI](/reference/airnode/v0.11/packages/admin-cli.md) using npx. Either -method will achieve the same results. The image forgoes downloading the admin -CLI package each time a command is executed using npx. +Use the admin CLI image as an alternative method to execute [Admin CLI](/reference/airnode/v0.11/packages/admin-cli.md) using npx. Either method will achieve the same results. The image forgoes downloading the admin CLI package each time a command is executed using npx. -If you want to build the admin CLI image from the source yourself, you can find -the -[image built instructions](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin/docker) -in the Airnode repository. +If you want to build the admin CLI image from the source yourself, you can find the [image built instructions](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin/docker) in the Airnode repository. -Additional information about the -[admin CLI image](/reference/airnode/v0.11/packages/admin-cli.md#using-docker) -is available in the admin CLI commands doc. +Additional information about the [admin CLI image](/reference/airnode/v0.11/packages/admin-cli.md#using-docker) is available in the admin CLI commands doc. ## Usage -The following example shows the difference between using the docker image versus -npx when executing the `get-sponsor-status` admin CLI command. +The following example shows the difference between using the docker image versus npx when executing the `get-sponsor-status` admin CLI command. ```sh #npx diff --git a/docs/reference/airnode/v0.11/docker/client-image.md b/docs/reference/airnode/v0.11/docker/client-image.md index 1865697c..8c83f0ce 100644 --- a/docs/reference/airnode/v0.11/docker/client-image.md +++ b/docs/reference/airnode/v0.11/docker/client-image.md @@ -19,29 +19,17 @@ tags: # {{$frontmatter.title}} -Usually the Airnode is deployed on a serverless platform using the -[deployer](/reference/airnode/v0.11/docker/deployer-image.md). However, there is -another option which is to run the Airnode in a docker container on your machine -locally, on premise or cloud hosted. +Usually the Airnode is deployed on a serverless platform using the [deployer](/reference/airnode/v0.11/docker/deployer-image.md). However, there is another option which is to run the Airnode in a docker container on your machine locally, on premise or cloud hosted. -A docker client image has been published on -[Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build -the container from the source yourself, you can find the image and built -instructions in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-node/docker). +A docker client image has been published on [Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build the container from the source yourself, you can find the image and built instructions in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-node/docker). ## Configuration -The Airnode needs two configuration files for its run: `config.json` and -`secrets.env`. These files need to be passed to the Docker container via -volumes. +The Airnode needs two configuration files for its run: `config.json` and `secrets.env`. These files need to be passed to the Docker container via volumes. -The Docker container looks for configuration files mounted internally in the -`/app/config` directory. +The Docker container looks for configuration files mounted internally in the `/app/config` directory. -Your current working directory should contain the configuration files above and -you bind it to the `/app/config` directory for the docker using the `--volume` -parameter. +Your current working directory should contain the configuration files above and you bind it to the `/app/config` directory for the docker using the `--volume` parameter. ::: code-group @@ -73,8 +61,7 @@ $ docker run --volume %cd%:/config:/app/config ... ## Usage -Example directory structure and commands for running the Airnode Docker -container. The below commands are run from the depicted directory. +Example directory structure and commands for running the Airnode Docker container. The below commands are run from the depicted directory. ### Running Airnode @@ -105,18 +92,11 @@ docker run ^ ::: -> If you want to connect Airnode to a blockchain running on localhost, you need -> to make the blockchain accessible from within the docker itself. If you use -> docker for linux you can use `--network="host"` parameter. If you are using -> Docker Desktop (on any platform), connect to -> `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See -> [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). +> If you want to connect Airnode to a blockchain running on localhost, you need to make the blockchain accessible from within the docker itself. If you use docker for linux you can use `--network="host"` parameter. If you are using Docker Desktop (on any platform), connect to `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). ### Checking Airnode logs -Logs will be output to the console after running the above command. If you -decide to run Airnode in detached mode with `--detach`, you need to use the -`logs` command, optionally with `--follow`, to access the logs. +Logs will be output to the console after running the above command. If you decide to run Airnode in detached mode with `--detach`, you need to use the `logs` command, optionally with `--follow`, to access the logs. ```bash docker logs airnode diff --git a/docs/reference/airnode/v0.11/docker/deployer-image.md b/docs/reference/airnode/v0.11/docker/deployer-image.md index fbc116ca..f025977c 100644 --- a/docs/reference/airnode/v0.11/docker/deployer-image.md +++ b/docs/reference/airnode/v0.11/docker/deployer-image.md @@ -19,26 +19,17 @@ tags: # {{$frontmatter.title}} -Use the deployer image to deploy or remove an Airnode with a cloud provider such -as AWS. The simplest way is to use the pre-built packages. If you would rather -build the images yourself see the -[README](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer/docker) -in the deployer package. +Use the deployer image to deploy or remove an Airnode with a cloud provider such as AWS. The simplest way is to use the pre-built packages. If you would rather build the images yourself see the [README](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer/docker) in the deployer package. ::: info Quick Deploy Demos -See the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -guides to quickly deploy and remove a preconfigured Airnode using the deployer -image. +See the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guides to quickly deploy and remove a preconfigured Airnode using the deployer image. ::: ## Configuration Files -The files `config.json` and `secrets.env` are used to configure the Airnode. The -`aws.env` and `gcp.json` files are used to define environment information the -deployer uses to connect to these cloud providers. +The files `config.json` and `secrets.env` are used to configure the Airnode. The `aws.env` and `gcp.json` files are used to define environment information the deployer uses to connect to these cloud providers. ``` my-airnode @@ -50,22 +41,15 @@ my-airnode ## Cloud Provider Credentials -In order to deploy Airnode to a serverless cloud provider, you need to provide -cloud provider credentials to the Airnode deployer image. The deployer image -currently supports deploying to AWS and GCP. For AWS deployment, see the -[AWS Setup](/reference/airnode/v0.11/understand/configuring.md#aws-setup-aws-deployment-only) -and for GCP deployment, see the -[GCP Setup](/reference/airnode/v0.11/understand/configuring.md#gcp-setup-gcp-deployment-only). +In order to deploy Airnode to a serverless cloud provider, you need to provide cloud provider credentials to the Airnode deployer image. The deployer image currently supports deploying to AWS and GCP. For AWS deployment, see the [AWS Setup](/reference/airnode/v0.11/understand/configuring.md#aws-setup-aws-deployment-only) and for GCP deployment, see the [GCP Setup](/reference/airnode/v0.11/understand/configuring.md#gcp-setup-gcp-deployment-only). ## Deployer Logs -The deployer saves log files by default into the `config/logs/` direcotry, but -this can be changed by passing a `--logs` argument to the command. +The deployer saves log files by default into the `config/logs/` direcotry, but this can be changed by passing a `--logs` argument to the command. ## Deployer Image Commands -Commands are similar for AWS and GCP. Any differences between AWS and GCP are -noted where they exist. +Commands are similar for AWS and GCP. Any differences between AWS and GCP are noted where they exist. - `deploy` - `list` @@ -77,22 +61,16 @@ noted where they exist. ### `deploy` -The [deploy](/reference/airnode/v0.11/packages/deployer.md#deploy) command will -create the Airnode with a cloud provider or update it if it already exists. -Three files are needed to run the deploy command. +The [deploy](/reference/airnode/v0.11/packages/deployer.md#deploy) command will create the Airnode with a cloud provider or update it if it already exists. Three files are needed to run the deploy command. - config.json - secrets.env - aws.env (AWS only) - gcp.json (GCP only) -See -[Deploying an Airnode](/reference/airnode/v0.11/understand/deploying.md#deploy-with-docker) -for deployment commands specific to various operating systems and cloud -providers. +See [Deploying an Airnode](/reference/airnode/v0.11/understand/deploying.md#deploy-with-docker) for deployment commands specific to various operating systems and cloud providers. -Note that a `receipt.json` file will be created upon completion. It contains -some deployment information and is used to remove the Airnode. +Note that a `receipt.json` file will be created upon completion. It contains some deployment information and is used to remove the Airnode. @@ -120,24 +98,14 @@ docker run -it --rm ^ #### Re-deployments -A unique deployment is defined by the value of -[nodeSetting.stage](/reference/airnode/v0.11/deployment-files/config-json.md#stage). -If you deploy again, using the same `nodeSetting.stage` value, then you are -re-deploying or updating the previous deployment. +A unique deployment is defined by the value of [nodeSetting.stage](/reference/airnode/v0.11/deployment-files/config-json.md#stage). If you deploy again, using the same `nodeSetting.stage` value, then you are re-deploying or updating the previous deployment. -By default the deployer will attempt to remove the Airnode should either a -deployment or re-deployment fail. But if either fails (and -[--auto-remove](/reference/airnode/v0.11/packages/deployer.md#deploy) is false) -then the Airnode will not be removed, however it could be left in an unstable -state. You can alter the `deploy` command to change this behavior using the -following. +By default the deployer will attempt to remove the Airnode should either a deployment or re-deployment fail. But if either fails (and [--auto-remove](/reference/airnode/v0.11/packages/deployer.md#deploy) is false) then the Airnode will not be removed, however it could be left in an unstable state. You can alter the `deploy` command to change this behavior using the following. - `--auto-remove true|false`: defaults to true - `--no-auto-remove` -Auto removal is usually recommended for development deployments. For production -deployments, consider changing the value of `nodeSetting.stage` to create a new -deployment and follow-up by removing the previous deployment. +Auto removal is usually recommended for development deployments. For production deployments, consider changing the value of `nodeSetting.stage` to create a new deployment and follow-up by removing the previous deployment. Use the following example to avoid the automatic removal of the Airnode. @@ -150,12 +118,7 @@ api3/airnode-deployer:0.11.2 deploy --auto-remove false ### `list` -Once one or more Airnodes were deployed using the -[deploy](/reference/airnode/v0.11/docker/deployer-image.md#deploy) command -above, the [list](/reference/airnode/v0.11/packages/deployer.md#list) command -can be used to list currently deployed Airnodes. Files for cloud provider -authentication are needed for the command to run correctly: `aws.env` (for AWS) -and/or `gcp.json` (for GCP). +Once one or more Airnodes were deployed using the [deploy](/reference/airnode/v0.11/docker/deployer-image.md#deploy) command above, the [list](/reference/airnode/v0.11/packages/deployer.md#list) command can be used to list currently deployed Airnodes. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -174,9 +137,7 @@ docker run -it --rm ^ ::: -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ::: code-group @@ -197,14 +158,7 @@ docker run -it --rm ^ ### `info` -Retrieve more information about a deployment with the -[info](/reference/airnode/v0.11/packages/deployer.md#info) command. Use the -deployment ID from the -[list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above to -request information about a specific deployment. The retrieved information -include deployment's Airnode address, stage, Airnode version and the update -history. Files for cloud provider authentication are needed for the command to -run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). +Retrieve more information about a deployment with the [info](/reference/airnode/v0.11/packages/deployer.md#info) command. Use the deployment ID from the [list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above to request information about a specific deployment. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -225,17 +179,7 @@ docker run -it --rm ^ ### `rollback` -To revert to a previous version of a deployment, use the -[rollback](/reference/airnode/v0.11/packages/deployer.md#rollback) command. -Provide the deployment ID from the -[list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above to -specify which deployment will be changed. Also provide the desired version ID -from the [info](/reference/airnode/v0.11/docker/deployer-image.md#info) command -above to revert to. The -[rollback](/reference/airnode/v0.11/packages/deployer.md#rollback) command will -then fetch the configuration files of the specified version and deploy the -version using its configuration. Check this with the -[info](/reference/airnode/v0.11/docker/deployer-image.md#info) command above. +To revert to a previous version of a deployment, use the [rollback](/reference/airnode/v0.11/packages/deployer.md#rollback) command. Provide the deployment ID from the [list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above to specify which deployment will be changed. Also provide the desired version ID from the [info](/reference/airnode/v0.11/docker/deployer-image.md#info) command above to revert to. The [rollback](/reference/airnode/v0.11/packages/deployer.md#rollback) command will then fetch the configuration files of the specified version and deploy the version using its configuration. Check this with the [info](/reference/airnode/v0.11/docker/deployer-image.md#info) command above. ::: code-group @@ -256,23 +200,7 @@ docker run -it --rm ^ ### `fetch-files` -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the -[fetch-files](/reference/airnode/v0.11/packages/deployer.md#fetch-files) command -to retrieve them. You need to provide the deployment ID from the -[list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above to -specify the desired deployment. By default, the files from the latest version of -this deployment are fetched. Alternatively, you can additionally provide a -deployment version ID from the -[info](/reference/airnode/v0.11/docker/deployer-image.md#info) command above to -specify the desired deployment version. By default, the archive with the files -is stored in the `config` directory **within the Docker container** that is, in -the example below, mapped to your current working directory. You can change the -output directory by providing an `--output-dir` option specifying a different -directory instead. Don't forget to add a mapping for the new output directory so -you'll be able to access the files. Files for cloud provider authentication are -needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for -GCP). +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the [fetch-files](/reference/airnode/v0.11/packages/deployer.md#fetch-files) command to retrieve them. You need to provide the deployment ID from the [list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above to specify the desired deployment. By default, the files from the latest version of this deployment are fetched. Alternatively, you can additionally provide a deployment version ID from the [info](/reference/airnode/v0.11/docker/deployer-image.md#info) command above to specify the desired deployment version. By default, the archive with the files is stored in the `config` directory **within the Docker container** that is, in the example below, mapped to your current working directory. You can change the output directory by providing an `--output-dir` option specifying a different directory instead. Don't forget to add a mapping for the new output directory so you'll be able to access the files. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -293,16 +221,7 @@ docker run -it --rm ^ ### `remove` -A deployed Airnode can be removed via the -[remove](/reference/airnode/v0.11/packages/deployer.md#remove) command. To -remove Airnode, use the deployment ID from the -[list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above. -Airnode's update history, that can be seen by the -[info](/reference/airnode/v0.11/docker/deployer-image.md#info) command, will be -removed as well. Files for cloud provider authentication are needed for the -command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is -the recommended way to remove a deployment, but an alternative is the -`remove-with-receipt` command. +A deployed Airnode can be removed via the [remove](/reference/airnode/v0.11/packages/deployer.md#remove) command. To remove Airnode, use the deployment ID from the [list](/reference/airnode/v0.11/docker/deployer-image.md#list) command above. Airnode's update history, that can be seen by the [info](/reference/airnode/v0.11/docker/deployer-image.md#info) command, will be removed as well. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is the recommended way to remove a deployment, but an alternative is the `remove-with-receipt` command. ::: code-group @@ -323,12 +242,7 @@ docker run -it --rm ^ ### `remove-with-receipt` -When an Airnode was deployed using the `deploy` command, a `receipt.json` file -was created. This file is used to remove the Airnode. The -[remove-with-receipt](/reference/airnode/v0.11/packages/deployer.md#remove-with-receipt) -command is identical for AWS and GCP. Files for cloud provider authentication -are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` -(for GCP). +When an Airnode was deployed using the `deploy` command, a `receipt.json` file was created. This file is used to remove the Airnode. The [remove-with-receipt](/reference/airnode/v0.11/packages/deployer.md#remove-with-receipt) command is identical for AWS and GCP. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -349,22 +263,11 @@ docker run -it --rm ^ ## Manual Removal -Optionally you can remove an Airnode manually though it is highly recommended -that you do so using the deployer image's `remove-with-receipt` or `remove` -commands. When removing manually, you will need the Airnode's deployment ID, -`deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., -`production`). They can be found in the -[receipt.json](/reference/airnode/v0.11/deployment-files/receipt-json.md) file -generated when deploying the Airnode. These are included in the element name of -AWS and GCP deployed features. Airnode has a presence in several areas of both -AWS and GCP as listed below. +Optionally you can remove an Airnode manually though it is highly recommended that you do so using the deployer image's `remove-with-receipt` or `remove` commands. When removing manually, you will need the Airnode's deployment ID, `deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., `production`). They can be found in the [receipt.json](/reference/airnode/v0.11/deployment-files/receipt-json.md) file generated when deploying the Airnode. These are included in the element name of AWS and GCP deployed features. Airnode has a presence in several areas of both AWS and GCP as listed below. ::: danger Remember -Only delete elements of a feature with the `deploymentId` and `stage` name -contained in the element's name. There can be more than one Airnode. Example: -(airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the -deploymentId and `production` is the stage name. +Only delete elements of a feature with the `deploymentId` and `stage` name contained in the element's name. There can be more than one Airnode. Example: (airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the deploymentId and `production` is the stage name. ::: @@ -376,7 +279,6 @@ deploymentId and `production` is the stage name. -Learn more about AWS or GCP resources that Airnode uses in the -[Cloud Resources](/reference/airnode/v0.11/cloud-resources.md) doc. +Learn more about AWS or GCP resources that Airnode uses in the [Cloud Resources](/reference/airnode/v0.11/cloud-resources.md) doc. diff --git a/docs/reference/airnode/v0.11/docker/index.md b/docs/reference/airnode/v0.11/docker/index.md index 06141683..3b35ae65 100644 --- a/docs/reference/airnode/v0.11/docker/index.md +++ b/docs/reference/airnode/v0.11/docker/index.md @@ -19,31 +19,19 @@ tags: # {{$frontmatter.title}} -Using Docker is the easiest way to both deploy an Airnode to a cloud provider -and to run an Airnode locally. There are two Docker images: the Airnode deployer -image and the Airnode client image. +Using Docker is the easiest way to both deploy an Airnode to a cloud provider and to run an Airnode locally. There are two Docker images: the Airnode deployer image and the Airnode client image. -There is also a docker image wrapping the admin CLI package, as an alternative -to using `npx`. +There is also a docker image wrapping the admin CLI package, as an alternative to using `npx`. -To use these images first install [Docker](https://docs.docker.com/get-docker/) -if it is not present on your system. +To use these images first install [Docker](https://docs.docker.com/get-docker/) if it is not present on your system. -If using a Linux distribution that enforces Selinux policies, allow the Docker -images access to the host directory by -[creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). +If using a Linux distribution that enforces Selinux policies, allow the Docker images access to the host directory by [creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). -- The [deployer image](/reference/airnode/v0.11/docker/deployer-image.md) - deploys the node in the form of serverless functions to a serverless cloud - provider (e.g. AWS Lambda). +- The [deployer image](/reference/airnode/v0.11/docker/deployer-image.md) deploys the node in the form of serverless functions to a serverless cloud provider (e.g. AWS Lambda). -- The [client image](/reference/airnode/v0.11/docker/client-image.md) is the - node itself, containerized. The container can be run locally or deployed to a - cloud hosting service (e.g. AWS EC2 or Lightsail). +- The [client image](/reference/airnode/v0.11/docker/client-image.md) is the node itself, containerized. The container can be run locally or deployed to a cloud hosting service (e.g. AWS EC2 or Lightsail). -- The [admin CLI image](/reference/airnode/v0.11/docker/admin-cli-image.md) - wraps the admin CLI package in a docker image to provide an alternative usage - option to the Admin CLI commands (npx). +- The [admin CLI image](/reference/airnode/v0.11/docker/admin-cli-image.md) wraps the admin CLI package in a docker image to provide an alternative usage option to the Admin CLI commands (npx). ## DockerHub diff --git a/docs/reference/airnode/v0.11/index.md b/docs/reference/airnode/v0.11/index.md index 113d99dc..dbadd471 100644 --- a/docs/reference/airnode/v0.11/index.md +++ b/docs/reference/airnode/v0.11/index.md @@ -19,17 +19,9 @@ tags: # {{$frontmatter.title}} -Use the contract addresses listed in the tables below to interact with Airnode -on EVM-compatible blockchains. Additional addresses will be added as contracts -are deployed, but feel free to -[submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a -new deployment. - -The contract addresses listed below are sourced from the Airnode monorepo -[airnode-protocol](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-protocol) -and can be found in its -[deployments](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-protocol/deployments) -directory. +Use the contract addresses listed in the tables below to interact with Airnode on EVM-compatible blockchains. Additional addresses will be added as contracts are deployed, but feel free to [submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a new deployment. + +The contract addresses listed below are sourced from the Airnode monorepo [airnode-protocol](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-protocol) and can be found in its [deployments](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-protocol/deployments) directory. ## AirnodeRrpV0 diff --git a/docs/reference/airnode/v0.11/migration.md b/docs/reference/airnode/v0.11/migration.md index 6f4931fa..8e5b591e 100644 --- a/docs/reference/airnode/v0.11/migration.md +++ b/docs/reference/airnode/v0.11/migration.md @@ -19,27 +19,19 @@ tags: # {{$frontmatter.title}} -The following guide assumes a valid v0.10.x `config.json` file. All changes -listed below will need to be implemented in order to migrate to Airnode v0.11.2. -This document is written in a way that will preserve existing behavior with -earlier Airnode versions. +The following guide assumes a valid v0.10.x `config.json` file. All changes listed below will need to be implemented in order to migrate to Airnode v0.11.2. This document is written in a way that will preserve existing behavior with earlier Airnode versions. -The document also mentions changes to user facing services related to Airnode, -such as airnode-deployer, airnode-admin, etc., and new features. +The document also mentions changes to user facing services related to Airnode, such as airnode-deployer, airnode-admin, etc., and new features. ## Summary -1. `ois[n].oisFormat` updated to "2.1.0". Note that Airnode v0.11.0 and v0.11.1 - use "2.0.0". +1. `ois[n].oisFormat` updated to "2.1.0". Note that Airnode v0.11.0 and v0.11.1 use "2.0.0". 2. `nodeSettings.nodeVersion` updated to "0.11.2". -3. `ois[n].endpoints[n].preProcessingSpecifications` and - `ois[n].endpoints[n].postProcessingSpecifications` have an updated allowed - Node environment value. +3. `ois[n].endpoints[n].preProcessingSpecifications` and `ois[n].endpoints[n].postProcessingSpecifications` have an updated allowed Node environment value. -4. `chains[n].authorizers.requesterAuthorizersWithErc721` and - `chains[n].authorizers.crossChainRequesterAuthorizersWithErc721` added. +4. `chains[n].authorizers.requesterAuthorizersWithErc721` and `chains[n].authorizers.crossChainRequesterAuthorizersWithErc721` added. 5. Section `nodeSettings.oevGateway` was added. @@ -67,13 +59,9 @@ Updated to "0.11.2" } ``` -3. `ois[n].endpoints[n].preProcessingSpecifications` and - `ois[n].endpoints[n].postProcessingSpecifications` +3. `ois[n].endpoints[n].preProcessingSpecifications` and `ois[n].endpoints[n].postProcessingSpecifications` -Removes `14` from the `Node 14` environment value to represent that the Node -version of the pre- and post-processing environments is dictated by the Node.js -version of Airnode. As of v0.11, the Node.js version of Airnode was upgraded -from 14 to 18. +Removes `14` from the `Node 14` environment value to represent that the Node version of the pre- and post-processing environments is dictated by the Node.js version of Airnode. As of v0.11, the Node.js version of Airnode was upgraded from 14 to 18. ```diff { @@ -101,15 +89,9 @@ from 14 to 18. } ``` -4. `chains[n].authorizers.requesterAuthorizersWithErc721` and - `chains[n].authorizers.crossChainRequesterAuthorizersWithErc721` +4. `chains[n].authorizers.requesterAuthorizersWithErc721` and `chains[n].authorizers.crossChainRequesterAuthorizersWithErc721` -Adds two new authorizers, `requesterAuthorizersWithErc721` and -`crossChainRequesterAuthorizersWithErc721`, that enable request authorization -using ERC721 tokens. These new fields are required, but their values may be -empty arrays if this feature is not required. For further details, see the -[Authorizers](/reference/airnode/v0.11/concepts/authorizers.md#how-are-authorizers-implemented) -page. +Adds two new authorizers, `requesterAuthorizersWithErc721` and `crossChainRequesterAuthorizersWithErc721`, that enable request authorization using ERC721 tokens. These new fields are required, but their values may be empty arrays if this feature is not required. For further details, see the [Authorizers](/reference/airnode/v0.11/concepts/authorizers.md#how-are-authorizers-implemented) page. ```diff "chains": [ @@ -124,9 +106,7 @@ page. ] ``` -5. With the new OEV gateway feature there's a new section in the `config.json` - file for it. The new section `nodeSettings.oevGateway` needs to be added in - order for the configuration file to be valid. +5. With the new OEV gateway feature there's a new section in the `config.json` file for it. The new section `nodeSettings.oevGateway` needs to be added in order for the configuration file to be valid. ```diff { @@ -141,23 +121,15 @@ page. } ``` -Read the [OEV gateway](/reference/airnode/v0.11/understand/oev-gateway.md) doc -to learn more about this feature. +Read the [OEV gateway](/reference/airnode/v0.11/understand/oev-gateway.md) doc to learn more about this feature. ## New features - The Node.js version of Airnode was upgraded from 14 to 18. -- The `coingecko-signed-data` and `coingecko-testable` HTTP gateway - `airnode-examples` integrations have been combined into a single - `coingecko-http-gateways` integration. -- There's a new gateway available called the OEV gateway. Read the - [OEV gateway](/reference/airnode/v0.11/understand/oev-gateway.md) doc to learn - more about this feature. +- The `coingecko-signed-data` and `coingecko-testable` HTTP gateway `airnode-examples` integrations have been combined into a single `coingecko-http-gateways` integration. +- There's a new gateway available called the OEV gateway. Read the [OEV gateway](/reference/airnode/v0.11/understand/oev-gateway.md) doc to learn more about this feature. - The heartbeat payload now includes `deployment_id`. -- The `value` for a `fixedOperationParameters` object is now allowed to be any - type, including an object; for example, the following specifies an array - containing multiple primitives. Note that this feature is only available - beginning in v0.11.2. +- The `value` for a `fixedOperationParameters` object is now allowed to be any type, including an object; for example, the following specifies an array containing multiple primitives. Note that this feature is only available beginning in v0.11.2. ```json { diff --git a/docs/reference/airnode/v0.11/packages/adapter.md b/docs/reference/airnode/v0.11/packages/adapter.md index 4cb9d7ca..206af4de 100644 --- a/docs/reference/airnode/v0.11/packages/adapter.md +++ b/docs/reference/airnode/v0.11/packages/adapter.md @@ -19,19 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-adapter](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-adapter) -package has multiple responsibilities. It is used for building requests from an -[Oracle Integration Specification (OIS)](/reference/ois/2.1/), executing them, -parsing the responses, but also converting and encoding them for on chain use. +The [airnode-adapter](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-adapter) package has multiple responsibilities. It is used for building requests from an [Oracle Integration Specification (OIS)](/reference/ois/2.1/), executing them, parsing the responses, but also converting and encoding them for on chain use. -It is an internal dependency of Airnode, but can also be used standalone as an -API. +It is an internal dependency of Airnode, but can also be used standalone as an API. ## Installation -You can install `@api3/airnode-adapter` by adding it to the `package.json` file -in your project. +You can install `@api3/airnode-adapter` by adding it to the `package.json` file in your project. ```sh npm install --save @api3/airnode-adapter @@ -39,35 +33,24 @@ npm install --save @api3/airnode-adapter yarn add @api3/airnode-adapter ``` -You shouldn't need to use the adapter package directly. However, you might want -to use its API to double check the conversion or encoding behavior for which you -can install this package and verify your assumptions. +You shouldn't need to use the adapter package directly. However, you might want to use its API to double check the conversion or encoding behavior for which you can install this package and verify your assumptions. ## Conversion -While the adapter package has many responsibilities, many of those can be -treated as implementation details. On the other hand, there are a few important -behaviors to be noted when converting the response values based on the target -type and making the response transaction on chain. +While the adapter package has many responsibilities, many of those can be treated as implementation details. On the other hand, there are a few important behaviors to be noted when converting the response values based on the target type and making the response transaction on chain. Altogether, the response cycle consists of multiple steps 1. A successful API call is made and Airnode receives a response value. -2. The value to be converted is extracted from the response using the - [\_path](/reference/ois/2.1/reserved-parameters.md#path) from the OIS object. -3. This extracted value is converted to the target type. Conversions are - performed internally by the `castValue(value, type)` function. -4. The converted value is encoded to the native solidity type based on the - [\_type](/reference/ois/2.1/reserved-parameters.md#type) from the OIS object. - Encoding is performed internally by the `encodeValue(value, type)` function. +2. The value to be converted is extracted from the response using the [\_path](/reference/ois/2.1/reserved-parameters.md#path) from the OIS object. +3. This extracted value is converted to the target type. Conversions are performed internally by the `castValue(value, type)` function. +4. The converted value is encoded to the native solidity type based on the [\_type](/reference/ois/2.1/reserved-parameters.md#type) from the OIS object. Encoding is performed internally by the `encodeValue(value, type)` function. -If any of the steps above fail, an error is thrown. This will fail the given API -request and the error reason can be found in the logs. +If any of the steps above fail, an error is thrown. This will fail the given API request and the error reason can be found in the logs. -The rest of this section covers the conversion logic for all of the supported -types. +The rest of this section covers the conversion logic for all of the supported types. ### `int256` or `uint256` @@ -86,8 +69,7 @@ const ERROR_VALUES = [ ]; ``` -There are a few special strings and boolean values that are convertible to -`int256` or `uint256`: +There are a few special strings and boolean values that are convertible to `int256` or `uint256`: ```ts const SPECIAL_INT_VALUES = [false, 'false', true, 'true']; @@ -97,11 +79,7 @@ console.log(values); // [0, 0, 1, 1]; ``` -Number strings and numbers will attempt to be converted to -[BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be -multiplied by the value of the -[\_times](/reference/ois/2.1/reserved-parameters.md#times) parameter if it is -present. +Number strings and numbers will attempt to be converted to [BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be multiplied by the value of the [\_times](/reference/ois/2.1/reserved-parameters.md#times) parameter if it is present. ```ts const VALID_INT_VALUES = ['123.456', 7777]; @@ -111,17 +89,11 @@ console.log(values); // [new BigNumber(123.456), new BigNumber(7777)]; ``` -Conversion for `int256` and `uint256` is the same - this means that `-123` can -be converted to `uint256`. However, an error will be thrown while encoding. +Conversion for `int256` and `uint256` is the same - this means that `-123` can be converted to `uint256`. However, an error will be thrown while encoding. :::warning Flooring -Beware that any floating point number will be **floored**. This is necessary, -because floating point numbers are not valid in solidity. To mitigate precision -loss, you can use the -[`_times`](/reference/ois/2.1/reserved-parameters.md#times) parameter that is -sufficiently large. For example, if the API response is a USD currency, you -might want to use `_times: "100"` to convert the value to cents. +Beware that any floating point number will be **floored**. This is necessary, because floating point numbers are not valid in solidity. To mitigate precision loss, you can use the [`_times`](/reference/ois/2.1/reserved-parameters.md#times) parameter that is sufficiently large. For example, if the API response is a USD currency, you might want to use `_times: "100"` to convert the value to cents. ::: @@ -144,17 +116,9 @@ All other values are converted to `true`. ### `bytes32` -There is no conversion for `bytes32` - the value is expected to be a valid hex -string representing the encoded 32 bytes value. This means that the encoding -**must** be implemented on the API side. If you want to delegate the encoding to -Airnode, see the documentation for -[`string32`](/reference/airnode/v0.11/packages/adapter.md#string32). +There is no conversion for `bytes32` - the value is expected to be a valid hex string representing the encoded 32 bytes value. This means that the encoding **must** be implemented on the API side. If you want to delegate the encoding to Airnode, see the documentation for [`string32`](/reference/airnode/v0.11/packages/adapter.md#string32). -For example, let's say the API wants to encode the following string -`simple string` with length 13. Its encoding is -0x73696d706c6520737472696e6700000000000000000000000000000000000000. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. +For example, let's say the API wants to encode the following string `simple string` with length 13. Its encoding is 0x73696d706c6520737472696e6700000000000000000000000000000000000000. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. You can use [ethers](https://docs.ethers.io/v5/) to encode these on the API side @@ -166,29 +130,16 @@ console.log(encoded); // 0x73696d706c6520737472696e67000000000000000000000000000 ### `address` -There is no conversion for `address` - the value is expected to be a string -representing a valid address. Valid examples are: +There is no conversion for `address` - the value is expected to be a string representing a valid address. Valid examples are: -- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) - of an address. -- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - - all lowercase address. +- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) of an address. +- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - all lowercase address. ### `bytes` -There is no conversion for `bytes` - the value is expected to be a valid hex -string representing the encoded value. This means that the encoding to bytes -**must** be implemented on the API side. If you want to send a string, see the -documentation for -[`string`](/reference/airnode/v0.11/packages/adapter.md#string). +There is no conversion for `bytes` - the value is expected to be a valid hex string representing the encoded value. This means that the encoding to bytes **must** be implemented on the API side. If you want to send a string, see the documentation for [`string`](/reference/airnode/v0.11/packages/adapter.md#string). -For example, let's say the API wants to encode the following string -`this is an example string that is a bit longer`. Its encoding is -0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these -on the API side. +For example, let's say the API wants to encode the following string `this is an example string that is a bit longer`. Its encoding is 0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these on the API side. ```js const value = 'this is an example string that is a bit longer'; @@ -198,9 +149,7 @@ console.log(encodedValue); // 0x7468697320697320616e206578616d706c6520737472696e ### `string` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. All other values will be converted to -`string` and before encoded on chain using the `string` type. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. All other values will be converted to `string` and before encoded on chain using the `string` type. ```js const values = [ @@ -220,20 +169,11 @@ const mappedValues = values.map((v) => { ### `string32` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. -However, there is one exception, if the stringified value contains more than 31 -characters it will be **trimmed down** to only the first 31 characters during -conversion. +However, there is one exception, if the stringified value contains more than 31 characters it will be **trimmed down** to only the first 31 characters during conversion. -For example, if the API response is the following string -`this is an example string that is a bit longer` with length 46. It will be -first trimmed to 31 characters, string `this is an example string that ` and -afterwards converted to -0x7468697320697320616e206578616d706c6520737472696e6720746861742000. -Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using -the following snippet +For example, if the API response is the following string `this is an example string that is a bit longer` with length 46. It will be first trimmed to 31 characters, string `this is an example string that ` and afterwards converted to 0x7468697320697320616e206578616d706c6520737472696e6720746861742000. Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using the following snippet ```js const encoded = @@ -244,17 +184,11 @@ console.log(decoded); // "this is an example string that " ### Arrays -Conversion of arrays depends on the primitive type. All values of the array (or -nested array) will be converted according to the rules of the primitive type. +Conversion of arrays depends on the primitive type. All values of the array (or nested array) will be converted according to the rules of the primitive type. For example: -- `int256[]` - has primitive type `int256`. All elements of this array follow - the [`int256`](/reference/airnode/v0.11/packages/adapter.md#int256-or-uint256) - rules. -- `string32[7][][5]` - is a multidimensional array, where some dimensions are - fixed and some not. This is irrelevant though, and all the elements are - converted based on - [`string32`](/reference/airnode/v0.11/packages/adapter.md#string32) rules. +- `int256[]` - has primitive type `int256`. All elements of this array follow the [`int256`](/reference/airnode/v0.11/packages/adapter.md#int256-or-uint256) rules. +- `string32[7][][5]` - is a multidimensional array, where some dimensions are fixed and some not. This is irrelevant though, and all the elements are converted based on [`string32`](/reference/airnode/v0.11/packages/adapter.md#string32) rules. diff --git a/docs/reference/airnode/v0.11/packages/admin-cli.md b/docs/reference/airnode/v0.11/packages/admin-cli.md index a289b26b..331406e8 100644 --- a/docs/reference/airnode/v0.11/packages/admin-cli.md +++ b/docs/reference/airnode/v0.11/packages/admin-cli.md @@ -19,54 +19,26 @@ tags: # {{$frontmatter.title}} -Use the -[airnode-admin](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin) -Admin CLI tool to interact with Airnode across blockchains. There are commands -for both developers (dApp) and API providers. Developers can sponsor -[requester](/reference/airnode/v0.11/concepts/requester.md) contracts and derive -[sponsorWallets](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) for -Airnodes. API providers can build -[Airnodes](/reference/airnode/v0.11/concepts/airnode.md) that serve their API -data to requester contracts. +Use the [airnode-admin](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin) Admin CLI tool to interact with Airnode across blockchains. There are commands for both developers (dApp) and API providers. Developers can sponsor [requester](/reference/airnode/v0.11/concepts/requester.md) contracts and derive [sponsorWallets](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) for Airnodes. API providers can build [Airnodes](/reference/airnode/v0.11/concepts/airnode.md) that serve their API data to requester contracts. ::: warning Transaction Gas Costs -Some commands will incur transaction fees. These are per call transaction gas -costs and are relatively small. See the -[Developer Fees](/reference/airnode/v0.11/developers/fees.md) -doc. +Some commands will incur transaction fees. These are per call transaction gas costs and are relatively small. See the [Developer Fees](/reference/airnode/v0.11/developers/fees.md) doc. ::: -Almost all commands require you to provide a blockchain `providerUrl`. Following -are just two examples of many possibilities. See the -[Chain Providers](/reference/airnode/v0.11/concepts/chain-providers.md) doc for -more information. +Almost all commands require you to provide a blockchain `providerUrl`. Following are just two examples of many possibilities. See the [Chain Providers](/reference/airnode/v0.11/concepts/chain-providers.md) doc for more information. - `https://eth-goerli.gateway.pokt.network/v1/lb/` - `https://sepolia.infura.io/v3/` -The CLI connects to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -or the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract, which addresses are derived from the current chain. You can optionally -specify the contract addresses yourself by providing optional -`airnode-rrp-address` or `requester-authorizer-with-airnode` command argument -with the address of the deployed contract on your targeted chain. - -Commands that require `mnemonic` will make an on-chain transaction. The -application will derive the account from the mnemonic with default ethereum -derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional -parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet -that is associated with the mnemonic is funded on the target chain. The -application will not exit until the transaction is confirmed. +The CLI connects to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) or the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract, which addresses are derived from the current chain. You can optionally specify the contract addresses yourself by providing optional `airnode-rrp-address` or `requester-authorizer-with-airnode` command argument with the address of the deployed contract on your targeted chain. + +Commands that require `mnemonic` will make an on-chain transaction. The application will derive the account from the mnemonic with default ethereum derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet that is associated with the mnemonic is funded on the target chain. The application will not exit until the transaction is confirmed. ### Using transaction overrides -CLI commands also support the following transaction overrides as optional -arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and -`max-priority-fee` (EIP-1559 transactions) and `nonce`. +CLI commands also support the following transaction overrides as optional arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and `max-priority-fee` (EIP-1559 transactions) and `nonce`. ### Default transaction overrides @@ -115,9 +87,7 @@ docker run api3/airnode-admin:0.11.2 $COMMAND --help ## SDK -You can also use the package programmatically. The SDK exports respective -functions for all CLI commands as well as helper functions for obtaining the -contract instance on the targeted chain. +You can also use the package programmatically. The SDK exports respective functions for all CLI commands as well as helper functions for obtaining the contract instance on the targeted chain. ```js import { sponsorRequester, getAirnodeRrpWithSigner } from '@api3/airnode-admin'; @@ -133,9 +103,7 @@ const airnodeRrp = await getAirnodeRrpWithSigner( const requester = await sponsorRequester(airnodeRrp, requester); ``` -If you plan to use multiple commands it might be tedious to pass the contract -instance to every function call. For this reason there is also class based -`AdminSdk` which you initialize with `AirnodeRrp` contract only once. +If you plan to use multiple commands it might be tedious to pass the contract instance to every function call. For this reason there is also class based `AdminSdk` which you initialize with `AirnodeRrp` contract only once. ```js import { AdminSdk } from '@api3/airnode-admin'; @@ -157,14 +125,11 @@ const requester = await adminSdk.sponsorRequester(requester); adminSdk.airnodeRrp = airnodeRrp.connect(someOtherWallet); ``` -The SDK will also provide TS typings out of the box. Please, refer to the -implementation for more details. +The SDK will also provide TS typings out of the box. Please, refer to the implementation for more details. ### Using transaction overrides -You can also use transaction overrides to customize gas limits and fee settings. -The SDK simply passes the overrides parameter to the contract method so you can -use any overrides supported by the ethers library. +You can also use transaction overrides to customize gas limits and fee settings. The SDK simply passes the overrides parameter to the contract method so you can use any overrides supported by the ethers library. ```js import { ethers } from 'ethers'; @@ -188,14 +153,7 @@ const requester = await adminSdk.sponsorRequester(requester, overrides); ## Sponsors -Commands related to a [sponsor's](/reference/airnode/v0.11/concepts/sponsor.md) -relationships between -[requesters](/reference/airnode/v0.11/concepts/requester.md) and -[sponsorWallets](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) as -well as [templates](/reference/airnode/v0.11/concepts/template.md) used by a -sponsor's requesters. Some of these commands connect to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract where the signer is sponsor account. +Commands related to a [sponsor's](/reference/airnode/v0.11/concepts/sponsor.md) relationships between [requesters](/reference/airnode/v0.11/concepts/requester.md) and [sponsorWallets](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) as well as [templates](/reference/airnode/v0.11/concepts/template.md) used by a sponsor's requesters. Some of these commands connect to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract where the signer is sponsor account. - [sponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/v0.11/packages/admin-cli.md#unsponsor-requester) @@ -210,39 +168,19 @@ protocol contract where the signer is sponsor account. ### `sponsor-requester` -[Sponsors](/reference/airnode/v0.11/concepts/sponsor.md) a -[requester](/reference/airnode/v0.11/concepts/requester.md) contract so that its -requests can be fulfilled by the -[sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) of -an Airnode. The account derived from the `mnemonic` you provide must belong to -the sponsor. +[Sponsors](/reference/airnode/v0.11/concepts/sponsor.md) a [requester](/reference/airnode/v0.11/concepts/requester.md) contract so that its requests can be fulfilled by the [sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) of an Airnode. The account derived from the `mnemonic` you provide must belong to the sponsor. -Sponsoring a requester and using the returned `sponsorAddress` to derive a -`sponsorWallet` for an Airnode creates a -[relationship](/reference/airnode/v0.11/concepts/sponsor.md) between the -requester and the Airnode, see the -[`derive-sponsor-wallet-address`](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Sponsoring a requester and using the returned `sponsorAddress` to derive a `sponsorWallet` for an Airnode creates a [relationship](/reference/airnode/v0.11/concepts/sponsor.md) between the requester and the Airnode, see the [`derive-sponsor-wallet-address`](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a - `sponsorAddress` as the default account of the mnemonic unless a - `derivation-path` is specified. It's also used to pay gas costs from the - mnemonic's default account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a `sponsorAddress` as the default account of the mnemonic unless a `derivation-path` is specified. It's also used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to sponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. If this parameter is not provided, it will be deduced from - the current chain. If there is no RRP address found for the given chain an - error is thrown. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. If this parameter is not provided, it will be deduced from the current chain. If there is no RRP address found for the given chain an error is thrown. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -265,29 +203,17 @@ npx @api3/airnode-admin sponsor-requester ^ ### `unsponsor-requester` -Removes the sponsorship of a -[requester](/reference/airnode/v0.11/concepts/requester.md) contract so that its -requests can no longer be fulfilled by the -[sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). The -account derived from the `mnemonic` you provide here has to belong to the -sponsor. +Removes the sponsorship of a [requester](/reference/airnode/v0.11/concepts/requester.md) contract so that its requests can no longer be fulfilled by the [sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). The account derived from the `mnemonic` you provide here has to belong to the sponsor. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used - to sponsor the requester. Used to pay gas costs from the mnemonic's default - account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used to sponsor the requester. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to unsponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -310,17 +236,12 @@ npx @api3/airnode-admin unsponsor-requester ^ ### `get-sponsor-status` -Returns the sponsor status for a given -[sponsor](/reference/airnode/v0.11/concepts/sponsor.md) and -[requester](/reference/airnode/v0.11/concepts/requester.md) (`true` if -sponsored, `false` otherwise). +Returns the sponsor status for a given [sponsor](/reference/airnode/v0.11/concepts/sponsor.md) and [requester](/reference/airnode/v0.11/concepts/requester.md) (`true` if sponsored, `false` otherwise). - `provider-url`: A valid blockchain provider URL. -- `sponsor-address`: The `sponsorAddress` returned when the requester was - sponsored. +- `sponsor-address`: The `sponsorAddress` returned when the requester was sponsored. - `requester-address`: The requester contract address. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -342,16 +263,9 @@ npx @api3/airnode-admin get-sponsor-status ^ ### `derive-sponsor-wallet-address` -Derives the address of the wallet designated by an Airnode for a -[sponsor](/reference/airnode/v0.11/concepts/sponsor.md), which is called the -[sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). -This command will error if `airnode-xpub` does not belong to the HDNode with the -path `m/44'/60'/0'` of the Airnode wallet. See the -[`derive-airnode-xpub`](/reference/airnode/v0.11/packages/admin-cli.md#derive-airnode-xpub) -command. +Derives the address of the wallet designated by an Airnode for a [sponsor](/reference/airnode/v0.11/concepts/sponsor.md), which is called the [sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). This command will error if `airnode-xpub` does not belong to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. See the [`derive-airnode-xpub`](/reference/airnode/v0.11/packages/admin-cli.md#derive-airnode-xpub) command. -- `airnode-xpub`: The extended public address of the Airnode for path - `m/44'/60'/0'`. +- `airnode-xpub`: The extended public address of the Airnode for path `m/44'/60'/0'`. - `airnode-address`: The public address of the Airnode. - `sponsor-address`: The address of the sponsor account. @@ -375,27 +289,17 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ### `create-template` -Reads a file, uses its contents to create a -[template](/reference/airnode/v0.11/concepts/template.md) and returns a -`template-id`. Also see -[Using Templates](/reference/airnode/v0.11/developers/using-templates.md) for an -example template file. +Reads a file, uses its contents to create a [template](/reference/airnode/v0.11/concepts/template.md) and returns a `template-id`. Also see [Using Templates](/reference/airnode/v0.11/developers/using-templates.md) for an example template file. - `provider-url`: A valid blockchain provider URL. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `template-file-path`: Path to the template file to create on-chain. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -418,20 +322,11 @@ npx @api3/airnode-admin create-template ^ ### `create-inline-template` -It is possible to inline Airnode templates inside config.json in a `templates` -section. These templates need to be published on chain, but inlining them inside -config provides more clarity which templates can be used for template requests -and also saves a blockchain call . +It is possible to inline Airnode templates inside config.json in a `templates` section. These templates need to be published on chain, but inlining them inside config provides more clarity which templates can be used for template requests and also saves a blockchain call . -The command reads a template file, uses its contents to create a -[template](/reference/airnode/v0.11/concepts/template.md) and returns the data -necessary to inline the template inside config. See -[Using Templates](/reference/airnode/v0.11/developers/using-templates.md) for an -example template file. +The command reads a template file, uses its contents to create a [template](/reference/airnode/v0.11/concepts/template.md) and returns the data necessary to inline the template inside config. See [Using Templates](/reference/airnode/v0.11/developers/using-templates.md) for an example template file. -This command does **not** create a template on chain. Be sure to use the -[create-template](/reference/airnode/v0.11/packages/admin-cli.md#create-template) -command on chain before making template requests. +This command does **not** create a template on chain. Be sure to use the [create-template](/reference/airnode/v0.11/packages/admin-cli.md#create-template) command on chain before making template requests. - `template-file-path`: Path to the template file to create on-chain. @@ -451,13 +346,11 @@ npx @api3/airnode-admin create-inline-template ^ ### `get-template` -Returns the [template](/reference/airnode/v0.11/concepts/template.md) for the -given `template-id`. +Returns the [template](/reference/airnode/v0.11/concepts/template.md) for the given `template-id`. - `provider-url`: A valid blockchain provider URL. - `template-id`: The id of a template to return. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -477,50 +370,28 @@ npx @api3/airnode-admin get-template ^ ### `request-withdrawal` -Requests a -[withdrawal](/reference/airnode/v0.11/concepts/sponsor.md#withdrawals) from a -[sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) -managed by an Airnode. +Requests a [withdrawal](/reference/airnode/v0.11/concepts/sponsor.md#withdrawals) from a [sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) managed by an Airnode. -The funds will be returned to the account derived from the `sponsor-mnemonic`. -This account must belong to a -[sponsor](/reference/airnode/v0.11/concepts/sponsor.md) for the specified -[sponsor wallet address](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) -in the command. +The funds will be returned to the account derived from the `sponsor-mnemonic`. This account must belong to a [sponsor](/reference/airnode/v0.11/concepts/sponsor.md) for the specified [sponsor wallet address](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) in the command. -After the request is made, it needs to be fulfilled by Airnode, so the return -value of this command is only a `withdrawal-request-id` which you can use to -call -[check-withdrawal-request](/reference/airnode/v0.11/packages/admin-cli.md#check-withdrawal-request) -to see whether the request was processed or not. +After the request is made, it needs to be fulfilled by Airnode, so the return value of this command is only a `withdrawal-request-id` which you can use to call [check-withdrawal-request](/reference/airnode/v0.11/packages/admin-cli.md#check-withdrawal-request) to see whether the request was processed or not. ::: warning Withdrawal Priority -Airnode will drop any pending API calls associated with a `sponsorWallet` once a -withdrawal is requested. +Airnode will drop any pending API calls associated with a `sponsorWallet` once a withdrawal is requested. ::: - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from - the mnemonic's default account unless a `derivation-path` is specified. - Withdrawn funds will be added to this mnemonic's default address unless a - `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. Withdrawn funds will be added to this mnemonic's default address unless a `derivation-path` is specified. - `airnode-address`: The public address of the Airnode. -- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw - from. This address was returned by the `derive-sponsor-wallet-address` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)` : The destination address of the `mnemonic` - parameter to add the withdrawn funds to if the default address is not desired. +- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw from. This address was returned by the `derive-sponsor-wallet-address` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)` : The destination address of the `mnemonic` parameter to add the withdrawn funds to if the default address is not desired. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -545,17 +416,11 @@ npx @api3/airnode-admin request-withdrawal ^ ### `check-withdrawal-request` -Checks the status of the -[withdrawal](/reference/airnode/v0.11/concepts/sponsor.md#withdrawals) request -with the given `withdrawal-request-id` from the -[request withdrawal command](/reference/airnode/v0.11/packages/admin-cli.md#request-withdrawal) -above. +Checks the status of the [withdrawal](/reference/airnode/v0.11/concepts/sponsor.md#withdrawals) request with the given `withdrawal-request-id` from the [request withdrawal command](/reference/airnode/v0.11/packages/admin-cli.md#request-withdrawal) above. - `provider-url`: A valid blockchain provider URL. -- `withdrawal-request-id`: This id was returned by the `request-withdrawal` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `withdrawal-request-id`: This id was returned by the `request-withdrawal` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -575,16 +440,7 @@ npx @api3/airnode-admin check-withdrawal-request ^ ### `verify-airnode-xpub` -Verifies that the `airnode-xpub` belongs to the HDNode with the path -`m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode -address can be derived with provided Airnode -[xpub](/reference/airnode/v0.11/concepts/airnode.md#xpub) with default -derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. -This command will most likely be used by a -[sponsor](/reference/airnode/v0.11/concepts/sponsor.md) to verify that the xpub -belongs to the Airnode before calling the -[derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Verifies that the `airnode-xpub` belongs to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode address can be derived with provided Airnode [xpub](/reference/airnode/v0.11/concepts/airnode.md#xpub) with default derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. This command will most likely be used by a [sponsor](/reference/airnode/v0.11/concepts/sponsor.md) to verify that the xpub belongs to the Airnode before calling the [derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) command. ::: code-group @@ -604,9 +460,7 @@ npx @api3/airnode-admin verify-airnode-xpub ^ ## Airnodes -Helper commands for a previously deployed Airnode. Some of these commands -connect to the AirnodeRrpV0.sol protocol contract where the signer must be the -Airnode wallet. +Helper commands for a previously deployed Airnode. Some of these commands connect to the AirnodeRrpV0.sol protocol contract where the signer must be the Airnode wallet. - [derive-airnode-xpub](/reference/airnode/v0.11/packages/admin-cli.md#derive-airnode-xpub) - [derive-endpoint-id](/reference/airnode/v0.11/packages/admin-cli.md#derive-endpoint-id) @@ -615,13 +469,7 @@ Airnode wallet. ### `derive-airnode-xpub` -Derives the Airnode extended public key -([xpub](/reference/airnode/v0.11/concepts/airnode.md#xpub)). This xpub must be -announced via off-chain channels because it will be needed to derive a -[sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) -address. See the -[derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Derives the Airnode extended public key ([xpub](/reference/airnode/v0.11/concepts/airnode.md#xpub)). This xpub must be announced via off-chain channels because it will be needed to derive a [sponsorWallet](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet) address. See the [derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `airnode-mnemonic`: The Airnode mnemonic for which the xpub is to be derived. @@ -639,15 +487,10 @@ npx @api3/airnode-admin derive-airnode-xpub --airnode-mnemonic "nature about sal ### `derive-endpoint-id` -Derives an -[endpointId](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) -from the OIS title and the endpoint's name as described in the -[endpoint](/reference/airnode/v0.11/concepts/endpoint.md) documentation. Add the -`endpointId` to the config.json file (`triggers.rrp[n].endpointId`). +Derives an [endpointId](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) from the OIS title and the endpoint's name as described in the [endpoint](/reference/airnode/v0.11/concepts/endpoint.md) documentation. Add the `endpointId` to the config.json file (`triggers.rrp[n].endpointId`). - `ois-title`: The title of the OIS from config.json (`ois.title`). -- `endpoint-name`: The name of the endpoint from config.json - (`triggers.rrp[n].endpointName`). +- `endpoint-name`: The name of the endpoint from config.json (`triggers.rrp[n].endpointName`). ::: code-group @@ -667,12 +510,7 @@ npx @api3/airnode-admin derive-endpoint-id ^ ### `generate-airnode-mnemonic` -Generates a unique mnemonic which can be used to create an -[airnode wallet](/reference/airnode/v0.11/concepts/airnode.md#mnemonic). In -addition to the mnemonic, this command will also display the corresponding -[airnode address](/reference/airnode/v0.11/concepts/airnode.md#airnodeaddress) -and its extended public key -([xpub](/reference/airnode/v0.11/concepts/airnode.md#xpub)). +Generates a unique mnemonic which can be used to create an [airnode wallet](/reference/airnode/v0.11/concepts/airnode.md#mnemonic). In addition to the mnemonic, this command will also display the corresponding [airnode address](/reference/airnode/v0.11/concepts/airnode.md#airnodeaddress) and its extended public key ([xpub](/reference/airnode/v0.11/concepts/airnode.md#xpub)). ```sh npx @api3/airnode-admin generate-airnode-mnemonic @@ -680,9 +518,7 @@ npx @api3/airnode-admin generate-airnode-mnemonic ### `generate-mnemonic` -Generates a unique mnemonic which can be used to create a wallet. In addition to -the mnemonic, this command will also display the corresponding default wallet -(path:m/44'/60'/0'/0/0) address. +Generates a unique mnemonic which can be used to create a wallet. In addition to the mnemonic, this command will also display the corresponding default wallet (path:m/44'/60'/0'/0/0) address. ```sh npx @api3/airnode-admin generate-mnemonic @@ -690,12 +526,7 @@ npx @api3/airnode-admin generate-mnemonic ### `derive-airnode-address` -Derives the -[airnode address](/reference/airnode/v0.11/concepts/airnode.md#airnodeaddress) -which is the identifier of the particular Airnode on chain. The address is the -default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this -identifier for many other admin CLI commands, such as -[derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address). +Derives the [airnode address](/reference/airnode/v0.11/concepts/airnode.md#airnodeaddress) which is the identifier of the particular Airnode on chain. The address is the default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this identifier for many other admin CLI commands, such as [derive-sponsor-wallet-address](/reference/airnode/v0.11/packages/admin-cli.md#derive-sponsor-wallet-address). - `airnode-mnemonic`: A mnemonic used to generate the airnode address. @@ -715,18 +546,11 @@ npx @api3/airnode-admin derive-airnode-address ^ ## RequesterAuthorizerWithAirnode -RequesterAuthorizerWithAirnode contract was written by API3 as an -[authorizer](/reference/airnode/v0.11/concepts/authorizers.md) contract that can -be used by any Airnode. Airnode owners can use this contract in addition to -authorizer contracts they have written themselves. +RequesterAuthorizerWithAirnode contract was written by API3 as an [authorizer](/reference/airnode/v0.11/concepts/authorizers.md) contract that can be used by any Airnode. Airnode owners can use this contract in addition to authorizer contracts they have written themselves. -This authorizer contract can whitelist -[requesters](/reference/airnode/v0.11/concepts/requester.md) where each Airnode -is administered by themselves. +This authorizer contract can whitelist [requesters](/reference/airnode/v0.11/concepts/requester.md) where each Airnode is administered by themselves. -These commands connect to the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract. +These commands connect to the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract. - [set-whitelist-expiration](/reference/airnode/v0.11/packages/admin-cli.md#set-whitelist-expiration) - [extend-whitelist-expiration](/reference/airnode/v0.11/packages/admin-cli.md#extend-whitelist-expiration) @@ -736,32 +560,20 @@ contract. ### `set-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration setter to set the -whitelisting expiration of a requester for the Airnode–endpoint pair. This can -hasten expiration in the case the new expiration timestamp is prior to a -previously set timestamp. +Called by the Airnode wallet or a whitelist expiration setter to set the whitelisting expiration of a requester for the Airnode–endpoint pair. This can hasten expiration in the case the new expiration timestamp is prior to a previously set timestamp. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. The mnemonic must be at least an Admin or - Airnode wallet. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -790,31 +602,20 @@ npx @api3/airnode-admin set-whitelist-expiration ^ ### `extend-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration extender to extend the -whitelist expiration of a requester for the Airnode–endpoint pair. This command -expects that the new expiration timestamp is later then the previously set -timestamp. +Called by the Airnode wallet or a whitelist expiration extender to extend the whitelist expiration of a requester for the Airnode–endpoint pair. This command expects that the new expiration timestamp is later then the previously set timestamp. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -843,34 +644,21 @@ npx @api3/airnode-admin extend-whitelist-expiration ^ ### `set-indefinite-whitelist-status` -Called by the Airnode wallet or an indefinite whitelister to whitelist a -requester indefinitely for the Airnode–endpoint pair. This command can be used -to make whitelisting permanent in cases where it is needed to allow requests -even beyond the expiration period. +Called by the Airnode wallet or an indefinite whitelister to whitelist a requester indefinitely for the Airnode–endpoint pair. This command can be used to make whitelisting permanent in cases where it is needed to allow requests even beyond the expiration period. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. The default address of - the mnemonic will be used unless a derivation-path is provided. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. The default address of the mnemonic will be used unless a derivation-path is provided. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. -- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be - whitelisted indefinitely or not. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. +- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be whitelisted indefinitely or not. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -899,17 +687,13 @@ npx @api3/airnode-admin set-indefinite-whitelist-status ^ ### `get-whitelist-status` -Called to get the detailed whitelist status of a requester for the -Airnode–endpoint pair. +Called to get the detailed whitelist status of a requester for the Airnode–endpoint pair. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. ::: code-group @@ -937,9 +721,7 @@ Called to check if a requester is whitelisted to use the Airnode–endpoint pair - `provider-url`: A valid blockchain provider URL. - `requester-authorizer-with-airnode`: The authorizer contract address. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.11/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. @@ -967,8 +749,6 @@ npx @api3/airnode-admin is-requester-whitelisted ^ ## More Examples -You can find more examples in the -[test directory](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin/test) -of the `@api3-dao/airnode/package/admin` repo. +You can find more examples in the [test directory](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin/test) of the `@api3-dao/airnode/package/admin` repo. diff --git a/docs/reference/airnode/v0.11/packages/airnode-abi.md b/docs/reference/airnode/v0.11/packages/airnode-abi.md index 6e46b75a..c83b14b9 100644 --- a/docs/reference/airnode/v0.11/packages/airnode-abi.md +++ b/docs/reference/airnode/v0.11/packages/airnode-abi.md @@ -19,29 +19,15 @@ tags: # {{$frontmatter.title}} -The -[airnode-abi](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-abi) -package is a unique way to encode and decode parameters for use with Airnode. -Parameters are provided with encoding types, names and values. The types are -shortened and grouped with a version as the "header". The name/value pairs are -then grouped and encoded as the rest of the body. - -An advantage of encoding parameters this way is that parameters can be decoded -natively using the language(s) of the specific blockchain. In the case of EVM -blockchains, this means that parameters can be encoded as well as decoded in -Solidity (or Vyper), without any additional requirements. - -You can find additional documentation in -[Airnode ABI Specifications](/reference/airnode/v0.11/specifications/airnode-abi.md) -doc. +The [airnode-abi](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-abi) package is a unique way to encode and decode parameters for use with Airnode. Parameters are provided with encoding types, names and values. The types are shortened and grouped with a version as the "header". The name/value pairs are then grouped and encoded as the rest of the body. + +An advantage of encoding parameters this way is that parameters can be decoded natively using the language(s) of the specific blockchain. In the case of EVM blockchains, this means that parameters can be encoded as well as decoded in Solidity (or Vyper), without any additional requirements. + +You can find additional documentation in [Airnode ABI Specifications](/reference/airnode/v0.11/specifications/airnode-abi.md) doc. ## Installation -You can install -[@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) -with either -[npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) -or [Yarn](https://yarnpkg.com/en/docs/install) +You can install [@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) with either [npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) or [Yarn](https://yarnpkg.com/en/docs/install) ```sh # npm @@ -57,16 +43,13 @@ yarn add @api3/airnode-abi Accepts an array of objects with the following required keys: -1. `type` - The full list of accepted types can be found in the - [Airnode ABI](/reference/airnode/v0.11/specifications/airnode-abi.md#type-encodings) - specifications doc. +1. `type` - The full list of accepted types can be found in the [Airnode ABI](/reference/airnode/v0.11/specifications/airnode-abi.md#type-encodings) specifications doc. 2. `name` 3. `value` -It is important to note that numeric values (`int256` and `uint256`) should be -submitted as **strings** in order to preserve precision. +It is important to note that numeric values (`int256` and `uint256`) should be submitted as **strings** in order to preserve precision. ```ts import { encode } from '@api3/airnode-abi'; @@ -83,11 +66,9 @@ console.log(encodedData); ## `decode` -Returns an object where the keys are the "names" and the values are the "values" -from the initial encoding. +Returns an object where the keys are the "names" and the values are the "values" from the initial encoding. -It is important to note that `int256` and `uint256` will be decoded back to -strings. +It is important to note that `int256` and `uint256` will be decoded back to strings. ```ts import { decode } from '@api3/airnode-abi'; diff --git a/docs/reference/airnode/v0.11/packages/deployer.md b/docs/reference/airnode/v0.11/packages/deployer.md index c9e5f4e4..0b7940c7 100644 --- a/docs/reference/airnode/v0.11/packages/deployer.md +++ b/docs/reference/airnode/v0.11/packages/deployer.md @@ -19,22 +19,11 @@ tags: # {{$frontmatter.title}} -The -[airnode-deployer](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer) -package is used primarily by the -[Docker Images](/reference/airnode/v0.11/docker/). This CLI tool provides the -underlying commands used by the Docker images when deploying an Airnode. API -providers are strongly encouraged to use the -[Docker Images](/reference/airnode/v0.11/docker/) when deploying an Airnode and -not the deployer CLI commands. +The [airnode-deployer](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer) package is used primarily by the [Docker Images](/reference/airnode/v0.11/docker/). This CLI tool provides the underlying commands used by the Docker images when deploying an Airnode. API providers are strongly encouraged to use the [Docker Images](/reference/airnode/v0.11/docker/) when deploying an Airnode and not the deployer CLI commands. ## Usage -The deployer's commands can be run using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), -installing a global npm package or by manually building the airnode-deployer -package. Using npx is the simplest method to interact with the deployer manually -if you do not wish to use the Docker images. +The deployer's commands can be run using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), installing a global npm package or by manually building the airnode-deployer package. Using npx is the simplest method to interact with the deployer manually if you do not wish to use the Docker images. - [Using npx](/reference/airnode/v0.11/packages/deployer.md#using-npx) - [Global Package](/reference/airnode/v0.11/packages/deployer.md#global-package) @@ -42,9 +31,7 @@ if you do not wish to use the Docker images. ### Using npx -The airnode-deployer package can be run as an npm package using npx. This allows -you to run deployer commands without installing the deployer npm package or -having to manually build the airnode-deployer package yourself. +The airnode-deployer package can be run as an npm package using npx. This allows you to run deployer commands without installing the deployer npm package or having to manually build the airnode-deployer package yourself. ```sh npx @api3/airnode-deployer deploy \ @@ -56,8 +43,7 @@ npx @api3/airnode-deployer deploy \ ### Global Package -The airnode-deployer package can be installed globally with yarn or npm. If -installed using yarn make sure yarn bin is added to `PATH`. +The airnode-deployer package can be installed globally with yarn or npm. If installed using yarn make sure yarn bin is added to `PATH`. ```sh yarn global add @api3/airnode-deployer @@ -120,27 +106,18 @@ cp config/secrets.env.example config/secrets.env ## Credentials -When using the `airnode-deployer` Docker image, AWS or GCP credentials are -loaded automatically. Conversely, when using the deployer CLI directly, you will -need to first load AWS or GCP credentials into the environment manually as -described below. +When using the `airnode-deployer` Docker image, AWS or GCP credentials are loaded automatically. Conversely, when using the deployer CLI directly, you will need to first load AWS or GCP credentials into the environment manually as described below. ### AWS Credentials For AWS, there are two options: -1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` - (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their - appropriate values. -2. Populate the AWS `credentials` file. See the AWS documentation for the - [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) - as well as its - [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). +1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their appropriate values. +2. Populate the AWS `credentials` file. See the AWS documentation for the [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) as well as its [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). ### GCP Credentials -Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of -the `gcp.json` credentials file. +Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the `gcp.json` credentials file. ## Commands @@ -153,33 +130,20 @@ the `gcp.json` credentials file. ### Airnode Deployment -When creating or updating an Airnode the `config.json` and `secrets.env` files -are needed. You can use the provided example -[config.json](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-deployer/config/config.example.json) -and -[secrets.env](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-deployer/config/secrets.example.env) -templates to get started quickly, but you will need to edit these with your own -API details and secrets. +When creating or updating an Airnode the `config.json` and `secrets.env` files are needed. You can use the provided example [config.json](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-deployer/config/config.example.json) and [secrets.env](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-deployer/config/secrets.example.env) templates to get started quickly, but you will need to edit these with your own API details and secrets. -Make sure `config.json` and `secrets.env` are available in the path for the -`--configuration` argument. +Make sure `config.json` and `secrets.env` are available in the path for the `--configuration` argument. #### deploy -When executed, the `deploy` command defaults to creating a `receipt.json` file -in the `config/` directory, although a different path can be specified using the -path and name with the `--receipt` argument. The receipt contains metadata about -the deployment and can be used to remove the Airnode. +When executed, the `deploy` command defaults to creating a `receipt.json` file in the `config/` directory, although a different path can be specified using the path and name with the `--receipt` argument. The receipt contains metadata about the deployment and can be used to remove the Airnode. -By default the deployer will save logs into the `config/logs/` directory. This -can be changed with the `--logs` argument. +By default the deployer will save logs into the `config/logs/` directory. This can be changed with the `--logs` argument. -If the deployment isn't successful, the command will try to automatically remove -deployed resources. You can disable this by running the deploy command with a -`--no-auto-remove` argument. +If the deployment isn't successful, the command will try to automatically remove deployed resources. You can disable this by running the deploy command with a `--no-auto-remove` argument. ```bash # Deploys an Airnode instance using the config.json and @@ -207,19 +171,15 @@ airnode-deployer deploy \ --logs config/logs/ ``` -See how [deploy](/reference/airnode/v0.11/docker/deployer-image.md#deploy) is -used via the AWS/GCP deployer image. +See how [deploy](/reference/airnode/v0.11/docker/deployer-image.md#deploy) is used via the AWS/GCP deployer image. ### Listing Airnodes -Once you've already deployed one or more Airnode, you can list your currently -deployed instances using the `list` command. +Once you've already deployed one or more Airnode, you can list your currently deployed instances using the `list` command. #### list -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ```bash # Lists deployed Airnode instances @@ -239,14 +199,11 @@ airnode-deployer list airnode-deployer list --cloud-providers gcp ``` -See how [list](/reference/airnode/v0.11/docker/deployer-image.md#list) is used -via the AWS/GCP deployer image. +See how [list](/reference/airnode/v0.11/docker/deployer-image.md#list) is used via the AWS/GCP deployer image. ### Fetching deployment information -You can use the `info` command to retrieve information about existing -deployments. The retrieved information include deployment's Airnode address, -stage, Airnode version and the update history. +You can use the `info` command to retrieve information about existing deployments. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. #### info @@ -266,8 +223,7 @@ Options: airnode-deployer info aws2c6ef2b3 ``` -See how [info](/reference/airnode/v0.11/docker/deployer-image.md#info) is used -via the AWS/GCP deployer image. +See how [info](/reference/airnode/v0.11/docker/deployer-image.md#info) is used via the AWS/GCP deployer image. ### Reverting to a previous version @@ -294,14 +250,11 @@ Options: airnode-deployer rollback aws808e2a22 5bbcd317 ``` -See how [rollback](/reference/airnode/v0.11/docker/deployer-image.md#rollback) -is used via the AWS/GCP deployer image. +See how [rollback](/reference/airnode/v0.11/docker/deployer-image.md#rollback) is used via the AWS/GCP deployer image. ### Fetching deployment files -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the `fetch-files` command to -retrieve them. +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the `fetch-files` command to retrieve them. #### fetch-files @@ -320,19 +273,14 @@ Options: airnode-deployer fetch-files aws2c6ef2b3 ``` -See how -[fetch-files](/reference/airnode/v0.11/docker/deployer-image.md#fetch-files) is -used via the AWS/GCP deployer image. +See how [fetch-files](/reference/airnode/v0.11/docker/deployer-image.md#fetch-files) is used via the AWS/GCP deployer image. ### Airnode Removal An Airnode can be removed in two different ways: -- **Best:** With `remove`, which uses the deployment ID found either in the - [deployment receipt file](/reference/airnode/v0.11/deployment-files/receipt-json.md) - or via the `list` command. -- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt - created when the Airnode was deployed. +- **Best:** With `remove`, which uses the deployment ID found either in the [deployment receipt file](/reference/airnode/v0.11/deployment-files/receipt-json.md) or via the `list` command. +- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt created when the Airnode was deployed. #### remove @@ -352,8 +300,7 @@ Options: airnode-deployer remove aws2c6ef2b3 ``` -See how [remove](/reference/airnode/v0.11/docker/deployer-image.md#remove) is -used via the AWS/GCP deployer image. +See how [remove](/reference/airnode/v0.11/docker/deployer-image.md#remove) is used via the AWS/GCP deployer image. #### remove-with-receipt @@ -376,8 +323,6 @@ airnode-deployer remove-with-receipt \ --logs config/logs/ ``` -See how -[remove-with-receipt](/reference/airnode/v0.11/docker/deployer-image.md#remove-with-receipt) -is used via the AWS/GCP deployer image. +See how [remove-with-receipt](/reference/airnode/v0.11/docker/deployer-image.md#remove-with-receipt) is used via the AWS/GCP deployer image. diff --git a/docs/reference/airnode/v0.11/packages/index.md b/docs/reference/airnode/v0.11/packages/index.md index 82122a91..deb37c34 100644 --- a/docs/reference/airnode/v0.11/packages/index.md +++ b/docs/reference/airnode/v0.11/packages/index.md @@ -19,13 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode is a fully-serverless oracle node that is designed specifically for API -providers to operate their own oracles. Its code base is a monorepo managed -using [Lerna](https://github.com/lerna/lerna). The -[Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.11/packages) has -several packages. Some of these packages are used by dApp developers and API -providers to interact with or to build Airnode. A few are simply used for -internal Airnode development. +Airnode is a fully-serverless oracle node that is designed specifically for API providers to operate their own oracles. Its code base is a monorepo managed using [Lerna](https://github.com/lerna/lerna). The [Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.11/packages) has several packages. Some of these packages are used by dApp developers and API providers to interact with or to build Airnode. A few are simply used for internal Airnode development. - [airnode-adapter](/reference/airnode/v0.11/packages/adapter.md) - [airnode-admin](/reference/airnode/v0.11/packages/admin-cli.md) @@ -36,49 +30,30 @@ internal Airnode development. **Read about each package in the monorepo.** -Airnode packages are cross platform, available as npm packages or docker -containers. You should also be able to clone, build and use the packages on any -platform. However there is no guarantee that the development only features (e.g. -test or examples) will work out of the box. It is recommend to use UNIX based -systems for development. If you are using Windows, consider -[WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). +Airnode packages are cross platform, available as npm packages or docker containers. You should also be able to clone, build and use the packages on any platform. However there is no guarantee that the development only features (e.g. test or examples) will work out of the box. It is recommend to use UNIX based systems for development. If you are using Windows, consider [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). -- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-adapter) - The module that makes an API call, processes the response and returns a single - value. +- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-adapter) The module that makes an API call, processes the response and returns a single value. -- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin) - A package/CLI tool to interact with the Airnode contracts across chains. +- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-admin) A package/CLI tool to interact with the Airnode contracts across chains. -- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-abi) - Encoding and decoding utilities for Airnode according to the - [Airnode ABI specifications](/reference/airnode/v0.11/specifications/airnode-abi.md). +- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-abi) Encoding and decoding utilities for Airnode according to the [Airnode ABI specifications](/reference/airnode/v0.11/specifications/airnode-abi.md). -- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer) - Tools to automate Airnode deployment. +- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer) Tools to automate Airnode deployment. -- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples) - A public list of examples showcasing the features of Airnode. +- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples) A public list of examples showcasing the features of Airnode. -- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-node) - The node part of Airnode that allows for connecting multiple blockchains to - the rest of the world. +- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-node) The node part of Airnode that allows for connecting multiple blockchains to the rest of the world. -- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-operation) - Development and testing utilities for the core parts of Airnode. +- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-operation) Development and testing utilities for the core parts of Airnode. -- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-protocol) - Contracts that implement Airnode RRP (request–response protocol). +- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-protocol) Contracts that implement Airnode RRP (request–response protocol). -- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-validator) - A package that can be used to validate Airnode configuration. +- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-validator) A package that can be used to validate Airnode configuration. ## OIS -The `airnode-ois` monorepo package was removed from the Airnode repo and is now -in its own repo (`ois`) starting with Airnode `v0.8`. +The `airnode-ois` monorepo package was removed from the Airnode repo and is now in its own repo (`ois`) starting with Airnode `v0.8`. -- [ois:](https://github.com/api3dao/ois/tree/v2.1.0) Types for - [Oracle Integration Specification (OIS)](/reference/ois/2.1/specification.md). +- [ois:](https://github.com/api3dao/ois/tree/v2.1.0) Types for [Oracle Integration Specification (OIS)](/reference/ois/2.1/specification.md). diff --git a/docs/reference/airnode/v0.11/packages/validator.md b/docs/reference/airnode/v0.11/packages/validator.md index f38863ea..aa014862 100644 --- a/docs/reference/airnode/v0.11/packages/validator.md +++ b/docs/reference/airnode/v0.11/packages/validator.md @@ -19,26 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-validator](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-validator) -is used internally by the [Docker Images](/reference/airnode/v0.11/docker/) to -validate the -[configuration files](/reference/airnode/v0.11/understand/configuring.md) you -provide when deploying an Airnode. - -However, validator can also be used as a standalone package to verify the -correctness of the configuration files without deploying the Airnode. The -recommended way is to use the -[validator CLI](/reference/airnode/v0.11/packages/validator.md#cli-usage), but -for advanced use cases you can use the -[validator SDK](/reference/airnode/v0.11/packages/validator.md#sdk-usage). +The [airnode-validator](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-validator) is used internally by the [Docker Images](/reference/airnode/v0.11/docker/) to validate the [configuration files](/reference/airnode/v0.11/understand/configuring.md) you provide when deploying an Airnode. + +However, validator can also be used as a standalone package to verify the correctness of the configuration files without deploying the Airnode. The recommended way is to use the [validator CLI](/reference/airnode/v0.11/packages/validator.md#cli-usage), but for advanced use cases you can use the [validator SDK](/reference/airnode/v0.11/packages/validator.md#sdk-usage). ## CLI Usage -The simplest way to run the CLI is using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). -Alternatively, you can install the validator package as a dependency in your -project. +The simplest way to run the CLI is using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). Alternatively, you can install the validator package as a dependency in your project. ```sh npx @api3/airnode-validator --config "config.json" --secrets "secrets.env" @@ -58,8 +45,7 @@ npx airnode-validator --config "config.json" --secrets "secrets.env" ### Examples -Assuming the configurations files inside current working directory are valid, -executing: +Assuming the configurations files inside current working directory are valid, executing: ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "valid-secrets.env" @@ -71,8 +57,7 @@ yields: ✔ The configuration is valid ``` -When there is an error during validation, the command prints out the error and -fails with a non zero status code. +When there is an error during validation, the command prints out the error and fails with a non zero status code. ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "non-existent-secrets.env" @@ -86,26 +71,17 @@ yields: ## SDK Usage -The validator package contains an API that can be used to validate Airnode -configuration files programatically. +The validator package contains an API that can be used to validate Airnode configuration files programatically. The following functions can be used: -- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` and validates the interpolated configuration. Expects both `config` - and `secrets` to be JSON objects. -- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a - JSON object. -- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be - a JSON object. -- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be - a JSON object. -- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` but does not perform any validation afterwards. Use this function - only when you can guarantee that the configuration is valid. - -Validator has also full TypeScript support. All of these functions return a -typed object. +- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` and validates the interpolated configuration. Expects both `config` and `secrets` to be JSON objects. +- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a JSON object. +- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be a JSON object. +- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be a JSON object. +- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` but does not perform any validation afterwards. Use this function only when you can guarantee that the configuration is valid. + +Validator has also full TypeScript support. All of these functions return a typed object. ### Examples @@ -148,7 +124,6 @@ if (parseResult.success) { ## Build Manually -See the build instructions for the validator in the -[airnode package repository](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-validator). +See the build instructions for the validator in the [airnode package repository](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-validator). diff --git a/docs/reference/airnode/v0.11/specifications/airnode-abi.md b/docs/reference/airnode/v0.11/specifications/airnode-abi.md index c471e58f..8fee8d16 100644 --- a/docs/reference/airnode/v0.11/specifications/airnode-abi.md +++ b/docs/reference/airnode/v0.11/specifications/airnode-abi.md @@ -19,39 +19,23 @@ tags: # {{$frontmatter.title}} -[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) -is used to encode different types of data while interacting with Ethereum -contracts. As a result, both Solidity and modules such as -[web3.js](https://web3js.readthedocs.io/) and -[ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality -as a first-class citizen. This makes using contract ABI for encoding API call -parameters a very attractive option. - -Although encoding API call parameters using contract ABI has many advantages, it -cannot be used for this purpose directly. Quoting from the -[Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): - -> The encoding is not self describing and thus requires a schema in order to -> decode. - -This means that when passing API call parameters (of type `bytes`), you would -also need to pass a list of the types for these parameters, which is cumbersome -and it is not clear how these types would be encoded. As a solution, Airnode -uses _Airnode ABI specifications_, an extension of contract ABI specifications -that includes a header that keeps the schema. +[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) is used to encode different types of data while interacting with Ethereum contracts. As a result, both Solidity and modules such as [web3.js](https://web3js.readthedocs.io/) and [ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality as a first-class citizen. This makes using contract ABI for encoding API call parameters a very attractive option. + +Although encoding API call parameters using contract ABI has many advantages, it cannot be used for this purpose directly. Quoting from the [Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): + +> The encoding is not self describing and thus requires a schema in order to decode. + +This means that when passing API call parameters (of type `bytes`), you would also need to pass a list of the types for these parameters, which is cumbersome and it is not clear how these types would be encoded. As a solution, Airnode uses _Airnode ABI specifications_, an extension of contract ABI specifications that includes a header that keeps the schema. ## Header -The Airnode ABI specifications header is of type `bytes32` and acts as the -schema (i.e., describes the types of the API call parameters). The header is -encoded in UTF-8 for ease of use. Here is an example: +The Airnode ABI specifications header is of type `bytes32` and acts as the schema (i.e., describes the types of the API call parameters). The header is encoded in UTF-8 for ease of use. Here is an example: ``` "1BSasbiuBa" ``` -The first character, `1`, represents the encoding version. Each following -character represents the type of an API call parameter. +The first character, `1`, represents the encoding version. Each following character represents the type of an API call parameter. ### Type encodings @@ -68,20 +52,11 @@ i: int256 f: bool ``` -Note that dynamically-sized types are represented with uppercase letters and -statically-sized types are represented with lowercase letters. Another thing to -notice is that `s` represents `string32`, but this is an artificial type and it -is not part of -[solidity types](https://docs.soliditylang.org/en/latest/types.html). This type -is instead represented on chain as `bytes32`. The reasons for this are explained -in depth in -[string32 details](/reference/airnode/v0.11/specifications/airnode-abi.md#string32) -section. +Note that dynamically-sized types are represented with uppercase letters and statically-sized types are represented with lowercase letters. Another thing to notice is that `s` represents `string32`, but this is an artificial type and it is not part of [solidity types](https://docs.soliditylang.org/en/latest/types.html). This type is instead represented on chain as `bytes32`. The reasons for this are explained in depth in [string32 details](/reference/airnode/v0.11/specifications/airnode-abi.md#string32) section. ## Encoding format -Airnode ABI specifications has the following encoding format (which is somewhat -similar to [SDS](https://github.com/antirez/sds)): +Airnode ABI specifications has the following encoding format (which is somewhat similar to [SDS](https://github.com/antirez/sds)): ``` [------------------------][-----------------------------------------] @@ -125,14 +100,11 @@ bytes memory parameters = abi.encode( ); ``` -Note that you do not need to add an external library to the contract, and -`abi.encode()` is fairly cheap in terms of gas usage (compared to alternative -encoding methods). +Note that you do not need to add an external library to the contract, and `abi.encode()` is fairly cheap in terms of gas usage (compared to alternative encoding methods). ## Example decoding -If you know the schema of the encoded parameters, then decode them on-chain. For -example, if the schema is `(bytes,string)`: +If you know the schema of the encoded parameters, then decode them on-chain. For example, if the schema is `(bytes,string)`: ```solidity ( @@ -142,17 +114,13 @@ example, if the schema is `(bytes,string)`: ) = abi.decode(parameters, (bytes32,bytes32,bytes,bytes32,string)); ``` -Note that this disregards the header and hard codes the schema into the code. It -is also possible to parse the header on-chain and decode accordingly, yet that -would be a lot more complex. +Note that this disregards the header and hard codes the schema into the code. It is also possible to parse the header on-chain and decode accordingly, yet that would be a lot more complex. ## Details ### `string32` -A parameter being of type `string32` (encoded as characted `s` in the ABI -specification schema header) implies that the parameter is UTF-8 encoded text. -For example, if the parameter is +A parameter being of type `string32` (encoded as characted `s` in the ABI specification schema header) implies that the parameter is UTF-8 encoded text. For example, if the parameter is ``` 0x68656c6c6f000000000000000000000000000000000000000000000000000000 @@ -164,9 +132,7 @@ Airnode will decode it as "hello" ``` -and feed that to the API, which is what the user would want to do in most cases. -This becomes a problem if the parameter is not encoded text, but for example a -hash such as: +and feed that to the API, which is what the user would want to do in most cases. This becomes a problem if the parameter is not encoded text, but for example a hash such as: ``` 0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71 @@ -179,15 +145,11 @@ If this hash is encoded as a `string32` type, Airnode will decode it as: !Õ$B˜±=/¡>q ``` -which is probably not what the user is looking for. For these use cases, the -user should use the -[`bytes32`](/reference/airnode/v0.11/specifications/airnode-abi.md#bytes32) type -instead. +which is probably not what the user is looking for. For these use cases, the user should use the [`bytes32`](/reference/airnode/v0.11/specifications/airnode-abi.md#bytes32) type instead. ### `bytes32` -To encode a `bytes32` hash on chain, use the `bytes32` type which is represented -by `b` in the ABI header schema. +To encode a `bytes32` hash on chain, use the `bytes32` type which is represented by `b` in the ABI header schema. ```solidity bytes memory parameters = abi.encode( @@ -202,46 +164,27 @@ When decoded by Airnode, the value would be the hash itself: "0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71" ``` -If you want to store 32 byte string values on chain, use the -[`string32`](/reference/airnode/v0.11/specifications/airnode-abi.md#string32) -type instead. +If you want to store 32 byte string values on chain, use the [`string32`](/reference/airnode/v0.11/specifications/airnode-abi.md#string32) type instead. ### `bool` -The `bool` type, encoded as character `f` using the ABI specification schema can -be used to encode a boolean value. The header symbol is `f`, because character -`b` was already reserved for bytes encodings. So we chose letter `f` as bool -values are commonly used to represent "boolean flags". +The `bool` type, encoded as character `f` using the ABI specification schema can be used to encode a boolean value. The header symbol is `f`, because character `b` was already reserved for bytes encodings. So we chose letter `f` as bool values are commonly used to represent "boolean flags". ### Omitted types -`array` and `tuple` are omitted because they are not suitable to be used as API -parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because -they are padded to 32 bytes by the ABI encoder anyway (meaning that the user -should simply typecast these to the 32-byte versions). +`array` and `tuple` are omitted because they are not suitable to be used as API parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because they are padded to 32 bytes by the ABI encoder anyway (meaning that the user should simply typecast these to the 32-byte versions). ### Size limit -The header can encode up to 31 parameters (and 1 byte is used to encode the -encoding version). This is far more than what would be needed in practice, and -thus is tolerated to avoid a more complex solution. +The header can encode up to 31 parameters (and 1 byte is used to encode the encoding version). This is far more than what would be needed in practice, and thus is tolerated to avoid a more complex solution. ### Padding -[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) -is used so that you can decode the values later on. This means that each -parameter will be padded with zeros to complete them to 32 bytes. Although this -padding increases gas costs, ABI encoding/decoding functions being cheap -balances this. Furthermore, the -[template](/reference/airnode/v0.11/concepts/template.md) pattern used in the -protocols allows for the referencing of these encoded parameters without -explicitly passing them in requests, making the increased cost induced by -padding irrelevant in most cases. +[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) is used so that you can decode the values later on. This means that each parameter will be padded with zeros to complete them to 32 bytes. Although this padding increases gas costs, ABI encoding/decoding functions being cheap balances this. Furthermore, the [template](/reference/airnode/v0.11/concepts/template.md) pattern used in the protocols allows for the referencing of these encoded parameters without explicitly passing them in requests, making the increased cost induced by padding irrelevant in most cases. ## `@api3/airnode-abi` -Encode and decode parameters with the -[airnode-abi](/reference/airnode/v0.11/packages/airnode-abi.md) package. +Encode and decode parameters with the [airnode-abi](/reference/airnode/v0.11/packages/airnode-abi.md) package. ```js import { encode } from '@api3/airnode-abi'; @@ -258,13 +201,6 @@ console.log('ENCODED:', encodedData); console.log('\nDECODED:', decoded); ``` -See the package doc -[airnode-abi](/reference/airnode/v0.11/packages/airnode-abi.md) for more -information on how to encode and decode with Airnode ABI off-chain. Also see -code samples in the -[examples](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples) -package. Lastly see the file -[request-utils.ts](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) -for example syntax on encoding parameters. +See the package doc [airnode-abi](/reference/airnode/v0.11/packages/airnode-abi.md) for more information on how to encode and decode with Airnode ABI off-chain. Also see code samples in the [examples](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples) package. Lastly see the file [request-utils.ts](https://github.com/api3dao/airnode/blob/v0.11/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) for example syntax on encoding parameters. diff --git a/docs/reference/airnode/v0.11/specifications/ois.md b/docs/reference/airnode/v0.11/specifications/ois.md index e50a6596..49859260 100644 --- a/docs/reference/airnode/v0.11/specifications/ois.md +++ b/docs/reference/airnode/v0.11/specifications/ois.md @@ -19,13 +19,8 @@ tags: # {{$frontmatter.title}} -The `ois` JSON object, in the `config.json` file that defines an Airnode, is an -integral part of an Airnode's understanding of an API's specification and its -endpoints. OIS provide a description of API endpoints and maps Airnode endpoints -to them. There can be more than one OIS object in the `config.json` file as -Airnode can serve endpoints from more than one API. - -Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) -in its versioned document set. +The `ois` JSON object, in the `config.json` file that defines an Airnode, is an integral part of an Airnode's understanding of an API's specification and its endpoints. OIS provide a description of API endpoints and maps Airnode endpoints to them. There can be more than one OIS object in the `config.json` file as Airnode can serve endpoints from more than one API. + +Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) in its versioned document set. diff --git a/docs/reference/airnode/v0.11/specifications/reserved-parameters.md b/docs/reference/airnode/v0.11/specifications/reserved-parameters.md index 5175291c..c29bae1e 100644 --- a/docs/reference/airnode/v0.11/specifications/reserved-parameters.md +++ b/docs/reference/airnode/v0.11/specifications/reserved-parameters.md @@ -19,10 +19,6 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an Airnode's defined endpoints in an -[Oracle Integration Specifications (OIS)](/reference/ois/2.1/) object. They do -not map to operation parameters and are used by Airnode for special purposes. -See the [Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) doc in -the OIS document set for an in-depth explanation. +Reserved parameters are part of an Airnode's defined endpoints in an [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) object. They do not map to operation parameters and are used by Airnode for special purposes. See the [Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) doc in the OIS document set for an in-depth explanation. diff --git a/docs/reference/airnode/v0.11/understand/api-integration.md b/docs/reference/airnode/v0.11/understand/api-integration.md index 009074c8..69081a1f 100644 --- a/docs/reference/airnode/v0.11/understand/api-integration.md +++ b/docs/reference/airnode/v0.11/understand/api-integration.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -A successful integration of an API with an Airnode requires the mapping of each -other's interface. This is accomplished using an OIS -([Oracle Integration Specifications](/reference/ois/2.1/specification.md)) json -object, found in the config.json file, designed to with three basic steps. +A successful integration of an API with an Airnode requires the mapping of each other's interface. This is accomplished using an OIS ([Oracle Integration Specifications](/reference/ois/2.1/specification.md)) json object, found in the config.json file, designed to with three basic steps. 1. API operations are specified 1. Airnode endpoints are specified @@ -34,60 +31,36 @@ object, found in the config.json file, designed to with three basic steps. > >

The OIS object in config.json contains mapping information of API operations to Airnode endpoint definitions.

-OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode -endpoints. When a requester contract calls one of the AirnodeRrpV0.sol -contract's request functions, such as `makeFullRequest(..., callData)`, the -callData is communicated to the off-chain Airnode which uses OIS mappings to -translate the callData into a valid HTTP request for the appropriate API -operation. +OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode endpoints. When a requester contract calls one of the AirnodeRrpV0.sol contract's request functions, such as `makeFullRequest(..., callData)`, the callData is communicated to the off-chain Airnode which uses OIS mappings to translate the callData into a valid HTTP request for the appropriate API operation. -OIS borrows formatting from -[OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). -If you have experience with OAS, OIS will seem familiar. +OIS borrows formatting from [OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). If you have experience with OAS, OIS will seem familiar. ::: info OAS -It is not recommended to refer to OAS for help while creating your OIS object. -OIS only borrows formatting practices from OAS. Everything needed to create an -OIS object is in these docs. +It is not recommended to refer to OAS for help while creating your OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: **Tips while reading ths page.** -- Open the [OIS template](/reference/ois/2.1/template.md) in another browser - window to follow along. -- View an example of an Airnode - [config.json](/reference/airnode/v0.11/deployment-files/examples/config-json.md) - file. +- Open the [OIS template](/reference/ois/2.1/template.md) in another browser window to follow along. +- View an example of an Airnode [config.json](/reference/airnode/v0.11/deployment-files/examples/config-json.md) file. ## OIS Template -OIS is a json object that is added to an Airnode's -[config.json](/reference/airnode/v0.11/deployment-files/templates/config-json.md) -file as the (`ois`) _key_, sometimes called a _field_. Try using the -[OIS template](/reference/ois/2.1/template.md) to construct an OIS and add it to -the Airnode's config.json file later. +OIS is a json object that is added to an Airnode's [config.json](/reference/airnode/v0.11/deployment-files/templates/config-json.md) file as the (`ois`) _key_, sometimes called a _field_. Try using the [OIS template](/reference/ois/2.1/template.md) to construct an OIS and add it to the Airnode's config.json file later. -In the OIS template, there are some fields that contain `{FILL_*}`. This means -that the value added is independent from other fields. On the other hand, if two -fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), -you must use the same value in them, because they are referencing each other. +In the OIS template, there are some fields that contain `{FILL_*}`. This means that the value added is independent from other fields. On the other hand, if two fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), you must use the same value in them, because they are referencing each other. -OIS uses a simplified version of the OAS. This means that if you have the -OpenAPI specifications of the API that you are going to integrate, you are about -80% done, because you can copy paste entire sections (but be sure to make the -necessary modifications to conform to the OIS format). +OIS uses a simplified version of the OAS. This means that if you have the OpenAPI specifications of the API that you are going to integrate, you are about 80% done, because you can copy paste entire sections (but be sure to make the necessary modifications to conform to the OIS format). -The remainder of this page will assume you do not have the OpenAPI -specifications of the API that you will be integrating. +The remainder of this page will assume you do not have the OpenAPI specifications of the API that you will be integrating. ## 1. Specify OIS Definitions -Start building an OIS by adding three descriptive fields to the root of the OIS -json object. +Start building an OIS by adding three descriptive fields to the root of the OIS json object. ```json { @@ -100,20 +73,15 @@ json object. ### oisFormat -A specific version of the -[OIS Specification](/reference/ois/2.1/specification.md#_1-oisformat) to be -used. For Airnode `v0.11.2`, the proper OIS version is `2.1.0`. +A specific version of the [OIS Specification](/reference/ois/2.1/specification.md#_1-oisformat) to be used. For Airnode `v0.11.2`, the proper OIS version is `2.1.0`. ### title -This is a unique title of the OIS. Note that an Airnode can be configured with -more than one OIS object and uses the title as the OIS identifier. +This is a unique title of the OIS. Note that an Airnode can be configured with more than one OIS object and uses the title as the OIS identifier. ### version -This is the version of the OIS which allows for version-control of the OIS -integration. It is recommended to use [semver](https://semver.org/) versioning. -The initial version could be `0.1.0`. +This is the version of the OIS which allows for version-control of the OIS integration. It is recommended to use [semver](https://semver.org/) versioning. The initial version could be `0.1.0`. @@ -134,15 +102,11 @@ The `apiSpecifications` field is used to describe the API and its operations. ### Servers -The first step of specifying an API is to enter its _baseURL_ in the -`apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed -in the `apiSpecifications.servers` array. A warning is raised during conversion -if servers has multiple elements. This baseURL will apply to all operations. +The first step of specifying an API is to enter its _baseURL_ in the `apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed in the `apiSpecifications.servers` array. A warning is raised during conversion if servers has multiple elements. This baseURL will apply to all operations. #### Choosing a Base URL -Consider the following full URL to execute an API operation that returns all -know tokens. +Consider the following full URL to execute an API operation that returns all know tokens. @@ -164,16 +128,11 @@ or > > **path:** `/data` -Because the call will be made to <`baseURL+path`> both will result in the same -full URL. +Because the call will be made to <`baseURL+path`> both will result in the same full URL. -Set the baseURL as the section of the full URL that you expect to be shared by -all operations. From the examples above it is recommended to use -`https://www.myapi.com`, in case additional paths starting with `/v2` get added -to the API in the future. As you can tell, API integration requires many -subjective choices, and is more art than science. +Set the baseURL as the section of the full URL that you expect to be shared by all operations. From the examples above it is recommended to use `https://www.myapi.com`, in case additional paths starting with `/v2` get added to the API in the future. As you can tell, API integration requires many subjective choices, and is more art than science. ```json "apiSpecifications": { @@ -188,20 +147,15 @@ subjective choices, and is more art than science. ### Paths -The _paths_ field defines all the API operations much like an OpenAPI -Specification file. +The _paths_ field defines all the API operations much like an OpenAPI Specification file. _What is an API operation?_ -> An API operation is specified as a unique combination of a _**path**_ and an -> HTTP _**method**_. `GET /token/{id}` +> An API operation is specified as a unique combination of a _**path**_ and an HTTP _**method**_. `GET /token/{id}` #### Operations -In the examples below, `GET` refers to an -[HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). -This implies that you could have another API operation that can be specified -using a different method but the same path. +In the examples below, `GET` refers to an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). This implies that you could have another API operation that can be specified using a different method but the same path. > path: /data > @@ -211,18 +165,11 @@ using a different method but the same path. > > method: POST -Therefore, a path is not enough to specify an API operation by itself, you must -also provide a method. If a new path is needed then it must be a new object in -paths with its own methods. Currently only the GET and POST methods are -supported by Airnode. +Therefore, a path is not enough to specify an API operation by itself, you must also provide a method. If a new path is needed then it must be a new object in paths with its own methods. Currently only the GET and POST methods are supported by Airnode. -With regards to the [OIS template](/reference/ois/2.1/template.md), the name of -the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., -`/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the -operation to integrate (e.g., `get`). The method must be lowercase. +With regards to the [OIS template](/reference/ois/2.1/template.md), the name of the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., `/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the operation to integrate (e.g., `get`). The method must be lowercase. -The following example illustrates three operations, `GET /data`, `POST /data`, -`GET /tokens`. +The following example illustrates three operations, `GET /data`, `POST /data`, `GET /tokens`. ```json "paths": { @@ -244,27 +191,16 @@ The following example illustrates three operations, `GET /data`, `POST /data`, #### Parameters (operation) -After specifying the path and method of an API operation, the final step is to -specify its parameters. Each parameter is an object in the -`apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` -and `name`. `in` tells where the parameter goes in the HTTP request and `name` -tells the name that the parameter value will be sent under. Currently Airnode -supports the following parameter types for use with `in`. +After specifying the path and method of an API operation, the final step is to specify its parameters. Each parameter is an object in the `apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` and `name`. `in` tells where the parameter goes in the HTTP request and `name` tells the name that the parameter value will be sent under. Currently Airnode supports the following parameter types for use with `in`. - query - header - path - cookie -When integrating a POST method, define the body parameters with `in: query`. -Airnode will convert all `query` types into the `requestBody`. Note that only -the non-nested application/json content-type is supported. +When integrating a POST method, define the body parameters with `in: query`. Airnode will convert all `query` types into the `requestBody`. Note that only the non-nested application/json content-type is supported. -It is not necessary to specify all API operation parameters, but only the ones -the on-chain requester will need to be able to provide (see Airnode endpoint -[parameters](/reference/airnode/v0.11/understand/api-integration.md#parameters)), -and the ones needed to hard-code a value for (see Airnode endpoint -[fixed operation parameters](/reference/airnode/v0.11/understand/api-integration.md#fixedoperationparameters)). +It is not necessary to specify all API operation parameters, but only the ones the on-chain requester will need to be able to provide (see Airnode endpoint [parameters](/reference/airnode/v0.11/understand/api-integration.md#parameters)), and the ones needed to hard-code a value for (see Airnode endpoint [fixed operation parameters](/reference/airnode/v0.11/understand/api-integration.md#fixedoperationparameters)). ```json "paths": { @@ -287,8 +223,7 @@ and the ones needed to hard-code a value for (see Airnode endpoint _Example: Get a token_ -The `GET /token/{id}` returns a token using the token's `id` which is a `path` -parameter. +The `GET /token/{id}` returns a token using the token's `id` which is a `path` parameter. | Method | Path | in | name | | ------ | ----------- | ---- | ---- | @@ -296,11 +231,7 @@ parameter. _Example: Create a token_ -The `POST /token` operation accepts three parameters. The name and description -of the token are placed in the type `query` and will be moved by Airnode to the -requestBody upon calling the API operation. The third is a `header` parameter -that describes the Content-Type of the request such as `application/json` or -`application/x-www-form-urlencoded`. +The `POST /token` operation accepts three parameters. The name and description of the token are placed in the type `query` and will be moved by Airnode to the requestBody upon calling the API operation. The third is a `header` parameter that describes the Content-Type of the request such as `application/json` or `application/x-www-form-urlencoded`. | Method | Path | in | name | | ------ | ------ | ------ | ----------- | @@ -310,9 +241,7 @@ that describes the Content-Type of the request such as `application/json` or _Example: Get all tokens_ -The `GET /tokens` returns a list of all tokens. The list count can be limited -using the `limit' parameter which the API operation considers as optional since -it will not return an error if omitted. +The `GET /tokens` returns a list of all tokens. The list count can be limited using the `limit' parameter which the API operation considers as optional since it will not return an error if omitted. > `GET /tokens` returns all tokens. > @@ -326,66 +255,25 @@ it will not return an error if omitted. ## 3. Specifying Airnode Endpoints -An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It -maps to an API operation, but the nature of this mapping is customizable. It is -the integrator's job to define what this service is. - -For example, if an API operation returns an asset price given its ticker (e.g., -`BTC`), specify the endpoint such that the requester provides the ticker as a -parameter. The resulting endpoint would be a general one that returns prices for -any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price -will be returned (using -[fixed operation parameters](/reference/airnode/v0.11/understand/api-integration.md#fixedoperationparameters)), -which would make the endpoint a specific one that only returns the BTC price. - -The recommended endpoint definition pattern is to create an Airnode endpoint for -each API operation, and allow the requesters to provide all operation parameters -themselves. This results in optimal flexibility, and essentially allows the -requesters to use the entire API functionality on-chain. Normally, competitor -oracle integrations strive to hard-code as many API parameters as possible -because passing these parameters on-chain results in a gas cost overhead. -However, the Airnode protocol uses -[templates](/reference/airnode/v0.11/concepts/template.md) (not to be confused -with the OIS template used for this guide), which allow requesters to specify a -large number of endpoint parameters at no additional gas cost. - -Note that there are some cases where you may not want to map endpoints to API -operations one-to-one. For example, an API operation can have a `header` -parameter, `Accept`, that can take the values `application/json` or -`application/xml` to determine how to format the data that the API will respond -to the call. Airnode expects responses to be in JSON format, and thus -hard-coding this parameter as `JSON` would be more suitable than letting the -requester decide, as there is only one valid choice. Again, the integrator's job -is to be aware of these subtleties and use judgement. +An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It maps to an API operation, but the nature of this mapping is customizable. It is the integrator's job to define what this service is. + +For example, if an API operation returns an asset price given its ticker (e.g., `BTC`), specify the endpoint such that the requester provides the ticker as a parameter. The resulting endpoint would be a general one that returns prices for any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price will be returned (using [fixed operation parameters](/reference/airnode/v0.11/understand/api-integration.md#fixedoperationparameters)), which would make the endpoint a specific one that only returns the BTC price. + +The recommended endpoint definition pattern is to create an Airnode endpoint for each API operation, and allow the requesters to provide all operation parameters themselves. This results in optimal flexibility, and essentially allows the requesters to use the entire API functionality on-chain. Normally, competitor oracle integrations strive to hard-code as many API parameters as possible because passing these parameters on-chain results in a gas cost overhead. However, the Airnode protocol uses [templates](/reference/airnode/v0.11/concepts/template.md) (not to be confused with the OIS template used for this guide), which allow requesters to specify a large number of endpoint parameters at no additional gas cost. + +Note that there are some cases where you may not want to map endpoints to API operations one-to-one. For example, an API operation can have a `header` parameter, `Accept`, that can take the values `application/json` or `application/xml` to determine how to format the data that the API will respond to the call. Airnode expects responses to be in JSON format, and thus hard-coding this parameter as `JSON` would be more suitable than letting the requester decide, as there is only one valid choice. Again, the integrator's job is to be aware of these subtleties and use judgement. ### Endpoints array -The field `endpoints` is an array, with each row representing an Airnode -endpoint. The first field to fill in is `name`. Make sure that it is descriptive -and unique from other endpoint names. If you are integrating API operations to -Airnode endpoints one-to-one, using the API operation path as the endpoint name -is a decent choice (i.e., `/token`). Note that you would also add the method to -this name if there were multiple operations with different methods for a single -path (i.e., `GET/token`). +The field `endpoints` is an array, with each row representing an Airnode endpoint. The first field to fill in is `name`. Make sure that it is descriptive and unique from other endpoint names. If you are integrating API operations to Airnode endpoints one-to-one, using the API operation path as the endpoint name is a decent choice (i.e., `/token`). Note that you would also add the method to this name if there were multiple operations with different methods for a single path (i.e., `GET/token`). -The next step is to fill in `operation` object. Here, you need to enter the -`path` and `method` of an API operation you have defined in -`apiSpecifications.paths`, resulting in the Airnode endpoint calling the now -linked API operation. +The next step is to fill in `operation` object. Here, you need to enter the `path` and `method` of an API operation you have defined in `apiSpecifications.paths`, resulting in the Airnode endpoint calling the now linked API operation. #### fixedOperationParameters -It is not uncommon to hard-code API parameters (recall the `Accept` operation -parameter in the above example). Such hard-coded parameters are called -`fixedOperationParameters`. +It is not uncommon to hard-code API parameters (recall the `Accept` operation parameter in the above example). Such hard-coded parameters are called `fixedOperationParameters`. -In the OIS template there is a fixed operation parameter under -`endpoints[n].fixedOperationParameters`, and it refers to the first API -operation parameter. This means that whenever the Airnode receives a request for -this endpoint, the respective API call will be made with that API operation -parameter set to -endpoints[n].fixedOperationParameters[n].value. -The requester does not supply a value for `fixedOperationParameters`. +In the OIS template there is a fixed operation parameter under `endpoints[n].fixedOperationParameters`, and it refers to the first API operation parameter. This means that whenever the Airnode receives a request for this endpoint, the respective API call will be made with that API operation parameter set to endpoints[n].fixedOperationParameters[n].value. The requester does not supply a value for `fixedOperationParameters`. ```json "fixedOperationParameters": [ @@ -400,31 +288,17 @@ The requester does not supply a value for `fixedOperationParameters`. ``` -An Airnode endpoint can have multiple `fixedOperationParameters`. An API -operation parameter cannot be in both `endpoints[n].fixedOperationParameters` -and `endpoints[n].parameters`. +An Airnode endpoint can have multiple `fixedOperationParameters`. An API operation parameter cannot be in both `endpoints[n].fixedOperationParameters` and `endpoints[n].parameters`. #### reservedParameters -The requester can provide some parameters that are not mapped to API operation -parameters. These parameters are called "reserved parameters", and their names -start with an underscore. See the -[related OIS docs](/reference/ois/2.1/specification.md#_5-4-reservedparameters) -for more information. +The requester can provide some parameters that are not mapped to API operation parameters. These parameters are called "reserved parameters", and their names start with an underscore. See the [related OIS docs](/reference/ois/2.1/specification.md#_5-4-reservedparameters) for more information. -The current list of reserved parameters are `_type`, `_path`, `_times`, -`_gasPrice`, and `_minConfirmations`. See -[Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) in the OIS -document set to understand what each of these parameters are for. +The current list of reserved parameters are `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. See [Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) in the OIS document set to understand what each of these parameters are for. #### parameters -Airnode endpoint -[parameters](/reference/ois/2.1/specification.md#_5-5-parameters) map to API -operation [parameters](/reference/ois/2.1/specification.md#_4-2-1-parameters) -that the requester is allowed to provide values for. It refers to an API -operation through its field `operationParameter`. You can also provide `default` -values for endpoint parameters, though this is not recommended in most cases. +Airnode endpoint [parameters](/reference/ois/2.1/specification.md#_5-5-parameters) map to API operation [parameters](/reference/ois/2.1/specification.md#_4-2-1-parameters) that the requester is allowed to provide values for. It refers to an API operation through its field `operationParameter`. You can also provide `default` values for endpoint parameters, though this is not recommended in most cases. ```json // apiSpecifications.paths...parameters[1] @@ -460,27 +334,14 @@ Mapping between API parameters and endpoint parameters. │ │ ] ``` -Endpoint parameters have a `name` field, which does not have to be the same as -the API operation parameter that they map to. As a separate note, an Airnode -endpoint can have multiple parameters. +Endpoint parameters have a `name` field, which does not have to be the same as the API operation parameter that they map to. As a separate note, an Airnode endpoint can have multiple parameters. ## Conclusion -The API operations and Airnode endpoints are now specified. Each Airnode -endpoint maps to an API operation, and each Airnode endpoint parameter or -fixedOperationParameter maps to an API operation parameter. The resulting OIS -includes no user-specific information, which means that you can share it for -others to easily provide the same services (for example, to set up a third-party -oracle network). - -Note that there was some subjectivity while defining the Airnode endpoints. This -means that two different OISes can exist for the same exact API, differing based -on how the integrators designed the interface that the requester will use. -However, in most cases, one would simply map API operations to Airnode endpoints -directly, and let the requester provide all API operation parameters through the -Airnode endpoint parameters. - -Now that you have an OIS object, the next step is -[API Security](/reference/airnode/v0.11/understand/api-security.md). +The API operations and Airnode endpoints are now specified. Each Airnode endpoint maps to an API operation, and each Airnode endpoint parameter or fixedOperationParameter maps to an API operation parameter. The resulting OIS includes no user-specific information, which means that you can share it for others to easily provide the same services (for example, to set up a third-party oracle network). + +Note that there was some subjectivity while defining the Airnode endpoints. This means that two different OISes can exist for the same exact API, differing based on how the integrators designed the interface that the requester will use. However, in most cases, one would simply map API operations to Airnode endpoints directly, and let the requester provide all API operation parameters through the Airnode endpoint parameters. + +Now that you have an OIS object, the next step is [API Security](/reference/airnode/v0.11/understand/api-security.md). diff --git a/docs/reference/airnode/v0.11/understand/api-security.md b/docs/reference/airnode/v0.11/understand/api-security.md index 8466e050..7c2b3916 100644 --- a/docs/reference/airnode/v0.11/understand/api-security.md +++ b/docs/reference/airnode/v0.11/understand/api-security.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode can pass along security information (schemes) when making calls to API -operations. There are two groups of security schemes. +Airnode can pass along security information (schemes) when making calls to API operations. There are two groups of security schemes. - [Airnode Authentication](/reference/airnode/v0.11/concepts/airnode-auth.md) - [Relayed Meta Data Authentication](/reference/airnode/v0.11/concepts/relay-meta-auth.md) @@ -31,8 +30,7 @@ operations. There are two groups of security schemes. > 1.

The Airnode uses Airnode Authentication Security Schemes to authenticate itself to an API operation of which the values are known only by the Airnode.

> 2.

The Airnode uses Relayed Meta Data Security Schemes to forward known information from the requester's request to an API operation.

-Security schemes are declared by the required `type` property inside the -security scheme definition. The following security scheme types are supported. +Security schemes are declared by the required `type` property inside the security scheme definition. The following security scheme types are supported. - Airnode Authentication Security Schemes - apiKey @@ -46,22 +44,16 @@ security scheme definition. The following security scheme types are supported. - relaySponsorWalletAddress - relayRequestId -It is important to note that the security schemes in any given OIS object apply -to all endpoints/API operations in the OIS object. If different security schemes -are required by a mix of endpoints/API operations, then more than one OIS object -will be required grouping endpoint/API operations based on their security needs. +It is important to note that the security schemes in any given OIS object apply to all endpoints/API operations in the OIS object. If different security schemes are required by a mix of endpoints/API operations, then more than one OIS object will be required grouping endpoint/API operations based on their security needs. ## Airnode Authentication Security Schemes -An Airnode can use the following security scheme types to authenticate itself to -API operations. +An Airnode can use the following security scheme types to authenticate itself to API operations. - [apiKey](/reference/airnode/v0.11/understand/api-security.md#apikey) - [http](/reference/airnode/v0.11/understand/api-security.md#http) -A security scheme requires a unique name within the OIS object for which it -exists. This name groups the security scheme values for `in`, `type`, and` name` -as shown in the two code examples below. +A security scheme requires a unique name within the OIS object for which it exists. This name groups the security scheme values for `in`, `type`, and` name` as shown in the two code examples below. - `securitySchemes.` - `security.` @@ -69,18 +61,12 @@ as shown in the two code examples below. ### apiKey -The `apiKey` security scheme type allows you to define an API key the Airnode -will send to API operations. It is an object which consists of the following -fields: +The `apiKey` security scheme type allows you to define an API key the Airnode will send to API operations. It is an object which consists of the following fields: - `type` must be `apiKey` -- `in` can be one of the `query`, `header` or `cookie`. This value specifies how - the value will be sent to an API operation. When using the `query` option, the - API key will be sent in the request body for POST requests and in query string - for GET requests. +- `in` can be one of the `query`, `header` or `cookie`. This value specifies how the value will be sent to an API operation. When using the `query` option, the API key will be sent in the request body for POST requests and in query string for GET requests. -- `name` is the name of the API key that should be sent to an API. For example - "X-Api-Key". +- `name` is the name of the API key that should be sent to an API. For example "X-Api-Key". ```json "ois": [ @@ -108,11 +94,7 @@ fields: ] │ ``` -The value of the `apiKey` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `apiKey` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json "apiCredentials": [ │ @@ -126,11 +108,7 @@ file. ### http -The `http` security scheme type is used to define either a `basic` or `bearer` -authentication scheme. This security scheme will always be sent in the headers. -The security scheme value should be base64 encoded value "username:password" for -`basic` auth and the encoded token for `bearer` auth. It is an object which -consists of the following fields: +The `http` security scheme type is used to define either a `basic` or `bearer` authentication scheme. This security scheme will always be sent in the headers. The security scheme value should be base64 encoded value "username:password" for `basic` auth and the encoded token for `bearer` auth. It is an object which consists of the following fields: - `type` must be `http` - `scheme` is either `basic` or `bearer` @@ -144,11 +122,7 @@ consists of the following fields: } ``` -The value of the `http` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `http` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json { @@ -160,19 +134,13 @@ file. ::: info Authentication Tutorial -The -[authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates authentication. +The [authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) monorepo example demonstrates authentication. ::: ## Relayed Meta Data Security Schemes -In addition to authenticating itself, Airnode can "relay" security information -about a request to an API operation. This is different then the authorization of -requesters using -[Authorizers](/reference/airnode/v0.11/understand/apply-auth.md) to access the -Airnode. +In addition to authenticating itself, Airnode can "relay" security information about a request to an API operation. This is different then the authorization of requesters using [Authorizers](/reference/airnode/v0.11/understand/apply-auth.md) to access the Airnode. - [relayRequesterAddress](/reference/airnode/v0.11/understand/api-security.md#relayrequesteraddress) - [relayChainId](/reference/airnode/v0.11/understand/api-security.md#relaychainid) @@ -181,29 +149,19 @@ Airnode. - [relaySponsorWalletAddress](/reference/airnode/v0.11/understand/api-security.md#relaysponsorwalletaddress) - [relayRequestId](/reference/airnode/v0.11/understand/api-security.md#relayrequestid) -For relayed meta data security schemes do not provide any values in -[apiCredentials](/reference/airnode/v0.11/deployment-files/config-json.md#apicredentials) -as they are extracted from the request by Airnode. +For relayed meta data security schemes do not provide any values in [apiCredentials](/reference/airnode/v0.11/deployment-files/config-json.md#apicredentials) as they are extracted from the request by Airnode. -Note that Airnode relays this metadata to an API operation and does not perform -any additional processing logic. The API provider must implement any desired -logic in the API operation for any desired security checks. See -[Relayed Meta Data Authentication](/reference/airnode/v0.11/concepts/relay-meta-auth.md) -for overview of its usage. +Note that Airnode relays this metadata to an API operation and does not perform any additional processing logic. The API provider must implement any desired logic in the API operation for any desired security checks. See [Relayed Meta Data Authentication](/reference/airnode/v0.11/concepts/relay-meta-auth.md) for overview of its usage. ::: info Relay Metadata Tutorial -The -[relay-security-schemes](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates how to relay request metadata like chain ID and -sponsor address to the API endpoint. +The [relay-security-schemes](/guides/airnode/monorepo-examples.md) monorepo example demonstrates how to relay request metadata like chain ID and sponsor address to the API endpoint. ::: ### relayRequesterAddress -The `relayRequesterAddress` security scheme type instructs Airnode to forward -the [requester](/reference/airnode/v0.11/concepts/requester.md) address. +The `relayRequesterAddress` security scheme type instructs Airnode to forward the [requester](/reference/airnode/v0.11/concepts/requester.md) address. ```json { @@ -215,8 +173,7 @@ the [requester](/reference/airnode/v0.11/concepts/requester.md) address. ### relayChainId -The `relayChainId` security scheme type instructs Airnode to forward the chain's -ID. +The `relayChainId` security scheme type instructs Airnode to forward the chain's ID. ```json { @@ -228,8 +185,7 @@ ID. ### relayChainType -The `relayChainType` security scheme type instructs Airnode to forward the -chain's type. +The `relayChainType` security scheme type instructs Airnode to forward the chain's type. ```json { @@ -241,8 +197,7 @@ chain's type. ### relaySponsorAddress -The `relaySponsorAddress` security scheme type instructs Airnode to forward the -[sponsor address](/reference/airnode/v0.11/concepts/sponsor.md#sponsoraddress). +The `relaySponsorAddress` security scheme type instructs Airnode to forward the [sponsor address](/reference/airnode/v0.11/concepts/sponsor.md#sponsoraddress). ```json { @@ -254,9 +209,7 @@ The `relaySponsorAddress` security scheme type instructs Airnode to forward the ### relaySponsorWalletAddress -The `relaySponsorWalletAddress` security scheme type instructs Airnode to -forward the -[sponsor wallet address](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). +The `relaySponsorWalletAddress` security scheme type instructs Airnode to forward the [sponsor wallet address](/reference/airnode/v0.11/concepts/sponsor.md#sponsorwallet). ```json { @@ -268,8 +221,7 @@ forward the ### relayRequestId -The `relayRequestId` security scheme type instructs Airnode to forward the -[id of the request](/reference/airnode/v0.11/concepts/request.md#requestid). +The `relayRequestId` security scheme type instructs Airnode to forward the [id of the request](/reference/airnode/v0.11/concepts/request.md#requestid). ```json { @@ -279,10 +231,7 @@ The `relayRequestId` security scheme type instructs Airnode to forward the } ``` -The following example shows how to set up relayed meta data to forward the -`relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that -unlike the Airnode authentication security scheme, no values are stored in -`apiCredentials` as Airnode passes these known values to the API operation. +The following example shows how to set up relayed meta data to forward the `relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that unlike the Airnode authentication security scheme, no values are stored in `apiCredentials` as Airnode passes these known values to the API operation. ```json "ois": [ @@ -318,29 +267,19 @@ unlike the Airnode authentication security scheme, no values are stored in ::: info Remember -The relayed meta data security schemes do not require a supplied value. Values -will be provided (relayed) by Airnode depending on the particular request. +The relayed meta data security schemes do not require a supplied value. Values will be provided (relayed) by Airnode depending on the particular request. ::: ## Example -OIS security is inspired by OAS security practices. This is implemented using -the security schemes and security field. All supported security schemes are -described in detail in the -[Airnode Authentication Security Schemes](/reference/airnode/v0.11/understand/api-security.md#airnode-authentication-security-schemes) -and -[Relayed Meta Data Security Schemes](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes) -sections above. The following example is related to _Airnode Authentication -Security Schemes_. Working with security schemes can be described in three -steps. +OIS security is inspired by OAS security practices. This is implemented using the security schemes and security field. All supported security schemes are described in detail in the [Airnode Authentication Security Schemes](/reference/airnode/v0.11/understand/api-security.md#airnode-authentication-security-schemes) and [Relayed Meta Data Security Schemes](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes) sections above. The following example is related to _Airnode Authentication Security Schemes_. Working with security schemes can be described in three steps. 1. [Define the security schemes for an OIS](/reference/airnode/v0.11/understand/api-security.md#step-1-define-the-security-schemes-for-an-ois) 2. [Turn on the defined security schemes](/reference/airnode/v0.11/understand/api-security.md#step-2-turn-on-the-defined-security-schemes) 3. [Specify the values for the defined security schemes](/reference/airnode/v0.11/understand/api-security.md#step-3-specify-the-values-for-the-defined-security-schemes) -Following is an example of a partial `config.json` which demonstrates the usage -of security scheme and security field. +Following is an example of a partial `config.json` which demonstrates the usage of security scheme and security field. ```json { @@ -377,60 +316,34 @@ of security scheme and security field. ### Step #1: Define the security schemes for an OIS -Use -ois[n].apiSpecifications.components.securitySchemes -to define the security schemes the API operation requires. Consider the partial -`config.json` above that declares a security scheme named `requiresXApiKey`. -This scheme declares that the API requires an API key that must exist in the -HTTP header named `X-api-key`. +Use ois[n].apiSpecifications.components.securitySchemes to define the security schemes the API operation requires. Consider the partial `config.json` above that declares a security scheme named `requiresXApiKey`. This scheme declares that the API requires an API key that must exist in the HTTP header named `X-api-key`. ### Step #2: Turn on the defined security schemes -When the scheme is defined, it is not turned on by default. You need to -explicitly list the security schemes you intend to use in the `security` field -located in `ois[n].apiSpecifications.security` object. The keys in this object -are the names of security schemes to be used. Use empty array (`[]`) as its -value. +When the scheme is defined, it is not turned on by default. You need to explicitly list the security schemes you intend to use in the `security` field located in `ois[n].apiSpecifications.security` object. The keys in this object are the names of security schemes to be used. Use empty array (`[]`) as its value. -_Be aware that this step seems like extra work since there is no reason to -define a security scheme that will not be used. However, Airnode may support -[more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) -logic in the future and using `[]` allows its implementation without a breaking -change._ +_Be aware that this step seems like extra work since there is no reason to define a security scheme that will not be used. However, Airnode may support [more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) logic in the future and using `[]` allows its implementation without a breaking change._ ### Step #3: Specify the values for the defined security schemes -After defining and turning on a security scheme, it may be unclear what provides -the value and how it is set. +After defining and turning on a security scheme, it may be unclear what provides the value and how it is set. -The authentication schemes are intended to be common for the whole OIS and set -by the API provider using `apiCredentials` which is part of `config.json`. The -`apiCredentials` is an array which specifies the values for all security schemes -in all OIS definitions. Each element of this array contains the following fields +The authentication schemes are intended to be common for the whole OIS and set by the API provider using `apiCredentials` which is part of `config.json`. The `apiCredentials` is an array which specifies the values for all security schemes in all OIS definitions. Each element of this array contains the following fields - `oisTitle` is the title of the OIS for the particular security scheme - `securitySchemeName` is the name of the security scheme -- `securitySchemeValue` is the actual value that should be used by Airnode when - making the API request. This value is usually a secret and it is recommended - to interpolate it from `secrets.env`. +- `securitySchemeValue` is the actual value that should be used by Airnode when making the API request. This value is usually a secret and it is recommended to interpolate it from `secrets.env`. ## Using Different Security Schemes -Currently, if you want different API operations to use different security -schemes they must be grouped in different OIS objects based on their common -security schemes. For example, your API has four operations, three require an -API key in the HTTP header, another (public `/ping` endpoint) requires no -security. +Currently, if you want different API operations to use different security schemes they must be grouped in different OIS objects based on their common security schemes. For example, your API has four operations, three require an API key in the HTTP header, another (public `/ping` endpoint) requires no security. -- The first three API operations might be in the `ois[0]` object with a security - scheme named _requiresXApiKey_ of type _apiKey_ as shown above. -- The /ping API operation would be in `ois[1]` which would not have any - `component.securitySchemes` and `security` would be an empty array. +- The first three API operations might be in the `ois[0]` object with a security scheme named _requiresXApiKey_ of type _apiKey_ as shown above. +- The /ping API operation would be in `ois[1]` which would not have any `component.securitySchemes` and `security` would be an empty array. ## Multiple Security Schemes -You can use multiple security schemes (e.g., an API key goes in the header, and -an additional secret goes in the query). +You can use multiple security schemes (e.g., an API key goes in the header, and an additional secret goes in the query). ```json // inside ois[n].apiSpecifications. @@ -456,7 +369,6 @@ an additional secret goes in the query). ## No Security -If the API you are integrating is publicly accessible, you can set both the -`security schemes` and `security` fields to empty objects. +If the API you are integrating is publicly accessible, you can set both the `security schemes` and `security` fields to empty objects. diff --git a/docs/reference/airnode/v0.11/understand/apply-auth.md b/docs/reference/airnode/v0.11/understand/apply-auth.md index ff48e623..8e7dde6e 100644 --- a/docs/reference/airnode/v0.11/understand/apply-auth.md +++ b/docs/reference/airnode/v0.11/understand/apply-auth.md @@ -19,51 +19,29 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using [Authorizers](/reference/airnode/v0.11/concepts/authorizers.md). -This method is on-chain and requires some blockchain knowledge by an API -provider. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizers](/reference/airnode/v0.11/concepts/authorizers.md). This method is on-chain and requires some blockchain knowledge by an API provider. ## What is an authorizer? -An [Authorizer](/reference/airnode/v0.11/concepts/authorizers.md) is a contract -which typically checks for a single condition ("has the requester made their -monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers -can be combined to enforce more complex policies. If any of the authorizers in -the list gives access, the request will considered to be authorized. From a -logical standpoint, the authorization outcomes get *OR*ed. +An [Authorizer](/reference/airnode/v0.11/concepts/authorizers.md) is a contract which typically checks for a single condition ("has the requester made their monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers can be combined to enforce more complex policies. If any of the authorizers in the list gives access, the request will considered to be authorized. From a logical standpoint, the authorization outcomes get *OR*ed. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: ## How to implement authorizers. -When you deploy your Airnode a receipt file is generated which contains the -Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use -`airnodeAddress` and an `endpointId` to make requests to your Airnode's -endpoints. However, rather than serve them publicly, you may want to: +When you deploy your Airnode a receipt file is generated which contains the Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use `airnodeAddress` and an `endpointId` to make requests to your Airnode's endpoints. However, rather than serve them publicly, you may want to: -- Only serve your own - [requester contracts](/reference/airnode/v0.11/developers/requesters-sponsors.md). +- Only serve your own [requester contracts](/reference/airnode/v0.11/developers/requesters-sponsors.md). - Only serve sponsors who have made a subscription payment. - Only serve sponsors who have gone through KYC. -The `chains[n].authorizers` object within `config.json` enables requests to be -authorized in a variety of ways and even across chains. Currently, the -authorizers include `requesterEndpointAuthorizers`, -`crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and -`crossChainRequesterAuthorizersWithErc721`. +The `chains[n].authorizers` object within `config.json` enables requests to be authorized in a variety of ways and even across chains. Currently, the authorizers include `requesterEndpointAuthorizers`, `crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and `crossChainRequesterAuthorizersWithErc721`. -Note that when all `chains[n].authorizers` values are empty arrays, all requests -are authorized, but still can be filtered by using -[Relayed Meta Data Security Schemes](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes). +Note that when all `chains[n].authorizers` values are empty arrays, all requests are authorized, but still can be filtered by using [Relayed Meta Data Security Schemes](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes). Below are examples of how to use the authorizers. @@ -125,23 +103,11 @@ Below are examples of how to use the authorizers. ## Using `RequesterAuthorizerWithAirnode` -A common use case for an authorizer is the -[RequesterAuthorizerWithAirnode](/reference/airnode/v0.11/concepts/authorizers.md#requesterauthorizerwithairnode) -authorizer contract developed for Airnode operators to use right out-of-the-box. -It allows the whitelisting of requester contracts (with or without expiration -timestamps) on a per endpoint basis. Endpoints are declared in the -`ois.endpoints` field of the `config.json` file. This is the most common use -case and can be implemented with the following steps: - -1. Add the RequesterAuthorizerWithAirnode - [authorizer contract address](/reference/airnode/v0.11/#requesterauthorizerwithairnode) - to the array `chains[n].authorizers.requesterEndpointAuthorizers`. -2. After your Airnode is deployed, call the Admin CLI command - [set-whitelist-expiration](/reference/airnode/v0.11/packages/admin-cli.md#set-whitelist-expiration) - to add the desired requester contract addresses to the whitelist maintained - by RequesterAuthorizerWithAirnode. - -Once implemented, only requester contract addresses you have added to -RequesterAuthorizerWithAirnode will have access to your Airnode. +A common use case for an authorizer is the [RequesterAuthorizerWithAirnode](/reference/airnode/v0.11/concepts/authorizers.md#requesterauthorizerwithairnode) authorizer contract developed for Airnode operators to use right out-of-the-box. It allows the whitelisting of requester contracts (with or without expiration timestamps) on a per endpoint basis. Endpoints are declared in the `ois.endpoints` field of the `config.json` file. This is the most common use case and can be implemented with the following steps: + +1. Add the RequesterAuthorizerWithAirnode [authorizer contract address](/reference/airnode/v0.11/#requesterauthorizerwithairnode) to the array `chains[n].authorizers.requesterEndpointAuthorizers`. +2. After your Airnode is deployed, call the Admin CLI command [set-whitelist-expiration](/reference/airnode/v0.11/packages/admin-cli.md#set-whitelist-expiration) to add the desired requester contract addresses to the whitelist maintained by RequesterAuthorizerWithAirnode. + +Once implemented, only requester contract addresses you have added to RequesterAuthorizerWithAirnode will have access to your Airnode. diff --git a/docs/reference/airnode/v0.11/understand/configuring.md b/docs/reference/airnode/v0.11/understand/configuring.md index ca5e747d..af85c403 100644 --- a/docs/reference/airnode/v0.11/understand/configuring.md +++ b/docs/reference/airnode/v0.11/understand/configuring.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -An Airnode is deployed or redeployed using configuration values from its -`config.json` and `secrets.env` files. The `config.json` specifies the -[Oracle Integration Specifications OIS](/reference/ois/2.1/specification.md) and -other specific configuration details. The `secrets.env` file holds secrets, such -as API keys and chain provider URLs, which are referenced within the config.json -file using interpolation. +An Airnode is deployed or redeployed using configuration values from its `config.json` and `secrets.env` files. The `config.json` specifies the [Oracle Integration Specifications OIS](/reference/ois/2.1/specification.md) and other specific configuration details. The `secrets.env` file holds secrets, such as API keys and chain provider URLs, which are referenced within the config.json file using interpolation. > > @@ -41,11 +36,7 @@ The following example files are useful while reading this doc. ## Creating `config.json` -Use the -[config.json template](/reference/airnode/v0.11/deployment-files/templates/config-json.md) -to build your own Airnode configuration file or alter the -[config.json example](/reference/airnode/v0.11/deployment-files/examples/config-json.md) -file. There are six root level fields in `config.json`. +Use the [config.json template](/reference/airnode/v0.11/deployment-files/templates/config-json.md) to build your own Airnode configuration file or alter the [config.json example](/reference/airnode/v0.11/deployment-files/examples/config-json.md) file. There are six root level fields in `config.json`. - [chains](/reference/airnode/v0.11/understand/configuring.md#chains) - [nodeSettings](/reference/airnode/v0.11/understand/configuring.md#nodesettings) @@ -56,15 +47,7 @@ file. There are six root level fields in `config.json`. ### chains -Each row in the `chains` array represents an Ethereum blockchain the Airnode -will serve as identified by the `id`. Currently Airnode only supports Ethereum -blockchains as denoted by `type: "evm"`. There are several supported -blockchains, see them in the -[Airnode contract addresses](/reference/airnode/v0.11/) doc. You can use -multiple chain providers for each chain and declare multiple chains each with -one of more chain providers. See -[Chains Providers](/reference/airnode/v0.11/concepts/chain-providers.md) in -_Concepts and Definitions_. +Each row in the `chains` array represents an Ethereum blockchain the Airnode will serve as identified by the `id`. Currently Airnode only supports Ethereum blockchains as denoted by `type: "evm"`. There are several supported blockchains, see them in the [Airnode contract addresses](/reference/airnode/v0.11/) doc. You can use multiple chain providers for each chain and declare multiple chains each with one of more chain providers. See [Chains Providers](/reference/airnode/v0.11/concepts/chain-providers.md) in _Concepts and Definitions_. Below is a simple chain array with a single chain provider. @@ -132,42 +115,26 @@ Below is a simple chain array with a single chain provider. ::: info Idiosyncrasies -See the dedicated -[Chain Idiosyncrasies](/reference/airnode/v0.11/chain-idiosyncrasies.md) -page for chain-specific configuration considerations. +See the dedicated [Chain Idiosyncrasies](/reference/airnode/v0.11/chain-idiosyncrasies.md) page for chain-specific configuration considerations. ::: #### Considerations: Gas Price Oracle -The gas price oracle strategies are applied in the order that they are listed. -Airnode supports four strategies: `latestBlockPercentileGasPrice`, -`providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and -`constantGasPrice`. The only required strategy is `constantGasPrice` and it is -recommended to place it as the last strategy in the list as it should be the -final fallback for the Airnode to use if all other strategies fail. For more -detail on these strategies, see the -[Gas Price Strategies](/reference/airnode/v0.11/concepts/gas-prices.md) page. +The gas price oracle strategies are applied in the order that they are listed. Airnode supports four strategies: `latestBlockPercentileGasPrice`, `providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and `constantGasPrice`. The only required strategy is `constantGasPrice` and it is recommended to place it as the last strategy in the list as it should be the final fallback for the Airnode to use if all other strategies fail. For more detail on these strategies, see the [Gas Price Strategies](/reference/airnode/v0.11/concepts/gas-prices.md) page. #### Considerations: Concurrency -If you set the `maxConcurrency` field to value X, then Airnode will guarantee -that: +If you set the `maxConcurrency` field to value X, then Airnode will guarantee that: - At most X api calls are made to the API -- At most X transactions (made by blockchain providers) will be made by the - blockchain providers of the respective chain +- At most X transactions (made by blockchain providers) will be made by the blockchain providers of the respective chain -When doing this, Airnode will calculate the total number of requests reported by -all blockchain providers. If this number exceeds the maximum concurrency limit, -Airnode will start processing the oldest request from the blockchain providers -until the number of processed requests reaches the limit. All other requests are -dropped and will be processed in the next Airnode run. +When doing this, Airnode will calculate the total number of requests reported by all blockchain providers. If this number exceeds the maximum concurrency limit, Airnode will start processing the oldest request from the blockchain providers until the number of processed requests reaches the limit. All other requests are dropped and will be processed in the next Airnode run. Note that this request dropping happens for each **chain** separately. -For example, if `maxConcurrency` is set to 5 and there are three providers (A, B -and C) and they reported the following requests: +For example, if `maxConcurrency` is set to 5 and there are three providers (A, B and C) and they reported the following requests: - A1, A2, A3, A4 and A5 - B1, B2 and B3 @@ -177,17 +144,13 @@ The above example results in the following requests: A1, A2, B1, B2, and C1. ::: warning -Note, that this limit only applies to the requests initiated on chain. For -example, requests initiated using HTTP gateway are not included in this limit. -Also note that, this limit is configured per chain and the limits of different -chains are unrelated to each other. +Note, that this limit only applies to the requests initiated on chain. For example, requests initiated using HTTP gateway are not included in this limit. Also note that, this limit is configured per chain and the limits of different chains are unrelated to each other. ::: #### References: `chains` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [authorizers](/reference/airnode/v0.11/deployment-files/config-json.md#authorizers) - [contracts](/reference/airnode/v0.11/deployment-files/config-json.md#contracts) @@ -239,26 +202,15 @@ The `nodeSettings` field holds node-specific (Airnode) configuration parameters. #### Considerations: Cloud Providers -Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are -supported cloud providers for hosting Airnode. Note that while many fields -within `nodeSettings` are required by both, there are some cloud provider -specific fields. For example, `cloudProvider.projectId` is only required with -GCP. Also note that not all cloud provider regions can be deployed to; see the -[cloudProvider.region reference](/reference/airnode/v0.11/deployment-files/config-json.md#cloudprovider-region) -for more information. +Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are supported cloud providers for hosting Airnode. Note that while many fields within `nodeSettings` are required by both, there are some cloud provider specific fields. For example, `cloudProvider.projectId` is only required with GCP. Also note that not all cloud provider regions can be deployed to; see the [cloudProvider.region reference](/reference/airnode/v0.11/deployment-files/config-json.md#cloudprovider-region) for more information. #### Considerations: Gateways -Airnode offers two gateways for accessing provider HTTP endpoints without using -the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information -on each of these see the -[HTTP Gateways](/reference/airnode/v0.11/understand/http-gateways.md) -documentation. Also note that that distinct API keys must be used for each. +Airnode offers two gateways for accessing provider HTTP endpoints without using the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information on each of these see the [HTTP Gateways](/reference/airnode/v0.11/understand/http-gateways.md) documentation. Also note that that distinct API keys must be used for each. #### References: `nodeSettings` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [cloudProvider](/reference/airnode/v0.11/deployment-files/config-json.md#cloudprovider) - [cloudProvider.type](/reference/airnode/v0.11/deployment-files/config-json.md#cloudprovider-type) @@ -285,15 +237,9 @@ Files section: ### triggers -The `triggers` field allow exposes Airnode endpoints from an OIS selectively for -the RRP protocol or via the HTTP gateway. For example, an OIS object may include -10 endpoints, but only two are desired for RRP and all 10 for the gateway. +The `triggers` field allow exposes Airnode endpoints from an OIS selectively for the RRP protocol or via the HTTP gateway. For example, an OIS object may include 10 endpoints, but only two are desired for RRP and all 10 for the gateway. -List the endpoints to serve with the request–response protocol (RRP) under -`triggers.rrp`. List the endpoints to serve with the HTTP gateway under -`triggers.http`. List the endpoints which can be used to get the signed data in -`triggers.httpSignedData`. In most cases create a trigger for each endpoint in -your OIS object. +List the endpoints to serve with the request–response protocol (RRP) under `triggers.rrp`. List the endpoints to serve with the HTTP gateway under `triggers.http`. List the endpoints which can be used to get the signed data in `triggers.httpSignedData`. In most cases create a trigger for each endpoint in your OIS object. ```json "triggers": { @@ -324,65 +270,38 @@ your OIS object. #### Considerations: triggers -The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived -from the `oisTitle` and `endpointName` using the CLI command -[derive-endpoint-id](/reference/airnode/v0.11/packages/admin-cli.md#derive-endpoint-id). -Remember that an Airnode's config.json file can have more than one OIS object -and that these endpoints can be triggers for `rrp`, `http`, and/or -`httpSignedData` as desired. +The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived from the `oisTitle` and `endpointName` using the CLI command [derive-endpoint-id](/reference/airnode/v0.11/packages/admin-cli.md#derive-endpoint-id). Remember that an Airnode's config.json file can have more than one OIS object and that these endpoints can be triggers for `rrp`, `http`, and/or `httpSignedData` as desired. #### Considerations: cached responses -When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API -responses on the local filesystem per request ID. This only applies to -blockchain requests. The flow is: +When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API responses on the local filesystem per request ID. This only applies to blockchain requests. The flow is: 1. A request is received from the Blockchain. 1. The Airnode does an HTTP/S call to a remote API based on the request. -1. [with caching enabled] Airnode stores the response on the local filesystem by - request ID. -1. Airnode then follows the usual process of extracting the response, - post-processing it and sending the response back on chain as a fulfillment - callback. -1. After all current requests are processed, Airnode then exits until the next - cycle (the next minute). -1. If during the next cycle, if the Airnode gets the same request and it isn't - fulfilled, it will try and fulfill the request again. Ordinarily, without - caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with - caching enabled it will fulfill the response using the cached API response - value. - -Clearance of the local filesystem cache is dependant on the environment Airnode -runs in. As a guideline: +1. [with caching enabled] Airnode stores the response on the local filesystem by request ID. +1. Airnode then follows the usual process of extracting the response, post-processing it and sending the response back on chain as a fulfillment callback. +1. After all current requests are processed, Airnode then exits until the next cycle (the next minute). +1. If during the next cycle, if the Airnode gets the same request and it isn't fulfilled, it will try and fulfill the request again. Ordinarily, without caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with caching enabled it will fulfill the response using the cached API response value. + +Clearance of the local filesystem cache is dependant on the environment Airnode runs in. As a guideline: - AWS Lambda persists for 2.5 hours. - Google Cloud persistence is completely arbitrary. - Docker persists as long as the container remains running. -If the local filesystem is cleared, the cache is lost and if a repeat request is -received after the cache has been cleared, Airnode will repeat the API call. -Airnode self-clears cached data after the data has reached 1 hour's age. +If the local filesystem is cleared, the cache is lost and if a repeat request is received after the cache has been cleared, Airnode will repeat the API call. Airnode self-clears cached data after the data has reached 1 hour's age. -Furthermore, as an example: "if an Airnode AWS Lambda environment/container" -(since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours -and Airnode gets a request, that request will only be cached until the container -resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. +Furthermore, as an example: "if an Airnode AWS Lambda environment/container" (since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours and Airnode gets a request, that request will only be cached until the container resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. -As described above, caching on serverless infrastructure is unreliable and if -request caching is mission critical, Airnode should be run in a Docker container -with a persistent `/tmp` directory. +As described above, caching on serverless infrastructure is unreliable and if request caching is mission critical, Airnode should be run in a Docker container with a persistent `/tmp` directory. -Caching is useful for non-idempotent API operations like random number -generators. Consider the following use-case: +Caching is useful for non-idempotent API operations like random number generators. Consider the following use-case: -> Random Numbers: in the absence of caching, a malicious blockchain provider can -> selectively block fulfillments containing numbers they don't like, allowing -> them to improve their odds of winning in a random-number betting game. +> Random Numbers: in the absence of caching, a malicious blockchain provider can selectively block fulfillments containing numbers they don't like, allowing them to improve their odds of winning in a random-number betting game. #### References: `triggers` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [rrp](/reference/airnode/v0.11/deployment-files/config-json.md#rrp) - [rrp[n].endpointId](/reference/airnode/v0.11/deployment-files/config-json.md#rrp-n-endpointid) @@ -400,13 +319,11 @@ Files section: ### templates -The templates field allows you to specify templates to be used to make template -requests. The array can be left empty if no templates will be used. +The templates field allows you to specify templates to be used to make template requests. The array can be left empty if no templates will be used. #### References: templates -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [templateId](/reference/airnode/v0.11/deployment-files/config-json.md#templateid) - [endpointId](/reference/airnode/v0.11/deployment-files/config-json.md#endpointid) @@ -414,23 +331,11 @@ Files section: ### ois -The `ois` field is a list OIS objects that Airnode will be serving. This means -that a single instance of an Airnode can serve multiple APIs. You can simply -copy paste OIS objects that you will be serving into the `ois` list. Use the -previous guide -[API Integration](/reference/airnode/v0.11/understand/api-integration.md) to -create an OIS object. The full specification is available in the -[Oracle Integration Specifications (OIS)](/reference/ois/2.1/) documentation. +The `ois` field is a list OIS objects that Airnode will be serving. This means that a single instance of an Airnode can serve multiple APIs. You can simply copy paste OIS objects that you will be serving into the `ois` list. Use the previous guide [API Integration](/reference/airnode/v0.11/understand/api-integration.md) to create an OIS object. The full specification is available in the [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) documentation. ### apiCredentials -Each entry in `apiCredentials` maps to a security scheme defined in an OIS -(`ois[n].components.securitySchemes.{securitySchemeName}` and -`ois[n].security`), where `oisTitle` is the `title` field of the related OIS, -and `securitySchemeName` is the name of the respective security scheme. These -would be `myOisTitle` and `mySecurityScheme` in the example below. -`securitySchemeValue` is the value used for the authentication with the security -scheme (e.g., the API key). +Each entry in `apiCredentials` maps to a security scheme defined in an OIS (`ois[n].components.securitySchemes.{securitySchemeName}` and `ois[n].security`), where `oisTitle` is the `title` field of the related OIS, and `securitySchemeName` is the name of the respective security scheme. These would be `myOisTitle` and `mySecurityScheme` in the example below. `securitySchemeValue` is the value used for the authentication with the security scheme (e.g., the API key). If no security scheme is needed, leave the `apiCredentials` array empty. @@ -467,14 +372,11 @@ If no security scheme is needed, leave the `apiCredentials` array empty. #### Considerations: apiCredentials -Currently Airnode supports the following security scheme types when making API -calls: `apiKey` and `http`. For more detail, visit the previous section on -[API Security](/reference/airnode/v0.11/understand/api-security.md). +Currently Airnode supports the following security scheme types when making API calls: `apiKey` and `http`. For more detail, visit the previous section on [API Security](/reference/airnode/v0.11/understand/api-security.md). #### References: `apiCredentials` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [oisTitle](/reference/airnode/v0.11/deployment-files/config-json.md#oistitle) - [securitySchemeName](/reference/airnode/v0.11/deployment-files/config-json.md#securityschemename) @@ -482,10 +384,7 @@ Files section: ## Creating `secrets.env` -The `secrets.env` file contains values (secrets) such as blockchain provider -urls, chain provider urls, etc. These secrets are embedded in -[config.json](/reference/airnode/v0.11/deployment-files/config-json.md) using -interpolation. +The `secrets.env` file contains values (secrets) such as blockchain provider urls, chain provider urls, etc. These secrets are embedded in [config.json](/reference/airnode/v0.11/deployment-files/config-json.md) using interpolation. ```json // Sample interpolation value from config.json @@ -499,25 +398,15 @@ interpolation. HEARTBEAT_API_KEY="d714a900-3b9e-4e4d-8eae-756ef06a8836" ``` -Use the -[secrets.env](/reference/airnode/v0.11/deployment-files/templates/secrets-env.md) -template and refer to -[Reference > Deployment Files > secrets.env](/reference/airnode/v0.11/deployment-files/secrets-env.md) -as needed. +Use the [secrets.env](/reference/airnode/v0.11/deployment-files/templates/secrets-env.md) template and refer to [Reference > Deployment Files > secrets.env](/reference/airnode/v0.11/deployment-files/secrets-env.md) as needed. ## AWS setup (AWS deployment only) -When it is time to deploy the Airnode to AWS, the Docker -[deployer image](/reference/airnode/v0.11/docker/deployer-image.md) will need -the AWS credentials to build the node on AWS Lambda. +When it is time to deploy the Airnode to AWS, the Docker [deployer image](/reference/airnode/v0.11/docker/deployer-image.md) will need the AWS credentials to build the node on AWS Lambda. ### Creating `aws.env` (AWS only) -Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It -explains how to create an IAM user and get security credentials. Put them in the -`aws.env` file as shown below. See an -[example file](/reference/airnode/v0.11/deployment-files/templates/aws-env.md) -in the reference section. +Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It explains how to create an IAM user and get security credentials. Put them in the `aws.env` file as shown below. See an [example file](/reference/airnode/v0.11/deployment-files/templates/aws-env.md) in the reference section. - Variable names cannot contain dashes (-) or start with a number. @@ -528,46 +417,26 @@ AWS_SECRET_ACCESS_KEY=ABC7...89 ## GCP setup (GCP deployment only) -When it is time to deploy the Airnode to GCP, the Docker -[deployer image](/reference/airnode/v0.11/docker/deployer-image.md) will need -the GCP project ID to build the Airnode. +When it is time to deploy the Airnode to GCP, the Docker [deployer image](/reference/airnode/v0.11/docker/deployer-image.md) will need the GCP project ID to build the Airnode. ### Creating a GCP project -First -[create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) -under which will the Airnode be deployed. Once the project is created, insert -its -[projectId](/reference/airnode/v0.11/deployment-files/config-json.md#cloudprovider) -into the `config.json` file. +First [create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) under which will the Airnode be deployed. Once the project is created, insert its [projectId](/reference/airnode/v0.11/deployment-files/config-json.md#cloudprovider) into the `config.json` file. ### Enable required API -In order for Airnode to deploy successfully, enable -[App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) -for the GCP project. After enabling it, wait a few minutes before the deployment -itself so the change will take place. +In order for Airnode to deploy successfully, enable [App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) for the GCP project. After enabling it, wait a few minutes before the deployment itself so the change will take place. ### Creating a Service Account -Create a new service account from the -[Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) -menu. Grant this service account access to the project by adding a role `Owner` -during the creation process. +Create a new service account from the [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) menu. Grant this service account access to the project by adding a role `Owner` during the creation process. -Once the account is created, add a new access key of type JSON for this account. -Download the key file as `gcp.json` into the root of your project. +Once the account is created, add a new access key of type JSON for this account. Download the key file as `gcp.json` into the root of your project. ## Summary -In this guide you created the `config.json`, `secrets.env` and obtained cloud -provider credentials required to deploy an Airnode to a cloud provider. Note -that `config.json` is user-specific and therefore it is not much use to others. +In this guide you created the `config.json`, `secrets.env` and obtained cloud provider credentials required to deploy an Airnode to a cloud provider. Note that `config.json` is user-specific and therefore it is not much use to others. -The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider -urls and security credentials, so they should be kept secret. Make sure that you -do not push your credentials to a repository or otherwise expose them as these -credentials can be used to gain access to your Airnode's private key, AWS -account or GCP account. +The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider urls and security credentials, so they should be kept secret. Make sure that you do not push your credentials to a repository or otherwise expose them as these credentials can be used to gain access to your Airnode's private key, AWS account or GCP account. diff --git a/docs/reference/airnode/v0.11/understand/deploying.md b/docs/reference/airnode/v0.11/understand/deploying.md index 219a8080..5bf302d5 100644 --- a/docs/reference/airnode/v0.11/understand/deploying.md +++ b/docs/reference/airnode/v0.11/understand/deploying.md @@ -19,49 +19,21 @@ tags: # {{$frontmatter.title}} -After integrating an API -([API Integration](/reference/airnode/v0.11/understand/api-integration.md)) and -creating the configuration files -([Configuring Airnode](/reference/airnode/v0.11/understand/configuring.md)), the -next step is to deploy the Airnode. +After integrating an API ([API Integration](/reference/airnode/v0.11/understand/api-integration.md)) and creating the configuration files ([Configuring Airnode](/reference/airnode/v0.11/understand/configuring.md)), the next step is to deploy the Airnode. ## Deploy with Docker -The recommended way to deploy Airnode is by using the Docker -[deployer image](/reference/airnode/v0.11/docker/deployer-image.md). This image -is simply a wrapper around the -[deployer CLI](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer). -Try the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -tutorial if you wish to become familiar with the deployer image first. There are -also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a -[client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as -well as several repo based examples in the -[Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.11.2/packages/airnode-examples) -package. - -The deployer interacts with a cloud provider to deploy Airnode programmatically, -without requiring you to click through a lot of ever-changing graphical -interfaces. For it to do so, a cloud project setup and credentials are required -and was discussed in -[Configuring an Airnode](/reference/airnode/v0.11/understand/configuring.md#aws-setup-aws-deployment-only). -There is additional guidance in the AWS and GCP quick start tutorials mentioned -above. +The recommended way to deploy Airnode is by using the Docker [deployer image](/reference/airnode/v0.11/docker/deployer-image.md). This image is simply a wrapper around the [deployer CLI](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-deployer). Try the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) tutorial if you wish to become familiar with the deployer image first. There are also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a [client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as well as several repo based examples in the [Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.11.2/packages/airnode-examples) package. + +The deployer interacts with a cloud provider to deploy Airnode programmatically, without requiring you to click through a lot of ever-changing graphical interfaces. For it to do so, a cloud project setup and credentials are required and was discussed in [Configuring an Airnode](/reference/airnode/v0.11/understand/configuring.md#aws-setup-aws-deployment-only). There is additional guidance in the AWS and GCP quick start tutorials mentioned above. ## Install Docker -The [deployer image](/reference/airnode/v0.11/docker/deployer-image.md) is -containerized as a Docker image. This will deploy the Airnode to the cloud -provider without the worry of installing dependencies and is the recommended way -to do a deployment. If you do not already have docker installed go to the -[Docker website](https://docs.docker.com/get-docker/) and install it. +The [deployer image](/reference/airnode/v0.11/docker/deployer-image.md) is containerized as a Docker image. This will deploy the Airnode to the cloud provider without the worry of installing dependencies and is the recommended way to do a deployment. If you do not already have docker installed go to the [Docker website](https://docs.docker.com/get-docker/) and install it. ## Deployment -At this point a project should resemble the following. The `config.json`, -`secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to -GCP) files should be ready to go. Other files and folders added to the project -are expected and are ignored by the deployer image. +At this point a project should resemble the following. The `config.json`, `secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to GCP) files should be ready to go. Other files and folders added to the project are expected and are ignored by the deployer image. ::: code-group @@ -84,13 +56,7 @@ my-airnode -From the root of the project directory run the Docker image command -[deploy](/reference/airnode/v0.11/docker/deployer-image.md#deploy) as shown -below to deploy the Airnode. When the deployment has completed a `receipt.json` -file will be written to the project directory, which is mounted to the -`/app/config` directory within the container. This file contains important -configuration information about the Airnode and is needed to remove the Airnode -should the need arise. +From the root of the project directory run the Docker image command [deploy](/reference/airnode/v0.11/docker/deployer-image.md#deploy) as shown below to deploy the Airnode. When the deployment has completed a `receipt.json` file will be written to the project directory, which is mounted to the `/app/config` directory within the container. This file contains important configuration information about the Airnode and is needed to remove the Airnode should the need arise.

@@ -114,10 +80,7 @@ docker run -it --rm ^ ### receipt.json -The `receipt.json` file is a product of a deployment attempt. It contains -Airnode configuration and deployment information and is used to remove the -Airnode. The field `success` is important in that it specifies whether the -deployment was successful or not. +The `receipt.json` file is a product of a deployment attempt. It contains Airnode configuration and deployment information and is used to remove the Airnode. The field `success` is important in that it specifies whether the deployment was successful or not. ```json { @@ -142,9 +105,7 @@ deployment was successful or not. ## Testing with HTTP Gateway -If you opted to enable the HTTP Gateway it can be used to test the Airnode while -bypassing the chain it was deployed to. There are examples that detail how to do -this. +If you opted to enable the HTTP Gateway it can be used to test the Airnode while bypassing the chain it was deployed to. There are examples that detail how to do this. - [HTTP Gateways](/reference/airnode/v0.11/understand/http-gateways.md#using-curl) - [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/#_5-test-the-airnode) @@ -153,15 +114,10 @@ this. ## Make an RRP request of the Airnode -Once the Airnode is deployed, see -[Calling an Airnode](/reference/airnode/v0.11/developers/index.md) to learn how -requests are made using the request-response protocol (RRP). +Once the Airnode is deployed, see [Calling an Airnode](/reference/airnode/v0.11/developers/index.md) to learn how requests are made using the request-response protocol (RRP). ## Removing the Airnode -If you would like to remove a deployed Airnode, see the Docker image commands -for [remove](/reference/airnode/v0.11/docker/deployer-image.md#remove) or -[remove-with-receipt](/reference/airnode/v0.11/docker/deployer-image.md#remove-with-receipt) -instructions. +If you would like to remove a deployed Airnode, see the Docker image commands for [remove](/reference/airnode/v0.11/docker/deployer-image.md#remove) or [remove-with-receipt](/reference/airnode/v0.11/docker/deployer-image.md#remove-with-receipt) instructions. diff --git a/docs/reference/airnode/v0.11/understand/heartbeat.md b/docs/reference/airnode/v0.11/understand/heartbeat.md index 09f80144..484a4a6d 100644 --- a/docs/reference/airnode/v0.11/understand/heartbeat.md +++ b/docs/reference/airnode/v0.11/understand/heartbeat.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -At the end of an Airnode's run (every minute), Airnode can make an HTTP POST -request to a specified URL. This is both to signal that the Airnode is alive and -working (useful especially right after the deployment) and also as a -notification every time it runs (self-operates). +At the end of an Airnode's run (every minute), Airnode can make an HTTP POST request to a specified URL. This is both to signal that the Airnode is alive and working (useful especially right after the deployment) and also as a notification every time it runs (self-operates). > > @@ -31,8 +28,7 @@ notification every time it runs (self-operates). > 3.

A response is sent to each request.

> 4.

Finally Airnode makes a request to the heartbeat URL (HTTP POST). This could be to an operation within the API Airnode supports or to any cloud REST endpoint such as a monitoring service.

-Turn on the optional heartbeat functionality by setting all fields in the -`config.json` section for `nodeSettings.heartbeat`. +Turn on the optional heartbeat functionality by setting all fields in the `config.json` section for `nodeSettings.heartbeat`. ```json{12-16} { @@ -95,8 +91,7 @@ The table below illustrates the parameters passed to the Heartbeat URL. | oev_gateway_url | body | string | | signature | body | string | -Below is an example of what is included in the request body. Note that -`airnode-heartbeat-api-key` can be found in the request header and not the body. +Below is an example of what is included in the request body. Note that `airnode-heartbeat-api-key` can be found in the request header and not the body. ```json { @@ -117,18 +112,13 @@ Below is an example of what is included in the request body. Note that The method by which the heartbeat payload is generated is as follows: -- An object is marshalled to JSON - this object contains multiple fields as - shown above. -- The Airnode's mnemonic (using the default EVM derivation path to derive a key) - is used to sign the payload. +- An object is marshalled to JSON - this object contains multiple fields as shown above. +- The Airnode's mnemonic (using the default EVM derivation path to derive a key) is used to sign the payload. - The payload and signature are included in a new object and marshalled to JSON. -The reason this nested JSON approach has been used is to prevent subtle -inconsistencies between JSON marshallers in different languages causing the -signature to not match the payload. +The reason this nested JSON approach has been used is to prevent subtle inconsistencies between JSON marshallers in different languages causing the signature to not match the payload. -The airnode's public key can be recovered from this signature and be used, -generally, to verify the authenticity of the payload. +The airnode's public key can be recovered from this signature and be used, generally, to verify the authenticity of the payload. The overall content to the heartbeat URL is as follows: diff --git a/docs/reference/airnode/v0.11/understand/http-gateways.md b/docs/reference/airnode/v0.11/understand/http-gateways.md index 2024be10..150a3479 100644 --- a/docs/reference/airnode/v0.11/understand/http-gateways.md +++ b/docs/reference/airnode/v0.11/understand/http-gateways.md @@ -19,44 +19,32 @@ tags: # {{$frontmatter.title}} -As part of the Airnode deployment you can decide to deploy two different HTTP -Gateways. +As part of the Airnode deployment you can decide to deploy two different HTTP Gateways. - HTTP Gateway: testing - HTTP Signed Data Gateway: production use ## Gateway Differences -Both gateways are setup identically. The differences are in their purpose and -response. +Both gateways are setup identically. The differences are in their purpose and response. > ### HTTP Gateway -The regular HTTP gateway is strictly for testing purposes. Using a simple tool -like CURL you can test that endpoints in the Airnode configuration are working -properly without accessing the blockchain. +The regular HTTP gateway is strictly for testing purposes. Using a simple tool like CURL you can test that endpoints in the Airnode configuration are working properly without accessing the blockchain. ### HTTP Signed Data Gateway -The HTTP signed data gateway is used for production purposes. While it is -executed in a similar way as the HTTP gateway, its response is signed and does -not contain a `rawValue` field. This gateway is executed by an off-chain code -source that may in turn push data to a blockchain. +The HTTP signed data gateway is used for production purposes. While it is executed in a similar way as the HTTP gateway, its response is signed and does not contain a `rawValue` field. This gateway is executed by an off-chain code source that may in turn push data to a blockchain. ## Setup -Enable either gateway in the `config.json` file fields -`nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. +Enable either gateway in the `config.json` file fields `nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. - **enabled**: A boolean to enable/disable the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless function instance serving gateway requests. When - omitted, there is no maximum concurrency set. This field is ignored for - Airnode client gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless function instance serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -80,10 +68,7 @@ Enable either gateway in the `config.json` file fields }, ``` -Add the desired endpoints a gateway can respond to in the `triggers.http[n]` -and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need -to match. It could be practical to test all endpoints but only serve certain -endpoints using the HTTP signed data gateway or via RRP. +Add the desired endpoints a gateway can respond to in the `triggers.http[n]` and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need to match. It could be practical to test all endpoints but only serve certain endpoints using the HTTP signed data gateway or via RRP. ```json // in config.json @@ -113,50 +98,28 @@ endpoints using the HTTP signed data gateway or via RRP. ## Gateway URLs -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URLs should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URLs should be kept secret. -The gateway URLs are also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/v0.11/understand/heartbeat.md) to a specified -heartbeat URL. +The gateway URLs are also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/v0.11/understand/heartbeat.md) to a specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated for each gateway (when enabled) when Airnode is -deployed. The URL including, the secret `UUID` path parameter, is displayed on -the terminal at the end of an Airnode deployment using the -[Docker image](/reference/airnode/v0.11/docker/deployer-image.md). +A gateway URL is generated for each gateway (when enabled) when Airnode is deployed. The URL including, the secret `UUID` path parameter, is displayed on the terminal at the end of an Airnode deployment using the [Docker image](/reference/airnode/v0.11/docker/deployer-image.md). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for both gateways, which is exposed on the host machine. -Doing so will make the gateways API accessible like a regular web server running -on the machine. Each gateway has a separate endpoint as shown below. Note the -`PORT` which is exposed as part of the Airnode client container. See the -[Airnode client usage](/reference/airnode/v0.11/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for both gateways, which is exposed on the host machine. Doing so will make the gateways API accessible like a regular web server running on the machine. Each gateway has a separate endpoint as shown below. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/v0.11/docker/client-image.md#usage) for more details. -- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Gateway -- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Signed Data Gateway +- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Gateway +- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Signed Data Gateway ## Using CURL -In order to execute an endpoint served by either gateway, the following are -required as part of the CURL call. +In order to execute an endpoint served by either gateway, the following are required as part of the CURL call. -- Make a POST request with the `endpointId` as a path parameter. An `endpointId` - can found in config.json under `triggers.http.endpointId` or - `triggers.httpSignedData.endpointId`. +- Make a POST request with the `endpointId` as a path parameter. An `endpointId` can found in config.json under `triggers.http.endpointId` or `triggers.httpSignedData.endpointId`. - Add the `Content-Type` header, set to `application/json`. - Place the parameters/encodedParameters in the request body. @@ -171,15 +134,11 @@ required as part of the CURL call. | \* parameters
HTTP Gateway
| body | `-d '{"parameters": {"param1": "myValue", "param2": 5}}'` | | \* encodedParameters
HTTP Signed Data Gateway
| body | `-d '{"encodedParameters": "0x3173737300....000"}'` | -\* Parameters for the gateways are named differently. The HTTP signed data -gateway requires that the `encodedParameters` be encoded using -[Airnode ABI](/reference/airnode/v0.11/specifications/airnode-abi.md). +\* Parameters for the gateways are named differently. The HTTP signed data gateway requires that the `encodedParameters` be encoded using [Airnode ABI](/reference/airnode/v0.11/specifications/airnode-abi.md). ### Request -Replace `` in the examples below with the URL displayed in the -terminal at the end of an Airnode deployment using a -[Docker image](/reference/airnode/v0.11/docker/). +Replace `` in the examples below with the URL displayed in the terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/v0.11/docker/). ::: code-group diff --git a/docs/reference/airnode/v0.11/understand/index.md b/docs/reference/airnode/v0.11/understand/index.md index e6970ed3..f601c079 100644 --- a/docs/reference/airnode/v0.11/understand/index.md +++ b/docs/reference/airnode/v0.11/understand/index.md @@ -19,17 +19,11 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that pushes off-chain API data on-chain via data -feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs -off-chain as a background component of the API3 ecosystem. **Understanding -Airnode** is a progression of pages that provides a detailed understanding of -the capabilities and functionality of Airnode. +Airnode is a first-party oracle that pushes off-chain API data on-chain via data feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs off-chain as a background component of the API3 ecosystem. **Understanding Airnode** is a progression of pages that provides a detailed understanding of the capabilities and functionality of Airnode. ## Project Folder -A typical Airnode project folder contains files used to define the Airnode. Show -below are typical project folders for each of AWS, GCP, and container -deployments. +A typical Airnode project folder contains files used to define the Airnode. Show below are typical project folders for each of AWS, GCP, and container deployments. ::: code-group @@ -55,12 +49,7 @@ my-airnode ::: code-group -Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the -files in the -[Templates](/reference/airnode/v0.11/deployment-files/templates/config-json.md) -as an aid to create all but the `gcp.json` files. Also see the -[Examples](/reference/airnode/v0.11/deployment-files/examples/config-json.md) -for demonstration purposes. +Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the files in the [Templates](/reference/airnode/v0.11/deployment-files/templates/config-json.md) as an aid to create all but the `gcp.json` files. Also see the [Examples](/reference/airnode/v0.11/deployment-files/examples/config-json.md) for demonstration purposes. ## Configuration files @@ -69,57 +58,40 @@ for demonstration purposes. - `aws.env`: AWS credentials. - `gcp.json`: GCP project information. -The diagrams below depict the configuration files needed for a successful -deployment of an Airnode to AWS, GCP, and a Docker Container. +The diagrams below depict the configuration files needed for a successful deployment of an Airnode to AWS, GCP, and a Docker Container. ### AWS -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **aws.env**: Contains AWS credentials required by the Docker deployer image. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### GCP -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **gcp.json**: GCP project file. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### Container -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. -3. **client image**: The Docker client image that contains the Airnode and runs - with the provided configuration. +3. **client image**: The Docker client image that contains the Airnode and runs with the provided configuration. ## Deploying -There are two ways to deploy and run an Airnode. The most popular is with a -cloud provider such as AWS or GCP. Use the Docker -[Airnode Deployer Image](/reference/airnode/v0.11/docker/deployer-image.md) for -these type of deployments. - -The second method is to run a containerized Airnode hosted internally or with a -cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker -[Airnode Client Image](/reference/airnode/v0.11/docker/client-image.md) for this -type of deployment. - -Try the guide AWS -[Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) -as a quick introduction to an Airnode deployment. Also be sure to visit -[ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an -Airnode. +There are two ways to deploy and run an Airnode. The most popular is with a cloud provider such as AWS or GCP. Use the Docker [Airnode Deployer Image](/reference/airnode/v0.11/docker/deployer-image.md) for these type of deployments. + +The second method is to run a containerized Airnode hosted internally or with a cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker [Airnode Client Image](/reference/airnode/v0.11/docker/client-image.md) for this type of deployment. + +Try the guide AWS [Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) as a quick introduction to an Airnode deployment. Also be sure to visit [ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an Airnode. diff --git a/docs/reference/airnode/v0.11/understand/monitor.md b/docs/reference/airnode/v0.11/understand/monitor.md index 088bd5f3..868103b8 100644 --- a/docs/reference/airnode/v0.11/understand/monitor.md +++ b/docs/reference/airnode/v0.11/understand/monitor.md @@ -19,43 +19,24 @@ tags: # {{$frontmatter.title}} -Airnode logs or log groups are named similarly in AWS and GCP and include the -following hyphen-separated components: `airnode`, ``, -``, and ``, for example, -`airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages -or request types and the logs they contain are as follows: - -- `startCoordinator`: Logs for chain provider initialization and request - fetching +Airnode logs or log groups are named similarly in AWS and GCP and include the following hyphen-separated components: `airnode`, ``, ``, and ``, for example, `airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages or request types and the logs they contain are as follows: + +- `startCoordinator`: Logs for chain provider initialization and request fetching - `run`: Logs of API calls and withdrawals originating from blockchain requests -- `httpReq`: Logs for - [HTTP gateway requests](/reference/airnode/v0.11/understand/http-gateways.md#http-gateway) -- `httpSignedReq`: Logs for - [HTTP signed data gateway requests](/reference/airnode/v0.11/understand/http-gateways.md) -- `signOevReq`: Logs for - [OEV gateway requests](/reference/airnode/v0.11/understand/oev-gateway.md) +- `httpReq`: Logs for [HTTP gateway requests](/reference/airnode/v0.11/understand/http-gateways.md#http-gateway) +- `httpSignedReq`: Logs for [HTTP signed data gateway requests](/reference/airnode/v0.11/understand/http-gateways.md) +- `signOevReq`: Logs for [OEV gateway requests](/reference/airnode/v0.11/understand/oev-gateway.md) ### AWS -Airnode logs are available in -[CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. -Note that for the HTTP gateways, AWS generates a unique `requestId` for each -request. These should not be confused with the `requestId` of a request -originating from a blockchain. +Airnode logs are available in [CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. Note that for the HTTP gateways, AWS generates a unique `requestId` for each request. These should not be confused with the `requestId` of a request originating from a blockchain. ### GCP -Airnode logs are available in the -[Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to -query or stream logs by the "Cloud Function" Resource Type and then by "Function -Name" in order to view a specific request type or Airnode cycle stage. +Airnode logs are available in the [Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to query or stream logs by the "Cloud Function" Resource Type and then by "Function Name" in order to view a specific request type or Airnode cycle stage. ## Local Airnode Client -Running the `airnode-client` Docker image will output container logs to the -command line. These logs are also available through the Docker interface e.g. -under Containers within Docker Desktop. See the Docker -[client image](/reference/airnode/v0.11/docker/client-image.md) for more -information. +Running the `airnode-client` Docker image will output container logs to the command line. These logs are also available through the Docker interface e.g. under Containers within Docker Desktop. See the Docker [client image](/reference/airnode/v0.11/docker/client-image.md) for more information. diff --git a/docs/reference/airnode/v0.11/understand/oev-gateway.md b/docs/reference/airnode/v0.11/understand/oev-gateway.md index a7488c30..a1e1838a 100644 --- a/docs/reference/airnode/v0.11/understand/oev-gateway.md +++ b/docs/reference/airnode/v0.11/understand/oev-gateway.md @@ -19,23 +19,15 @@ tags: # {{$frontmatter.title}} -OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The -data is signed by the Airnode so that only the searcher who won the auction can -use it to update the data feed. You can learn more about OEV at -https://api3.org. +OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The data is signed by the Airnode so that only the searcher who won the auction can use it to update the data feed. You can learn more about OEV at https://api3.org. ## Setup -Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` -section. +Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` section. - **enabled**: A boolean to enable/disable for the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless functions serving gateway requests. When omitted, - there is no maximum concurrency set. This field is ignored for Airnode client - gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless functions serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -56,44 +48,25 @@ section. ## Gateway URL -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URL should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URL should be kept secret. -The gateway URL is also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/v0.11/understand/heartbeat.md) to your specified -heartbeat URL. +The gateway URL is also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/v0.11/understand/heartbeat.md) to your specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated when Airnode is deployed. You can see the URLs -including the secret `UUID` path parameter, displayed on your terminal at the -end of an Airnode deployment using a -[Docker image](/reference/airnode/v0.11/docker/). +A gateway URL is generated when Airnode is deployed. You can see the URLs including the secret `UUID` path parameter, displayed on your terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/v0.11/docker/). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for the gateway, which is exposed on the host machine. -Doing so will make the gateway API accessible like a regular web server running -on the machine. Note the `PORT` which is exposed as part of the Airnode client -container. See the -[Airnode client usage](/reference/airnode/v0.11/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for the gateway, which is exposed on the host machine. Doing so will make the gateway API accessible like a regular web server running on the machine. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/v0.11/docker/client-image.md#usage) for more details. -- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - - Gateway URL for the OEV Gateway +- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - Gateway URL for the OEV Gateway ## Usage -In order to execute the processing on the gateway, it needs to receive a -properly constructed HTTP request: +In order to execute the processing on the gateway, it needs to receive a properly constructed HTTP request: - It must be a `POST` request - It must contain a `Content-Type` header, set to `application/json`. @@ -136,8 +109,7 @@ where: - `updateId` - Auction update ID. - `bidderAddress` - Blockchain address of the winning searcher. - `bidAmount` - Bid amount that won the auction. -- `beacons` - A list of beacon data to be signed. It can contain two types: full - beacon data, only beacon metadata +- `beacons` - A list of beacon data to be signed. It can contain two types: full beacon data, only beacon metadata - `airnodeAddress` - Airnode address identifying a beacon - `endpointId` - Endpoint ID identifying a beacon - `encodedParameters` - Parameters in their encoded form identifying a beacon @@ -181,8 +153,6 @@ curl --location '' \ ] ``` -The gateway will return a list of signatures. There is a signature for each -beacon within the data feed that is served by the given Airnode, returned in the -same order as they are specified in the request body. +The gateway will return a list of signatures. There is a signature for each beacon within the data feed that is served by the given Airnode, returned in the same order as they are specified in the request body. diff --git a/docs/reference/airnode/v0.11/understand/using-authorizations.md b/docs/reference/airnode/v0.11/understand/using-authorizations.md index 5f0e12aa..6e1a516b 100644 --- a/docs/reference/airnode/v0.11/understand/using-authorizations.md +++ b/docs/reference/airnode/v0.11/understand/using-authorizations.md @@ -19,39 +19,22 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using -[Authorizations](/reference/airnode/v0.11/concepts/authorizations.md). This -method is off-chain and requires no blockchain knowledge by an API provider. It -is different than -[Authorizers](/reference/airnode/v0.11/concepts/authorizers.md) which is an -on-chain auth scheme. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizations](/reference/airnode/v0.11/concepts/authorizations.md). This method is off-chain and requires no blockchain knowledge by an API provider. It is different than [Authorizers](/reference/airnode/v0.11/concepts/authorizers.md) which is an on-chain auth scheme. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/v0.11/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: -Authorizations use scheme types that hard-code access to an Airnode's endpoints -in the same file that defines the Airnode, its `config.json` file. These -hard-coded values are endpointId/address pairs that the Airnode will use to -allow access to its endpoints by requesters (smart contracts). +Authorizations use scheme types that hard-code access to an Airnode's endpoints in the same file that defines the Airnode, its `config.json` file. These hard-coded values are endpointId/address pairs that the Airnode will use to allow access to its endpoints by requesters (smart contracts). -Nothing in _authorizers_ can supersede permissions granted by _authorizations_ -as the latter takes precedence. -Currently there is only one _authorizations_ scheme type, -`requesterEndpointAuthorizations`. +Nothing in _authorizers_ can supersede permissions granted by _authorizations_ as the latter takes precedence. +Currently there is only one _authorizations_ scheme type, `requesterEndpointAuthorizations`. ## requesterEndpointAuthorizations -Currently `requesterEndpointAuthorizations` is the only scheme type available -for _authorizations_. It defines a list of endpointIds each with a array of -requester addresses that can access them. +Currently `requesterEndpointAuthorizations` is the only scheme type available for _authorizations_. It defines a list of endpointIds each with a array of requester addresses that can access them. ```json { diff --git a/docs/reference/airnode/v0.11/versions.md b/docs/reference/airnode/v0.11/versions.md index 5b74c7d9..aeff1e7c 100644 --- a/docs/reference/airnode/v0.11/versions.md +++ b/docs/reference/airnode/v0.11/versions.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -The latest version of Airnode is `v0.11.x`. See -[releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for -all Airnode versions. Below is a list of Airnode versions included in this -documentation website. +The latest version of Airnode is `v0.11.x`. See [releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for all Airnode versions. Below is a list of Airnode versions included in this documentation website. | | | ------- | @@ -30,9 +27,7 @@ documentation website. ## Other Versions -Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their -documentation is available at -[https://old-docs.api3.org](https://old-docs.api3.org). +Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their documentation is available at [https://old-docs.api3.org](https://old-docs.api3.org). | | | --------------------------------------------------------- | diff --git a/docs/reference/airnode/v0.12/chain-idiosyncrasies.md b/docs/reference/airnode/v0.12/chain-idiosyncrasies.md index be227efa..a5c40832 100644 --- a/docs/reference/airnode/v0.12/chain-idiosyncrasies.md +++ b/docs/reference/airnode/v0.12/chain-idiosyncrasies.md @@ -19,60 +19,28 @@ tags: # {{$frontmatter.title}} -Differences in chain design inevitably lead to some unique chain-specific -considerations. Below are idiosyncrasies we have identified, though it may not -be comprehensive and we are interested in hearing if you encounter others. +Differences in chain design inevitably lead to some unique chain-specific considerations. Below are idiosyncrasies we have identified, though it may not be comprehensive and we are interested in hearing if you encounter others. ## config.json - `chains` field -The idiosyncrasies below relate to the `chains` field of `config.json` discussed -in -[Configuring Airnode](/reference/airnode/v0.12/understand/configuring.md#chains) -and -[Deployment Files](/reference/airnode/v0.12/deployment-files/config-json.md#chains) -section. +The idiosyncrasies below relate to the `chains` field of `config.json` discussed in [Configuring Airnode](/reference/airnode/v0.12/understand/configuring.md#chains) and [Deployment Files](/reference/airnode/v0.12/deployment-files/config-json.md#chains) section. ### Avalanche -Gas prices on Avalanche mainnet are often underestimated when getting `type 0` -estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error -manifests as the `maxFeePerGas` being set to less than the block -`baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set -`recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. +Gas prices on Avalanche mainnet are often underestimated when getting `type 0` estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error manifests as the `maxFeePerGas` being set to less than the block `baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set `recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. ### Arbitrum -Execution costs on Arbitrum are calculated slightly differently than Ethereum, -which impacts the gas required to fulfill requests. To account for this, it is -recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when -using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is -optional, so if it is not specified, Airnode will attempt to estimate the -appropriate gas limit automatically. Read more about -[ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. +Execution costs on Arbitrum are calculated slightly differently than Ethereum, which impacts the gas required to fulfill requests. To account for this, it is recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. Read more about [ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. ### Metis -On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is -recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that -`fulfillmentGasLimit` is optional, so if it is not specified, Airnode will -attempt to estimate the appropriate gas limit automatically. +On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. ### Optimism -Using `type 0` transaction types is recommended over `type 2` so the use of -`providerRecommendedEip1559GasPrice` is discouraged. - -As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, -which are -[accounted for separately](https://docs.optimism.io/stack/transactions/fees). To -cover the L1 data fee when a sponsor requests a -[withdrawal](/reference/airnode/v0.12/concepts/sponsor.md#withdrawals), an -amount has to be subtracted from the funds returned to the sponsor. The -`withdrawalRemainder` parameter has been introduced specifically for this -reason, though the value required will differ between Optimism mainnet and -testnet due to differences in L1 gas fees. For Optimism testnet, a -`withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a -value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover -an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. +Using `type 0` transaction types is recommended over `type 2` so the use of `providerRecommendedEip1559GasPrice` is discouraged. + +As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, which are [accounted for separately](https://docs.optimism.io/stack/transactions/fees). To cover the L1 data fee when a sponsor requests a [withdrawal](/reference/airnode/v0.12/concepts/sponsor.md#withdrawals), an amount has to be subtracted from the funds returned to the sponsor. The `withdrawalRemainder` parameter has been introduced specifically for this reason, though the value required will differ between Optimism mainnet and testnet due to differences in L1 gas fees. For Optimism testnet, a `withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. diff --git a/docs/reference/airnode/v0.12/cloud-resources.md b/docs/reference/airnode/v0.12/cloud-resources.md index a682940e..a2d074e7 100644 --- a/docs/reference/airnode/v0.12/cloud-resources.md +++ b/docs/reference/airnode/v0.12/cloud-resources.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain -resources to fully operate and supports most regions. +When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain resources to fully operate and supports most regions. ## Resources diff --git a/docs/reference/airnode/v0.12/concepts/airnode-auth.md b/docs/reference/airnode/v0.12/concepts/airnode-auth.md index d0b2c475..72113df9 100644 --- a/docs/reference/airnode/v0.12/concepts/airnode-auth.md +++ b/docs/reference/airnode/v0.12/concepts/airnode-auth.md @@ -19,40 +19,24 @@ tags: # {{$frontmatter.title}} -API providers can instruct Airnode to authenticate requests to their endpoints. -This is done by setting up a security scheme in the config.json file for their -Airnode. Airnode supports three methods of authentication from the OpenAPI -specification. +API providers can instruct Airnode to authenticate requests to their endpoints. This is done by setting up a security scheme in the config.json file for their Airnode. Airnode supports three methods of authentication from the OpenAPI specification. > -[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) -uses the term **security scheme** for authentication and authorization schemes. -Airnode only uses standard OAS defined authentication schemes to identify itself -to API endpoints. Airnode supports two types of authentication, `http` and -`apiKey`. +[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) uses the term **security scheme** for authentication and authorization schemes. Airnode only uses standard OAS defined authentication schemes to identify itself to API endpoints. Airnode supports two types of authentication, `http` and `apiKey`. -- HTTP authentication schemes (using the `Authorization` header) supported by - Airnode: +- HTTP authentication schemes (using the `Authorization` header) supported by Airnode: - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) - [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) -- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in - the request header, cookie in header or query string +- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in the request header, cookie in header or query string -How Airnode sends the authentication data is explained in the sections **Basic, -Bearer and API Key** below. +How Airnode sends the authentication data is explained in the sections **Basic, Bearer and API Key** below. ## Basic -Basic authentication is a simple authentication scheme built into the HTTP -protocol. The Authorization request header contains the Base64-encoded username -and password, separated by a colon. When handling the request, the server -decodes the login details and checks if the user can access the requested -content. +Basic authentication is a simple authentication scheme built into the HTTP protocol. The Authorization request header contains the Base64-encoded username and password, separated by a colon. When handling the request, the server decodes the login details and checks if the user can access the requested content. -The header field is in the form of `Authorization: Basic ` where -`credentials` is the Base64 encoding of a username and password joined by a -single colon (`airnode:airnode-password`). +The header field is in the form of `Authorization: Basic ` where `credentials` is the Base64 encoding of a username and password joined by a single colon (`airnode:airnode-password`). `Authorization: Basic ` @@ -63,10 +47,7 @@ curl -H "Authorization: Basic YW5kZXJzb25AZ21haWwuY29tOjEyM215cGFzc3dvcmQ=" \ ## Bearer -Bearer authentication (also called token authentication) is an HTTP -authentication scheme that involves security tokens called bearer tokens. The -API provider supplies a token used by Airnode to authenticate itself to API -endpoints. +Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The API provider supplies a token used by Airnode to authenticate itself to API endpoints. The header field is in the form of `Authorization: Bearer `. @@ -77,9 +58,7 @@ curl -H "Authorization: Bearer RZ8Y65TG" \ ## API Key -Some APIs use an `apiKey` for authentication. The API provider supplies an -`apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can -send the `apiKey` three ways. +Some APIs use an `apiKey` for authentication. The API provider supplies an `apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can send the `apiKey` three ways. ```sh # In the query string. diff --git a/docs/reference/airnode/v0.12/concepts/airnode.md b/docs/reference/airnode/v0.12/concepts/airnode.md index e3a876fc..08379376 100644 --- a/docs/reference/airnode/v0.12/concepts/airnode.md +++ b/docs/reference/airnode/v0.12/concepts/airnode.md @@ -19,37 +19,17 @@ tags: # {{$frontmatter.title}} -Airnode is a serverless oracle node implemented with a "set and forget" -philosophy. Airnode is flexible in that it can move API provider data on-chain -for multiple purposes. The most important of which are data feeds -([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in -response to dApp direct requests for API provider data -([RRP](/reference/airnode/v0.12/developers/)). +Airnode is a serverless oracle node implemented with a "set and forget" philosophy. Airnode is flexible in that it can move API provider data on-chain for multiple purposes. The most important of which are data feeds ([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in response to dApp direct requests for API provider data ([RRP](/reference/airnode/v0.12/developers/)). ## Airnode sources data to dAPIs -An Airnode supplies API provider data to beacons from API providers. These -beacons are the underlying data source for data feeds known as dAPIs. +An Airnode supplies API provider data to beacons from API providers. These beacons are the underlying data source for data feeds known as dAPIs. -API providers, owners of first-party Airnodes, store data feed values on-chain -as individual beacons that in are turn sourced by the -[Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) -contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). -Airnode has an internal mechanism that looks for a deviation in the value of API -provider's API operations. This mechanism updates beacons on-chain as needed. +API providers, owners of first-party Airnodes, store data feed values on-chain as individual beacons that in are turn sourced by the [Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). Airnode has an internal mechanism that looks for a deviation in the value of API provider's API operations. This mechanism updates beacons on-chain as needed. ## Airnode processes RRP requests -An Airnode is capable of serving the data from one or more APIs directly to -[requesters](/reference/airnode/v0.12/concepts/requester.md) (which are on-chain -smart contracts) that request data served by a particular Airnode. This is done -using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 -protocol is designed to be flexible and is meant to serve a variety of use -cases. See the the -[Calling Airnode (RRP)](/reference/airnode/v0.12/developers/index.md) for more -details on how an RRP request is made. Also see the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/contracts) -for potential design patterns. +An Airnode is capable of serving the data from one or more APIs directly to [requesters](/reference/airnode/v0.12/concepts/requester.md) (which are on-chain smart contracts) that request data served by a particular Airnode. This is done using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 protocol is designed to be flexible and is meant to serve a variety of use cases. See the the [Calling Airnode (RRP)](/reference/airnode/v0.12/developers/index.md) for more details on how an RRP request is made. Also see the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/contracts) for potential design patterns. diff --git a/docs/reference/airnode/v0.12/deployment-files/templates/aws-env.md b/docs/reference/airnode/v0.12/deployment-files/templates/aws-env.md index 13ff5a64..a345605e 100644 --- a/docs/reference/airnode/v0.12/deployment-files/templates/aws-env.md +++ b/docs/reference/airnode/v0.12/deployment-files/templates/aws-env.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -The `aws.env` contains AWS credentials from an IAM user. These credentials are -used by the Docker -[deployer image](/reference/airnode/v0.12/docker/deployer-image.md) to deploy an -Airnode to AWS. For more details, see the full description of the -[aws.env](/reference/airnode/v0.12/deployment-files/templates/aws-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `aws.env` contains AWS credentials from an IAM user. These credentials are used by the Docker [deployer image](/reference/airnode/v0.12/docker/deployer-image.md) to deploy an Airnode to AWS. For more details, see the full description of the [aws.env](/reference/airnode/v0.12/deployment-files/templates/aws-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AWS_ACCESS_KEY_ID= diff --git a/docs/reference/airnode/v0.12/deployment-files/templates/config-json.md b/docs/reference/airnode/v0.12/deployment-files/templates/config-json.md index 3f362325..26b92542 100644 --- a/docs/reference/airnode/v0.12/deployment-files/templates/config-json.md +++ b/docs/reference/airnode/v0.12/deployment-files/templates/config-json.md @@ -19,33 +19,23 @@ tags: # {{$frontmatter.title}} -A template for an Airnode's configuration file. Below are notations to help -explain contents of the template. +A template for an Airnode's configuration file. Below are notations to help explain contents of the template. -- `, , `: The value added is independent from - other fields and a value is needed unless otherwise indicated. These values - are not considered secret unless you want them to be. +- `, , `: The value added is independent from other fields and a value is needed unless otherwise indicated. These values are not considered secret unless you want them to be. -- ``: If two fields contain the same - expression, use the same value in them because they are referencing each - other. Usually these are not considered to be secret. +- ``: If two fields contain the same expression, use the same value in them because they are referencing each other. Usually these are not considered to be secret. -- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to - `secrets.env` though it is not required. +- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to `secrets.env` though it is not required. Consider the following relationships. - `ois[0].title` is related to `triggers.rrp[0].oisTitle`. -- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to - ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in -- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to - ois[0].endpoints[0].parameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to ois[0].endpoints[0].parameters[0].operationParameter.in -See -[config.json](/reference/airnode/v0.12/deployment-files/templates/config-json.md) -as a reference while building a config.json file. +See [config.json](/reference/airnode/v0.12/deployment-files/templates/config-json.md) as a reference while building a config.json file. ```json { diff --git a/docs/reference/airnode/v0.12/deployment-files/templates/ois-json.md b/docs/reference/airnode/v0.12/deployment-files/templates/ois-json.md index b1911e8b..e36417c9 100644 --- a/docs/reference/airnode/v0.12/deployment-files/templates/ois-json.md +++ b/docs/reference/airnode/v0.12/deployment-files/templates/ois-json.md @@ -19,11 +19,6 @@ tags: # {{$frontmatter.title}} -An [OIS (Oracle Integration Specifications)](/reference/ois/2.1/) JSON object is -part of an Airnode's -[config.json](/reference/airnode/v0.12/deployment-files/templates/config-json.md) -file. There can be more than one OIS object in the `config.json` file that -defines an Airnode. See the [OIS Template](/reference/ois/2.1/template.md) in -the OIS document set. +An [OIS (Oracle Integration Specifications)](/reference/ois/2.1/) JSON object is part of an Airnode's [config.json](/reference/airnode/v0.12/deployment-files/templates/config-json.md) file. There can be more than one OIS object in the `config.json` file that defines an Airnode. See the [OIS Template](/reference/ois/2.1/template.md) in the OIS document set. diff --git a/docs/reference/airnode/v0.12/deployment-files/templates/secrets-env.md b/docs/reference/airnode/v0.12/deployment-files/templates/secrets-env.md index b4f2c9f1..67106136 100644 --- a/docs/reference/airnode/v0.12/deployment-files/templates/secrets-env.md +++ b/docs/reference/airnode/v0.12/deployment-files/templates/secrets-env.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The `secrets.env` contains the secrets that the respective Airnode deployments -will need. All variables defined in a `secrets.env` can be interpolated inside -`config.json`. For more details, see the full description of the -[secrets.env](/reference/airnode/v0.12/deployment-files/secrets-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `secrets.env` contains the secrets that the respective Airnode deployments will need. All variables defined in a `secrets.env` can be interpolated inside `config.json`. For more details, see the full description of the [secrets.env](/reference/airnode/v0.12/deployment-files/secrets-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AIRNODE_WALLET_MNEMONIC="" diff --git a/docs/reference/airnode/v0.12/developers/fees.md b/docs/reference/airnode/v0.12/developers/fees.md index ccb9f794..f18a38d3 100644 --- a/docs/reference/airnode/v0.12/developers/fees.md +++ b/docs/reference/airnode/v0.12/developers/fees.md @@ -19,18 +19,11 @@ tags: # {{$frontmatter.title}} -There are some one-time setup/maintenance costs and some ongoing costs of -calling an Airnode. The Airnode protocol is designed in a way that the requester -assumes all gas costs, including the request fulfillment (response) -transactions. +There are some one-time setup/maintenance costs and some ongoing costs of calling an Airnode. The Airnode protocol is designed in a way that the requester assumes all gas costs, including the request fulfillment (response) transactions. ## Sponsors -Fees are encountered when a sponsor engages in setup activity such as sponsoring -a requester. These are per call transaction gas costs and are relatively small. -The funds come from the wallet mnemonic that the sponsor supplies when calling -certain [admin commands](/reference/airnode/v0.12/packages/admin-cli.md) as -shown below. +Fees are encountered when a sponsor engages in setup activity such as sponsoring a requester. These are per call transaction gas costs and are relatively small. The funds come from the wallet mnemonic that the sponsor supplies when calling certain [admin commands](/reference/airnode/v0.12/packages/admin-cli.md) as shown below. - [sponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#unsponsor-requester) @@ -39,32 +32,18 @@ shown below. ## Airnodes -The fees take the form of transaction gas costs. These are applied when funding -a requester's sponsor wallet for an Airnode and when executing the Airnode in -response to a request. +The fees take the form of transaction gas costs. These are applied when funding a requester's sponsor wallet for an Airnode and when executing the Airnode in response to a request. -- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is - funded manually by a sponsor using their preferred wallet management tool such - as MetaMask. +- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is funded manually by a sponsor using their preferred wallet management tool such as MetaMask. -- [Calling](/reference/airnode/v0.12/developers/index.md) an Airnode: - Transaction gas fees are withdrawn from the sponsor wallet related to the - Airnode being called by a sponsored requester. +- [Calling](/reference/airnode/v0.12/developers/index.md) an Airnode: Transaction gas fees are withdrawn from the sponsor wallet related to the Airnode being called by a sponsored requester. -Learn more about [sponsor wallets](/reference/airnode/v0.12/concepts/sponsor.md) -in the reference section. +Learn more about [sponsor wallets](/reference/airnode/v0.12/concepts/sponsor.md) in the reference section. ## API Provider Fees -Some API providers charge a subscription fee for access to their data. This is a -typical practice and usually requires the requester to create an account on the -provider's website and then subscribe to a level of service offered. These types -of services are usually billed monthly and can be based on an annual rate to -save costs. The subscription (even if free) will most likely involve the use of -a security scheme such as an API key that must be used to access the data. See -[Calling an Airnode](/reference/airnode/v0.12/developers/index.md) to learn more -on how to pass the security credentials to an Airnode. +Some API providers charge a subscription fee for access to their data. This is a typical practice and usually requires the requester to create an account on the provider's website and then subscribe to a level of service offered. These types of services are usually billed monthly and can be based on an annual rate to save costs. The subscription (even if free) will most likely involve the use of a security scheme such as an API key that must be used to access the data. See [Calling an Airnode](/reference/airnode/v0.12/developers/index.md) to learn more on how to pass the security credentials to an Airnode. diff --git a/docs/reference/airnode/v0.12/developers/index.md b/docs/reference/airnode/v0.12/developers/index.md index 8255971b..bb8f9580 100644 --- a/docs/reference/airnode/v0.12/developers/index.md +++ b/docs/reference/airnode/v0.12/developers/index.md @@ -19,47 +19,22 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that can push off-chain API data to an on-chain -contract. While dApp developers will find -[dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the -most useful aspect of an Airnode's capabilities, there is the option for -developers to access Airnode data using its request-response protocol (RRP). The -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12.0/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract facilitates RRP and is designed to be flexible and is meant to -serve a variety of use cases. See the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/contracts) -for potential design patterns. +Airnode is a first-party oracle that can push off-chain API data to an on-chain contract. While dApp developers will find [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the most useful aspect of an Airnode's capabilities, there is the option for developers to access Airnode data using its request-response protocol (RRP). The [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12.0/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract facilitates RRP and is designed to be flexible and is meant to serve a variety of use cases. See the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/contracts) for potential design patterns. ## It starts with a requester -A requester is a smart contract that can trigger an Airnode RRP request. To do -so, the requester needs to be sponsored and make the request using a matching -sponsor wallet. See -[Requesters and Sponsors](/reference/airnode/v0.12/developers/requesters-sponsors.md) -on how to sponsor a requester and derive the sponsor wallet. +A requester is a smart contract that can trigger an Airnode RRP request. To do so, the requester needs to be sponsored and make the request using a matching sponsor wallet. See [Requesters and Sponsors](/reference/airnode/v0.12/developers/requesters-sponsors.md) on how to sponsor a requester and derive the sponsor wallet. ## A simplified understanding -In the diagram below, any typical smart contract is called a requester if it -makes a request of Airnode's RRP protocol. It makes a request to the on-chain -RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event -logs. The off-chain Airnode then accesses the event logs, gets the API data and -performs a callback to the requester. +In the diagram below, any typical smart contract is called a requester if it makes a request of Airnode's RRP protocol. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event logs. The off-chain Airnode then accesses the event logs, gets the API data and performs a callback to the requester. In summary, the requester will do two things. -- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol - contract, which returns a - [`requestId`](/reference/airnode/v0.12/concepts/request.md#requestid). -- Add a `myFulfill()` function (call it what you like) to your requester where - the off-chain Airnode can send the requested data when ready. The data - includes the same `requestId` as the one returned at the time of making the - request. +- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol contract, which returns a [`requestId`](/reference/airnode/v0.12/concepts/request.md#requestid). +- Add a `myFulfill()` function (call it what you like) to your requester where the off-chain Airnode can send the requested data when ready. The data includes the same `requestId` as the one returned at the time of making the request. -In the diagram below a requester makes a request to the on-chain RRP protocol -contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its -run cycle the off-chain Airnode accesses the event logs, gets the requested data -from the the API provider, then performs a callback to the requester. +In the diagram below a requester makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its run cycle the off-chain Airnode accesses the event logs, gets the requested data from the the API provider, then performs a callback to the requester. > > @@ -68,19 +43,13 @@ from the the API provider, then performs a callback to the requester. > 3.

Airnode gathers response data from the API specified in the request.

> 4.

Airnode performs a callback to a named function myFulfill() in myContract.sol via the AirnodeRrpV0.sol function fulfill() with the requested data and the requestId.

-See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn -how to make a RRP request of an Airnode. +See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn how to make a RRP request of an Airnode. ## A deeper dive -This section, through its detailed illustration, builds on the previous section -([A simplified understanding](/reference/airnode/v0.12/developers/index.md#a-simplified-understanding)) -in an attempt to further illustrate and explain the mechanics of how an Airnode -response to a request made by a requester. +This section, through its detailed illustration, builds on the previous section ([A simplified understanding](/reference/airnode/v0.12/developers/index.md#a-simplified-understanding)) in an attempt to further illustrate and explain the mechanics of how an Airnode response to a request made by a requester. -Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") -deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain -**protocol contract** AirnodeRrpV0.sol. +Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain **protocol contract** AirnodeRrpV0.sol. > > diff --git a/docs/reference/airnode/v0.12/developers/requesters-sponsors.md b/docs/reference/airnode/v0.12/developers/requesters-sponsors.md index 4daf2e0e..8a3cdba8 100644 --- a/docs/reference/airnode/v0.12/developers/requesters-sponsors.md +++ b/docs/reference/airnode/v0.12/developers/requesters-sponsors.md @@ -19,143 +19,80 @@ tags: # {{$frontmatter.title}} -As a dApp developer it helps to understand what a **requester** is and what a -**sponsor** does. They are both important parts of the Airnode ecosystem. This -doc will further define them and walk you through the process of sponsoring a -requester and deriving a sponsor wallet using the admin CLI commands. +As a dApp developer it helps to understand what a **requester** is and what a **sponsor** does. They are both important parts of the Airnode ecosystem. This doc will further define them and walk you through the process of sponsoring a requester and deriving a sponsor wallet using the admin CLI commands. ## What is a Requester? -The term [requester](/reference/airnode/v0.12/concepts/requester.md) is -important to remember. When requester is mentioned, the reference is to your -smart contract that makes a request of an Airnode. +The term [requester](/reference/airnode/v0.12/concepts/requester.md) is important to remember. When requester is mentioned, the reference is to your smart contract that makes a request of an Airnode. > -As an example see the `myContract.sol` contract in the diagram within the -[Overview](/reference/airnode/v0.12/concepts/) doc, it is a requester. +As an example see the `myContract.sol` contract in the diagram within the [Overview](/reference/airnode/v0.12/concepts/) doc, it is a requester. ## What is a Sponsor? -Equally important is the term -[sponsor](/reference/airnode/v0.12/concepts/sponsor.md). A sponsor is an entity -such as yourself, an organization, etc. Sponsors create relationships between -requesters and Airnodes. +Equally important is the term [sponsor](/reference/airnode/v0.12/concepts/sponsor.md). A sponsor is an entity such as yourself, an organization, etc. Sponsors create relationships between requesters and Airnodes. ### Sponsor's Requester/Airnode Relationships -As a sponsor you will use the public address from an account within a mnemonic -you own to "**sponsor a requester**" and then use the public address (known as a -[sponsorAddress](/reference/airnode/v0.12/concepts/sponsor.md#sponsoraddress)) -to "**derive a -[sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet)**" -for an Airnode. This action creates a relationship between a sponsor's requester -and a particular Airnode. You do this because a sponsor is the entity that pays -for the fulfillment of a request, the gas costs the Airnode will incur. These -costs will be withdrawn from the `sponsorWallet` of the Airnode when the -requester calls it. +As a sponsor you will use the public address from an account within a mnemonic you own to "**sponsor a requester**" and then use the public address (known as a [sponsorAddress](/reference/airnode/v0.12/concepts/sponsor.md#sponsoraddress)) to "**derive a [sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet)**" for an Airnode. This action creates a relationship between a sponsor's requester and a particular Airnode. You do this because a sponsor is the entity that pays for the fulfillment of a request, the gas costs the Airnode will incur. These costs will be withdrawn from the `sponsorWallet` of the Airnode when the requester calls it. ::: info sponsorAddress -A [sponsorAddress](/reference/airnode/v0.12/concepts/sponsor.md#sponsoraddress) -is a public address of an account from a mnemonic, usually the default account. -Rather than the default account another account from the mnemonic can be used. -The `sponsorAddress` is used to uniquely identify a sponsor. +A [sponsorAddress](/reference/airnode/v0.12/concepts/sponsor.md#sponsoraddress) is a public address of an account from a mnemonic, usually the default account. Rather than the default account another account from the mnemonic can be used. The `sponsorAddress` is used to uniquely identify a sponsor. ::: -1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester - with the Admin CLI. The CLI will use the default address of the mnemonic - passed as the `sponsorAddress` for the sponsorship unless another account is - specified. +1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester with the Admin CLI. The CLI will use the default address of the mnemonic passed as the `sponsorAddress` for the sponsorship unless another account is specified. -2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the - `sponsorAddress`. +2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the `sponsorAddress`. 3. The requester can now make requests of the Airnode. > -In the above diagram it is possible to use the same sponsorAddress -`(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is -possible to sponsor more than one requester with the same `sponsorAddress`. -However it is important to remember that all requesters can now access all the -Airnodes regardless if they need to. There is no harm in this scenario. +In the above diagram it is possible to use the same sponsorAddress `(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is possible to sponsor more than one requester with the same `sponsorAddress`. However it is important to remember that all requesters can now access all the Airnodes regardless if they need to. There is no harm in this scenario. ### Advanced Scenarios - **Two requesters, one Airnode, one sponsorWallet**: - Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) - would access the same Airnode using a single sponsorWallet derived by the - `sponsorAddress`. + Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) would access the same Airnode using a single sponsorWallet derived by the `sponsorAddress`. - **Two requesters, one Airnode, two sponsorWallets**: - Sponsor two different requesters each with a different `sponsorAddress` (e.g., - `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you - can derive two separate sponsorWallets for the same Airnode. Now each - requester will deplete funds from a separate Airnode sponsorWallet when using - the Airnode. + Sponsor two different requesters each with a different `sponsorAddress` (e.g., `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you can derive two separate sponsorWallets for the same Airnode. Now each requester will deplete funds from a separate Airnode sponsorWallet when using the Airnode. - **One requester, two Airnodes, two sponsorWallets**: - A requester can make requests from two different Airnodes. Sponsor the - requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of - two the Airnodes, using the `sponsorAddress`. Despite the fact that the - sponsorWallet for each Airnode was derived with the same `sponsorAddress` the - sponsorWallets are different since they are derived using the airnode's xpub - plus the `sponsorAddress`. The sponsor must fund both wallets separately using - the unique `sponsorWallet` address of the two sponsorWallets. + A requester can make requests from two different Airnodes. Sponsor the requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of two the Airnodes, using the `sponsorAddress`. Despite the fact that the sponsorWallet for each Airnode was derived with the same `sponsorAddress` the sponsorWallets are different since they are derived using the airnode's xpub plus the `sponsorAddress`. The sponsor must fund both wallets separately using the unique `sponsorWallet` address of the two sponsorWallets. ### Things to Remember -When you sponsor a requester with a `sponsorAddress` you are giving it -permission to use the sponsorWallet (associated with a Airnode) that was derived -using the same `sponsorAddress`. +When you sponsor a requester with a `sponsorAddress` you are giving it permission to use the sponsorWallet (associated with a Airnode) that was derived using the same `sponsorAddress`. -When the requester makes a request to the Airnode, the Airnode will use funds -from the corresponding sponsorWallet to pay gas costs in response to the -request. Therefore the sponsor pays for the fulfillment of the request. +When the requester makes a request to the Airnode, the Airnode will use funds from the corresponding sponsorWallet to pay gas costs in response to the request. Therefore the sponsor pays for the fulfillment of the request. -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/v0.12/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/v0.12/developers/fees.md#api-provider-fees). ## Admin CLI Commands -There are several sponsor and requester related commands in the -[Admin CLI Commands](/reference/airnode/v0.12/packages/admin-cli.md) package. -You can also see a list of available commands using -`npx @api3/airnode-admin --help`. +There are several sponsor and requester related commands in the [Admin CLI Commands](/reference/airnode/v0.12/packages/admin-cli.md) package. You can also see a list of available commands using `npx @api3/airnode-admin --help`. -In the next two sections of this doc you will use two commands from the -`@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor -wallet_. +In the next two sections of this doc you will use two commands from the `@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor wallet_. -1. [sponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#sponsor-requester) - sponsors a requester. -2. [derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address)creates - a sponsor wallet associated with an Airnode. +1. [sponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#sponsor-requester) sponsors a requester. +2. [derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address)creates a sponsor wallet associated with an Airnode. ## How to Sponsor a Requester -To sponsor a requester execute the `sponsor-requester` command using the -parameters detailed in the list below. Your requester should already be deployed -on-chain. This command has transaction gas costs. +To sponsor a requester execute the `sponsor-requester` command using the parameters detailed in the list below. Your requester should already be deployed on-chain. This command has transaction gas costs. -- `providerURL`: A blockchain provider URL (such as Infura) with providerID for - the desired network. -- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to - derive the sponsorAddress from the default address. The sponsorAddress will be - needed to derive a sponsorWallet for an Airnode. +- `providerURL`: A blockchain provider URL (such as Infura) with providerID for the desired network. +- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to derive the sponsorAddress from the default address. The sponsorAddress will be needed to derive a sponsorWallet for an Airnode. - `requester-address`: Address of the requester contract. -- `derivation-path (optional)` (_not used in the example below_): Selects an - alternate account to use from the mnemonic rather than the default account. +- `derivation-path (optional)` (_not used in the example below_): Selects an alternate account to use from the mnemonic rather than the default account. -Executing the command -[sponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#sponsor-requester) -will sponsor a requester and returns the requesterAddress and sponsorAddress. +Executing the command [sponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#sponsor-requester) will sponsor a requester and returns the requesterAddress and sponsorAddress. ::: code-group @@ -181,27 +118,15 @@ npx @api3/airnode-admin sponsor-requester ^ ## How to Derive a Sponsor Wallet -To use a particular Airnode you must _derive a sponsorWallet_. Once the -sponsorWallet is created it must be funded using the public address -(`sponsorWallet` address) returned by the command -`derive-sponsor-wallet-address`. Each Airnode keeps a separate list of -individual sponsorWallets that can access the Airnode. Learn more about a -[sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). +To use a particular Airnode you must _derive a sponsorWallet_. Once the sponsorWallet is created it must be funded using the public address (`sponsorWallet` address) returned by the command `derive-sponsor-wallet-address`. Each Airnode keeps a separate list of individual sponsorWallets that can access the Airnode. Learn more about a [sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). -To derive a sponsorWallet for an Airnode execute the -[derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) -command using the parameters detailed in the list below. There are no -transaction gas costs to do so. +To derive a sponsorWallet for an Airnode execute the [derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) command using the parameters detailed in the list below. There are no transaction gas costs to do so. -- `airnode-xpub`: The extended public address of the Airnode for path - m/44'/60'/0'. +- `airnode-xpub`: The extended public address of the Airnode for path m/44'/60'/0'. - `airnode-address`: The public address of the desired Airnode. -- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) - owned by a sponsor. Usually the sponsorAddress is the one returned when - sponsoring a requester. +- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) owned by a sponsor. Usually the sponsorAddress is the one returned when sponsoring a requester. -The command `derive-sponsor-wallet-address` will return the public address -(`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. +The command `derive-sponsor-wallet-address` will return the public address (`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. ::: code-group @@ -225,22 +150,15 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ::: -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/v0.12/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/v0.12/developers/fees.md#api-provider-fees). -If you forget the public address (`sponsorWallet` address) of the sponsorWallet -simply run `derive-sponsor-wallet-address` again. Since the wallet already -exists for the airnodeAddress/sponsorAddress pair it will just return the -address. +If you forget the public address (`sponsorWallet` address) of the sponsorWallet simply run `derive-sponsor-wallet-address` again. Since the wallet already exists for the airnodeAddress/sponsorAddress pair it will just return the address. ## Record Keeping -During and after sponsoring requesters and deriving a sponsorWallet there are a -few things to keep track of. +During and after sponsoring requesters and deriving a sponsorWallet there are a few things to keep track of. | Item | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -248,11 +166,6 @@ few things to keep track of. | sponsor address | The public address of an account derived from a sponsor's mnemonic when sponsoring a requester. Record which `sponsorAddress` was used to create a sponsorWallet for each Airnode. | | sponsor wallet address | Record the `sponsorWallet` address of the sponsorWallet derived for an Airnode. For each Airnode you have derived a sponsorWallet, the Airnode keeps the private key and returns the public address (`sponsorWallet` address) which is used to fund the sponsorWallet. | -You can acquire the public address (`sponsorWallet` address) of a sponsorWallet -later, if you lose it, by running the command `derive-sponsor-wallet-address` -again. Since the sponsorWallet was already created for the -`sponsorAddress/airnodeAddress` pair, the command will only return the public -address for the wallet. However you must use the same `sponsorAddress` used when -the wallet was first created or a new sponsorWallet will be created. +You can acquire the public address (`sponsorWallet` address) of a sponsorWallet later, if you lose it, by running the command `derive-sponsor-wallet-address` again. Since the sponsorWallet was already created for the `sponsorAddress/airnodeAddress` pair, the command will only return the public address for the wallet. However you must use the same `sponsorAddress` used when the wallet was first created or a new sponsorWallet will be created. diff --git a/docs/reference/airnode/v0.12/developers/using-templates.md b/docs/reference/airnode/v0.12/developers/using-templates.md index 8dda5ab8..87408126 100644 --- a/docs/reference/airnode/v0.12/developers/using-templates.md +++ b/docs/reference/airnode/v0.12/developers/using-templates.md @@ -19,15 +19,7 @@ tags: # {{$frontmatter.title}} -A request to an Airnode can have many parameters. It is very common for -requester contracts (e.g., a data feed) to make repeated requests with the exact -same parameters. In such instances, it is wasteful to pass all of these -parameters repeatedly. Templates are used to hold a set of parameter values -on-chain that can be used repeatedly when calling -the`makeTemplateRequest()`function in -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). -Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester -pass`templateId`which identifies a template. +A request to an Airnode can have many parameters. It is very common for requester contracts (e.g., a data feed) to make repeated requests with the exact same parameters. In such instances, it is wasteful to pass all of these parameters repeatedly. Templates are used to hold a set of parameter values on-chain that can be used repeatedly when calling the`makeTemplateRequest()`function in [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester pass`templateId`which identifies a template. ```solidity function makeTemplateRequest( @@ -40,10 +32,7 @@ function makeTemplateRequest( ) external override returns (bytes32 requestId) { ``` -When a template is used to make a request, both the parameters encoded in -parameters of the template and parameters provided at request-time (if any) will -be used by the Airnode. In case the two include a parameter with the same name, -the one provided at request-time will be used. +When a template is used to make a request, both the parameters encoded in parameters of the template and parameters provided at request-time (if any) will be used by the Airnode. In case the two include a parameter with the same name, the one provided at request-time will be used. The structure of a template, as shown below, is simple. @@ -59,10 +48,6 @@ struct Template { } ``` -See the guide -[Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn -how to create and use a template. Also visit the -[coingecko-template](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/integrations/coingecko-template) -monorepo example demonstrates template requests. +See the guide [Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn how to create and use a template. Also visit the [coingecko-template](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/integrations/coingecko-template) monorepo example demonstrates template requests. diff --git a/docs/reference/airnode/v0.12/developers/verify-airnode-addresses.md b/docs/reference/airnode/v0.12/developers/verify-airnode-addresses.md index b54e6629..f294853e 100644 --- a/docs/reference/airnode/v0.12/developers/verify-airnode-addresses.md +++ b/docs/reference/airnode/v0.12/developers/verify-airnode-addresses.md @@ -19,18 +19,9 @@ tags: # {{$frontmatter.title}} -An Airnode is owned and operated by an API provider. Every Airnode has a unique -on-chain -[`airnodeAddress`](/reference/airnode/v0.12/concepts/airnode.md#airnodeaddress) -created and known by its API provider. API providers normally announce their -Airnode addresses in the form of a DNS `TXT` record within their DNS -registration, which also serves to prove ownership. An API provider's Airnode -address is the same for all chains. - -The key for the `TXT` record is `chainapi-verification-keys` and is an array of -Airnode addresses owned by the API provider. Below is an example of the Airnode -for -[dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). +An Airnode is owned and operated by an API provider. Every Airnode has a unique on-chain [`airnodeAddress`](/reference/airnode/v0.12/concepts/airnode.md#airnodeaddress) created and known by its API provider. API providers normally announce their Airnode addresses in the form of a DNS `TXT` record within their DNS registration, which also serves to prove ownership. An API provider's Airnode address is the same for all chains. + +The key for the `TXT` record is `chainapi-verification-keys` and is an array of Airnode addresses owned by the API provider. Below is an example of the Airnode for [dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). ![dxfeed-txt-record](../assets/images/txt-record-dxfeed.png) @@ -56,5 +47,4 @@ The following list of links go to the DNS lookup at DigitalOcean. - [Kaiko](https://www.digitalocean.com/community/tools/dns?domain=kaiko.io#TXT-Records) - [NewChangeFX](https://www.digitalocean.com/community/tools/dns?domain=newchangefx.com#TXT-Records) - [Nodary](https://www.digitalocean.com/community/tools/dns?domain=nodary.io#TXT-Records) -- [twelvedata](https://www.digitalocean.com/community/tools/dns?domain=twelvedata.com#TXT-Records) - +- [twelvedata](https://www.digitalocean.com/community/tools/dns?domain=twelvedata.com#TXT-Records) diff --git a/docs/reference/airnode/v0.12/docker/admin-cli-image.md b/docs/reference/airnode/v0.12/docker/admin-cli-image.md index c8d19c30..ffed93a4 100644 --- a/docs/reference/airnode/v0.12/docker/admin-cli-image.md +++ b/docs/reference/airnode/v0.12/docker/admin-cli-image.md @@ -22,24 +22,15 @@ tags: -Use the admin CLI image as an alternative method to execute -[Admin CLI](/reference/airnode/v0.12/packages/admin-cli.md) using npx. Either -method will achieve the same results. The image forgoes downloading the admin -CLI package each time a command is executed using npx. +Use the admin CLI image as an alternative method to execute [Admin CLI](/reference/airnode/v0.12/packages/admin-cli.md) using npx. Either method will achieve the same results. The image forgoes downloading the admin CLI package each time a command is executed using npx. -If you want to build the admin CLI image from the source yourself, you can find -the -[image built instructions](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin/docker) -in the Airnode repository. +If you want to build the admin CLI image from the source yourself, you can find the [image built instructions](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin/docker) in the Airnode repository. -Additional information about the -[admin CLI image](/reference/airnode/v0.12/packages/admin-cli.md#using-docker) -is available in the admin CLI commands doc. +Additional information about the [admin CLI image](/reference/airnode/v0.12/packages/admin-cli.md#using-docker) is available in the admin CLI commands doc. ## Usage -The following example shows the difference between using the docker image versus -npx when executing the `get-sponsor-status` admin CLI command. +The following example shows the difference between using the docker image versus npx when executing the `get-sponsor-status` admin CLI command. ```sh #npx diff --git a/docs/reference/airnode/v0.12/docker/client-image.md b/docs/reference/airnode/v0.12/docker/client-image.md index fdfb3b30..3dec913b 100644 --- a/docs/reference/airnode/v0.12/docker/client-image.md +++ b/docs/reference/airnode/v0.12/docker/client-image.md @@ -19,29 +19,17 @@ tags: # {{$frontmatter.title}} -Usually the Airnode is deployed on a serverless platform using the -[deployer](/reference/airnode/v0.12/docker/deployer-image.md). However, there is -another option which is to run the Airnode in a docker container on your machine -locally, on premise or cloud hosted. +Usually the Airnode is deployed on a serverless platform using the [deployer](/reference/airnode/v0.12/docker/deployer-image.md). However, there is another option which is to run the Airnode in a docker container on your machine locally, on premise or cloud hosted. -A docker client image has been published on -[Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build -the container from the source yourself, you can find the image and built -instructions in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-node/docker). +A docker client image has been published on [Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build the container from the source yourself, you can find the image and built instructions in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-node/docker). ## Configuration -The Airnode needs two configuration files for its run: `config.json` and -`secrets.env`. These files need to be passed to the Docker container via -volumes. +The Airnode needs two configuration files for its run: `config.json` and `secrets.env`. These files need to be passed to the Docker container via volumes. -The Docker container looks for configuration files mounted internally in the -`/app/config` directory. +The Docker container looks for configuration files mounted internally in the `/app/config` directory. -Your current working directory should contain the configuration files above and -you bind it to the `/app/config` directory for the docker using the `--volume` -parameter. +Your current working directory should contain the configuration files above and you bind it to the `/app/config` directory for the docker using the `--volume` parameter. ::: code-group @@ -73,8 +61,7 @@ $ docker run --volume %cd%:/config:/app/config ... ## Usage -Example directory structure and commands for running the Airnode Docker -container. The below commands are run from the depicted directory. +Example directory structure and commands for running the Airnode Docker container. The below commands are run from the depicted directory. ### Running Airnode @@ -105,18 +92,11 @@ docker run ^ ::: -> If you want to connect Airnode to a blockchain running on localhost, you need -> to make the blockchain accessible from within the docker itself. If you use -> docker for linux you can use `--network="host"` parameter. If you are using -> Docker Desktop (on any platform), connect to -> `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See -> [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). +> If you want to connect Airnode to a blockchain running on localhost, you need to make the blockchain accessible from within the docker itself. If you use docker for linux you can use `--network="host"` parameter. If you are using Docker Desktop (on any platform), connect to `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). ### Checking Airnode logs -Logs will be output to the console after running the above command. If you -decide to run Airnode in detached mode with `--detach`, you need to use the -`logs` command, optionally with `--follow`, to access the logs. +Logs will be output to the console after running the above command. If you decide to run Airnode in detached mode with `--detach`, you need to use the `logs` command, optionally with `--follow`, to access the logs. ```bash docker logs airnode diff --git a/docs/reference/airnode/v0.12/docker/deployer-image.md b/docs/reference/airnode/v0.12/docker/deployer-image.md index 97470409..fc9ec26b 100644 --- a/docs/reference/airnode/v0.12/docker/deployer-image.md +++ b/docs/reference/airnode/v0.12/docker/deployer-image.md @@ -19,26 +19,17 @@ tags: # {{$frontmatter.title}} -Use the deployer image to deploy or remove an Airnode with a cloud provider such -as AWS. The simplest way is to use the pre-built packages. If you would rather -build the images yourself see the -[README](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer/docker) -in the deployer package. +Use the deployer image to deploy or remove an Airnode with a cloud provider such as AWS. The simplest way is to use the pre-built packages. If you would rather build the images yourself see the [README](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer/docker) in the deployer package. ::: info Quick Deploy Demos -See the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -guides to quickly deploy and remove a preconfigured Airnode using the deployer -image. +See the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guides to quickly deploy and remove a preconfigured Airnode using the deployer image. ::: ## Configuration Files -The files `config.json` and `secrets.env` are used to configure the Airnode. The -`aws.env` and `gcp.json` files are used to define environment information the -deployer uses to connect to these cloud providers. +The files `config.json` and `secrets.env` are used to configure the Airnode. The `aws.env` and `gcp.json` files are used to define environment information the deployer uses to connect to these cloud providers. ``` my-airnode @@ -50,22 +41,15 @@ my-airnode ## Cloud Provider Credentials -In order to deploy Airnode to a serverless cloud provider, you need to provide -cloud provider credentials to the Airnode deployer image. The deployer image -currently supports deploying to AWS and GCP. For AWS deployment, see the -[AWS Setup](/reference/airnode/v0.12/understand/configuring.md#aws-setup-aws-deployment-only) -and for GCP deployment, see the -[GCP Setup](/reference/airnode/v0.12/understand/configuring.md#gcp-setup-gcp-deployment-only). +In order to deploy Airnode to a serverless cloud provider, you need to provide cloud provider credentials to the Airnode deployer image. The deployer image currently supports deploying to AWS and GCP. For AWS deployment, see the [AWS Setup](/reference/airnode/v0.12/understand/configuring.md#aws-setup-aws-deployment-only) and for GCP deployment, see the [GCP Setup](/reference/airnode/v0.12/understand/configuring.md#gcp-setup-gcp-deployment-only). ## Deployer Logs -The deployer saves log files by default into the `config/logs/` direcotry, but -this can be changed by passing a `--logs` argument to the command. +The deployer saves log files by default into the `config/logs/` direcotry, but this can be changed by passing a `--logs` argument to the command. ## Deployer Image Commands -Commands are similar for AWS and GCP. Any differences between AWS and GCP are -noted where they exist. +Commands are similar for AWS and GCP. Any differences between AWS and GCP are noted where they exist. - `deploy` - `list` @@ -77,22 +61,16 @@ noted where they exist. ### `deploy` -The [deploy](/reference/airnode/v0.12/packages/deployer.md#deploy) command will -create the Airnode with a cloud provider or update it if it already exists. -Three files are needed to run the deploy command. +The [deploy](/reference/airnode/v0.12/packages/deployer.md#deploy) command will create the Airnode with a cloud provider or update it if it already exists. Three files are needed to run the deploy command. - config.json - secrets.env - aws.env (AWS only) - gcp.json (GCP only) -See -[Deploying an Airnode](/reference/airnode/v0.12/understand/deploying.md#deploy-with-docker) -for deployment commands specific to various operating systems and cloud -providers. +See [Deploying an Airnode](/reference/airnode/v0.12/understand/deploying.md#deploy-with-docker) for deployment commands specific to various operating systems and cloud providers. -Note that a `receipt.json` file will be created upon completion. It contains -some deployment information and is used to remove the Airnode. +Note that a `receipt.json` file will be created upon completion. It contains some deployment information and is used to remove the Airnode. @@ -120,24 +98,14 @@ docker run -it --rm ^ #### Re-deployments -A unique deployment is defined by the value of -[nodeSetting.stage](/reference/airnode/v0.12/deployment-files/config-json.md#stage). -If you deploy again, using the same `nodeSetting.stage` value, then you are -re-deploying or updating the previous deployment. +A unique deployment is defined by the value of [nodeSetting.stage](/reference/airnode/v0.12/deployment-files/config-json.md#stage). If you deploy again, using the same `nodeSetting.stage` value, then you are re-deploying or updating the previous deployment. -By default the deployer will attempt to remove the Airnode should either a -deployment or re-deployment fail. But if either fails (and -[--auto-remove](/reference/airnode/v0.12/packages/deployer.md#deploy) is false) -then the Airnode will not be removed, however it could be left in an unstable -state. You can alter the `deploy` command to change this behavior using the -following. +By default the deployer will attempt to remove the Airnode should either a deployment or re-deployment fail. But if either fails (and [--auto-remove](/reference/airnode/v0.12/packages/deployer.md#deploy) is false) then the Airnode will not be removed, however it could be left in an unstable state. You can alter the `deploy` command to change this behavior using the following. - `--auto-remove true|false`: defaults to true - `--no-auto-remove` -Auto removal is usually recommended for development deployments. For production -deployments, consider changing the value of `nodeSetting.stage` to create a new -deployment and follow-up by removing the previous deployment. +Auto removal is usually recommended for development deployments. For production deployments, consider changing the value of `nodeSetting.stage` to create a new deployment and follow-up by removing the previous deployment. Use the following example to avoid the automatic removal of the Airnode. @@ -150,12 +118,7 @@ api3/airnode-deployer:0.12.0 deploy --auto-remove false ### `list` -Once one or more Airnodes were deployed using the -[deploy](/reference/airnode/v0.12/docker/deployer-image.md#deploy) command -above, the [list](/reference/airnode/v0.12/packages/deployer.md#list) command -can be used to list currently deployed Airnodes. Files for cloud provider -authentication are needed for the command to run correctly: `aws.env` (for AWS) -and/or `gcp.json` (for GCP). +Once one or more Airnodes were deployed using the [deploy](/reference/airnode/v0.12/docker/deployer-image.md#deploy) command above, the [list](/reference/airnode/v0.12/packages/deployer.md#list) command can be used to list currently deployed Airnodes. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -174,9 +137,7 @@ docker run -it --rm ^ ::: -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ::: code-group @@ -197,14 +158,7 @@ docker run -it --rm ^ ### `info` -Retrieve more information about a deployment with the -[info](/reference/airnode/v0.12/packages/deployer.md#info) command. Use the -deployment ID from the -[list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above to -request information about a specific deployment. The retrieved information -include deployment's Airnode address, stage, Airnode version and the update -history. Files for cloud provider authentication are needed for the command to -run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). +Retrieve more information about a deployment with the [info](/reference/airnode/v0.12/packages/deployer.md#info) command. Use the deployment ID from the [list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above to request information about a specific deployment. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -225,17 +179,7 @@ docker run -it --rm ^ ### `rollback` -To revert to a previous version of a deployment, use the -[rollback](/reference/airnode/v0.12/packages/deployer.md#rollback) command. -Provide the deployment ID from the -[list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above to -specify which deployment will be changed. Also provide the desired version ID -from the [info](/reference/airnode/v0.12/docker/deployer-image.md#info) command -above to revert to. The -[rollback](/reference/airnode/v0.12/packages/deployer.md#rollback) command will -then fetch the configuration files of the specified version and deploy the -version using its configuration. Check this with the -[info](/reference/airnode/v0.12/docker/deployer-image.md#info) command above. +To revert to a previous version of a deployment, use the [rollback](/reference/airnode/v0.12/packages/deployer.md#rollback) command. Provide the deployment ID from the [list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above to specify which deployment will be changed. Also provide the desired version ID from the [info](/reference/airnode/v0.12/docker/deployer-image.md#info) command above to revert to. The [rollback](/reference/airnode/v0.12/packages/deployer.md#rollback) command will then fetch the configuration files of the specified version and deploy the version using its configuration. Check this with the [info](/reference/airnode/v0.12/docker/deployer-image.md#info) command above. ::: code-group @@ -256,23 +200,7 @@ docker run -it --rm ^ ### `fetch-files` -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the -[fetch-files](/reference/airnode/v0.12/packages/deployer.md#fetch-files) command -to retrieve them. You need to provide the deployment ID from the -[list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above to -specify the desired deployment. By default, the files from the latest version of -this deployment are fetched. Alternatively, you can additionally provide a -deployment version ID from the -[info](/reference/airnode/v0.12/docker/deployer-image.md#info) command above to -specify the desired deployment version. By default, the archive with the files -is stored in the `config` directory **within the Docker container** that is, in -the example below, mapped to your current working directory. You can change the -output directory by providing an `--output-dir` option specifying a different -directory instead. Don't forget to add a mapping for the new output directory so -you'll be able to access the files. Files for cloud provider authentication are -needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for -GCP). +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the [fetch-files](/reference/airnode/v0.12/packages/deployer.md#fetch-files) command to retrieve them. You need to provide the deployment ID from the [list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above to specify the desired deployment. By default, the files from the latest version of this deployment are fetched. Alternatively, you can additionally provide a deployment version ID from the [info](/reference/airnode/v0.12/docker/deployer-image.md#info) command above to specify the desired deployment version. By default, the archive with the files is stored in the `config` directory **within the Docker container** that is, in the example below, mapped to your current working directory. You can change the output directory by providing an `--output-dir` option specifying a different directory instead. Don't forget to add a mapping for the new output directory so you'll be able to access the files. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -293,16 +221,7 @@ docker run -it --rm ^ ### `remove` -A deployed Airnode can be removed via the -[remove](/reference/airnode/v0.12/packages/deployer.md#remove) command. To -remove Airnode, use the deployment ID from the -[list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above. -Airnode's update history, that can be seen by the -[info](/reference/airnode/v0.12/docker/deployer-image.md#info) command, will be -removed as well. Files for cloud provider authentication are needed for the -command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is -the recommended way to remove a deployment, but an alternative is the -`remove-with-receipt` command. +A deployed Airnode can be removed via the [remove](/reference/airnode/v0.12/packages/deployer.md#remove) command. To remove Airnode, use the deployment ID from the [list](/reference/airnode/v0.12/docker/deployer-image.md#list) command above. Airnode's update history, that can be seen by the [info](/reference/airnode/v0.12/docker/deployer-image.md#info) command, will be removed as well. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is the recommended way to remove a deployment, but an alternative is the `remove-with-receipt` command. ::: code-group @@ -323,12 +242,7 @@ docker run -it --rm ^ ### `remove-with-receipt` -When an Airnode was deployed using the `deploy` command, a `receipt.json` file -was created. This file is used to remove the Airnode. The -[remove-with-receipt](/reference/airnode/v0.12/packages/deployer.md#remove-with-receipt) -command is identical for AWS and GCP. Files for cloud provider authentication -are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` -(for GCP). +When an Airnode was deployed using the `deploy` command, a `receipt.json` file was created. This file is used to remove the Airnode. The [remove-with-receipt](/reference/airnode/v0.12/packages/deployer.md#remove-with-receipt) command is identical for AWS and GCP. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -349,22 +263,11 @@ docker run -it --rm ^ ## Manual Removal -Optionally you can remove an Airnode manually though it is highly recommended -that you do so using the deployer image's `remove-with-receipt` or `remove` -commands. When removing manually, you will need the Airnode's deployment ID, -`deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., -`production`). They can be found in the -[receipt.json](/reference/airnode/v0.12/deployment-files/receipt-json.md) file -generated when deploying the Airnode. These are included in the element name of -AWS and GCP deployed features. Airnode has a presence in several areas of both -AWS and GCP as listed below. +Optionally you can remove an Airnode manually though it is highly recommended that you do so using the deployer image's `remove-with-receipt` or `remove` commands. When removing manually, you will need the Airnode's deployment ID, `deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., `production`). They can be found in the [receipt.json](/reference/airnode/v0.12/deployment-files/receipt-json.md) file generated when deploying the Airnode. These are included in the element name of AWS and GCP deployed features. Airnode has a presence in several areas of both AWS and GCP as listed below. ::: danger Remember -Only delete elements of a feature with the `deploymentId` and `stage` name -contained in the element's name. There can be more than one Airnode. Example: -(airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the -deploymentId and `production` is the stage name. +Only delete elements of a feature with the `deploymentId` and `stage` name contained in the element's name. There can be more than one Airnode. Example: (airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the deploymentId and `production` is the stage name. ::: @@ -376,7 +279,6 @@ deploymentId and `production` is the stage name. -Learn more about AWS or GCP resources that Airnode uses in the -[Cloud Resources](/reference/airnode/v0.12/cloud-resources.md) doc. +Learn more about AWS or GCP resources that Airnode uses in the [Cloud Resources](/reference/airnode/v0.12/cloud-resources.md) doc. diff --git a/docs/reference/airnode/v0.12/docker/index.md b/docs/reference/airnode/v0.12/docker/index.md index 82a0f18e..f879bbec 100644 --- a/docs/reference/airnode/v0.12/docker/index.md +++ b/docs/reference/airnode/v0.12/docker/index.md @@ -19,31 +19,19 @@ tags: # {{$frontmatter.title}} -Using Docker is the easiest way to both deploy an Airnode to a cloud provider -and to run an Airnode locally. There are two Docker images: the Airnode deployer -image and the Airnode client image. +Using Docker is the easiest way to both deploy an Airnode to a cloud provider and to run an Airnode locally. There are two Docker images: the Airnode deployer image and the Airnode client image. -There is also a docker image wrapping the admin CLI package, as an alternative -to using `npx`. +There is also a docker image wrapping the admin CLI package, as an alternative to using `npx`. -To use these images first install [Docker](https://docs.docker.com/get-docker/) -if it is not present on your system. +To use these images first install [Docker](https://docs.docker.com/get-docker/) if it is not present on your system. -If using a Linux distribution that enforces Selinux policies, allow the Docker -images access to the host directory by -[creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). +If using a Linux distribution that enforces Selinux policies, allow the Docker images access to the host directory by [creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). -- The [deployer image](/reference/airnode/v0.12/docker/deployer-image.md) - deploys the node in the form of serverless functions to a serverless cloud - provider (e.g. AWS Lambda). +- The [deployer image](/reference/airnode/v0.12/docker/deployer-image.md) deploys the node in the form of serverless functions to a serverless cloud provider (e.g. AWS Lambda). -- The [client image](/reference/airnode/v0.12/docker/client-image.md) is the - node itself, containerized. The container can be run locally or deployed to a - cloud hosting service (e.g. AWS EC2 or Lightsail). +- The [client image](/reference/airnode/v0.12/docker/client-image.md) is the node itself, containerized. The container can be run locally or deployed to a cloud hosting service (e.g. AWS EC2 or Lightsail). -- The [admin CLI image](/reference/airnode/v0.12/docker/admin-cli-image.md) - wraps the admin CLI package in a docker image to provide an alternative usage - option to the Admin CLI commands (npx). +- The [admin CLI image](/reference/airnode/v0.12/docker/admin-cli-image.md) wraps the admin CLI package in a docker image to provide an alternative usage option to the Admin CLI commands (npx). ## DockerHub diff --git a/docs/reference/airnode/v0.12/index.md b/docs/reference/airnode/v0.12/index.md index af03a6fa..98341a1f 100644 --- a/docs/reference/airnode/v0.12/index.md +++ b/docs/reference/airnode/v0.12/index.md @@ -19,17 +19,9 @@ tags: # {{$frontmatter.title}} -Use the contract addresses listed in the tables below to interact with Airnode -on EVM-compatible blockchains. Additional addresses will be added as contracts -are deployed, but feel free to -[submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a -new deployment. - -The contract addresses listed below are sourced from the Airnode monorepo -[airnode-protocol](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-protocol) -and can be found in its -[deployments](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-protocol/deployments) -directory. +Use the contract addresses listed in the tables below to interact with Airnode on EVM-compatible blockchains. Additional addresses will be added as contracts are deployed, but feel free to [submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a new deployment. + +The contract addresses listed below are sourced from the Airnode monorepo [airnode-protocol](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-protocol) and can be found in its [deployments](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-protocol/deployments) directory. ## AirnodeRrpV0 diff --git a/docs/reference/airnode/v0.12/migration.md b/docs/reference/airnode/v0.12/migration.md index 57d71048..94ba0933 100644 --- a/docs/reference/airnode/v0.12/migration.md +++ b/docs/reference/airnode/v0.12/migration.md @@ -19,18 +19,13 @@ tags: # {{$frontmatter.title}} -The following guide assumes a valid v0.11.2 `config.json` file. All changes -listed below will need to be implemented in order to migrate to Airnode v0.12.0. -This document is written in a way that will preserve existing behavior with -earlier Airnode versions. +The following guide assumes a valid v0.11.2 `config.json` file. All changes listed below will need to be implemented in order to migrate to Airnode v0.12.0. This document is written in a way that will preserve existing behavior with earlier Airnode versions. -The document also mentions changes to user facing services related to Airnode, -such as airnode-deployer, airnode-admin, etc., and new features. +The document also mentions changes to user facing services related to Airnode, such as airnode-deployer, airnode-admin, etc., and new features. ## Summary -1. `ois[n].oisFormat` updated to "2.1.0". This has not changed since v0.11.2, - but has changed since v0.11.0 and v0.11.1 for which it was "2.0.0". +1. `ois[n].oisFormat` updated to "2.1.0". This has not changed since v0.11.2, but has changed since v0.11.0 and v0.11.1 for which it was "2.0.0". 2. `nodeSettings.nodeVersion` updated to "0.12.0". @@ -38,8 +33,7 @@ such as airnode-deployer, airnode-admin, etc., and new features. 1. `ois[n].oisFormat` -Updated to "2.1.0". This has not changed since v0.11.2, but has changed since -v0.11.0 and v0.11.1 for which it was "2.0.0". +Updated to "2.1.0". This has not changed since v0.11.2, but has changed since v0.11.0 and v0.11.1 for which it was "2.0.0". ```diff { @@ -61,23 +55,13 @@ Updated to "0.12.0" ## New features and updates -- There is no longer a hardcoded limit to the maximum number of sponsor wallet - requests processed each cycle. +- There is no longer a hardcoded limit to the maximum number of sponsor wallet requests processed each cycle. -- Data from the HTTP Gateway is returned from successful API calls that fail - response processing in order to assist with debugging. For an example, see the - [HTTP Gateways](/reference/airnode/v0.12/understand/http-gateways.md#http-gateway) - page. +- Data from the HTTP Gateway is returned from successful API calls that fail response processing in order to assist with debugging. For an example, see the [HTTP Gateways](/reference/airnode/v0.12/understand/http-gateways.md#http-gateway) page. -- In all pre-processing and post-processing steps, parameters are now immutably - exposed via an `endpointParameters` object and reserved parameters are no - longer accessible. +- In all pre-processing and post-processing steps, parameters are now immutably exposed via an `endpointParameters` object and reserved parameters are no longer accessible. -- The `value` for a `fixedOperationParameters` object is now allowed to be any - type, including an object; for example, the following specifies an array - containing multiple primitives. This has not changed since v0.11.2, but has - changed since v0.11.0 and v0.11.1 for which it was only allowed to be a - string. +- The `value` for a `fixedOperationParameters` object is now allowed to be any type, including an object; for example, the following specifies an array containing multiple primitives. This has not changed since v0.11.2, but has changed since v0.11.0 and v0.11.1 for which it was only allowed to be a string. ```json { @@ -93,22 +77,11 @@ Updated to "0.12.0" } ``` -- A new gas strategy, `sanitizedProviderRecommendedGasPrice`, has been added. - See the - [gas price documentation](/reference/airnode/v0.12/concepts/gas-prices.md#sanitizedproviderrecommendedgasprice) - for more details. - -- Gas can now be automatically estimated for RRP fulfillments on supported - chains by excluding `chains[n].options.fulfillmentGasLimit` from - `config.json`. For more details see the - [corresponding documentation](/reference/airnode/v0.12/deployment-files/config-json.md#options-fulfillmentgaslimit). - -- `AirnodeRrpV0` and `RequesterAuthorizerWithErc721` contract addresses are now - optional if there is an API3 deployment for that contract on the specified - chain. A table of such deployments can be found on the - [Contract Addresses](/reference/airnode/v0.12/index.md) page. The following - illustrates how the addresses can be omitted. First, within the `chains[n]` - object: +- A new gas strategy, `sanitizedProviderRecommendedGasPrice`, has been added. See the [gas price documentation](/reference/airnode/v0.12/concepts/gas-prices.md#sanitizedproviderrecommendedgasprice) for more details. + +- Gas can now be automatically estimated for RRP fulfillments on supported chains by excluding `chains[n].options.fulfillmentGasLimit` from `config.json`. For more details see the [corresponding documentation](/reference/airnode/v0.12/deployment-files/config-json.md#options-fulfillmentgaslimit). + +- `AirnodeRrpV0` and `RequesterAuthorizerWithErc721` contract addresses are now optional if there is an API3 deployment for that contract on the specified chain. A table of such deployments can be found on the [Contract Addresses](/reference/airnode/v0.12/index.md) page. The following illustrates how the addresses can be omitted. First, within the `chains[n]` object: ```diff { diff --git a/docs/reference/airnode/v0.12/packages/adapter.md b/docs/reference/airnode/v0.12/packages/adapter.md index e39f6161..ede276d2 100644 --- a/docs/reference/airnode/v0.12/packages/adapter.md +++ b/docs/reference/airnode/v0.12/packages/adapter.md @@ -19,19 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-adapter](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-adapter) -package has multiple responsibilities. It is used for building requests from an -[Oracle Integration Specification (OIS)](/reference/ois/2.1/), executing them, -parsing the responses, but also converting and encoding them for on chain use. +The [airnode-adapter](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-adapter) package has multiple responsibilities. It is used for building requests from an [Oracle Integration Specification (OIS)](/reference/ois/2.1/), executing them, parsing the responses, but also converting and encoding them for on chain use. -It is an internal dependency of Airnode, but can also be used standalone as an -API. +It is an internal dependency of Airnode, but can also be used standalone as an API. ## Installation -You can install `@api3/airnode-adapter` by adding it to the `package.json` file -in your project. +You can install `@api3/airnode-adapter` by adding it to the `package.json` file in your project. ```sh npm install --save @api3/airnode-adapter @@ -39,35 +33,24 @@ npm install --save @api3/airnode-adapter yarn add @api3/airnode-adapter ``` -You shouldn't need to use the adapter package directly. However, you might want -to use its API to double check the conversion or encoding behavior for which you -can install this package and verify your assumptions. +You shouldn't need to use the adapter package directly. However, you might want to use its API to double check the conversion or encoding behavior for which you can install this package and verify your assumptions. ## Conversion -While the adapter package has many responsibilities, many of those can be -treated as implementation details. On the other hand, there are a few important -behaviors to be noted when converting the response values based on the target -type and making the response transaction on chain. +While the adapter package has many responsibilities, many of those can be treated as implementation details. On the other hand, there are a few important behaviors to be noted when converting the response values based on the target type and making the response transaction on chain. Altogether, the response cycle consists of multiple steps 1. A successful API call is made and Airnode receives a response value. -2. The value to be converted is extracted from the response using the - [\_path](/reference/ois/2.1/reserved-parameters.md#path) from the OIS object. -3. This extracted value is converted to the target type. Conversions are - performed internally by the `castValue(value, type)` function. -4. The converted value is encoded to the native solidity type based on the - [\_type](/reference/ois/2.1/reserved-parameters.md#type) from the OIS object. - Encoding is performed internally by the `encodeValue(value, type)` function. +2. The value to be converted is extracted from the response using the [\_path](/reference/ois/2.1/reserved-parameters.md#path) from the OIS object. +3. This extracted value is converted to the target type. Conversions are performed internally by the `castValue(value, type)` function. +4. The converted value is encoded to the native solidity type based on the [\_type](/reference/ois/2.1/reserved-parameters.md#type) from the OIS object. Encoding is performed internally by the `encodeValue(value, type)` function. -If any of the steps above fail, an error is thrown. This will fail the given API -request and the error reason can be found in the logs. +If any of the steps above fail, an error is thrown. This will fail the given API request and the error reason can be found in the logs. -The rest of this section covers the conversion logic for all of the supported -types. +The rest of this section covers the conversion logic for all of the supported types. ### `int256` or `uint256` @@ -86,8 +69,7 @@ const ERROR_VALUES = [ ]; ``` -There are a few special strings and boolean values that are convertible to -`int256` or `uint256`: +There are a few special strings and boolean values that are convertible to `int256` or `uint256`: ```ts const SPECIAL_INT_VALUES = [false, 'false', true, 'true']; @@ -97,11 +79,7 @@ console.log(values); // [0, 0, 1, 1]; ``` -Number strings and numbers will attempt to be converted to -[BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be -multiplied by the value of the -[\_times](/reference/ois/2.1/reserved-parameters.md#times) parameter if it is -present. +Number strings and numbers will attempt to be converted to [BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be multiplied by the value of the [\_times](/reference/ois/2.1/reserved-parameters.md#times) parameter if it is present. ```ts const VALID_INT_VALUES = ['123.456', 7777]; @@ -111,17 +89,11 @@ console.log(values); // [new BigNumber(123.456), new BigNumber(7777)]; ``` -Conversion for `int256` and `uint256` is the same - this means that `-123` can -be converted to `uint256`. However, an error will be thrown while encoding. +Conversion for `int256` and `uint256` is the same - this means that `-123` can be converted to `uint256`. However, an error will be thrown while encoding. :::warning Flooring -Beware that any floating point number will be **floored**. This is necessary, -because floating point numbers are not valid in solidity. To mitigate precision -loss, you can use the -[`_times`](/reference/ois/2.1/reserved-parameters.md#times) parameter that is -sufficiently large. For example, if the API response is a USD currency, you -might want to use `_times: "100"` to convert the value to cents. +Beware that any floating point number will be **floored**. This is necessary, because floating point numbers are not valid in solidity. To mitigate precision loss, you can use the [`_times`](/reference/ois/2.1/reserved-parameters.md#times) parameter that is sufficiently large. For example, if the API response is a USD currency, you might want to use `_times: "100"` to convert the value to cents. ::: @@ -144,17 +116,9 @@ All other values are converted to `true`. ### `bytes32` -There is no conversion for `bytes32` - the value is expected to be a valid hex -string representing the encoded 32 bytes value. This means that the encoding -**must** be implemented on the API side. If you want to delegate the encoding to -Airnode, see the documentation for -[`string32`](/reference/airnode/v0.12/packages/adapter.md#string32). +There is no conversion for `bytes32` - the value is expected to be a valid hex string representing the encoded 32 bytes value. This means that the encoding **must** be implemented on the API side. If you want to delegate the encoding to Airnode, see the documentation for [`string32`](/reference/airnode/v0.12/packages/adapter.md#string32). -For example, let's say the API wants to encode the following string -`simple string` with length 13. Its encoding is -0x73696d706c6520737472696e6700000000000000000000000000000000000000. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. +For example, let's say the API wants to encode the following string `simple string` with length 13. Its encoding is 0x73696d706c6520737472696e6700000000000000000000000000000000000000. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. You can use [ethers](https://docs.ethers.io/v5/) to encode these on the API side @@ -166,29 +130,16 @@ console.log(encoded); // 0x73696d706c6520737472696e67000000000000000000000000000 ### `address` -There is no conversion for `address` - the value is expected to be a string -representing a valid address. Valid examples are: +There is no conversion for `address` - the value is expected to be a string representing a valid address. Valid examples are: -- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) - of an address. -- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - - all lowercase address. +- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) of an address. +- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - all lowercase address. ### `bytes` -There is no conversion for `bytes` - the value is expected to be a valid hex -string representing the encoded value. This means that the encoding to bytes -**must** be implemented on the API side. If you want to send a string, see the -documentation for -[`string`](/reference/airnode/v0.12/packages/adapter.md#string). +There is no conversion for `bytes` - the value is expected to be a valid hex string representing the encoded value. This means that the encoding to bytes **must** be implemented on the API side. If you want to send a string, see the documentation for [`string`](/reference/airnode/v0.12/packages/adapter.md#string). -For example, let's say the API wants to encode the following string -`this is an example string that is a bit longer`. Its encoding is -0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these -on the API side. +For example, let's say the API wants to encode the following string `this is an example string that is a bit longer`. Its encoding is 0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these on the API side. ```js const value = 'this is an example string that is a bit longer'; @@ -198,9 +149,7 @@ console.log(encodedValue); // 0x7468697320697320616e206578616d706c6520737472696e ### `string` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. All other values will be converted to -`string` and before encoded on chain using the `string` type. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. All other values will be converted to `string` and before encoded on chain using the `string` type. ```js const values = [ @@ -220,20 +169,11 @@ const mappedValues = values.map((v) => { ### `string32` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. -However, there is one exception, if the stringified value contains more than 31 -characters it will be **trimmed down** to only the first 31 characters during -conversion. +However, there is one exception, if the stringified value contains more than 31 characters it will be **trimmed down** to only the first 31 characters during conversion. -For example, if the API response is the following string -`this is an example string that is a bit longer` with length 46. It will be -first trimmed to 31 characters, string `this is an example string that ` and -afterwards converted to -0x7468697320697320616e206578616d706c6520737472696e6720746861742000. -Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using -the following snippet +For example, if the API response is the following string `this is an example string that is a bit longer` with length 46. It will be first trimmed to 31 characters, string `this is an example string that ` and afterwards converted to 0x7468697320697320616e206578616d706c6520737472696e6720746861742000. Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using the following snippet ```js const encoded = @@ -244,17 +184,11 @@ console.log(decoded); // "this is an example string that " ### Arrays -Conversion of arrays depends on the primitive type. All values of the array (or -nested array) will be converted according to the rules of the primitive type. +Conversion of arrays depends on the primitive type. All values of the array (or nested array) will be converted according to the rules of the primitive type. For example: -- `int256[]` - has primitive type `int256`. All elements of this array follow - the [`int256`](/reference/airnode/v0.12/packages/adapter.md#int256-or-uint256) - rules. -- `string32[7][][5]` - is a multidimensional array, where some dimensions are - fixed and some not. This is irrelevant though, and all the elements are - converted based on - [`string32`](/reference/airnode/v0.12/packages/adapter.md#string32) rules. +- `int256[]` - has primitive type `int256`. All elements of this array follow the [`int256`](/reference/airnode/v0.12/packages/adapter.md#int256-or-uint256) rules. +- `string32[7][][5]` - is a multidimensional array, where some dimensions are fixed and some not. This is irrelevant though, and all the elements are converted based on [`string32`](/reference/airnode/v0.12/packages/adapter.md#string32) rules. diff --git a/docs/reference/airnode/v0.12/packages/admin-cli.md b/docs/reference/airnode/v0.12/packages/admin-cli.md index 59782a4a..476613f3 100644 --- a/docs/reference/airnode/v0.12/packages/admin-cli.md +++ b/docs/reference/airnode/v0.12/packages/admin-cli.md @@ -19,54 +19,26 @@ tags: # {{$frontmatter.title}} -Use the -[airnode-admin](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin) -Admin CLI tool to interact with Airnode across blockchains. There are commands -for both developers (dApp) and API providers. Developers can sponsor -[requester](/reference/airnode/v0.12/concepts/requester.md) contracts and derive -[sponsorWallets](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) for -Airnodes. API providers can build -[Airnodes](/reference/airnode/v0.12/concepts/airnode.md) that serve their API -data to requester contracts. +Use the [airnode-admin](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin) Admin CLI tool to interact with Airnode across blockchains. There are commands for both developers (dApp) and API providers. Developers can sponsor [requester](/reference/airnode/v0.12/concepts/requester.md) contracts and derive [sponsorWallets](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) for Airnodes. API providers can build [Airnodes](/reference/airnode/v0.12/concepts/airnode.md) that serve their API data to requester contracts. ::: warning Transaction Gas Costs -Some commands will incur transaction fees. These are per call transaction gas -costs and are relatively small. See the -[Developer Fees](/reference/airnode/v0.12/developers/fees.md) -doc. +Some commands will incur transaction fees. These are per call transaction gas costs and are relatively small. See the [Developer Fees](/reference/airnode/v0.12/developers/fees.md) doc. ::: -Almost all commands require you to provide a blockchain `providerUrl`. Following -are just two examples of many possibilities. See the -[Chain Providers](/reference/airnode/v0.12/concepts/chain-providers.md) doc for -more information. +Almost all commands require you to provide a blockchain `providerUrl`. Following are just two examples of many possibilities. See the [Chain Providers](/reference/airnode/v0.12/concepts/chain-providers.md) doc for more information. - `https://eth-goerli.gateway.pokt.network/v1/lb/` - `https://sepolia.infura.io/v3/` -The CLI connects to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -or the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract, which addresses are derived from the current chain. You can optionally -specify the contract addresses yourself by providing optional -`airnode-rrp-address` or `requester-authorizer-with-airnode` command argument -with the address of the deployed contract on your targeted chain. - -Commands that require `mnemonic` will make an on-chain transaction. The -application will derive the account from the mnemonic with default ethereum -derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional -parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet -that is associated with the mnemonic is funded on the target chain. The -application will not exit until the transaction is confirmed. +The CLI connects to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) or the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract, which addresses are derived from the current chain. You can optionally specify the contract addresses yourself by providing optional `airnode-rrp-address` or `requester-authorizer-with-airnode` command argument with the address of the deployed contract on your targeted chain. + +Commands that require `mnemonic` will make an on-chain transaction. The application will derive the account from the mnemonic with default ethereum derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet that is associated with the mnemonic is funded on the target chain. The application will not exit until the transaction is confirmed. ### Using transaction overrides -CLI commands also support the following transaction overrides as optional -arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and -`max-priority-fee` (EIP-1559 transactions) and `nonce`. +CLI commands also support the following transaction overrides as optional arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and `max-priority-fee` (EIP-1559 transactions) and `nonce`. ### Default transaction overrides @@ -115,9 +87,7 @@ docker run api3/airnode-admin:0.12.0 $COMMAND --help ## SDK -You can also use the package programmatically. The SDK exports respective -functions for all CLI commands as well as helper functions for obtaining the -contract instance on the targeted chain. +You can also use the package programmatically. The SDK exports respective functions for all CLI commands as well as helper functions for obtaining the contract instance on the targeted chain. ```js import { sponsorRequester, getAirnodeRrpWithSigner } from '@api3/airnode-admin'; @@ -133,9 +103,7 @@ const airnodeRrp = await getAirnodeRrpWithSigner( const requester = await sponsorRequester(airnodeRrp, requester); ``` -If you plan to use multiple commands it might be tedious to pass the contract -instance to every function call. For this reason there is also class based -`AdminSdk` which you initialize with `AirnodeRrp` contract only once. +If you plan to use multiple commands it might be tedious to pass the contract instance to every function call. For this reason there is also class based `AdminSdk` which you initialize with `AirnodeRrp` contract only once. ```js import { AdminSdk } from '@api3/airnode-admin'; @@ -157,14 +125,11 @@ const requester = await adminSdk.sponsorRequester(requester); adminSdk.airnodeRrp = airnodeRrp.connect(someOtherWallet); ``` -The SDK will also provide TS typings out of the box. Please, refer to the -implementation for more details. +The SDK will also provide TS typings out of the box. Please, refer to the implementation for more details. ### Using transaction overrides -You can also use transaction overrides to customize gas limits and fee settings. -The SDK simply passes the overrides parameter to the contract method so you can -use any overrides supported by the ethers library. +You can also use transaction overrides to customize gas limits and fee settings. The SDK simply passes the overrides parameter to the contract method so you can use any overrides supported by the ethers library. ```js import { ethers } from 'ethers'; @@ -188,14 +153,7 @@ const requester = await adminSdk.sponsorRequester(requester, overrides); ## Sponsors -Commands related to a [sponsor's](/reference/airnode/v0.12/concepts/sponsor.md) -relationships between -[requesters](/reference/airnode/v0.12/concepts/requester.md) and -[sponsorWallets](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) as -well as [templates](/reference/airnode/v0.12/concepts/template.md) used by a -sponsor's requesters. Some of these commands connect to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract where the signer is sponsor account. +Commands related to a [sponsor's](/reference/airnode/v0.12/concepts/sponsor.md) relationships between [requesters](/reference/airnode/v0.12/concepts/requester.md) and [sponsorWallets](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) as well as [templates](/reference/airnode/v0.12/concepts/template.md) used by a sponsor's requesters. Some of these commands connect to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract where the signer is sponsor account. - [sponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/v0.12/packages/admin-cli.md#unsponsor-requester) @@ -210,39 +168,19 @@ protocol contract where the signer is sponsor account. ### `sponsor-requester` -[Sponsors](/reference/airnode/v0.12/concepts/sponsor.md) a -[requester](/reference/airnode/v0.12/concepts/requester.md) contract so that its -requests can be fulfilled by the -[sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) of -an Airnode. The account derived from the `mnemonic` you provide must belong to -the sponsor. +[Sponsors](/reference/airnode/v0.12/concepts/sponsor.md) a [requester](/reference/airnode/v0.12/concepts/requester.md) contract so that its requests can be fulfilled by the [sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) of an Airnode. The account derived from the `mnemonic` you provide must belong to the sponsor. -Sponsoring a requester and using the returned `sponsorAddress` to derive a -`sponsorWallet` for an Airnode creates a -[relationship](/reference/airnode/v0.12/concepts/sponsor.md) between the -requester and the Airnode, see the -[`derive-sponsor-wallet-address`](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Sponsoring a requester and using the returned `sponsorAddress` to derive a `sponsorWallet` for an Airnode creates a [relationship](/reference/airnode/v0.12/concepts/sponsor.md) between the requester and the Airnode, see the [`derive-sponsor-wallet-address`](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a - `sponsorAddress` as the default account of the mnemonic unless a - `derivation-path` is specified. It's also used to pay gas costs from the - mnemonic's default account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a `sponsorAddress` as the default account of the mnemonic unless a `derivation-path` is specified. It's also used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to sponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. If this parameter is not provided, it will be deduced from - the current chain. If there is no RRP address found for the given chain an - error is thrown. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. If this parameter is not provided, it will be deduced from the current chain. If there is no RRP address found for the given chain an error is thrown. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -265,29 +203,17 @@ npx @api3/airnode-admin sponsor-requester ^ ### `unsponsor-requester` -Removes the sponsorship of a -[requester](/reference/airnode/v0.12/concepts/requester.md) contract so that its -requests can no longer be fulfilled by the -[sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). The -account derived from the `mnemonic` you provide here has to belong to the -sponsor. +Removes the sponsorship of a [requester](/reference/airnode/v0.12/concepts/requester.md) contract so that its requests can no longer be fulfilled by the [sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). The account derived from the `mnemonic` you provide here has to belong to the sponsor. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used - to sponsor the requester. Used to pay gas costs from the mnemonic's default - account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used to sponsor the requester. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to unsponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -310,17 +236,12 @@ npx @api3/airnode-admin unsponsor-requester ^ ### `get-sponsor-status` -Returns the sponsor status for a given -[sponsor](/reference/airnode/v0.12/concepts/sponsor.md) and -[requester](/reference/airnode/v0.12/concepts/requester.md) (`true` if -sponsored, `false` otherwise). +Returns the sponsor status for a given [sponsor](/reference/airnode/v0.12/concepts/sponsor.md) and [requester](/reference/airnode/v0.12/concepts/requester.md) (`true` if sponsored, `false` otherwise). - `provider-url`: A valid blockchain provider URL. -- `sponsor-address`: The `sponsorAddress` returned when the requester was - sponsored. +- `sponsor-address`: The `sponsorAddress` returned when the requester was sponsored. - `requester-address`: The requester contract address. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -342,16 +263,9 @@ npx @api3/airnode-admin get-sponsor-status ^ ### `derive-sponsor-wallet-address` -Derives the address of the wallet designated by an Airnode for a -[sponsor](/reference/airnode/v0.12/concepts/sponsor.md), which is called the -[sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). -This command will error if `airnode-xpub` does not belong to the HDNode with the -path `m/44'/60'/0'` of the Airnode wallet. See the -[`derive-airnode-xpub`](/reference/airnode/v0.12/packages/admin-cli.md#derive-airnode-xpub) -command. +Derives the address of the wallet designated by an Airnode for a [sponsor](/reference/airnode/v0.12/concepts/sponsor.md), which is called the [sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). This command will error if `airnode-xpub` does not belong to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. See the [`derive-airnode-xpub`](/reference/airnode/v0.12/packages/admin-cli.md#derive-airnode-xpub) command. -- `airnode-xpub`: The extended public address of the Airnode for path - `m/44'/60'/0'`. +- `airnode-xpub`: The extended public address of the Airnode for path `m/44'/60'/0'`. - `airnode-address`: The public address of the Airnode. - `sponsor-address`: The address of the sponsor account. @@ -375,27 +289,17 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ### `create-template` -Reads a file, uses its contents to create a -[template](/reference/airnode/v0.12/concepts/template.md) and returns a -`template-id`. Also see -[Using Templates](/reference/airnode/v0.12/developers/using-templates.md) for an -example template file. +Reads a file, uses its contents to create a [template](/reference/airnode/v0.12/concepts/template.md) and returns a `template-id`. Also see [Using Templates](/reference/airnode/v0.12/developers/using-templates.md) for an example template file. - `provider-url`: A valid blockchain provider URL. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `template-file-path`: Path to the template file to create on-chain. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -418,20 +322,11 @@ npx @api3/airnode-admin create-template ^ ### `create-inline-template` -It is possible to inline Airnode templates inside config.json in a `templates` -section. These templates need to be published on chain, but inlining them inside -config provides more clarity which templates can be used for template requests -and also saves a blockchain call . +It is possible to inline Airnode templates inside config.json in a `templates` section. These templates need to be published on chain, but inlining them inside config provides more clarity which templates can be used for template requests and also saves a blockchain call . -The command reads a template file, uses its contents to create a -[template](/reference/airnode/v0.12/concepts/template.md) and returns the data -necessary to inline the template inside config. See -[Using Templates](/reference/airnode/v0.12/developers/using-templates.md) for an -example template file. +The command reads a template file, uses its contents to create a [template](/reference/airnode/v0.12/concepts/template.md) and returns the data necessary to inline the template inside config. See [Using Templates](/reference/airnode/v0.12/developers/using-templates.md) for an example template file. -This command does **not** create a template on chain. Be sure to use the -[create-template](/reference/airnode/v0.12/packages/admin-cli.md#create-template) -command on chain before making template requests. +This command does **not** create a template on chain. Be sure to use the [create-template](/reference/airnode/v0.12/packages/admin-cli.md#create-template) command on chain before making template requests. - `template-file-path`: Path to the template file to create on-chain. @@ -451,13 +346,11 @@ npx @api3/airnode-admin create-inline-template ^ ### `get-template` -Returns the [template](/reference/airnode/v0.12/concepts/template.md) for the -given `template-id`. +Returns the [template](/reference/airnode/v0.12/concepts/template.md) for the given `template-id`. - `provider-url`: A valid blockchain provider URL. - `template-id`: The id of a template to return. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -477,50 +370,28 @@ npx @api3/airnode-admin get-template ^ ### `request-withdrawal` -Requests a -[withdrawal](/reference/airnode/v0.12/concepts/sponsor.md#withdrawals) from a -[sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) -managed by an Airnode. +Requests a [withdrawal](/reference/airnode/v0.12/concepts/sponsor.md#withdrawals) from a [sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) managed by an Airnode. -The funds will be returned to the account derived from the `sponsor-mnemonic`. -This account must belong to a -[sponsor](/reference/airnode/v0.12/concepts/sponsor.md) for the specified -[sponsor wallet address](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) -in the command. +The funds will be returned to the account derived from the `sponsor-mnemonic`. This account must belong to a [sponsor](/reference/airnode/v0.12/concepts/sponsor.md) for the specified [sponsor wallet address](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) in the command. -After the request is made, it needs to be fulfilled by Airnode, so the return -value of this command is only a `withdrawal-request-id` which you can use to -call -[check-withdrawal-request](/reference/airnode/v0.12/packages/admin-cli.md#check-withdrawal-request) -to see whether the request was processed or not. +After the request is made, it needs to be fulfilled by Airnode, so the return value of this command is only a `withdrawal-request-id` which you can use to call [check-withdrawal-request](/reference/airnode/v0.12/packages/admin-cli.md#check-withdrawal-request) to see whether the request was processed or not. ::: warning Withdrawal Priority -Airnode will drop any pending API calls associated with a `sponsorWallet` once a -withdrawal is requested. +Airnode will drop any pending API calls associated with a `sponsorWallet` once a withdrawal is requested. ::: - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from - the mnemonic's default account unless a `derivation-path` is specified. - Withdrawn funds will be added to this mnemonic's default address unless a - `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. Withdrawn funds will be added to this mnemonic's default address unless a `derivation-path` is specified. - `airnode-address`: The public address of the Airnode. -- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw - from. This address was returned by the `derive-sponsor-wallet-address` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)` : The destination address of the `mnemonic` - parameter to add the withdrawn funds to if the default address is not desired. +- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw from. This address was returned by the `derive-sponsor-wallet-address` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)` : The destination address of the `mnemonic` parameter to add the withdrawn funds to if the default address is not desired. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -545,17 +416,11 @@ npx @api3/airnode-admin request-withdrawal ^ ### `check-withdrawal-request` -Checks the status of the -[withdrawal](/reference/airnode/v0.12/concepts/sponsor.md#withdrawals) request -with the given `withdrawal-request-id` from the -[request withdrawal command](/reference/airnode/v0.12/packages/admin-cli.md#request-withdrawal) -above. +Checks the status of the [withdrawal](/reference/airnode/v0.12/concepts/sponsor.md#withdrawals) request with the given `withdrawal-request-id` from the [request withdrawal command](/reference/airnode/v0.12/packages/admin-cli.md#request-withdrawal) above. - `provider-url`: A valid blockchain provider URL. -- `withdrawal-request-id`: This id was returned by the `request-withdrawal` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `withdrawal-request-id`: This id was returned by the `request-withdrawal` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -575,16 +440,7 @@ npx @api3/airnode-admin check-withdrawal-request ^ ### `verify-airnode-xpub` -Verifies that the `airnode-xpub` belongs to the HDNode with the path -`m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode -address can be derived with provided Airnode -[xpub](/reference/airnode/v0.12/concepts/airnode.md#xpub) with default -derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. -This command will most likely be used by a -[sponsor](/reference/airnode/v0.12/concepts/sponsor.md) to verify that the xpub -belongs to the Airnode before calling the -[derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Verifies that the `airnode-xpub` belongs to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode address can be derived with provided Airnode [xpub](/reference/airnode/v0.12/concepts/airnode.md#xpub) with default derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. This command will most likely be used by a [sponsor](/reference/airnode/v0.12/concepts/sponsor.md) to verify that the xpub belongs to the Airnode before calling the [derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) command. ::: code-group @@ -604,9 +460,7 @@ npx @api3/airnode-admin verify-airnode-xpub ^ ## Airnodes -Helper commands for a previously deployed Airnode. Some of these commands -connect to the AirnodeRrpV0.sol protocol contract where the signer must be the -Airnode wallet. +Helper commands for a previously deployed Airnode. Some of these commands connect to the AirnodeRrpV0.sol protocol contract where the signer must be the Airnode wallet. - [derive-airnode-xpub](/reference/airnode/v0.12/packages/admin-cli.md#derive-airnode-xpub) - [derive-endpoint-id](/reference/airnode/v0.12/packages/admin-cli.md#derive-endpoint-id) @@ -615,13 +469,7 @@ Airnode wallet. ### `derive-airnode-xpub` -Derives the Airnode extended public key -([xpub](/reference/airnode/v0.12/concepts/airnode.md#xpub)). This xpub must be -announced via off-chain channels because it will be needed to derive a -[sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) -address. See the -[derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Derives the Airnode extended public key ([xpub](/reference/airnode/v0.12/concepts/airnode.md#xpub)). This xpub must be announced via off-chain channels because it will be needed to derive a [sponsorWallet](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet) address. See the [derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `airnode-mnemonic`: The Airnode mnemonic for which the xpub is to be derived. @@ -639,15 +487,10 @@ npx @api3/airnode-admin derive-airnode-xpub --airnode-mnemonic "nature about sal ### `derive-endpoint-id` -Derives an -[endpointId](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) -from the OIS title and the endpoint's name as described in the -[endpoint](/reference/airnode/v0.12/concepts/endpoint.md) documentation. Add the -`endpointId` to the config.json file (`triggers.rrp[n].endpointId`). +Derives an [endpointId](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) from the OIS title and the endpoint's name as described in the [endpoint](/reference/airnode/v0.12/concepts/endpoint.md) documentation. Add the `endpointId` to the config.json file (`triggers.rrp[n].endpointId`). - `ois-title`: The title of the OIS from config.json (`ois.title`). -- `endpoint-name`: The name of the endpoint from config.json - (`triggers.rrp[n].endpointName`). +- `endpoint-name`: The name of the endpoint from config.json (`triggers.rrp[n].endpointName`). ::: code-group @@ -667,12 +510,7 @@ npx @api3/airnode-admin derive-endpoint-id ^ ### `generate-airnode-mnemonic` -Generates a unique mnemonic which can be used to create an -[airnode wallet](/reference/airnode/v0.12/concepts/airnode.md#mnemonic). In -addition to the mnemonic, this command will also display the corresponding -[airnode address](/reference/airnode/v0.12/concepts/airnode.md#airnodeaddress) -and its extended public key -([xpub](/reference/airnode/v0.12/concepts/airnode.md#xpub)). +Generates a unique mnemonic which can be used to create an [airnode wallet](/reference/airnode/v0.12/concepts/airnode.md#mnemonic). In addition to the mnemonic, this command will also display the corresponding [airnode address](/reference/airnode/v0.12/concepts/airnode.md#airnodeaddress) and its extended public key ([xpub](/reference/airnode/v0.12/concepts/airnode.md#xpub)). ```sh npx @api3/airnode-admin generate-airnode-mnemonic @@ -680,9 +518,7 @@ npx @api3/airnode-admin generate-airnode-mnemonic ### `generate-mnemonic` -Generates a unique mnemonic which can be used to create a wallet. In addition to -the mnemonic, this command will also display the corresponding default wallet -(path:m/44'/60'/0'/0/0) address. +Generates a unique mnemonic which can be used to create a wallet. In addition to the mnemonic, this command will also display the corresponding default wallet (path:m/44'/60'/0'/0/0) address. ```sh npx @api3/airnode-admin generate-mnemonic @@ -690,12 +526,7 @@ npx @api3/airnode-admin generate-mnemonic ### `derive-airnode-address` -Derives the -[airnode address](/reference/airnode/v0.12/concepts/airnode.md#airnodeaddress) -which is the identifier of the particular Airnode on chain. The address is the -default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this -identifier for many other admin CLI commands, such as -[derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address). +Derives the [airnode address](/reference/airnode/v0.12/concepts/airnode.md#airnodeaddress) which is the identifier of the particular Airnode on chain. The address is the default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this identifier for many other admin CLI commands, such as [derive-sponsor-wallet-address](/reference/airnode/v0.12/packages/admin-cli.md#derive-sponsor-wallet-address). - `airnode-mnemonic`: A mnemonic used to generate the airnode address. @@ -715,18 +546,11 @@ npx @api3/airnode-admin derive-airnode-address ^ ## RequesterAuthorizerWithAirnode -RequesterAuthorizerWithAirnode contract was written by API3 as an -[authorizer](/reference/airnode/v0.12/concepts/authorizers.md) contract that can -be used by any Airnode. Airnode owners can use this contract in addition to -authorizer contracts they have written themselves. +RequesterAuthorizerWithAirnode contract was written by API3 as an [authorizer](/reference/airnode/v0.12/concepts/authorizers.md) contract that can be used by any Airnode. Airnode owners can use this contract in addition to authorizer contracts they have written themselves. -This authorizer contract can whitelist -[requesters](/reference/airnode/v0.12/concepts/requester.md) where each Airnode -is administered by themselves. +This authorizer contract can whitelist [requesters](/reference/airnode/v0.12/concepts/requester.md) where each Airnode is administered by themselves. -These commands connect to the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract. +These commands connect to the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract. - [set-whitelist-expiration](/reference/airnode/v0.12/packages/admin-cli.md#set-whitelist-expiration) - [extend-whitelist-expiration](/reference/airnode/v0.12/packages/admin-cli.md#extend-whitelist-expiration) @@ -736,32 +560,20 @@ contract. ### `set-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration setter to set the -whitelisting expiration of a requester for the Airnode–endpoint pair. This can -hasten expiration in the case the new expiration timestamp is prior to a -previously set timestamp. +Called by the Airnode wallet or a whitelist expiration setter to set the whitelisting expiration of a requester for the Airnode–endpoint pair. This can hasten expiration in the case the new expiration timestamp is prior to a previously set timestamp. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. The mnemonic must be at least an Admin or - Airnode wallet. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -790,31 +602,20 @@ npx @api3/airnode-admin set-whitelist-expiration ^ ### `extend-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration extender to extend the -whitelist expiration of a requester for the Airnode–endpoint pair. This command -expects that the new expiration timestamp is later then the previously set -timestamp. +Called by the Airnode wallet or a whitelist expiration extender to extend the whitelist expiration of a requester for the Airnode–endpoint pair. This command expects that the new expiration timestamp is later then the previously set timestamp. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -843,34 +644,21 @@ npx @api3/airnode-admin extend-whitelist-expiration ^ ### `set-indefinite-whitelist-status` -Called by the Airnode wallet or an indefinite whitelister to whitelist a -requester indefinitely for the Airnode–endpoint pair. This command can be used -to make whitelisting permanent in cases where it is needed to allow requests -even beyond the expiration period. +Called by the Airnode wallet or an indefinite whitelister to whitelist a requester indefinitely for the Airnode–endpoint pair. This command can be used to make whitelisting permanent in cases where it is needed to allow requests even beyond the expiration period. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. The default address of - the mnemonic will be used unless a derivation-path is provided. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. The default address of the mnemonic will be used unless a derivation-path is provided. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. -- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be - whitelisted indefinitely or not. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. +- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be whitelisted indefinitely or not. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -899,17 +687,13 @@ npx @api3/airnode-admin set-indefinite-whitelist-status ^ ### `get-whitelist-status` -Called to get the detailed whitelist status of a requester for the -Airnode–endpoint pair. +Called to get the detailed whitelist status of a requester for the Airnode–endpoint pair. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. ::: code-group @@ -937,9 +721,7 @@ Called to check if a requester is whitelisted to use the Airnode–endpoint pair - `provider-url`: A valid blockchain provider URL. - `requester-authorizer-with-airnode`: The authorizer contract address. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.12/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. @@ -967,8 +749,6 @@ npx @api3/airnode-admin is-requester-whitelisted ^ ## More Examples -You can find more examples in the -[test directory](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin/test) -of the `@api3-dao/airnode/package/admin` repo. +You can find more examples in the [test directory](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin/test) of the `@api3-dao/airnode/package/admin` repo. diff --git a/docs/reference/airnode/v0.12/packages/airnode-abi.md b/docs/reference/airnode/v0.12/packages/airnode-abi.md index 1e5c321b..932fdbf9 100644 --- a/docs/reference/airnode/v0.12/packages/airnode-abi.md +++ b/docs/reference/airnode/v0.12/packages/airnode-abi.md @@ -19,29 +19,15 @@ tags: # {{$frontmatter.title}} -The -[airnode-abi](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-abi) -package is a unique way to encode and decode parameters for use with Airnode. -Parameters are provided with encoding types, names and values. The types are -shortened and grouped with a version as the "header". The name/value pairs are -then grouped and encoded as the rest of the body. - -An advantage of encoding parameters this way is that parameters can be decoded -natively using the language(s) of the specific blockchain. In the case of EVM -blockchains, this means that parameters can be encoded as well as decoded in -Solidity (or Vyper), without any additional requirements. - -You can find additional documentation in -[Airnode ABI Specifications](/reference/airnode/v0.12/specifications/airnode-abi.md) -doc. +The [airnode-abi](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-abi) package is a unique way to encode and decode parameters for use with Airnode. Parameters are provided with encoding types, names and values. The types are shortened and grouped with a version as the "header". The name/value pairs are then grouped and encoded as the rest of the body. + +An advantage of encoding parameters this way is that parameters can be decoded natively using the language(s) of the specific blockchain. In the case of EVM blockchains, this means that parameters can be encoded as well as decoded in Solidity (or Vyper), without any additional requirements. + +You can find additional documentation in [Airnode ABI Specifications](/reference/airnode/v0.12/specifications/airnode-abi.md) doc. ## Installation -You can install -[@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) -with either -[npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) -or [Yarn](https://yarnpkg.com/en/docs/install) +You can install [@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) with either [npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) or [Yarn](https://yarnpkg.com/en/docs/install) ```sh # npm @@ -57,16 +43,13 @@ yarn add @api3/airnode-abi Accepts an array of objects with the following required keys: -1. `type` - The full list of accepted types can be found in the - [Airnode ABI](/reference/airnode/v0.12/specifications/airnode-abi.md#type-encodings) - specifications doc. +1. `type` - The full list of accepted types can be found in the [Airnode ABI](/reference/airnode/v0.12/specifications/airnode-abi.md#type-encodings) specifications doc. 2. `name` 3. `value` -It is important to note that numeric values (`int256` and `uint256`) should be -submitted as **strings** in order to preserve precision. +It is important to note that numeric values (`int256` and `uint256`) should be submitted as **strings** in order to preserve precision. ```ts import { encode } from '@api3/airnode-abi'; @@ -83,11 +66,9 @@ console.log(encodedData); ## `decode` -Returns an object where the keys are the "names" and the values are the "values" -from the initial encoding. +Returns an object where the keys are the "names" and the values are the "values" from the initial encoding. -It is important to note that `int256` and `uint256` will be decoded back to -strings. +It is important to note that `int256` and `uint256` will be decoded back to strings. ```ts import { decode } from '@api3/airnode-abi'; diff --git a/docs/reference/airnode/v0.12/packages/deployer.md b/docs/reference/airnode/v0.12/packages/deployer.md index 42b8c113..0d724aa1 100644 --- a/docs/reference/airnode/v0.12/packages/deployer.md +++ b/docs/reference/airnode/v0.12/packages/deployer.md @@ -19,22 +19,11 @@ tags: # {{$frontmatter.title}} -The -[airnode-deployer](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer) -package is used primarily by the -[Docker Images](/reference/airnode/v0.12/docker/). This CLI tool provides the -underlying commands used by the Docker images when deploying an Airnode. API -providers are strongly encouraged to use the -[Docker Images](/reference/airnode/v0.12/docker/) when deploying an Airnode and -not the deployer CLI commands. +The [airnode-deployer](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer) package is used primarily by the [Docker Images](/reference/airnode/v0.12/docker/). This CLI tool provides the underlying commands used by the Docker images when deploying an Airnode. API providers are strongly encouraged to use the [Docker Images](/reference/airnode/v0.12/docker/) when deploying an Airnode and not the deployer CLI commands. ## Usage -The deployer's commands can be run using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), -installing a global npm package or by manually building the airnode-deployer -package. Using npx is the simplest method to interact with the deployer manually -if you do not wish to use the Docker images. +The deployer's commands can be run using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), installing a global npm package or by manually building the airnode-deployer package. Using npx is the simplest method to interact with the deployer manually if you do not wish to use the Docker images. - [Using npx](/reference/airnode/v0.12/packages/deployer.md#using-npx) - [Global Package](/reference/airnode/v0.12/packages/deployer.md#global-package) @@ -42,9 +31,7 @@ if you do not wish to use the Docker images. ### Using npx -The airnode-deployer package can be run as an npm package using npx. This allows -you to run deployer commands without installing the deployer npm package or -having to manually build the airnode-deployer package yourself. +The airnode-deployer package can be run as an npm package using npx. This allows you to run deployer commands without installing the deployer npm package or having to manually build the airnode-deployer package yourself. ```sh npx @api3/airnode-deployer deploy \ @@ -56,8 +43,7 @@ npx @api3/airnode-deployer deploy \ ### Global Package -The airnode-deployer package can be installed globally with yarn or npm. If -installed using yarn make sure yarn bin is added to `PATH`. +The airnode-deployer package can be installed globally with yarn or npm. If installed using yarn make sure yarn bin is added to `PATH`. ```sh yarn global add @api3/airnode-deployer @@ -120,27 +106,18 @@ cp config/secrets.env.example config/secrets.env ## Credentials -When using the `airnode-deployer` Docker image, AWS or GCP credentials are -loaded automatically. Conversely, when using the deployer CLI directly, you will -need to first load AWS or GCP credentials into the environment manually as -described below. +When using the `airnode-deployer` Docker image, AWS or GCP credentials are loaded automatically. Conversely, when using the deployer CLI directly, you will need to first load AWS or GCP credentials into the environment manually as described below. ### AWS Credentials For AWS, there are two options: -1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` - (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their - appropriate values. -2. Populate the AWS `credentials` file. See the AWS documentation for the - [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) - as well as its - [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). +1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their appropriate values. +2. Populate the AWS `credentials` file. See the AWS documentation for the [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) as well as its [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). ### GCP Credentials -Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of -the `gcp.json` credentials file. +Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the `gcp.json` credentials file. ## Commands @@ -153,33 +130,20 @@ the `gcp.json` credentials file. ### Airnode Deployment -When creating or updating an Airnode the `config.json` and `secrets.env` files -are needed. You can use the provided example -[config.json](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-deployer/config/config.example.json) -and -[secrets.env](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-deployer/config/secrets.example.env) -templates to get started quickly, but you will need to edit these with your own -API details and secrets. +When creating or updating an Airnode the `config.json` and `secrets.env` files are needed. You can use the provided example [config.json](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-deployer/config/config.example.json) and [secrets.env](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-deployer/config/secrets.example.env) templates to get started quickly, but you will need to edit these with your own API details and secrets. -Make sure `config.json` and `secrets.env` are available in the path for the -`--configuration` argument. +Make sure `config.json` and `secrets.env` are available in the path for the `--configuration` argument. #### deploy -When executed, the `deploy` command defaults to creating a `receipt.json` file -in the `config/` directory, although a different path can be specified using the -path and name with the `--receipt` argument. The receipt contains metadata about -the deployment and can be used to remove the Airnode. +When executed, the `deploy` command defaults to creating a `receipt.json` file in the `config/` directory, although a different path can be specified using the path and name with the `--receipt` argument. The receipt contains metadata about the deployment and can be used to remove the Airnode. -By default the deployer will save logs into the `config/logs/` directory. This -can be changed with the `--logs` argument. +By default the deployer will save logs into the `config/logs/` directory. This can be changed with the `--logs` argument. -If the deployment isn't successful, the command will try to automatically remove -deployed resources. You can disable this by running the deploy command with a -`--no-auto-remove` argument. +If the deployment isn't successful, the command will try to automatically remove deployed resources. You can disable this by running the deploy command with a `--no-auto-remove` argument. ```bash # Deploys an Airnode instance using the config.json and @@ -207,19 +171,15 @@ airnode-deployer deploy \ --logs config/logs/ ``` -See how [deploy](/reference/airnode/v0.12/docker/deployer-image.md#deploy) is -used via the AWS/GCP deployer image. +See how [deploy](/reference/airnode/v0.12/docker/deployer-image.md#deploy) is used via the AWS/GCP deployer image. ### Listing Airnodes -Once you've already deployed one or more Airnode, you can list your currently -deployed instances using the `list` command. +Once you've already deployed one or more Airnode, you can list your currently deployed instances using the `list` command. #### list -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ```bash # Lists deployed Airnode instances @@ -239,14 +199,11 @@ airnode-deployer list airnode-deployer list --cloud-providers gcp ``` -See how [list](/reference/airnode/v0.12/docker/deployer-image.md#list) is used -via the AWS/GCP deployer image. +See how [list](/reference/airnode/v0.12/docker/deployer-image.md#list) is used via the AWS/GCP deployer image. ### Fetching deployment information -You can use the `info` command to retrieve information about existing -deployments. The retrieved information include deployment's Airnode address, -stage, Airnode version and the update history. +You can use the `info` command to retrieve information about existing deployments. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. #### info @@ -266,8 +223,7 @@ Options: airnode-deployer info aws2c6ef2b3 ``` -See how [info](/reference/airnode/v0.12/docker/deployer-image.md#info) is used -via the AWS/GCP deployer image. +See how [info](/reference/airnode/v0.12/docker/deployer-image.md#info) is used via the AWS/GCP deployer image. ### Reverting to a previous version @@ -294,14 +250,11 @@ Options: airnode-deployer rollback aws808e2a22 5bbcd317 ``` -See how [rollback](/reference/airnode/v0.12/docker/deployer-image.md#rollback) -is used via the AWS/GCP deployer image. +See how [rollback](/reference/airnode/v0.12/docker/deployer-image.md#rollback) is used via the AWS/GCP deployer image. ### Fetching deployment files -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the `fetch-files` command to -retrieve them. +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the `fetch-files` command to retrieve them. #### fetch-files @@ -320,19 +273,14 @@ Options: airnode-deployer fetch-files aws2c6ef2b3 ``` -See how -[fetch-files](/reference/airnode/v0.12/docker/deployer-image.md#fetch-files) is -used via the AWS/GCP deployer image. +See how [fetch-files](/reference/airnode/v0.12/docker/deployer-image.md#fetch-files) is used via the AWS/GCP deployer image. ### Airnode Removal An Airnode can be removed in two different ways: -- **Best:** With `remove`, which uses the deployment ID found either in the - [deployment receipt file](/reference/airnode/v0.12/deployment-files/receipt-json.md) - or via the `list` command. -- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt - created when the Airnode was deployed. +- **Best:** With `remove`, which uses the deployment ID found either in the [deployment receipt file](/reference/airnode/v0.12/deployment-files/receipt-json.md) or via the `list` command. +- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt created when the Airnode was deployed. #### remove @@ -352,8 +300,7 @@ Options: airnode-deployer remove aws2c6ef2b3 ``` -See how [remove](/reference/airnode/v0.12/docker/deployer-image.md#remove) is -used via the AWS/GCP deployer image. +See how [remove](/reference/airnode/v0.12/docker/deployer-image.md#remove) is used via the AWS/GCP deployer image. #### remove-with-receipt @@ -376,8 +323,6 @@ airnode-deployer remove-with-receipt \ --logs config/logs/ ``` -See how -[remove-with-receipt](/reference/airnode/v0.12/docker/deployer-image.md#remove-with-receipt) -is used via the AWS/GCP deployer image. +See how [remove-with-receipt](/reference/airnode/v0.12/docker/deployer-image.md#remove-with-receipt) is used via the AWS/GCP deployer image. diff --git a/docs/reference/airnode/v0.12/packages/index.md b/docs/reference/airnode/v0.12/packages/index.md index 5e313282..d93e6b5e 100644 --- a/docs/reference/airnode/v0.12/packages/index.md +++ b/docs/reference/airnode/v0.12/packages/index.md @@ -19,13 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode is a fully-serverless oracle node that is designed specifically for API -providers to operate their own oracles. Its code base is a monorepo managed -using [Lerna](https://github.com/lerna/lerna). The -[Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.12/packages) has -several packages. Some of these packages are used by dApp developers and API -providers to interact with or to build Airnode. A few are simply used for -internal Airnode development. +Airnode is a fully-serverless oracle node that is designed specifically for API providers to operate their own oracles. Its code base is a monorepo managed using [Lerna](https://github.com/lerna/lerna). The [Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.12/packages) has several packages. Some of these packages are used by dApp developers and API providers to interact with or to build Airnode. A few are simply used for internal Airnode development. - [airnode-adapter](/reference/airnode/v0.12/packages/adapter.md) - [airnode-admin](/reference/airnode/v0.12/packages/admin-cli.md) @@ -36,49 +30,30 @@ internal Airnode development. **Read about each package in the monorepo.** -Airnode packages are cross platform, available as npm packages or docker -containers. You should also be able to clone, build and use the packages on any -platform. However there is no guarantee that the development only features (e.g. -test or examples) will work out of the box. It is recommend to use UNIX based -systems for development. If you are using Windows, consider -[WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). +Airnode packages are cross platform, available as npm packages or docker containers. You should also be able to clone, build and use the packages on any platform. However there is no guarantee that the development only features (e.g. test or examples) will work out of the box. It is recommend to use UNIX based systems for development. If you are using Windows, consider [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). -- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-adapter) - The module that makes an API call, processes the response and returns a single - value. +- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-adapter) The module that makes an API call, processes the response and returns a single value. -- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin) - A package/CLI tool to interact with the Airnode contracts across chains. +- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-admin) A package/CLI tool to interact with the Airnode contracts across chains. -- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-abi) - Encoding and decoding utilities for Airnode according to the - [Airnode ABI specifications](/reference/airnode/v0.12/specifications/airnode-abi.md). +- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-abi) Encoding and decoding utilities for Airnode according to the [Airnode ABI specifications](/reference/airnode/v0.12/specifications/airnode-abi.md). -- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer) - Tools to automate Airnode deployment. +- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer) Tools to automate Airnode deployment. -- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples) - A public list of examples showcasing the features of Airnode. +- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples) A public list of examples showcasing the features of Airnode. -- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-node) - The node part of Airnode that allows for connecting multiple blockchains to - the rest of the world. +- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-node) The node part of Airnode that allows for connecting multiple blockchains to the rest of the world. -- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-operation) - Development and testing utilities for the core parts of Airnode. +- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-operation) Development and testing utilities for the core parts of Airnode. -- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-protocol) - Contracts that implement Airnode RRP (request–response protocol). +- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-protocol) Contracts that implement Airnode RRP (request–response protocol). -- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-validator) - A package that can be used to validate Airnode configuration. +- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-validator) A package that can be used to validate Airnode configuration. ## OIS -The `airnode-ois` monorepo package was removed from the Airnode repo and is now -in its own repo (`ois`) starting with Airnode `v0.8`. +The `airnode-ois` monorepo package was removed from the Airnode repo and is now in its own repo (`ois`) starting with Airnode `v0.8`. -- [ois:](https://github.com/api3dao/ois/tree/v2.0.0) Types for - [Oracle Integration Specification (OIS)](/reference/ois/2.1/specification.md). +- [ois:](https://github.com/api3dao/ois/tree/v2.0.0) Types for [Oracle Integration Specification (OIS)](/reference/ois/2.1/specification.md). diff --git a/docs/reference/airnode/v0.12/packages/validator.md b/docs/reference/airnode/v0.12/packages/validator.md index bdb75e76..1c5f9285 100644 --- a/docs/reference/airnode/v0.12/packages/validator.md +++ b/docs/reference/airnode/v0.12/packages/validator.md @@ -19,26 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-validator](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-validator) -is used internally by the [Docker Images](/reference/airnode/v0.12/docker/) to -validate the -[configuration files](/reference/airnode/v0.12/understand/configuring.md) you -provide when deploying an Airnode. - -However, validator can also be used as a standalone package to verify the -correctness of the configuration files without deploying the Airnode. The -recommended way is to use the -[validator CLI](/reference/airnode/v0.12/packages/validator.md#cli-usage), but -for advanced use cases you can use the -[validator SDK](/reference/airnode/v0.12/packages/validator.md#sdk-usage). +The [airnode-validator](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-validator) is used internally by the [Docker Images](/reference/airnode/v0.12/docker/) to validate the [configuration files](/reference/airnode/v0.12/understand/configuring.md) you provide when deploying an Airnode. + +However, validator can also be used as a standalone package to verify the correctness of the configuration files without deploying the Airnode. The recommended way is to use the [validator CLI](/reference/airnode/v0.12/packages/validator.md#cli-usage), but for advanced use cases you can use the [validator SDK](/reference/airnode/v0.12/packages/validator.md#sdk-usage). ## CLI Usage -The simplest way to run the CLI is using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). -Alternatively, you can install the validator package as a dependency in your -project. +The simplest way to run the CLI is using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). Alternatively, you can install the validator package as a dependency in your project. ```sh npx @api3/airnode-validator --config "config.json" --secrets "secrets.env" @@ -58,8 +45,7 @@ npx airnode-validator --config "config.json" --secrets "secrets.env" ### Examples -Assuming the configurations files inside current working directory are valid, -executing: +Assuming the configurations files inside current working directory are valid, executing: ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "valid-secrets.env" @@ -71,8 +57,7 @@ yields: ✔ The configuration is valid ``` -When there is an error during validation, the command prints out the error and -fails with a non zero status code. +When there is an error during validation, the command prints out the error and fails with a non zero status code. ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "non-existent-secrets.env" @@ -86,26 +71,17 @@ yields: ## SDK Usage -The validator package contains an API that can be used to validate Airnode -configuration files programatically. +The validator package contains an API that can be used to validate Airnode configuration files programatically. The following functions can be used: -- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` and validates the interpolated configuration. Expects both `config` - and `secrets` to be JSON objects. -- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a - JSON object. -- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be - a JSON object. -- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be - a JSON object. -- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` but does not perform any validation afterwards. Use this function - only when you can guarantee that the configuration is valid. - -Validator has also full TypeScript support. All of these functions return a -typed object. +- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` and validates the interpolated configuration. Expects both `config` and `secrets` to be JSON objects. +- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a JSON object. +- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be a JSON object. +- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be a JSON object. +- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` but does not perform any validation afterwards. Use this function only when you can guarantee that the configuration is valid. + +Validator has also full TypeScript support. All of these functions return a typed object. ### Examples @@ -148,7 +124,6 @@ if (parseResult.success) { ## Build Manually -See the build instructions for the validator in the -[airnode package repository](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-validator). +See the build instructions for the validator in the [airnode package repository](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-validator). diff --git a/docs/reference/airnode/v0.12/specifications/airnode-abi.md b/docs/reference/airnode/v0.12/specifications/airnode-abi.md index 890c527d..e1a3d4c3 100644 --- a/docs/reference/airnode/v0.12/specifications/airnode-abi.md +++ b/docs/reference/airnode/v0.12/specifications/airnode-abi.md @@ -19,39 +19,23 @@ tags: # {{$frontmatter.title}} -[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) -is used to encode different types of data while interacting with Ethereum -contracts. As a result, both Solidity and modules such as -[web3.js](https://web3js.readthedocs.io/) and -[ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality -as a first-class citizen. This makes using contract ABI for encoding API call -parameters a very attractive option. - -Although encoding API call parameters using contract ABI has many advantages, it -cannot be used for this purpose directly. Quoting from the -[Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): - -> The encoding is not self describing and thus requires a schema in order to -> decode. - -This means that when passing API call parameters (of type `bytes`), you would -also need to pass a list of the types for these parameters, which is cumbersome -and it is not clear how these types would be encoded. As a solution, Airnode -uses _Airnode ABI specifications_, an extension of contract ABI specifications -that includes a header that keeps the schema. +[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) is used to encode different types of data while interacting with Ethereum contracts. As a result, both Solidity and modules such as [web3.js](https://web3js.readthedocs.io/) and [ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality as a first-class citizen. This makes using contract ABI for encoding API call parameters a very attractive option. + +Although encoding API call parameters using contract ABI has many advantages, it cannot be used for this purpose directly. Quoting from the [Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): + +> The encoding is not self describing and thus requires a schema in order to decode. + +This means that when passing API call parameters (of type `bytes`), you would also need to pass a list of the types for these parameters, which is cumbersome and it is not clear how these types would be encoded. As a solution, Airnode uses _Airnode ABI specifications_, an extension of contract ABI specifications that includes a header that keeps the schema. ## Header -The Airnode ABI specifications header is of type `bytes32` and acts as the -schema (i.e., describes the types of the API call parameters). The header is -encoded in UTF-8 for ease of use. Here is an example: +The Airnode ABI specifications header is of type `bytes32` and acts as the schema (i.e., describes the types of the API call parameters). The header is encoded in UTF-8 for ease of use. Here is an example: ``` "1BSasbiuBa" ``` -The first character, `1`, represents the encoding version. Each following -character represents the type of an API call parameter. +The first character, `1`, represents the encoding version. Each following character represents the type of an API call parameter. ### Type encodings @@ -68,20 +52,11 @@ i: int256 f: bool ``` -Note that dynamically-sized types are represented with uppercase letters and -statically-sized types are represented with lowercase letters. Another thing to -notice is that `s` represents `string32`, but this is an artificial type and it -is not part of -[solidity types](https://docs.soliditylang.org/en/latest/types.html). This type -is instead represented on chain as `bytes32`. The reasons for this are explained -in depth in -[string32 details](/reference/airnode/v0.12/specifications/airnode-abi.md#string32) -section. +Note that dynamically-sized types are represented with uppercase letters and statically-sized types are represented with lowercase letters. Another thing to notice is that `s` represents `string32`, but this is an artificial type and it is not part of [solidity types](https://docs.soliditylang.org/en/latest/types.html). This type is instead represented on chain as `bytes32`. The reasons for this are explained in depth in [string32 details](/reference/airnode/v0.12/specifications/airnode-abi.md#string32) section. ## Encoding format -Airnode ABI specifications has the following encoding format (which is somewhat -similar to [SDS](https://github.com/antirez/sds)): +Airnode ABI specifications has the following encoding format (which is somewhat similar to [SDS](https://github.com/antirez/sds)): ``` [------------------------][-----------------------------------------] @@ -125,14 +100,11 @@ bytes memory parameters = abi.encode( ); ``` -Note that you do not need to add an external library to the contract, and -`abi.encode()` is fairly cheap in terms of gas usage (compared to alternative -encoding methods). +Note that you do not need to add an external library to the contract, and `abi.encode()` is fairly cheap in terms of gas usage (compared to alternative encoding methods). ## Example decoding -If you know the schema of the encoded parameters, then decode them on-chain. For -example, if the schema is `(bytes,string)`: +If you know the schema of the encoded parameters, then decode them on-chain. For example, if the schema is `(bytes,string)`: ```solidity ( @@ -142,17 +114,13 @@ example, if the schema is `(bytes,string)`: ) = abi.decode(parameters, (bytes32,bytes32,bytes,bytes32,string)); ``` -Note that this disregards the header and hard codes the schema into the code. It -is also possible to parse the header on-chain and decode accordingly, yet that -would be a lot more complex. +Note that this disregards the header and hard codes the schema into the code. It is also possible to parse the header on-chain and decode accordingly, yet that would be a lot more complex. ## Details ### `string32` -A parameter being of type `string32` (encoded as characted `s` in the ABI -specification schema header) implies that the parameter is UTF-8 encoded text. -For example, if the parameter is +A parameter being of type `string32` (encoded as characted `s` in the ABI specification schema header) implies that the parameter is UTF-8 encoded text. For example, if the parameter is ``` 0x68656c6c6f000000000000000000000000000000000000000000000000000000 @@ -164,9 +132,7 @@ Airnode will decode it as "hello" ``` -and feed that to the API, which is what the user would want to do in most cases. -This becomes a problem if the parameter is not encoded text, but for example a -hash such as: +and feed that to the API, which is what the user would want to do in most cases. This becomes a problem if the parameter is not encoded text, but for example a hash such as: ``` 0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71 @@ -179,15 +145,11 @@ If this hash is encoded as a `string32` type, Airnode will decode it as: !Õ$B˜±=/¡>q ``` -which is probably not what the user is looking for. For these use cases, the -user should use the -[`bytes32`](/reference/airnode/v0.12/specifications/airnode-abi.md#bytes32) type -instead. +which is probably not what the user is looking for. For these use cases, the user should use the [`bytes32`](/reference/airnode/v0.12/specifications/airnode-abi.md#bytes32) type instead. ### `bytes32` -To encode a `bytes32` hash on chain, use the `bytes32` type which is represented -by `b` in the ABI header schema. +To encode a `bytes32` hash on chain, use the `bytes32` type which is represented by `b` in the ABI header schema. ```solidity bytes memory parameters = abi.encode( @@ -202,46 +164,27 @@ When decoded by Airnode, the value would be the hash itself: "0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71" ``` -If you want to store 32 byte string values on chain, use the -[`string32`](/reference/airnode/v0.12/specifications/airnode-abi.md#string32) -type instead. +If you want to store 32 byte string values on chain, use the [`string32`](/reference/airnode/v0.12/specifications/airnode-abi.md#string32) type instead. ### `bool` -The `bool` type, encoded as character `f` using the ABI specification schema can -be used to encode a boolean value. The header symbol is `f`, because character -`b` was already reserved for bytes encodings. So we chose letter `f` as bool -values are commonly used to represent "boolean flags". +The `bool` type, encoded as character `f` using the ABI specification schema can be used to encode a boolean value. The header symbol is `f`, because character `b` was already reserved for bytes encodings. So we chose letter `f` as bool values are commonly used to represent "boolean flags". ### Omitted types -`array` and `tuple` are omitted because they are not suitable to be used as API -parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because -they are padded to 32 bytes by the ABI encoder anyway (meaning that the user -should simply typecast these to the 32-byte versions). +`array` and `tuple` are omitted because they are not suitable to be used as API parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because they are padded to 32 bytes by the ABI encoder anyway (meaning that the user should simply typecast these to the 32-byte versions). ### Size limit -The header can encode up to 31 parameters (and 1 byte is used to encode the -encoding version). This is far more than what would be needed in practice, and -thus is tolerated to avoid a more complex solution. +The header can encode up to 31 parameters (and 1 byte is used to encode the encoding version). This is far more than what would be needed in practice, and thus is tolerated to avoid a more complex solution. ### Padding -[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) -is used so that you can decode the values later on. This means that each -parameter will be padded with zeros to complete them to 32 bytes. Although this -padding increases gas costs, ABI encoding/decoding functions being cheap -balances this. Furthermore, the -[template](/reference/airnode/v0.12/concepts/template.md) pattern used in the -protocols allows for the referencing of these encoded parameters without -explicitly passing them in requests, making the increased cost induced by -padding irrelevant in most cases. +[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) is used so that you can decode the values later on. This means that each parameter will be padded with zeros to complete them to 32 bytes. Although this padding increases gas costs, ABI encoding/decoding functions being cheap balances this. Furthermore, the [template](/reference/airnode/v0.12/concepts/template.md) pattern used in the protocols allows for the referencing of these encoded parameters without explicitly passing them in requests, making the increased cost induced by padding irrelevant in most cases. ## `@api3/airnode-abi` -Encode and decode parameters with the -[airnode-abi](/reference/airnode/v0.12/packages/airnode-abi.md) package. +Encode and decode parameters with the [airnode-abi](/reference/airnode/v0.12/packages/airnode-abi.md) package. ```js import { encode } from '@api3/airnode-abi'; @@ -258,13 +201,6 @@ console.log('ENCODED:', encodedData); console.log('\nDECODED:', decoded); ``` -See the package doc -[airnode-abi](/reference/airnode/v0.12/packages/airnode-abi.md) for more -information on how to encode and decode with Airnode ABI off-chain. Also see -code samples in the -[examples](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples) -package. Lastly see the file -[request-utils.ts](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) -for example syntax on encoding parameters. +See the package doc [airnode-abi](/reference/airnode/v0.12/packages/airnode-abi.md) for more information on how to encode and decode with Airnode ABI off-chain. Also see code samples in the [examples](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples) package. Lastly see the file [request-utils.ts](https://github.com/api3dao/airnode/blob/v0.12/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) for example syntax on encoding parameters. diff --git a/docs/reference/airnode/v0.12/specifications/ois.md b/docs/reference/airnode/v0.12/specifications/ois.md index 644d6610..5844bd24 100644 --- a/docs/reference/airnode/v0.12/specifications/ois.md +++ b/docs/reference/airnode/v0.12/specifications/ois.md @@ -19,13 +19,8 @@ tags: # {{$frontmatter.title}} -The `ois` JSON object, in the `config.json` file that defines an Airnode, is an -integral part of an Airnode's understanding of an API's specification and its -endpoints. OIS provide a description of API endpoints and maps Airnode endpoints -to them. There can be more than one OIS object in the `config.json` file as -Airnode can serve endpoints from more than one API. - -Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) -in its versioned document set. +The `ois` JSON object, in the `config.json` file that defines an Airnode, is an integral part of an Airnode's understanding of an API's specification and its endpoints. OIS provide a description of API endpoints and maps Airnode endpoints to them. There can be more than one OIS object in the `config.json` file as Airnode can serve endpoints from more than one API. + +Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) in its versioned document set. diff --git a/docs/reference/airnode/v0.12/specifications/reserved-parameters.md b/docs/reference/airnode/v0.12/specifications/reserved-parameters.md index 421ba731..decca400 100644 --- a/docs/reference/airnode/v0.12/specifications/reserved-parameters.md +++ b/docs/reference/airnode/v0.12/specifications/reserved-parameters.md @@ -19,10 +19,6 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an Airnode's defined endpoints in an -[Oracle Integration Specifications (OIS)](/reference/ois/2.1/) object. They do -not map to operation parameters and are used by Airnode for special purposes. -See the [Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) doc in -the OIS document set for an in-depth explanation. +Reserved parameters are part of an Airnode's defined endpoints in an [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) object. They do not map to operation parameters and are used by Airnode for special purposes. See the [Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) doc in the OIS document set for an in-depth explanation. diff --git a/docs/reference/airnode/v0.12/understand/api-integration.md b/docs/reference/airnode/v0.12/understand/api-integration.md index c6067664..442a2844 100644 --- a/docs/reference/airnode/v0.12/understand/api-integration.md +++ b/docs/reference/airnode/v0.12/understand/api-integration.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -A successful integration of an API with an Airnode requires the mapping of each -other's interface. This is accomplished using an OIS -([Oracle Integration Specifications](/reference/ois/2.1/specification.md)) json -object, found in the config.json file, designed to with three basic steps. +A successful integration of an API with an Airnode requires the mapping of each other's interface. This is accomplished using an OIS ([Oracle Integration Specifications](/reference/ois/2.1/specification.md)) json object, found in the config.json file, designed to with three basic steps. 1. API operations are specified 1. Airnode endpoints are specified @@ -34,60 +31,36 @@ object, found in the config.json file, designed to with three basic steps. > >

The OIS object in config.json contains mapping information of API operations to Airnode endpoint definitions.

-OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode -endpoints. When a requester contract calls one of the AirnodeRrpV0.sol -contract's request functions, such as `makeFullRequest(..., callData)`, the -callData is communicated to the off-chain Airnode which uses OIS mappings to -translate the callData into a valid HTTP request for the appropriate API -operation. +OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode endpoints. When a requester contract calls one of the AirnodeRrpV0.sol contract's request functions, such as `makeFullRequest(..., callData)`, the callData is communicated to the off-chain Airnode which uses OIS mappings to translate the callData into a valid HTTP request for the appropriate API operation. -OIS borrows formatting from -[OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). -If you have experience with OAS, OIS will seem familiar. +OIS borrows formatting from [OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). If you have experience with OAS, OIS will seem familiar. ::: info OAS -It is not recommended to refer to OAS for help while creating your OIS object. -OIS only borrows formatting practices from OAS. Everything needed to create an -OIS object is in these docs. +It is not recommended to refer to OAS for help while creating your OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: **Tips while reading ths page.** -- Open the [OIS template](/reference/ois/2.1/template.md) in another browser - window to follow along. -- View an example of an Airnode - [config.json](/reference/airnode/v0.12/deployment-files/examples/config-json.md) - file. +- Open the [OIS template](/reference/ois/2.1/template.md) in another browser window to follow along. +- View an example of an Airnode [config.json](/reference/airnode/v0.12/deployment-files/examples/config-json.md) file. ## OIS Template -OIS is a json object that is added to an Airnode's -[config.json](/reference/airnode/v0.12/deployment-files/templates/config-json.md) -file as the (`ois`) _key_, sometimes called a _field_. Try using the -[OIS template](/reference/ois/2.1/template.md) to construct an OIS and add it to -the Airnode's config.json file later. +OIS is a json object that is added to an Airnode's [config.json](/reference/airnode/v0.12/deployment-files/templates/config-json.md) file as the (`ois`) _key_, sometimes called a _field_. Try using the [OIS template](/reference/ois/2.1/template.md) to construct an OIS and add it to the Airnode's config.json file later. -In the OIS template, there are some fields that contain `{FILL_*}`. This means -that the value added is independent from other fields. On the other hand, if two -fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), -you must use the same value in them, because they are referencing each other. +In the OIS template, there are some fields that contain `{FILL_*}`. This means that the value added is independent from other fields. On the other hand, if two fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), you must use the same value in them, because they are referencing each other. -OIS uses a simplified version of the OAS. This means that if you have the -OpenAPI specifications of the API that you are going to integrate, you are about -80% done, because you can copy paste entire sections (but be sure to make the -necessary modifications to conform to the OIS format). +OIS uses a simplified version of the OAS. This means that if you have the OpenAPI specifications of the API that you are going to integrate, you are about 80% done, because you can copy paste entire sections (but be sure to make the necessary modifications to conform to the OIS format). -The remainder of this page will assume you do not have the OpenAPI -specifications of the API that you will be integrating. +The remainder of this page will assume you do not have the OpenAPI specifications of the API that you will be integrating. ## 1. Specify OIS Definitions -Start building an OIS by adding three descriptive fields to the root of the OIS -json object. +Start building an OIS by adding three descriptive fields to the root of the OIS json object. ```json { @@ -100,20 +73,15 @@ json object. ### oisFormat -A specific version of the -[OIS Specification](/reference/ois/2.1/specification.md#_1-oisformat) to be -used. For Airnode `v0.12`, the proper OIS version is `2.1.0`. +A specific version of the [OIS Specification](/reference/ois/2.1/specification.md#_1-oisformat) to be used. For Airnode `v0.12`, the proper OIS version is `2.1.0`. ### title -This is a unique title of the OIS. Note that an Airnode can be configured with -more than one OIS object and uses the title as the OIS identifier. +This is a unique title of the OIS. Note that an Airnode can be configured with more than one OIS object and uses the title as the OIS identifier. ### version -This is the version of the OIS which allows for version-control of the OIS -integration. It is recommended to use [semver](https://semver.org/) versioning. -The initial version could be `0.1.0`. +This is the version of the OIS which allows for version-control of the OIS integration. It is recommended to use [semver](https://semver.org/) versioning. The initial version could be `0.1.0`. @@ -134,15 +102,11 @@ The `apiSpecifications` field is used to describe the API and its operations. ### Servers -The first step of specifying an API is to enter its _baseURL_ in the -`apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed -in the `apiSpecifications.servers` array. A warning is raised during conversion -if servers has multiple elements. This baseURL will apply to all operations. +The first step of specifying an API is to enter its _baseURL_ in the `apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed in the `apiSpecifications.servers` array. A warning is raised during conversion if servers has multiple elements. This baseURL will apply to all operations. #### Choosing a Base URL -Consider the following full URL to execute an API operation that returns all -know tokens. +Consider the following full URL to execute an API operation that returns all know tokens. @@ -164,16 +128,11 @@ or > > **path:** `/data` -Because the call will be made to <`baseURL+path`> both will result in the same -full URL. +Because the call will be made to <`baseURL+path`> both will result in the same full URL. -Set the baseURL as the section of the full URL that you expect to be shared by -all operations. From the examples above it is recommended to use -`https://www.myapi.com`, in case additional paths starting with `/v2` get added -to the API in the future. As you can tell, API integration requires many -subjective choices, and is more art than science. +Set the baseURL as the section of the full URL that you expect to be shared by all operations. From the examples above it is recommended to use `https://www.myapi.com`, in case additional paths starting with `/v2` get added to the API in the future. As you can tell, API integration requires many subjective choices, and is more art than science. ```json "apiSpecifications": { @@ -188,20 +147,15 @@ subjective choices, and is more art than science. ### Paths -The _paths_ field defines all the API operations much like an OpenAPI -Specification file. +The _paths_ field defines all the API operations much like an OpenAPI Specification file. _What is an API operation?_ -> An API operation is specified as a unique combination of a _**path**_ and an -> HTTP _**method**_. `GET /token/{id}` +> An API operation is specified as a unique combination of a _**path**_ and an HTTP _**method**_. `GET /token/{id}` #### Operations -In the examples below, `GET` refers to an -[HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). -This implies that you could have another API operation that can be specified -using a different method but the same path. +In the examples below, `GET` refers to an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). This implies that you could have another API operation that can be specified using a different method but the same path. > path: /data > @@ -211,18 +165,11 @@ using a different method but the same path. > > method: POST -Therefore, a path is not enough to specify an API operation by itself, you must -also provide a method. If a new path is needed then it must be a new object in -paths with its own methods. Currently only the GET and POST methods are -supported by Airnode. +Therefore, a path is not enough to specify an API operation by itself, you must also provide a method. If a new path is needed then it must be a new object in paths with its own methods. Currently only the GET and POST methods are supported by Airnode. -With regards to the [OIS template](/reference/ois/2.1/template.md), the name of -the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., -`/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the -operation to integrate (e.g., `get`). The method must be lowercase. +With regards to the [OIS template](/reference/ois/2.1/template.md), the name of the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., `/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the operation to integrate (e.g., `get`). The method must be lowercase. -The following example illustrates three operations, `GET /data`, `POST /data`, -`GET /tokens`. +The following example illustrates three operations, `GET /data`, `POST /data`, `GET /tokens`. ```json "paths": { @@ -244,27 +191,16 @@ The following example illustrates three operations, `GET /data`, `POST /data`, #### Parameters (operation) -After specifying the path and method of an API operation, the final step is to -specify its parameters. Each parameter is an object in the -`apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` -and `name`. `in` tells where the parameter goes in the HTTP request and `name` -tells the name that the parameter value will be sent under. Currently Airnode -supports the following parameter types for use with `in`. +After specifying the path and method of an API operation, the final step is to specify its parameters. Each parameter is an object in the `apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` and `name`. `in` tells where the parameter goes in the HTTP request and `name` tells the name that the parameter value will be sent under. Currently Airnode supports the following parameter types for use with `in`. - query - header - path - cookie -When integrating a POST method, define the body parameters with `in: query`. -Airnode will convert all `query` types into the `requestBody`. Note that only -the non-nested application/json content-type is supported. +When integrating a POST method, define the body parameters with `in: query`. Airnode will convert all `query` types into the `requestBody`. Note that only the non-nested application/json content-type is supported. -It is not necessary to specify all API operation parameters, but only the ones -the on-chain requester will need to be able to provide (see Airnode endpoint -[parameters](/reference/airnode/v0.12/understand/api-integration.md#parameters)), -and the ones needed to hard-code a value for (see Airnode endpoint -[fixed operation parameters](/reference/airnode/v0.12/understand/api-integration.md#fixedoperationparameters)). +It is not necessary to specify all API operation parameters, but only the ones the on-chain requester will need to be able to provide (see Airnode endpoint [parameters](/reference/airnode/v0.12/understand/api-integration.md#parameters)), and the ones needed to hard-code a value for (see Airnode endpoint [fixed operation parameters](/reference/airnode/v0.12/understand/api-integration.md#fixedoperationparameters)). ```json "paths": { @@ -287,8 +223,7 @@ and the ones needed to hard-code a value for (see Airnode endpoint _Example: Get a token_ -The `GET /token/{id}` returns a token using the token's `id` which is a `path` -parameter. +The `GET /token/{id}` returns a token using the token's `id` which is a `path` parameter. | Method | Path | in | name | | ------ | ----------- | ---- | ---- | @@ -296,11 +231,7 @@ parameter. _Example: Create a token_ -The `POST /token` operation accepts three parameters. The name and description -of the token are placed in the type `query` and will be moved by Airnode to the -requestBody upon calling the API operation. The third is a `header` parameter -that describes the Content-Type of the request such as `application/json` or -`application/x-www-form-urlencoded`. +The `POST /token` operation accepts three parameters. The name and description of the token are placed in the type `query` and will be moved by Airnode to the requestBody upon calling the API operation. The third is a `header` parameter that describes the Content-Type of the request such as `application/json` or `application/x-www-form-urlencoded`. | Method | Path | in | name | | ------ | ------ | ------ | ----------- | @@ -310,9 +241,7 @@ that describes the Content-Type of the request such as `application/json` or _Example: Get all tokens_ -The `GET /tokens` returns a list of all tokens. The list count can be limited -using the `limit' parameter which the API operation considers as optional since -it will not return an error if omitted. +The `GET /tokens` returns a list of all tokens. The list count can be limited using the `limit' parameter which the API operation considers as optional since it will not return an error if omitted. > `GET /tokens` returns all tokens. > @@ -326,66 +255,25 @@ it will not return an error if omitted. ## 3. Specifying Airnode Endpoints -An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It -maps to an API operation, but the nature of this mapping is customizable. It is -the integrator's job to define what this service is. - -For example, if an API operation returns an asset price given its ticker (e.g., -`BTC`), specify the endpoint such that the requester provides the ticker as a -parameter. The resulting endpoint would be a general one that returns prices for -any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price -will be returned (using -[fixed operation parameters](/reference/airnode/v0.12/understand/api-integration.md#fixedoperationparameters)), -which would make the endpoint a specific one that only returns the BTC price. - -The recommended endpoint definition pattern is to create an Airnode endpoint for -each API operation, and allow the requesters to provide all operation parameters -themselves. This results in optimal flexibility, and essentially allows the -requesters to use the entire API functionality on-chain. Normally, competitor -oracle integrations strive to hard-code as many API parameters as possible -because passing these parameters on-chain results in a gas cost overhead. -However, the Airnode protocol uses -[templates](/reference/airnode/v0.12/concepts/template.md) (not to be confused -with the OIS template used for this guide), which allow requesters to specify a -large number of endpoint parameters at no additional gas cost. - -Note that there are some cases where you may not want to map endpoints to API -operations one-to-one. For example, an API operation can have a `header` -parameter, `Accept`, that can take the values `application/json` or -`application/xml` to determine how to format the data that the API will respond -to the call. Airnode expects responses to be in JSON format, and thus -hard-coding this parameter as `JSON` would be more suitable than letting the -requester decide, as there is only one valid choice. Again, the integrator's job -is to be aware of these subtleties and use judgement. +An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It maps to an API operation, but the nature of this mapping is customizable. It is the integrator's job to define what this service is. + +For example, if an API operation returns an asset price given its ticker (e.g., `BTC`), specify the endpoint such that the requester provides the ticker as a parameter. The resulting endpoint would be a general one that returns prices for any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price will be returned (using [fixed operation parameters](/reference/airnode/v0.12/understand/api-integration.md#fixedoperationparameters)), which would make the endpoint a specific one that only returns the BTC price. + +The recommended endpoint definition pattern is to create an Airnode endpoint for each API operation, and allow the requesters to provide all operation parameters themselves. This results in optimal flexibility, and essentially allows the requesters to use the entire API functionality on-chain. Normally, competitor oracle integrations strive to hard-code as many API parameters as possible because passing these parameters on-chain results in a gas cost overhead. However, the Airnode protocol uses [templates](/reference/airnode/v0.12/concepts/template.md) (not to be confused with the OIS template used for this guide), which allow requesters to specify a large number of endpoint parameters at no additional gas cost. + +Note that there are some cases where you may not want to map endpoints to API operations one-to-one. For example, an API operation can have a `header` parameter, `Accept`, that can take the values `application/json` or `application/xml` to determine how to format the data that the API will respond to the call. Airnode expects responses to be in JSON format, and thus hard-coding this parameter as `JSON` would be more suitable than letting the requester decide, as there is only one valid choice. Again, the integrator's job is to be aware of these subtleties and use judgement. ### Endpoints array -The field `endpoints` is an array, with each row representing an Airnode -endpoint. The first field to fill in is `name`. Make sure that it is descriptive -and unique from other endpoint names. If you are integrating API operations to -Airnode endpoints one-to-one, using the API operation path as the endpoint name -is a decent choice (i.e., `/token`). Note that you would also add the method to -this name if there were multiple operations with different methods for a single -path (i.e., `GET/token`). +The field `endpoints` is an array, with each row representing an Airnode endpoint. The first field to fill in is `name`. Make sure that it is descriptive and unique from other endpoint names. If you are integrating API operations to Airnode endpoints one-to-one, using the API operation path as the endpoint name is a decent choice (i.e., `/token`). Note that you would also add the method to this name if there were multiple operations with different methods for a single path (i.e., `GET/token`). -The next step is to fill in `operation` object. Here, you need to enter the -`path` and `method` of an API operation you have defined in -`apiSpecifications.paths`, resulting in the Airnode endpoint calling the now -linked API operation. +The next step is to fill in `operation` object. Here, you need to enter the `path` and `method` of an API operation you have defined in `apiSpecifications.paths`, resulting in the Airnode endpoint calling the now linked API operation. #### fixedOperationParameters -It is not uncommon to hard-code API parameters (recall the `Accept` operation -parameter in the above example). Such hard-coded parameters are called -`fixedOperationParameters`. +It is not uncommon to hard-code API parameters (recall the `Accept` operation parameter in the above example). Such hard-coded parameters are called `fixedOperationParameters`. -In the OIS template there is a fixed operation parameter under -`endpoints[n].fixedOperationParameters`, and it refers to the first API -operation parameter. This means that whenever the Airnode receives a request for -this endpoint, the respective API call will be made with that API operation -parameter set to -endpoints[n].fixedOperationParameters[n].value. -The requester does not supply a value for `fixedOperationParameters`. +In the OIS template there is a fixed operation parameter under `endpoints[n].fixedOperationParameters`, and it refers to the first API operation parameter. This means that whenever the Airnode receives a request for this endpoint, the respective API call will be made with that API operation parameter set to endpoints[n].fixedOperationParameters[n].value. The requester does not supply a value for `fixedOperationParameters`. ```json "fixedOperationParameters": [ @@ -400,31 +288,17 @@ The requester does not supply a value for `fixedOperationParameters`. ``` -An Airnode endpoint can have multiple `fixedOperationParameters`. An API -operation parameter cannot be in both `endpoints[n].fixedOperationParameters` -and `endpoints[n].parameters`. +An Airnode endpoint can have multiple `fixedOperationParameters`. An API operation parameter cannot be in both `endpoints[n].fixedOperationParameters` and `endpoints[n].parameters`. #### reservedParameters -The requester can provide some parameters that are not mapped to API operation -parameters. These parameters are called "reserved parameters", and their names -start with an underscore. See the -[related OIS docs](/reference/ois/2.1/specification.md#_5-4-reservedparameters) -for more information. +The requester can provide some parameters that are not mapped to API operation parameters. These parameters are called "reserved parameters", and their names start with an underscore. See the [related OIS docs](/reference/ois/2.1/specification.md#_5-4-reservedparameters) for more information. -The current list of reserved parameters are `_type`, `_path`, `_times`, -`_gasPrice`, and `_minConfirmations`. See -[Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) in the OIS -document set to understand what each of these parameters are for. +The current list of reserved parameters are `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. See [Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) in the OIS document set to understand what each of these parameters are for. #### parameters -Airnode endpoint -[parameters](/reference/ois/2.1/specification.md#_5-5-parameters) map to API -operation [parameters](/reference/ois/2.1/specification.md#_4-2-1-parameters) -that the requester is allowed to provide values for. It refers to an API -operation through its field `operationParameter`. You can also provide `default` -values for endpoint parameters, though this is not recommended in most cases. +Airnode endpoint [parameters](/reference/ois/2.1/specification.md#_5-5-parameters) map to API operation [parameters](/reference/ois/2.1/specification.md#_4-2-1-parameters) that the requester is allowed to provide values for. It refers to an API operation through its field `operationParameter`. You can also provide `default` values for endpoint parameters, though this is not recommended in most cases. ```json // apiSpecifications.paths...parameters[1] @@ -460,27 +334,14 @@ Mapping between API parameters and endpoint parameters. │ │ ] ``` -Endpoint parameters have a `name` field, which does not have to be the same as -the API operation parameter that they map to. As a separate note, an Airnode -endpoint can have multiple parameters. +Endpoint parameters have a `name` field, which does not have to be the same as the API operation parameter that they map to. As a separate note, an Airnode endpoint can have multiple parameters. ## Conclusion -The API operations and Airnode endpoints are now specified. Each Airnode -endpoint maps to an API operation, and each Airnode endpoint parameter or -fixedOperationParameter maps to an API operation parameter. The resulting OIS -includes no user-specific information, which means that you can share it for -others to easily provide the same services (for example, to set up a third-party -oracle network). - -Note that there was some subjectivity while defining the Airnode endpoints. This -means that two different OISes can exist for the same exact API, differing based -on how the integrators designed the interface that the requester will use. -However, in most cases, one would simply map API operations to Airnode endpoints -directly, and let the requester provide all API operation parameters through the -Airnode endpoint parameters. - -Now that you have an OIS object, the next step is -[API Security](/reference/airnode/v0.12/understand/api-security.md). +The API operations and Airnode endpoints are now specified. Each Airnode endpoint maps to an API operation, and each Airnode endpoint parameter or fixedOperationParameter maps to an API operation parameter. The resulting OIS includes no user-specific information, which means that you can share it for others to easily provide the same services (for example, to set up a third-party oracle network). + +Note that there was some subjectivity while defining the Airnode endpoints. This means that two different OISes can exist for the same exact API, differing based on how the integrators designed the interface that the requester will use. However, in most cases, one would simply map API operations to Airnode endpoints directly, and let the requester provide all API operation parameters through the Airnode endpoint parameters. + +Now that you have an OIS object, the next step is [API Security](/reference/airnode/v0.12/understand/api-security.md). diff --git a/docs/reference/airnode/v0.12/understand/api-security.md b/docs/reference/airnode/v0.12/understand/api-security.md index 50e99f84..da1ce5c2 100644 --- a/docs/reference/airnode/v0.12/understand/api-security.md +++ b/docs/reference/airnode/v0.12/understand/api-security.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode can pass along security information (schemes) when making calls to API -operations. There are two groups of security schemes. +Airnode can pass along security information (schemes) when making calls to API operations. There are two groups of security schemes. - [Airnode Authentication](/reference/airnode/v0.12/concepts/airnode-auth.md) - [Relayed Meta Data Authentication](/reference/airnode/v0.12/concepts/relay-meta-auth.md) @@ -31,8 +30,7 @@ operations. There are two groups of security schemes. > 1.

The Airnode uses Airnode Authentication Security Schemes to authenticate itself to an API operation of which the values are known only by the Airnode.

> 2.

The Airnode uses Relayed Meta Data Security Schemes to forward known information from the requester's request to an API operation.

-Security schemes are declared by the required `type` property inside the -security scheme definition. The following security scheme types are supported. +Security schemes are declared by the required `type` property inside the security scheme definition. The following security scheme types are supported. - Airnode Authentication Security Schemes - apiKey @@ -46,22 +44,16 @@ security scheme definition. The following security scheme types are supported. - relaySponsorWalletAddress - relayRequestId -It is important to note that the security schemes in any given OIS object apply -to all endpoints/API operations in the OIS object. If different security schemes -are required by a mix of endpoints/API operations, then more than one OIS object -will be required grouping endpoint/API operations based on their security needs. +It is important to note that the security schemes in any given OIS object apply to all endpoints/API operations in the OIS object. If different security schemes are required by a mix of endpoints/API operations, then more than one OIS object will be required grouping endpoint/API operations based on their security needs. ## Airnode Authentication Security Schemes -An Airnode can use the following security scheme types to authenticate itself to -API operations. +An Airnode can use the following security scheme types to authenticate itself to API operations. - [apiKey](/reference/airnode/v0.12/understand/api-security.md#apikey) - [http](/reference/airnode/v0.12/understand/api-security.md#http) -A security scheme requires a unique name within the OIS object for which it -exists. This name groups the security scheme values for `in`, `type`, and` name` -as shown in the two code examples below. +A security scheme requires a unique name within the OIS object for which it exists. This name groups the security scheme values for `in`, `type`, and` name` as shown in the two code examples below. - `securitySchemes.` - `security.` @@ -69,18 +61,12 @@ as shown in the two code examples below. ### apiKey -The `apiKey` security scheme type allows you to define an API key the Airnode -will send to API operations. It is an object which consists of the following -fields: +The `apiKey` security scheme type allows you to define an API key the Airnode will send to API operations. It is an object which consists of the following fields: - `type` must be `apiKey` -- `in` can be one of the `query`, `header` or `cookie`. This value specifies how - the value will be sent to an API operation. When using the `query` option, the - API key will be sent in the request body for POST requests and in query string - for GET requests. +- `in` can be one of the `query`, `header` or `cookie`. This value specifies how the value will be sent to an API operation. When using the `query` option, the API key will be sent in the request body for POST requests and in query string for GET requests. -- `name` is the name of the API key that should be sent to an API. For example - "X-Api-Key". +- `name` is the name of the API key that should be sent to an API. For example "X-Api-Key". ```json "ois": [ @@ -108,11 +94,7 @@ fields: ] │ ``` -The value of the `apiKey` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `apiKey` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json "apiCredentials": [ │ @@ -126,11 +108,7 @@ file. ### http -The `http` security scheme type is used to define either a `basic` or `bearer` -authentication scheme. This security scheme will always be sent in the headers. -The security scheme value should be base64 encoded value "username:password" for -`basic` auth and the encoded token for `bearer` auth. It is an object which -consists of the following fields: +The `http` security scheme type is used to define either a `basic` or `bearer` authentication scheme. This security scheme will always be sent in the headers. The security scheme value should be base64 encoded value "username:password" for `basic` auth and the encoded token for `bearer` auth. It is an object which consists of the following fields: - `type` must be `http` - `scheme` is either `basic` or `bearer` @@ -144,11 +122,7 @@ consists of the following fields: } ``` -The value of the `http` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `http` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json { @@ -160,19 +134,13 @@ file. ::: info Authentication Tutorial -The -[authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates authentication. +The [authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) monorepo example demonstrates authentication. ::: ## Relayed Meta Data Security Schemes -In addition to authenticating itself, Airnode can "relay" security information -about a request to an API operation. This is different then the authorization of -requesters using -[Authorizers](/reference/airnode/v0.12/understand/apply-auth.md) to access the -Airnode. +In addition to authenticating itself, Airnode can "relay" security information about a request to an API operation. This is different then the authorization of requesters using [Authorizers](/reference/airnode/v0.12/understand/apply-auth.md) to access the Airnode. - [relayRequesterAddress](/reference/airnode/v0.12/understand/api-security.md#relayrequesteraddress) - [relayChainId](/reference/airnode/v0.12/understand/api-security.md#relaychainid) @@ -181,29 +149,19 @@ Airnode. - [relaySponsorWalletAddress](/reference/airnode/v0.12/understand/api-security.md#relaysponsorwalletaddress) - [relayRequestId](/reference/airnode/v0.12/understand/api-security.md#relayrequestid) -For relayed meta data security schemes do not provide any values in -[apiCredentials](/reference/airnode/v0.12/deployment-files/config-json.md#apicredentials) -as they are extracted from the request by Airnode. +For relayed meta data security schemes do not provide any values in [apiCredentials](/reference/airnode/v0.12/deployment-files/config-json.md#apicredentials) as they are extracted from the request by Airnode. -Note that Airnode relays this metadata to an API operation and does not perform -any additional processing logic. The API provider must implement any desired -logic in the API operation for any desired security checks. See -[Relayed Meta Data Authentication](/reference/airnode/v0.12/concepts/relay-meta-auth.md) -for overview of its usage. +Note that Airnode relays this metadata to an API operation and does not perform any additional processing logic. The API provider must implement any desired logic in the API operation for any desired security checks. See [Relayed Meta Data Authentication](/reference/airnode/v0.12/concepts/relay-meta-auth.md) for overview of its usage. ::: info Relay Metadata Tutorial -The -[relay-security-schemes](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates how to relay request metadata like chain ID and -sponsor address to the API endpoint. +The [relay-security-schemes](/guides/airnode/monorepo-examples.md) monorepo example demonstrates how to relay request metadata like chain ID and sponsor address to the API endpoint. ::: ### relayRequesterAddress -The `relayRequesterAddress` security scheme type instructs Airnode to forward -the [requester](/reference/airnode/v0.12/concepts/requester.md) address. +The `relayRequesterAddress` security scheme type instructs Airnode to forward the [requester](/reference/airnode/v0.12/concepts/requester.md) address. ```json { @@ -215,8 +173,7 @@ the [requester](/reference/airnode/v0.12/concepts/requester.md) address. ### relayChainId -The `relayChainId` security scheme type instructs Airnode to forward the chain's -ID. +The `relayChainId` security scheme type instructs Airnode to forward the chain's ID. ```json { @@ -228,8 +185,7 @@ ID. ### relayChainType -The `relayChainType` security scheme type instructs Airnode to forward the -chain's type. +The `relayChainType` security scheme type instructs Airnode to forward the chain's type. ```json { @@ -241,8 +197,7 @@ chain's type. ### relaySponsorAddress -The `relaySponsorAddress` security scheme type instructs Airnode to forward the -[sponsor address](/reference/airnode/v0.12/concepts/sponsor.md#sponsoraddress). +The `relaySponsorAddress` security scheme type instructs Airnode to forward the [sponsor address](/reference/airnode/v0.12/concepts/sponsor.md#sponsoraddress). ```json { @@ -254,9 +209,7 @@ The `relaySponsorAddress` security scheme type instructs Airnode to forward the ### relaySponsorWalletAddress -The `relaySponsorWalletAddress` security scheme type instructs Airnode to -forward the -[sponsor wallet address](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). +The `relaySponsorWalletAddress` security scheme type instructs Airnode to forward the [sponsor wallet address](/reference/airnode/v0.12/concepts/sponsor.md#sponsorwallet). ```json { @@ -268,8 +221,7 @@ forward the ### relayRequestId -The `relayRequestId` security scheme type instructs Airnode to forward the -[id of the request](/reference/airnode/v0.12/concepts/request.md#requestid). +The `relayRequestId` security scheme type instructs Airnode to forward the [id of the request](/reference/airnode/v0.12/concepts/request.md#requestid). ```json { @@ -279,10 +231,7 @@ The `relayRequestId` security scheme type instructs Airnode to forward the } ``` -The following example shows how to set up relayed meta data to forward the -`relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that -unlike the Airnode authentication security scheme, no values are stored in -`apiCredentials` as Airnode passes these known values to the API operation. +The following example shows how to set up relayed meta data to forward the `relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that unlike the Airnode authentication security scheme, no values are stored in `apiCredentials` as Airnode passes these known values to the API operation. ```json "ois": [ @@ -318,29 +267,19 @@ unlike the Airnode authentication security scheme, no values are stored in ::: info Remember -The relayed meta data security schemes do not require a supplied value. Values -will be provided (relayed) by Airnode depending on the particular request. +The relayed meta data security schemes do not require a supplied value. Values will be provided (relayed) by Airnode depending on the particular request. ::: ## Example -OIS security is inspired by OAS security practices. This is implemented using -the security schemes and security field. All supported security schemes are -described in detail in the -[Airnode Authentication Security Schemes](/reference/airnode/v0.12/understand/api-security.md#airnode-authentication-security-schemes) -and -[Relayed Meta Data Security Schemes](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes) -sections above. The following example is related to _Airnode Authentication -Security Schemes_. Working with security schemes can be described in three -steps. +OIS security is inspired by OAS security practices. This is implemented using the security schemes and security field. All supported security schemes are described in detail in the [Airnode Authentication Security Schemes](/reference/airnode/v0.12/understand/api-security.md#airnode-authentication-security-schemes) and [Relayed Meta Data Security Schemes](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes) sections above. The following example is related to _Airnode Authentication Security Schemes_. Working with security schemes can be described in three steps. 1. [Define the security schemes for an OIS](/reference/airnode/v0.12/understand/api-security.md#step-1-define-the-security-schemes-for-an-ois) 2. [Turn on the defined security schemes](/reference/airnode/v0.12/understand/api-security.md#step-2-turn-on-the-defined-security-schemes) 3. [Specify the values for the defined security schemes](/reference/airnode/v0.12/understand/api-security.md#step-3-specify-the-values-for-the-defined-security-schemes) -Following is an example of a partial `config.json` which demonstrates the usage -of security scheme and security field. +Following is an example of a partial `config.json` which demonstrates the usage of security scheme and security field. ```json { @@ -377,60 +316,34 @@ of security scheme and security field. ### Step #1: Define the security schemes for an OIS -Use -ois[n].apiSpecifications.components.securitySchemes -to define the security schemes the API operation requires. Consider the partial -`config.json` above that declares a security scheme named `requiresXApiKey`. -This scheme declares that the API requires an API key that must exist in the -HTTP header named `X-api-key`. +Use ois[n].apiSpecifications.components.securitySchemes to define the security schemes the API operation requires. Consider the partial `config.json` above that declares a security scheme named `requiresXApiKey`. This scheme declares that the API requires an API key that must exist in the HTTP header named `X-api-key`. ### Step #2: Turn on the defined security schemes -When the scheme is defined, it is not turned on by default. You need to -explicitly list the security schemes you intend to use in the `security` field -located in `ois[n].apiSpecifications.security` object. The keys in this object -are the names of security schemes to be used. Use empty array (`[]`) as its -value. +When the scheme is defined, it is not turned on by default. You need to explicitly list the security schemes you intend to use in the `security` field located in `ois[n].apiSpecifications.security` object. The keys in this object are the names of security schemes to be used. Use empty array (`[]`) as its value. -_Be aware that this step seems like extra work since there is no reason to -define a security scheme that will not be used. However, Airnode may support -[more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) -logic in the future and using `[]` allows its implementation without a breaking -change._ +_Be aware that this step seems like extra work since there is no reason to define a security scheme that will not be used. However, Airnode may support [more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) logic in the future and using `[]` allows its implementation without a breaking change._ ### Step #3: Specify the values for the defined security schemes -After defining and turning on a security scheme, it may be unclear what provides -the value and how it is set. +After defining and turning on a security scheme, it may be unclear what provides the value and how it is set. -The authentication schemes are intended to be common for the whole OIS and set -by the API provider using `apiCredentials` which is part of `config.json`. The -`apiCredentials` is an array which specifies the values for all security schemes -in all OIS definitions. Each element of this array contains the following fields +The authentication schemes are intended to be common for the whole OIS and set by the API provider using `apiCredentials` which is part of `config.json`. The `apiCredentials` is an array which specifies the values for all security schemes in all OIS definitions. Each element of this array contains the following fields - `oisTitle` is the title of the OIS for the particular security scheme - `securitySchemeName` is the name of the security scheme -- `securitySchemeValue` is the actual value that should be used by Airnode when - making the API request. This value is usually a secret and it is recommended - to interpolate it from `secrets.env`. +- `securitySchemeValue` is the actual value that should be used by Airnode when making the API request. This value is usually a secret and it is recommended to interpolate it from `secrets.env`. ## Using Different Security Schemes -Currently, if you want different API operations to use different security -schemes they must be grouped in different OIS objects based on their common -security schemes. For example, your API has four operations, three require an -API key in the HTTP header, another (public `/ping` endpoint) requires no -security. +Currently, if you want different API operations to use different security schemes they must be grouped in different OIS objects based on their common security schemes. For example, your API has four operations, three require an API key in the HTTP header, another (public `/ping` endpoint) requires no security. -- The first three API operations might be in the `ois[0]` object with a security - scheme named _requiresXApiKey_ of type _apiKey_ as shown above. -- The /ping API operation would be in `ois[1]` which would not have any - `component.securitySchemes` and `security` would be an empty array. +- The first three API operations might be in the `ois[0]` object with a security scheme named _requiresXApiKey_ of type _apiKey_ as shown above. +- The /ping API operation would be in `ois[1]` which would not have any `component.securitySchemes` and `security` would be an empty array. ## Multiple Security Schemes -You can use multiple security schemes (e.g., an API key goes in the header, and -an additional secret goes in the query). +You can use multiple security schemes (e.g., an API key goes in the header, and an additional secret goes in the query). ```json // inside ois[n].apiSpecifications. @@ -456,7 +369,6 @@ an additional secret goes in the query). ## No Security -If the API you are integrating is publicly accessible, you can set both the -`security schemes` and `security` fields to empty objects. +If the API you are integrating is publicly accessible, you can set both the `security schemes` and `security` fields to empty objects. diff --git a/docs/reference/airnode/v0.12/understand/apply-auth.md b/docs/reference/airnode/v0.12/understand/apply-auth.md index 80344c52..d413b0b5 100644 --- a/docs/reference/airnode/v0.12/understand/apply-auth.md +++ b/docs/reference/airnode/v0.12/understand/apply-auth.md @@ -19,51 +19,29 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using [Authorizers](/reference/airnode/v0.12/concepts/authorizers.md). -This method is on-chain and requires some blockchain knowledge by an API -provider. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizers](/reference/airnode/v0.12/concepts/authorizers.md). This method is on-chain and requires some blockchain knowledge by an API provider. ## What is an authorizer? -An [Authorizer](/reference/airnode/v0.12/concepts/authorizers.md) is a contract -which typically checks for a single condition ("has the requester made their -monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers -can be combined to enforce more complex policies. If any of the authorizers in -the list gives access, the request will considered to be authorized. From a -logical standpoint, the authorization outcomes get *OR*ed. +An [Authorizer](/reference/airnode/v0.12/concepts/authorizers.md) is a contract which typically checks for a single condition ("has the requester made their monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers can be combined to enforce more complex policies. If any of the authorizers in the list gives access, the request will considered to be authorized. From a logical standpoint, the authorization outcomes get *OR*ed. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: ## How to implement authorizers. -When you deploy your Airnode a receipt file is generated which contains the -Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use -`airnodeAddress` and an `endpointId` to make requests to your Airnode's -endpoints. However, rather than serve them publicly, you may want to: +When you deploy your Airnode a receipt file is generated which contains the Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use `airnodeAddress` and an `endpointId` to make requests to your Airnode's endpoints. However, rather than serve them publicly, you may want to: -- Only serve your own - [requester contracts](/reference/airnode/v0.12/developers/requesters-sponsors.md). +- Only serve your own [requester contracts](/reference/airnode/v0.12/developers/requesters-sponsors.md). - Only serve sponsors who have made a subscription payment. - Only serve sponsors who have gone through KYC. -The `chains[n].authorizers` object within `config.json` enables requests to be -authorized in a variety of ways and even across chains. Currently, the -authorizers include `requesterEndpointAuthorizers`, -`crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and -`crossChainRequesterAuthorizersWithErc721`. +The `chains[n].authorizers` object within `config.json` enables requests to be authorized in a variety of ways and even across chains. Currently, the authorizers include `requesterEndpointAuthorizers`, `crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and `crossChainRequesterAuthorizersWithErc721`. -Note that when all `chains[n].authorizers` values are empty arrays, all requests -are authorized, but still can be filtered by using -[Relayed Meta Data Security Schemes](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes). +Note that when all `chains[n].authorizers` values are empty arrays, all requests are authorized, but still can be filtered by using [Relayed Meta Data Security Schemes](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes). Below are examples of how to use the authorizers. @@ -122,23 +100,11 @@ Below are examples of how to use the authorizers. ## Using `RequesterAuthorizerWithAirnode` -A common use case for an authorizer is the -[RequesterAuthorizerWithAirnode](/reference/airnode/v0.12/concepts/authorizers.md#requesterauthorizerwithairnode) -authorizer contract developed for Airnode operators to use right out-of-the-box. -It allows the whitelisting of requester contracts (with or without expiration -timestamps) on a per endpoint basis. Endpoints are declared in the -`ois.endpoints` field of the `config.json` file. This is the most common use -case and can be implemented with the following steps: - -1. Add the RequesterAuthorizerWithAirnode - [authorizer contract address](/reference/airnode/v0.12/#requesterauthorizerwithairnode) - to the array `chains[n].authorizers.requesterEndpointAuthorizers`. -2. After your Airnode is deployed, call the Admin CLI command - [set-whitelist-expiration](/reference/airnode/v0.12/packages/admin-cli.md#set-whitelist-expiration) - to add the desired requester contract addresses to the whitelist maintained - by RequesterAuthorizerWithAirnode. - -Once implemented, only requester contract addresses you have added to -RequesterAuthorizerWithAirnode will have access to your Airnode. +A common use case for an authorizer is the [RequesterAuthorizerWithAirnode](/reference/airnode/v0.12/concepts/authorizers.md#requesterauthorizerwithairnode) authorizer contract developed for Airnode operators to use right out-of-the-box. It allows the whitelisting of requester contracts (with or without expiration timestamps) on a per endpoint basis. Endpoints are declared in the `ois.endpoints` field of the `config.json` file. This is the most common use case and can be implemented with the following steps: + +1. Add the RequesterAuthorizerWithAirnode [authorizer contract address](/reference/airnode/v0.12/#requesterauthorizerwithairnode) to the array `chains[n].authorizers.requesterEndpointAuthorizers`. +2. After your Airnode is deployed, call the Admin CLI command [set-whitelist-expiration](/reference/airnode/v0.12/packages/admin-cli.md#set-whitelist-expiration) to add the desired requester contract addresses to the whitelist maintained by RequesterAuthorizerWithAirnode. + +Once implemented, only requester contract addresses you have added to RequesterAuthorizerWithAirnode will have access to your Airnode. diff --git a/docs/reference/airnode/v0.12/understand/configuring.md b/docs/reference/airnode/v0.12/understand/configuring.md index e2cd6ff0..3a3aea95 100644 --- a/docs/reference/airnode/v0.12/understand/configuring.md +++ b/docs/reference/airnode/v0.12/understand/configuring.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -An Airnode is deployed or redeployed using configuration values from its -`config.json` and `secrets.env` files. The `config.json` specifies the -[Oracle Integration Specifications OIS](/reference/ois/2.1/specification.md) and -other specific configuration details. The `secrets.env` file holds secrets, such -as API keys and chain provider URLs, which are referenced within the config.json -file using interpolation. +An Airnode is deployed or redeployed using configuration values from its `config.json` and `secrets.env` files. The `config.json` specifies the [Oracle Integration Specifications OIS](/reference/ois/2.1/specification.md) and other specific configuration details. The `secrets.env` file holds secrets, such as API keys and chain provider URLs, which are referenced within the config.json file using interpolation. > > @@ -41,11 +36,7 @@ The following example files are useful while reading this doc. ## Creating `config.json` -Use the -[config.json template](/reference/airnode/v0.12/deployment-files/templates/config-json.md) -to build your own Airnode configuration file or alter the -[config.json example](/reference/airnode/v0.12/deployment-files/examples/config-json.md) -file. There are six root level fields in `config.json`. +Use the [config.json template](/reference/airnode/v0.12/deployment-files/templates/config-json.md) to build your own Airnode configuration file or alter the [config.json example](/reference/airnode/v0.12/deployment-files/examples/config-json.md) file. There are six root level fields in `config.json`. - [chains](/reference/airnode/v0.12/understand/configuring.md#chains) - [nodeSettings](/reference/airnode/v0.12/understand/configuring.md#nodesettings) @@ -56,15 +47,7 @@ file. There are six root level fields in `config.json`. ### chains -Each row in the `chains` array represents an Ethereum blockchain the Airnode -will serve as identified by the `id`. Currently Airnode only supports Ethereum -blockchains as denoted by `type: "evm"`. There are several supported -blockchains, see them in the -[Airnode contract addresses](/reference/airnode/v0.12/) doc. You can use -multiple chain providers for each chain and declare multiple chains each with -one of more chain providers. See -[Chains Providers](/reference/airnode/v0.12/concepts/chain-providers.md) in -_Concepts and Definitions_. +Each row in the `chains` array represents an Ethereum blockchain the Airnode will serve as identified by the `id`. Currently Airnode only supports Ethereum blockchains as denoted by `type: "evm"`. There are several supported blockchains, see them in the [Airnode contract addresses](/reference/airnode/v0.12/) doc. You can use multiple chain providers for each chain and declare multiple chains each with one of more chain providers. See [Chains Providers](/reference/airnode/v0.12/concepts/chain-providers.md) in _Concepts and Definitions_. Below is a simple chain array with a single chain provider. @@ -128,42 +111,26 @@ Below is a simple chain array with a single chain provider. ::: info Idiosyncrasies -See the dedicated -[Chain Idiosyncrasies](/reference/airnode/v0.12/chain-idiosyncrasies.md) -page for chain-specific configuration considerations. +See the dedicated [Chain Idiosyncrasies](/reference/airnode/v0.12/chain-idiosyncrasies.md) page for chain-specific configuration considerations. ::: #### Considerations: Gas Price Oracle -The gas price oracle strategies are applied in the order that they are listed. -Airnode supports four strategies: `latestBlockPercentileGasPrice`, -`providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and -`constantGasPrice`. The only required strategy is `constantGasPrice` and it is -recommended to place it as the last strategy in the list as it should be the -final fallback for the Airnode to use if all other strategies fail. For more -detail on these strategies, see the -[Gas Price Strategies](/reference/airnode/v0.12/concepts/gas-prices.md) page. +The gas price oracle strategies are applied in the order that they are listed. Airnode supports four strategies: `latestBlockPercentileGasPrice`, `providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and `constantGasPrice`. The only required strategy is `constantGasPrice` and it is recommended to place it as the last strategy in the list as it should be the final fallback for the Airnode to use if all other strategies fail. For more detail on these strategies, see the [Gas Price Strategies](/reference/airnode/v0.12/concepts/gas-prices.md) page. #### Considerations: Concurrency -If you set the `maxConcurrency` field to value X, then Airnode will guarantee -that: +If you set the `maxConcurrency` field to value X, then Airnode will guarantee that: - At most X api calls are made to the API -- At most X transactions (made by blockchain providers) will be made by the - blockchain providers of the respective chain +- At most X transactions (made by blockchain providers) will be made by the blockchain providers of the respective chain -When doing this, Airnode will calculate the total number of requests reported by -all blockchain providers. If this number exceeds the maximum concurrency limit, -Airnode will start processing the oldest request from the blockchain providers -until the number of processed requests reaches the limit. All other requests are -dropped and will be processed in the next Airnode run. +When doing this, Airnode will calculate the total number of requests reported by all blockchain providers. If this number exceeds the maximum concurrency limit, Airnode will start processing the oldest request from the blockchain providers until the number of processed requests reaches the limit. All other requests are dropped and will be processed in the next Airnode run. Note that this request dropping happens for each **chain** separately. -For example, if `maxConcurrency` is set to 5 and there are three providers (A, B -and C) and they reported the following requests: +For example, if `maxConcurrency` is set to 5 and there are three providers (A, B and C) and they reported the following requests: - A1, A2, A3, A4 and A5 - B1, B2 and B3 @@ -173,17 +140,13 @@ The above example results in the following requests: A1, A2, B1, B2, and C1. ::: warning -Note, that this limit only applies to the requests initiated on chain. For -example, requests initiated using HTTP gateway are not included in this limit. -Also note that, this limit is configured per chain and the limits of different -chains are unrelated to each other. +Note, that this limit only applies to the requests initiated on chain. For example, requests initiated using HTTP gateway are not included in this limit. Also note that, this limit is configured per chain and the limits of different chains are unrelated to each other. ::: #### References: `chains` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [authorizers](/reference/airnode/v0.12/deployment-files/config-json.md#authorizers) - [id](/reference/airnode/v0.12/deployment-files/config-json.md#id) @@ -233,26 +196,15 @@ The `nodeSettings` field holds node-specific (Airnode) configuration parameters. #### Considerations: Cloud Providers -Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are -supported cloud providers for hosting Airnode. Note that while many fields -within `nodeSettings` are required by both, there are some cloud provider -specific fields. For example, `cloudProvider.projectId` is only required with -GCP. Also note that not all cloud provider regions can be deployed to; see the -[cloudProvider.region reference](/reference/airnode/v0.12/deployment-files/config-json.md#cloudprovider-region) -for more information. +Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are supported cloud providers for hosting Airnode. Note that while many fields within `nodeSettings` are required by both, there are some cloud provider specific fields. For example, `cloudProvider.projectId` is only required with GCP. Also note that not all cloud provider regions can be deployed to; see the [cloudProvider.region reference](/reference/airnode/v0.12/deployment-files/config-json.md#cloudprovider-region) for more information. #### Considerations: Gateways -Airnode offers two gateways for accessing provider HTTP endpoints without using -the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information -on each of these see the -[HTTP Gateways](/reference/airnode/v0.12/understand/http-gateways.md) -documentation. Also note that that distinct API keys must be used for each. +Airnode offers two gateways for accessing provider HTTP endpoints without using the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information on each of these see the [HTTP Gateways](/reference/airnode/v0.12/understand/http-gateways.md) documentation. Also note that that distinct API keys must be used for each. #### References: `nodeSettings` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [cloudProvider](/reference/airnode/v0.12/deployment-files/config-json.md#cloudprovider) - [cloudProvider.type](/reference/airnode/v0.12/deployment-files/config-json.md#cloudprovider-type) @@ -279,15 +231,9 @@ Files section: ### triggers -The `triggers` field allow exposes Airnode endpoints from an OIS selectively for -the RRP protocol or via the HTTP gateway. For example, an OIS object may include -10 endpoints, but only two are desired for RRP and all 10 for the gateway. +The `triggers` field allow exposes Airnode endpoints from an OIS selectively for the RRP protocol or via the HTTP gateway. For example, an OIS object may include 10 endpoints, but only two are desired for RRP and all 10 for the gateway. -List the endpoints to serve with the request–response protocol (RRP) under -`triggers.rrp`. List the endpoints to serve with the HTTP gateway under -`triggers.http`. List the endpoints which can be used to get the signed data in -`triggers.httpSignedData`. In most cases create a trigger for each endpoint in -your OIS object. +List the endpoints to serve with the request–response protocol (RRP) under `triggers.rrp`. List the endpoints to serve with the HTTP gateway under `triggers.http`. List the endpoints which can be used to get the signed data in `triggers.httpSignedData`. In most cases create a trigger for each endpoint in your OIS object. ```json "triggers": { @@ -318,65 +264,38 @@ your OIS object. #### Considerations: triggers -The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived -from the `oisTitle` and `endpointName` using the CLI command -[derive-endpoint-id](/reference/airnode/v0.12/packages/admin-cli.md#derive-endpoint-id). -Remember that an Airnode's config.json file can have more than one OIS object -and that these endpoints can be triggers for `rrp`, `http`, and/or -`httpSignedData` as desired. +The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived from the `oisTitle` and `endpointName` using the CLI command [derive-endpoint-id](/reference/airnode/v0.12/packages/admin-cli.md#derive-endpoint-id). Remember that an Airnode's config.json file can have more than one OIS object and that these endpoints can be triggers for `rrp`, `http`, and/or `httpSignedData` as desired. #### Considerations: cached responses -When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API -responses on the local filesystem per request ID. This only applies to -blockchain requests. The flow is: +When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API responses on the local filesystem per request ID. This only applies to blockchain requests. The flow is: 1. A request is received from the Blockchain. 1. The Airnode does an HTTP/S call to a remote API based on the request. -1. [with caching enabled] Airnode stores the response on the local filesystem by - request ID. -1. Airnode then follows the usual process of extracting the response, - post-processing it and sending the response back on chain as a fulfillment - callback. -1. After all current requests are processed, Airnode then exits until the next - cycle (the next minute). -1. If during the next cycle, if the Airnode gets the same request and it isn't - fulfilled, it will try and fulfill the request again. Ordinarily, without - caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with - caching enabled it will fulfill the response using the cached API response - value. - -Clearance of the local filesystem cache is dependant on the environment Airnode -runs in. As a guideline: +1. [with caching enabled] Airnode stores the response on the local filesystem by request ID. +1. Airnode then follows the usual process of extracting the response, post-processing it and sending the response back on chain as a fulfillment callback. +1. After all current requests are processed, Airnode then exits until the next cycle (the next minute). +1. If during the next cycle, if the Airnode gets the same request and it isn't fulfilled, it will try and fulfill the request again. Ordinarily, without caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with caching enabled it will fulfill the response using the cached API response value. + +Clearance of the local filesystem cache is dependant on the environment Airnode runs in. As a guideline: - AWS Lambda persists for 2.5 hours. - Google Cloud persistence is completely arbitrary. - Docker persists as long as the container remains running. -If the local filesystem is cleared, the cache is lost and if a repeat request is -received after the cache has been cleared, Airnode will repeat the API call. -Airnode self-clears cached data after the data has reached 1 hour's age. +If the local filesystem is cleared, the cache is lost and if a repeat request is received after the cache has been cleared, Airnode will repeat the API call. Airnode self-clears cached data after the data has reached 1 hour's age. -Furthermore, as an example: "if an Airnode AWS Lambda environment/container" -(since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours -and Airnode gets a request, that request will only be cached until the container -resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. +Furthermore, as an example: "if an Airnode AWS Lambda environment/container" (since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours and Airnode gets a request, that request will only be cached until the container resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. -As described above, caching on serverless infrastructure is unreliable and if -request caching is mission critical, Airnode should be run in a Docker container -with a persistent `/tmp` directory. +As described above, caching on serverless infrastructure is unreliable and if request caching is mission critical, Airnode should be run in a Docker container with a persistent `/tmp` directory. -Caching is useful for non-idempotent API operations like random number -generators. Consider the following use-case: +Caching is useful for non-idempotent API operations like random number generators. Consider the following use-case: -> Random Numbers: in the absence of caching, a malicious blockchain provider can -> selectively block fulfillments containing numbers they don't like, allowing -> them to improve their odds of winning in a random-number betting game. +> Random Numbers: in the absence of caching, a malicious blockchain provider can selectively block fulfillments containing numbers they don't like, allowing them to improve their odds of winning in a random-number betting game. #### References: `triggers` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [rrp](/reference/airnode/v0.12/deployment-files/config-json.md#rrp) - [rrp[n].endpointId](/reference/airnode/v0.12/deployment-files/config-json.md#rrp-n-endpointid) @@ -394,13 +313,11 @@ Files section: ### templates -The templates field allows you to specify templates to be used to make template -requests. The array can be left empty if no templates will be used. +The templates field allows you to specify templates to be used to make template requests. The array can be left empty if no templates will be used. #### References: templates -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [templateId](/reference/airnode/v0.12/deployment-files/config-json.md#templateid) - [endpointId](/reference/airnode/v0.12/deployment-files/config-json.md#endpointid) @@ -408,23 +325,11 @@ Files section: ### ois -The `ois` field is a list OIS objects that Airnode will be serving. This means -that a single instance of an Airnode can serve multiple APIs. You can simply -copy paste OIS objects that you will be serving into the `ois` list. Use the -previous guide -[API Integration](/reference/airnode/v0.12/understand/api-integration.md) to -create an OIS object. The full specification is available in the -[Oracle Integration Specifications (OIS)](/reference/ois/2.1/) documentation. +The `ois` field is a list OIS objects that Airnode will be serving. This means that a single instance of an Airnode can serve multiple APIs. You can simply copy paste OIS objects that you will be serving into the `ois` list. Use the previous guide [API Integration](/reference/airnode/v0.12/understand/api-integration.md) to create an OIS object. The full specification is available in the [Oracle Integration Specifications (OIS)](/reference/ois/2.1/) documentation. ### apiCredentials -Each entry in `apiCredentials` maps to a security scheme defined in an OIS -(`ois[n].components.securitySchemes.{securitySchemeName}` and -`ois[n].security`), where `oisTitle` is the `title` field of the related OIS, -and `securitySchemeName` is the name of the respective security scheme. These -would be `myOisTitle` and `mySecurityScheme` in the example below. -`securitySchemeValue` is the value used for the authentication with the security -scheme (e.g., the API key). +Each entry in `apiCredentials` maps to a security scheme defined in an OIS (`ois[n].components.securitySchemes.{securitySchemeName}` and `ois[n].security`), where `oisTitle` is the `title` field of the related OIS, and `securitySchemeName` is the name of the respective security scheme. These would be `myOisTitle` and `mySecurityScheme` in the example below. `securitySchemeValue` is the value used for the authentication with the security scheme (e.g., the API key). If no security scheme is needed, leave the `apiCredentials` array empty. @@ -461,14 +366,11 @@ If no security scheme is needed, leave the `apiCredentials` array empty. #### Considerations: apiCredentials -Currently Airnode supports the following security scheme types when making API -calls: `apiKey` and `http`. For more detail, visit the previous section on -[API Security](/reference/airnode/v0.12/understand/api-security.md). +Currently Airnode supports the following security scheme types when making API calls: `apiKey` and `http`. For more detail, visit the previous section on [API Security](/reference/airnode/v0.12/understand/api-security.md). #### References: `apiCredentials` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [oisTitle](/reference/airnode/v0.12/deployment-files/config-json.md#oistitle) - [securitySchemeName](/reference/airnode/v0.12/deployment-files/config-json.md#securityschemename) @@ -476,10 +378,7 @@ Files section: ## Creating `secrets.env` -The `secrets.env` file contains values (secrets) such as blockchain provider -urls, chain provider urls, etc. These secrets are embedded in -[config.json](/reference/airnode/v0.12/deployment-files/config-json.md) using -interpolation. +The `secrets.env` file contains values (secrets) such as blockchain provider urls, chain provider urls, etc. These secrets are embedded in [config.json](/reference/airnode/v0.12/deployment-files/config-json.md) using interpolation. ```json // Sample interpolation value from config.json @@ -493,25 +392,15 @@ interpolation. HEARTBEAT_API_KEY="d714a900-3b9e-4e4d-8eae-756ef06a8836" ``` -Use the -[secrets.env](/reference/airnode/v0.12/deployment-files/templates/secrets-env.md) -template and refer to -[Reference > Deployment Files > secrets.env](/reference/airnode/v0.12/deployment-files/secrets-env.md) -as needed. +Use the [secrets.env](/reference/airnode/v0.12/deployment-files/templates/secrets-env.md) template and refer to [Reference > Deployment Files > secrets.env](/reference/airnode/v0.12/deployment-files/secrets-env.md) as needed. ## AWS setup (AWS deployment only) -When it is time to deploy the Airnode to AWS, the Docker -[deployer image](/reference/airnode/v0.12/docker/deployer-image.md) will need -the AWS credentials to build the node on AWS Lambda. +When it is time to deploy the Airnode to AWS, the Docker [deployer image](/reference/airnode/v0.12/docker/deployer-image.md) will need the AWS credentials to build the node on AWS Lambda. ### Creating `aws.env` (AWS only) -Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It -explains how to create an IAM user and get security credentials. Put them in the -`aws.env` file as shown below. See an -[example file](/reference/airnode/v0.12/deployment-files/templates/aws-env.md) -in the reference section. +Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It explains how to create an IAM user and get security credentials. Put them in the `aws.env` file as shown below. See an [example file](/reference/airnode/v0.12/deployment-files/templates/aws-env.md) in the reference section. - Variable names cannot contain dashes (-) or start with a number. @@ -522,46 +411,26 @@ AWS_SECRET_ACCESS_KEY=ABC7...89 ## GCP setup (GCP deployment only) -When it is time to deploy the Airnode to GCP, the Docker -[deployer image](/reference/airnode/v0.12/docker/deployer-image.md) will need -the GCP project ID to build the Airnode. +When it is time to deploy the Airnode to GCP, the Docker [deployer image](/reference/airnode/v0.12/docker/deployer-image.md) will need the GCP project ID to build the Airnode. ### Creating a GCP project -First -[create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) -under which will the Airnode be deployed. Once the project is created, insert -its -[projectId](/reference/airnode/v0.12/deployment-files/config-json.md#cloudprovider) -into the `config.json` file. +First [create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) under which will the Airnode be deployed. Once the project is created, insert its [projectId](/reference/airnode/v0.12/deployment-files/config-json.md#cloudprovider) into the `config.json` file. ### Enable required API -In order for Airnode to deploy successfully, enable -[App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) -for the GCP project. After enabling it, wait a few minutes before the deployment -itself so the change will take place. +In order for Airnode to deploy successfully, enable [App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) for the GCP project. After enabling it, wait a few minutes before the deployment itself so the change will take place. ### Creating a Service Account -Create a new service account from the -[Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) -menu. Grant this service account access to the project by adding a role `Owner` -during the creation process. +Create a new service account from the [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) menu. Grant this service account access to the project by adding a role `Owner` during the creation process. -Once the account is created, add a new access key of type JSON for this account. -Download the key file as `gcp.json` into the root of your project. +Once the account is created, add a new access key of type JSON for this account. Download the key file as `gcp.json` into the root of your project. ## Summary -In this guide you created the `config.json`, `secrets.env` and obtained cloud -provider credentials required to deploy an Airnode to a cloud provider. Note -that `config.json` is user-specific and therefore it is not much use to others. +In this guide you created the `config.json`, `secrets.env` and obtained cloud provider credentials required to deploy an Airnode to a cloud provider. Note that `config.json` is user-specific and therefore it is not much use to others. -The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider -urls and security credentials, so they should be kept secret. Make sure that you -do not push your credentials to a repository or otherwise expose them as these -credentials can be used to gain access to your Airnode's private key, AWS -account or GCP account. +The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider urls and security credentials, so they should be kept secret. Make sure that you do not push your credentials to a repository or otherwise expose them as these credentials can be used to gain access to your Airnode's private key, AWS account or GCP account. diff --git a/docs/reference/airnode/v0.12/understand/deploying.md b/docs/reference/airnode/v0.12/understand/deploying.md index 768cc50b..cab6d669 100644 --- a/docs/reference/airnode/v0.12/understand/deploying.md +++ b/docs/reference/airnode/v0.12/understand/deploying.md @@ -19,49 +19,21 @@ tags: # {{$frontmatter.title}} -After integrating an API -([API Integration](/reference/airnode/v0.12/understand/api-integration.md)) and -creating the configuration files -([Configuring Airnode](/reference/airnode/v0.12/understand/configuring.md)), the -next step is to deploy the Airnode. +After integrating an API ([API Integration](/reference/airnode/v0.12/understand/api-integration.md)) and creating the configuration files ([Configuring Airnode](/reference/airnode/v0.12/understand/configuring.md)), the next step is to deploy the Airnode. ## Deploy with Docker -The recommended way to deploy Airnode is by using the Docker -[deployer image](/reference/airnode/v0.12/docker/deployer-image.md). This image -is simply a wrapper around the -[deployer CLI](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer). -Try the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -tutorial if you wish to become familiar with the deployer image first. There are -also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a -[client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as -well as several repo based examples in the -[Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.12.0/packages/airnode-examples) -package. - -The deployer interacts with a cloud provider to deploy Airnode programmatically, -without requiring you to click through a lot of ever-changing graphical -interfaces. For it to do so, a cloud project setup and credentials are required -and was discussed in -[Configuring an Airnode](/reference/airnode/v0.12/understand/configuring.md#aws-setup-aws-deployment-only). -There is additional guidance in the AWS and GCP quick start tutorials mentioned -above. +The recommended way to deploy Airnode is by using the Docker [deployer image](/reference/airnode/v0.12/docker/deployer-image.md). This image is simply a wrapper around the [deployer CLI](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-deployer). Try the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) tutorial if you wish to become familiar with the deployer image first. There are also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a [client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as well as several repo based examples in the [Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.12.0/packages/airnode-examples) package. + +The deployer interacts with a cloud provider to deploy Airnode programmatically, without requiring you to click through a lot of ever-changing graphical interfaces. For it to do so, a cloud project setup and credentials are required and was discussed in [Configuring an Airnode](/reference/airnode/v0.12/understand/configuring.md#aws-setup-aws-deployment-only). There is additional guidance in the AWS and GCP quick start tutorials mentioned above. ## Install Docker -The [deployer image](/reference/airnode/v0.12/docker/deployer-image.md) is -containerized as a Docker image. This will deploy the Airnode to the cloud -provider without the worry of installing dependencies and is the recommended way -to do a deployment. If you do not already have docker installed go to the -[Docker website](https://docs.docker.com/get-docker/) and install it. +The [deployer image](/reference/airnode/v0.12/docker/deployer-image.md) is containerized as a Docker image. This will deploy the Airnode to the cloud provider without the worry of installing dependencies and is the recommended way to do a deployment. If you do not already have docker installed go to the [Docker website](https://docs.docker.com/get-docker/) and install it. ## Deployment -At this point a project should resemble the following. The `config.json`, -`secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to -GCP) files should be ready to go. Other files and folders added to the project -are expected and are ignored by the deployer image. +At this point a project should resemble the following. The `config.json`, `secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to GCP) files should be ready to go. Other files and folders added to the project are expected and are ignored by the deployer image. ::: code-group @@ -84,13 +56,7 @@ my-airnode -From the root of the project directory run the Docker image command -[deploy](/reference/airnode/v0.12/docker/deployer-image.md#deploy) as shown -below to deploy the Airnode. When the deployment has completed a `receipt.json` -file will be written to the project directory, which is mounted to the -`/app/config` directory within the container. This file contains important -configuration information about the Airnode and is needed to remove the Airnode -should the need arise. +From the root of the project directory run the Docker image command [deploy](/reference/airnode/v0.12/docker/deployer-image.md#deploy) as shown below to deploy the Airnode. When the deployment has completed a `receipt.json` file will be written to the project directory, which is mounted to the `/app/config` directory within the container. This file contains important configuration information about the Airnode and is needed to remove the Airnode should the need arise.

@@ -114,10 +80,7 @@ docker run -it --rm ^ ### receipt.json -The `receipt.json` file is a product of a deployment attempt. It contains -Airnode configuration and deployment information and is used to remove the -Airnode. The field `success` is important in that it specifies whether the -deployment was successful or not. +The `receipt.json` file is a product of a deployment attempt. It contains Airnode configuration and deployment information and is used to remove the Airnode. The field `success` is important in that it specifies whether the deployment was successful or not. ```json { @@ -142,9 +105,7 @@ deployment was successful or not. ## Testing with HTTP Gateway -If you opted to enable the HTTP Gateway it can be used to test the Airnode while -bypassing the chain it was deployed to. There are examples that detail how to do -this. +If you opted to enable the HTTP Gateway it can be used to test the Airnode while bypassing the chain it was deployed to. There are examples that detail how to do this. - [HTTP Gateways](/reference/airnode/v0.12/understand/http-gateways.md#using-curl) - [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/#_5-test-the-airnode) @@ -153,15 +114,10 @@ this. ## Make an RRP request of the Airnode -Once the Airnode is deployed, see -[Calling an Airnode](/reference/airnode/v0.12/developers/index.md) to learn how -requests are made using the request-response protocol (RRP). +Once the Airnode is deployed, see [Calling an Airnode](/reference/airnode/v0.12/developers/index.md) to learn how requests are made using the request-response protocol (RRP). ## Removing the Airnode -If you would like to remove a deployed Airnode, see the Docker image commands -for [remove](/reference/airnode/v0.12/docker/deployer-image.md#remove) or -[remove-with-receipt](/reference/airnode/v0.12/docker/deployer-image.md#remove-with-receipt) -instructions. +If you would like to remove a deployed Airnode, see the Docker image commands for [remove](/reference/airnode/v0.12/docker/deployer-image.md#remove) or [remove-with-receipt](/reference/airnode/v0.12/docker/deployer-image.md#remove-with-receipt) instructions. diff --git a/docs/reference/airnode/v0.12/understand/heartbeat.md b/docs/reference/airnode/v0.12/understand/heartbeat.md index 5201c96f..81f47475 100644 --- a/docs/reference/airnode/v0.12/understand/heartbeat.md +++ b/docs/reference/airnode/v0.12/understand/heartbeat.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -At the end of an Airnode's run (every minute), Airnode can make an HTTP POST -request to a specified URL. This is both to signal that the Airnode is alive and -working (useful especially right after the deployment) and also as a -notification every time it runs (self-operates). +At the end of an Airnode's run (every minute), Airnode can make an HTTP POST request to a specified URL. This is both to signal that the Airnode is alive and working (useful especially right after the deployment) and also as a notification every time it runs (self-operates). > > @@ -31,8 +28,7 @@ notification every time it runs (self-operates). > 3.

A response is sent to each request.

> 4.

Finally Airnode makes a request to the heartbeat URL (HTTP POST). This could be to an operation within the API Airnode supports or to any cloud REST endpoint such as a monitoring service.

-Turn on the optional heartbeat functionality by setting all fields in the -`config.json` section for `nodeSettings.heartbeat`. +Turn on the optional heartbeat functionality by setting all fields in the `config.json` section for `nodeSettings.heartbeat`. ```json{12-16} { @@ -95,8 +91,7 @@ The table below illustrates the parameters passed to the Heartbeat URL. | oev_gateway_url | body | string | | signature | body | string | -Below is an example of what is included in the request body. Note that -`airnode-heartbeat-api-key` can be found in the request header and not the body. +Below is an example of what is included in the request body. Note that `airnode-heartbeat-api-key` can be found in the request header and not the body. ```json { @@ -117,18 +112,13 @@ Below is an example of what is included in the request body. Note that The method by which the heartbeat payload is generated is as follows: -- An object is marshalled to JSON - this object contains multiple fields as - shown above. -- The Airnode's mnemonic (using the default EVM derivation path to derive a key) - is used to sign the payload. +- An object is marshalled to JSON - this object contains multiple fields as shown above. +- The Airnode's mnemonic (using the default EVM derivation path to derive a key) is used to sign the payload. - The payload and signature are included in a new object and marshalled to JSON. -The reason this nested JSON approach has been used is to prevent subtle -inconsistencies between JSON marshallers in different languages causing the -signature to not match the payload. +The reason this nested JSON approach has been used is to prevent subtle inconsistencies between JSON marshallers in different languages causing the signature to not match the payload. -The airnode's public key can be recovered from this signature and be used, -generally, to verify the authenticity of the payload. +The airnode's public key can be recovered from this signature and be used, generally, to verify the authenticity of the payload. The overall content to the heartbeat URL is as follows: diff --git a/docs/reference/airnode/v0.12/understand/http-gateways.md b/docs/reference/airnode/v0.12/understand/http-gateways.md index 2caf6a84..bd61947d 100644 --- a/docs/reference/airnode/v0.12/understand/http-gateways.md +++ b/docs/reference/airnode/v0.12/understand/http-gateways.md @@ -19,36 +19,24 @@ tags: # {{$frontmatter.title}} -As part of the Airnode deployment you can decide to deploy two different HTTP -Gateways. +As part of the Airnode deployment you can decide to deploy two different HTTP Gateways. - HTTP Gateway: testing - HTTP Signed Data Gateway: production use ## Gateway Differences -Both gateways are setup identically. The differences are in their purpose and -response. +Both gateways are setup identically. The differences are in their purpose and response. > ### HTTP Gateway -The regular HTTP gateway is strictly for testing purposes. Using a simple tool -like CURL you can test that endpoints in the Airnode configuration are working -properly without accessing the blockchain. +The regular HTTP gateway is strictly for testing purposes. Using a simple tool like CURL you can test that endpoints in the Airnode configuration are working properly without accessing the blockchain. -In order to facilitate configuration and testing of parameters, HTTP gateway -requests have the following differences in handling when compared to blockchain -requests or requests to the HTTP signed data gateway: +In order to facilitate configuration and testing of parameters, HTTP gateway requests have the following differences in handling when compared to blockchain requests or requests to the HTTP signed data gateway: -1. When a request's API call is successful but then that response fails - extraction and encoding, data are still returned. This is in contrast to the - other types of requests for which only an error would be returned. The API - call response, after undergoing any - [post-processing](/reference/ois/2.1/processing.md), will be present in the - response body if encoding fails, and in the `rawValue` field if the encoding - is successful: +1. When a request's API call is successful but then that response fails extraction and encoding, data are still returned. This is in contrast to the other types of requests for which only an error would be returned. The API call response, after undergoing any [post-processing](/reference/ois/2.1/processing.md), will be present in the response body if encoding fails, and in the `rawValue` field if the encoding is successful: ```json { @@ -56,29 +44,19 @@ requests or requests to the HTTP signed data gateway: } ``` -2. Reserved parameters are inaccessible in response pre/post processing. This is - only relevant if reserved parameters are being _modified_ in pre/post - processing (advanced use case). +2. Reserved parameters are inaccessible in response pre/post processing. This is only relevant if reserved parameters are being _modified_ in pre/post processing (advanced use case). ### HTTP Signed Data Gateway -The HTTP signed data gateway is used for production purposes. While it is -executed in a similar way as the HTTP gateway, its response is signed and does -not contain a `rawValue` field. This gateway is executed by an off-chain code -source that may in turn push data to a blockchain. +The HTTP signed data gateway is used for production purposes. While it is executed in a similar way as the HTTP gateway, its response is signed and does not contain a `rawValue` field. This gateway is executed by an off-chain code source that may in turn push data to a blockchain. ## Setup -Enable either gateway in the `config.json` file fields -`nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. +Enable either gateway in the `config.json` file fields `nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. - **enabled**: A boolean to enable/disable the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless function instance serving gateway requests. When - omitted, there is no maximum concurrency set. This field is ignored for - Airnode client gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless function instance serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -102,10 +80,7 @@ Enable either gateway in the `config.json` file fields }, ``` -Add the desired endpoints a gateway can respond to in the `triggers.http[n]` -and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need -to match. It could be practical to test all endpoints but only serve certain -endpoints using the HTTP signed data gateway or via RRP. +Add the desired endpoints a gateway can respond to in the `triggers.http[n]` and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need to match. It could be practical to test all endpoints but only serve certain endpoints using the HTTP signed data gateway or via RRP. ```json // in config.json @@ -135,50 +110,28 @@ endpoints using the HTTP signed data gateway or via RRP. ## Gateway URLs -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URLs should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URLs should be kept secret. -The gateway URLs are also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/v0.12/understand/heartbeat.md) to a specified -heartbeat URL. +The gateway URLs are also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/v0.12/understand/heartbeat.md) to a specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated for each gateway (when enabled) when Airnode is -deployed. The URL including, the secret `UUID` path parameter, is displayed on -the terminal at the end of an Airnode deployment using the -[Docker image](/reference/airnode/v0.12/docker/deployer-image.md). +A gateway URL is generated for each gateway (when enabled) when Airnode is deployed. The URL including, the secret `UUID` path parameter, is displayed on the terminal at the end of an Airnode deployment using the [Docker image](/reference/airnode/v0.12/docker/deployer-image.md). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for both gateways, which is exposed on the host machine. -Doing so will make the gateways API accessible like a regular web server running -on the machine. Each gateway has a separate endpoint as shown below. Note the -`PORT` which is exposed as part of the Airnode client container. See the -[Airnode client usage](/reference/airnode/v0.12/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for both gateways, which is exposed on the host machine. Doing so will make the gateways API accessible like a regular web server running on the machine. Each gateway has a separate endpoint as shown below. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/v0.12/docker/client-image.md#usage) for more details. -- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Gateway -- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Signed Data Gateway +- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Gateway +- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Signed Data Gateway ## Using CURL -In order to execute an endpoint served by either gateway, the following are -required as part of the CURL call. +In order to execute an endpoint served by either gateway, the following are required as part of the CURL call. -- Make a POST request with the `endpointId` as a path parameter. An `endpointId` - can found in config.json under `triggers.http.endpointId` or - `triggers.httpSignedData.endpointId`. +- Make a POST request with the `endpointId` as a path parameter. An `endpointId` can found in config.json under `triggers.http.endpointId` or `triggers.httpSignedData.endpointId`. - Add the `Content-Type` header, set to `application/json`. - Place the parameters/encodedParameters in the request body. @@ -193,15 +146,11 @@ required as part of the CURL call. | \* parameters
HTTP Gateway
| body | `-d '{"parameters": {"param1": "myValue", "param2": 5}}'` | | \* encodedParameters
HTTP Signed Data Gateway
| body | `-d '{"encodedParameters": "0x3173737300....000"}'` | -\* Parameters for the gateways are named differently. The HTTP signed data -gateway requires that the `encodedParameters` be encoded using -[Airnode ABI](/reference/airnode/v0.12/specifications/airnode-abi.md). +\* Parameters for the gateways are named differently. The HTTP signed data gateway requires that the `encodedParameters` be encoded using [Airnode ABI](/reference/airnode/v0.12/specifications/airnode-abi.md). ### Request -Replace `` in the examples below with the URL displayed in the -terminal at the end of an Airnode deployment using a -[Docker image](/reference/airnode/v0.12/docker/). +Replace `` in the examples below with the URL displayed in the terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/v0.12/docker/). ::: code-group diff --git a/docs/reference/airnode/v0.12/understand/index.md b/docs/reference/airnode/v0.12/understand/index.md index 550c9f6c..f87c05c3 100644 --- a/docs/reference/airnode/v0.12/understand/index.md +++ b/docs/reference/airnode/v0.12/understand/index.md @@ -19,17 +19,11 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that pushes off-chain API data on-chain via data -feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs -off-chain as a background component of the API3 ecosystem. **Understanding -Airnode** is a progression of pages that provides a detailed understanding of -the capabilities and functionality of Airnode. +Airnode is a first-party oracle that pushes off-chain API data on-chain via data feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs off-chain as a background component of the API3 ecosystem. **Understanding Airnode** is a progression of pages that provides a detailed understanding of the capabilities and functionality of Airnode. ## Project Folder -A typical Airnode project folder contains files used to define the Airnode. Show -below are typical project folders for each of AWS, GCP, and container -deployments. +A typical Airnode project folder contains files used to define the Airnode. Show below are typical project folders for each of AWS, GCP, and container deployments. ::: code-group @@ -55,12 +49,7 @@ my-airnode ::: code-group -Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the -files in the -[Templates](/reference/airnode/v0.12/deployment-files/templates/config-json.md) -as an aid to create all but the `gcp.json` files. Also see the -[Examples](/reference/airnode/v0.12/deployment-files/examples/config-json.md) -for demonstration purposes. +Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the files in the [Templates](/reference/airnode/v0.12/deployment-files/templates/config-json.md) as an aid to create all but the `gcp.json` files. Also see the [Examples](/reference/airnode/v0.12/deployment-files/examples/config-json.md) for demonstration purposes. ## Configuration files @@ -69,57 +58,40 @@ for demonstration purposes. - `aws.env`: AWS credentials. - `gcp.json`: GCP project information. -The diagrams below depict the configuration files needed for a successful -deployment of an Airnode to AWS, GCP, and a Docker Container. +The diagrams below depict the configuration files needed for a successful deployment of an Airnode to AWS, GCP, and a Docker Container. ### AWS -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **aws.env**: Contains AWS credentials required by the Docker deployer image. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### GCP -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **gcp.json**: GCP project file. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### Container -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. -3. **client image**: The Docker client image that contains the Airnode and runs - with the provided configuration. +3. **client image**: The Docker client image that contains the Airnode and runs with the provided configuration. ## Deploying -There are two ways to deploy and run an Airnode. The most popular is with a -cloud provider such as AWS or GCP. Use the Docker -[Airnode Deployer Image](/reference/airnode/v0.12/docker/deployer-image.md) for -these type of deployments. - -The second method is to run a containerized Airnode hosted internally or with a -cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker -[Airnode Client Image](/reference/airnode/v0.12/docker/client-image.md) for this -type of deployment. - -Try the guide AWS -[Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) -as a quick introduction to an Airnode deployment. Also be sure to visit -[ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an -Airnode. +There are two ways to deploy and run an Airnode. The most popular is with a cloud provider such as AWS or GCP. Use the Docker [Airnode Deployer Image](/reference/airnode/v0.12/docker/deployer-image.md) for these type of deployments. + +The second method is to run a containerized Airnode hosted internally or with a cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker [Airnode Client Image](/reference/airnode/v0.12/docker/client-image.md) for this type of deployment. + +Try the guide AWS [Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) as a quick introduction to an Airnode deployment. Also be sure to visit [ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an Airnode. diff --git a/docs/reference/airnode/v0.12/understand/monitor.md b/docs/reference/airnode/v0.12/understand/monitor.md index aaf6cd85..3fd84b3c 100644 --- a/docs/reference/airnode/v0.12/understand/monitor.md +++ b/docs/reference/airnode/v0.12/understand/monitor.md @@ -19,43 +19,24 @@ tags: # {{$frontmatter.title}} -Airnode logs or log groups are named similarly in AWS and GCP and include the -following hyphen-separated components: `airnode`, ``, -``, and ``, for example, -`airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages -or request types and the logs they contain are as follows: - -- `startCoordinator`: Logs for chain provider initialization and request - fetching +Airnode logs or log groups are named similarly in AWS and GCP and include the following hyphen-separated components: `airnode`, ``, ``, and ``, for example, `airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages or request types and the logs they contain are as follows: + +- `startCoordinator`: Logs for chain provider initialization and request fetching - `run`: Logs of API calls and withdrawals originating from blockchain requests -- `httpReq`: Logs for - [HTTP gateway requests](/reference/airnode/v0.12/understand/http-gateways.md#http-gateway) -- `httpSignedReq`: Logs for - [HTTP signed data gateway requests](/reference/airnode/v0.12/understand/http-gateways.md) -- `signOevReq`: Logs for - [OEV gateway requests](/reference/airnode/v0.12/understand/oev-gateway.md) +- `httpReq`: Logs for [HTTP gateway requests](/reference/airnode/v0.12/understand/http-gateways.md#http-gateway) +- `httpSignedReq`: Logs for [HTTP signed data gateway requests](/reference/airnode/v0.12/understand/http-gateways.md) +- `signOevReq`: Logs for [OEV gateway requests](/reference/airnode/v0.12/understand/oev-gateway.md) ### AWS -Airnode logs are available in -[CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. -Note that for the HTTP gateways, AWS generates a unique `requestId` for each -request. These should not be confused with the `requestId` of a request -originating from a blockchain. +Airnode logs are available in [CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. Note that for the HTTP gateways, AWS generates a unique `requestId` for each request. These should not be confused with the `requestId` of a request originating from a blockchain. ### GCP -Airnode logs are available in the -[Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to -query or stream logs by the "Cloud Function" Resource Type and then by "Function -Name" in order to view a specific request type or Airnode cycle stage. +Airnode logs are available in the [Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to query or stream logs by the "Cloud Function" Resource Type and then by "Function Name" in order to view a specific request type or Airnode cycle stage. ## Local Airnode Client -Running the `airnode-client` Docker image will output container logs to the -command line. These logs are also available through the Docker interface e.g. -under Containers within Docker Desktop. See the Docker -[client image](/reference/airnode/v0.12/docker/client-image.md) for more -information. +Running the `airnode-client` Docker image will output container logs to the command line. These logs are also available through the Docker interface e.g. under Containers within Docker Desktop. See the Docker [client image](/reference/airnode/v0.12/docker/client-image.md) for more information. diff --git a/docs/reference/airnode/v0.12/understand/oev-gateway.md b/docs/reference/airnode/v0.12/understand/oev-gateway.md index 5da00b8c..6ee6cc0f 100644 --- a/docs/reference/airnode/v0.12/understand/oev-gateway.md +++ b/docs/reference/airnode/v0.12/understand/oev-gateway.md @@ -19,23 +19,15 @@ tags: # {{$frontmatter.title}} -OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The -data is signed by the Airnode so that only the searcher who won the auction can -use it to update the data feed. You can learn more about OEV at -https://api3.org. +OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The data is signed by the Airnode so that only the searcher who won the auction can use it to update the data feed. You can learn more about OEV at https://api3.org. ## Setup -Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` -section. +Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` section. - **enabled**: A boolean to enable/disable for the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless functions serving gateway requests. When omitted, - there is no maximum concurrency set. This field is ignored for Airnode client - gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless functions serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -56,44 +48,25 @@ section. ## Gateway URL -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URL should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URL should be kept secret. -The gateway URL is also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/v0.12/understand/heartbeat.md) to your specified -heartbeat URL. +The gateway URL is also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/v0.12/understand/heartbeat.md) to your specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated when Airnode is deployed. You can see the URLs -including the secret `UUID` path parameter, displayed on your terminal at the -end of an Airnode deployment using a -[Docker image](/reference/airnode/v0.12/docker/). +A gateway URL is generated when Airnode is deployed. You can see the URLs including the secret `UUID` path parameter, displayed on your terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/v0.12/docker/). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for the gateway, which is exposed on the host machine. -Doing so will make the gateway API accessible like a regular web server running -on the machine. Note the `PORT` which is exposed as part of the Airnode client -container. See the -[Airnode client usage](/reference/airnode/v0.12/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for the gateway, which is exposed on the host machine. Doing so will make the gateway API accessible like a regular web server running on the machine. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/v0.12/docker/client-image.md#usage) for more details. -- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - - Gateway URL for the OEV Gateway +- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - Gateway URL for the OEV Gateway ## Usage -In order to execute the processing on the gateway, it needs to receive a -properly constructed HTTP request: +In order to execute the processing on the gateway, it needs to receive a properly constructed HTTP request: - It must be a `POST` request - It must contain a `Content-Type` header, set to `application/json`. @@ -136,8 +109,7 @@ where: - `updateId` - Auction update ID. - `bidderAddress` - Blockchain address of the winning searcher. - `bidAmount` - Bid amount that won the auction. -- `beacons` - A list of beacon data to be signed. It can contain two types: full - beacon data, only beacon metadata +- `beacons` - A list of beacon data to be signed. It can contain two types: full beacon data, only beacon metadata - `airnodeAddress` - Airnode address identifying a beacon - `endpointId` - Endpoint ID identifying a beacon - `encodedParameters` - Parameters in their encoded form identifying a beacon @@ -181,8 +153,6 @@ curl --location '' \ ] ``` -The gateway will return a list of signatures. There is a signature for each -beacon within the data feed that is served by the given Airnode, returned in the -same order as they are specified in the request body. +The gateway will return a list of signatures. There is a signature for each beacon within the data feed that is served by the given Airnode, returned in the same order as they are specified in the request body. diff --git a/docs/reference/airnode/v0.12/understand/using-authorizations.md b/docs/reference/airnode/v0.12/understand/using-authorizations.md index fa730bb9..f1b09d84 100644 --- a/docs/reference/airnode/v0.12/understand/using-authorizations.md +++ b/docs/reference/airnode/v0.12/understand/using-authorizations.md @@ -19,39 +19,22 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using -[Authorizations](/reference/airnode/v0.12/concepts/authorizations.md). This -method is off-chain and requires no blockchain knowledge by an API provider. It -is different than -[Authorizers](/reference/airnode/v0.12/concepts/authorizers.md) which is an -on-chain auth scheme. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizations](/reference/airnode/v0.12/concepts/authorizations.md). This method is off-chain and requires no blockchain knowledge by an API provider. It is different than [Authorizers](/reference/airnode/v0.12/concepts/authorizers.md) which is an on-chain auth scheme. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/v0.12/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: -Authorizations use scheme types that hard-code access to an Airnode's endpoints -in the same file that defines the Airnode, its `config.json` file. These -hard-coded values are endpointId/address pairs that the Airnode will use to -allow access to its endpoints by requesters (smart contracts). +Authorizations use scheme types that hard-code access to an Airnode's endpoints in the same file that defines the Airnode, its `config.json` file. These hard-coded values are endpointId/address pairs that the Airnode will use to allow access to its endpoints by requesters (smart contracts). -Nothing in _authorizers_ can supersede permissions granted by _authorizations_ -as the latter takes precedence. -Currently there is only one _authorizations_ scheme type, -`requesterEndpointAuthorizations`. +Nothing in _authorizers_ can supersede permissions granted by _authorizations_ as the latter takes precedence. +Currently there is only one _authorizations_ scheme type, `requesterEndpointAuthorizations`. ## requesterEndpointAuthorizations -Currently `requesterEndpointAuthorizations` is the only scheme type available -for _authorizations_. It defines a list of endpointIds each with a array of -requester addresses that can access them. +Currently `requesterEndpointAuthorizations` is the only scheme type available for _authorizations_. It defines a list of endpointIds each with a array of requester addresses that can access them. ```json { diff --git a/docs/reference/airnode/v0.12/versions.md b/docs/reference/airnode/v0.12/versions.md index 4c815182..be4bc831 100644 --- a/docs/reference/airnode/v0.12/versions.md +++ b/docs/reference/airnode/v0.12/versions.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -The latest version of Airnode is `v0.12.x`. See -[releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for -all Airnode versions. Below is a list of Airnode versions included in this -documentation website. +The latest version of Airnode is `v0.12.x`. See [releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for all Airnode versions. Below is a list of Airnode versions included in this documentation website. | | | ----------------------------------------------- | @@ -31,9 +28,7 @@ documentation website. ## Other Versions -Prior to version `v0.12.x` there are several `v0.x` versions of Airnode. Their -documentation is available at -[https://old-docs.api3.org](https://old-docs.api3.org). +Prior to version `v0.12.x` there are several `v0.x` versions of Airnode. Their documentation is available at [https://old-docs.api3.org](https://old-docs.api3.org). | | | --------------------------------------------------------- | diff --git a/docs/reference/airnode/v0.13/chain-idiosyncrasies.md b/docs/reference/airnode/v0.13/chain-idiosyncrasies.md index d6b9c43d..456382b0 100644 --- a/docs/reference/airnode/v0.13/chain-idiosyncrasies.md +++ b/docs/reference/airnode/v0.13/chain-idiosyncrasies.md @@ -19,60 +19,28 @@ tags: # {{$frontmatter.title}} -Differences in chain design inevitably lead to some unique chain-specific -considerations. Below are idiosyncrasies we have identified, though it may not -be comprehensive and we are interested in hearing if you encounter others. +Differences in chain design inevitably lead to some unique chain-specific considerations. Below are idiosyncrasies we have identified, though it may not be comprehensive and we are interested in hearing if you encounter others. ## config.json - `chains` field -The idiosyncrasies below relate to the `chains` field of `config.json` discussed -in -[Configuring Airnode](/reference/airnode/v0.13/understand/configuring.md#chains) -and -[Deployment Files](/reference/airnode/v0.13/deployment-files/config-json.md#chains) -section. +The idiosyncrasies below relate to the `chains` field of `config.json` discussed in [Configuring Airnode](/reference/airnode/v0.13/understand/configuring.md#chains) and [Deployment Files](/reference/airnode/v0.13/deployment-files/config-json.md#chains) section. ### Avalanche -Gas prices on Avalanche mainnet are often underestimated when getting `type 0` -estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error -manifests as the `maxFeePerGas` being set to less than the block -`baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set -`recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. +Gas prices on Avalanche mainnet are often underestimated when getting `type 0` estimates (e.g. for the `providerRecommendedGasPrice` strategy). The error manifests as the `maxFeePerGas` being set to less than the block `baseFeePerGas`, resulting in unfulfilled requests. A solution to this is to set `recommendedGasPriceMultiplier` to slightly greater than `1` e.g. `1.1`. ### Arbitrum -Execution costs on Arbitrum are calculated slightly differently than Ethereum, -which impacts the gas required to fulfill requests. To account for this, it is -recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when -using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is -optional, so if it is not specified, Airnode will attempt to estimate the -appropriate gas limit automatically. Read more about -[ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. +Execution costs on Arbitrum are calculated slightly differently than Ethereum, which impacts the gas required to fulfill requests. To account for this, it is recommended to use a minimum value of `5000000` for `fulfillmentGasLimit` when using both Arbitrum mainnet and testnet. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. Read more about [ArbGas](https://developer.offchainlabs.com/docs/arbgas) gas and fees. ### Metis -On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is -recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that -`fulfillmentGasLimit` is optional, so if it is not specified, Airnode will -attempt to estimate the appropriate gas limit automatically. +On the Metis testnet Stardust, though not on the Metis mainnet Andromeda, it is recommended to use a `fulfillmentGasLimit` of at least `5000000`. Note that `fulfillmentGasLimit` is optional, so if it is not specified, Airnode will attempt to estimate the appropriate gas limit automatically. ### Optimism -Using `type 0` transaction types is recommended over `type 2` so the use of -`providerRecommendedEip1559GasPrice` is discouraged. - -As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, -which are -[accounted for separately](https://docs.optimism.io/stack/transactions/fees). To -cover the L1 data fee when a sponsor requests a -[withdrawal](/reference/airnode/v0.13/concepts/sponsor.md#withdrawals), an -amount has to be subtracted from the funds returned to the sponsor. The -`withdrawalRemainder` parameter has been introduced specifically for this -reason, though the value required will differ between Optimism mainnet and -testnet due to differences in L1 gas fees. For Optimism testnet, a -`withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a -value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover -an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. +Using `type 0` transaction types is recommended over `type 2` so the use of `providerRecommendedEip1559GasPrice` is discouraged. + +As a L2 scaling solution, Optimism has an L1 data fee and an L2 execution fee, which are [accounted for separately](https://docs.optimism.io/stack/transactions/fees). To cover the L1 data fee when a sponsor requests a [withdrawal](/reference/airnode/v0.13/concepts/sponsor.md#withdrawals), an amount has to be subtracted from the funds returned to the sponsor. The `withdrawalRemainder` parameter has been introduced specifically for this reason, though the value required will differ between Optimism mainnet and testnet due to differences in L1 gas fees. For Optimism testnet, a `withdrawalRemainder` of `1 gwei` should suffice, while for Optimism mainnet, a value as high as `2.4 finney` (`2400000 gwei`) may be required in order to cover an L1 gas price of `300 gwei` and `8000` L1 gas used by the transaction. diff --git a/docs/reference/airnode/v0.13/cloud-resources.md b/docs/reference/airnode/v0.13/cloud-resources.md index 998e1377..692c9599 100644 --- a/docs/reference/airnode/v0.13/cloud-resources.md +++ b/docs/reference/airnode/v0.13/cloud-resources.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain -resources to fully operate and supports most regions. +When deployed to a cloud provider, such as AWS or GCP, Airnode uses certain resources to fully operate and supports most regions. ## Resources diff --git a/docs/reference/airnode/v0.13/concepts/airnode-auth.md b/docs/reference/airnode/v0.13/concepts/airnode-auth.md index a8c2afd5..2562b04a 100644 --- a/docs/reference/airnode/v0.13/concepts/airnode-auth.md +++ b/docs/reference/airnode/v0.13/concepts/airnode-auth.md @@ -19,40 +19,24 @@ tags: # {{$frontmatter.title}} -API providers can instruct Airnode to authenticate requests to their endpoints. -This is done by setting up a security scheme in the config.json file for their -Airnode. Airnode supports three methods of authentication from the OpenAPI -specification. +API providers can instruct Airnode to authenticate requests to their endpoints. This is done by setting up a security scheme in the config.json file for their Airnode. Airnode supports three methods of authentication from the OpenAPI specification. > -[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) -uses the term **security scheme** for authentication and authorization schemes. -Airnode only uses standard OAS defined authentication schemes to identify itself -to API endpoints. Airnode supports two types of authentication, `http` and -`apiKey`. +[OAS OpenAPI Specification](https://swagger.io/docs/specification/authentication/) uses the term **security scheme** for authentication and authorization schemes. Airnode only uses standard OAS defined authentication schemes to identify itself to API endpoints. Airnode supports two types of authentication, `http` and `apiKey`. -- HTTP authentication schemes (using the `Authorization` header) supported by - Airnode: +- HTTP authentication schemes (using the `Authorization` header) supported by Airnode: - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) - [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) -- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in - the request header, cookie in header or query string +- [API key](https://swagger.io/docs/specification/authentication/api-keys/) in the request header, cookie in header or query string -How Airnode sends the authentication data is explained in the sections **Basic, -Bearer and API Key** below. +How Airnode sends the authentication data is explained in the sections **Basic, Bearer and API Key** below. ## Basic -Basic authentication is a simple authentication scheme built into the HTTP -protocol. The Authorization request header contains the Base64-encoded username -and password, separated by a colon. When handling the request, the server -decodes the login details and checks if the user can access the requested -content. +Basic authentication is a simple authentication scheme built into the HTTP protocol. The Authorization request header contains the Base64-encoded username and password, separated by a colon. When handling the request, the server decodes the login details and checks if the user can access the requested content. -The header field is in the form of `Authorization: Basic ` where -`credentials` is the Base64 encoding of a username and password joined by a -single colon (`airnode:airnode-password`). +The header field is in the form of `Authorization: Basic ` where `credentials` is the Base64 encoding of a username and password joined by a single colon (`airnode:airnode-password`). `Authorization: Basic ` @@ -63,10 +47,7 @@ curl -H "Authorization: Basic YW5kZXJzb25AZ21haWwuY29tOjEyM215cGFzc3dvcmQ=" \ ## Bearer -Bearer authentication (also called token authentication) is an HTTP -authentication scheme that involves security tokens called bearer tokens. The -API provider supplies a token used by Airnode to authenticate itself to API -endpoints. +Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The API provider supplies a token used by Airnode to authenticate itself to API endpoints. The header field is in the form of `Authorization: Bearer `. @@ -77,9 +58,7 @@ curl -H "Authorization: Bearer RZ8Y65TG" \ ## API Key -Some APIs use an `apiKey` for authentication. The API provider supplies an -`apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can -send the `apiKey` three ways. +Some APIs use an `apiKey` for authentication. The API provider supplies an `apiKey` used by Airnode to authenticate itself to API endpoints. Airnode can send the `apiKey` three ways. ```sh # In the query string. diff --git a/docs/reference/airnode/v0.13/concepts/airnode.md b/docs/reference/airnode/v0.13/concepts/airnode.md index b04cbc7d..8cec33ec 100644 --- a/docs/reference/airnode/v0.13/concepts/airnode.md +++ b/docs/reference/airnode/v0.13/concepts/airnode.md @@ -19,37 +19,17 @@ tags: # {{$frontmatter.title}} -Airnode is a serverless oracle node implemented with a "set and forget" -philosophy. Airnode is flexible in that it can move API provider data on-chain -for multiple purposes. The most important of which are data feeds -([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in -response to dApp direct requests for API provider data -([RRP](/reference/airnode/v0.13/developers/)). +Airnode is a serverless oracle node implemented with a "set and forget" philosophy. Airnode is flexible in that it can move API provider data on-chain for multiple purposes. The most important of which are data feeds ([dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/)) and also in response to dApp direct requests for API provider data ([RRP](/reference/airnode/v0.13/developers/)). ## Airnode sources data to dAPIs -An Airnode supplies API provider data to beacons from API providers. These -beacons are the underlying data source for data feeds known as dAPIs. +An Airnode supplies API provider data to beacons from API providers. These beacons are the underlying data source for data feeds known as dAPIs. -API providers, owners of first-party Airnodes, store data feed values on-chain -as individual beacons that in are turn sourced by the -[Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) -contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). -Airnode has an internal mechanism that looks for a deviation in the value of API -provider's API operations. This mechanism updates beacons on-chain as needed. +API providers, owners of first-party Airnodes, store data feed values on-chain as individual beacons that in are turn sourced by the [Api3ServerV1.sol](https://github.com/api3dao/airnode-protocol-v1/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) contract as [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/). Airnode has an internal mechanism that looks for a deviation in the value of API provider's API operations. This mechanism updates beacons on-chain as needed. ## Airnode processes RRP requests -An Airnode is capable of serving the data from one or more APIs directly to -[requesters](/reference/airnode/v0.13/concepts/requester.md) (which are on-chain -smart contracts) that request data served by a particular Airnode. This is done -using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 -protocol is designed to be flexible and is meant to serve a variety of use -cases. See the the -[Calling Airnode (RRP)](/reference/airnode/v0.13/developers/index.md) for more -details on how an RRP request is made. Also see the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/contracts) -for potential design patterns. +An Airnode is capable of serving the data from one or more APIs directly to [requesters](/reference/airnode/v0.13/concepts/requester.md) (which are on-chain smart contracts) that request data served by a particular Airnode. This is done using the request-response protocol (RRP) mechanism of Airnode. The AirnodeRrpV0 protocol is designed to be flexible and is meant to serve a variety of use cases. See the the [Calling Airnode (RRP)](/reference/airnode/v0.13/developers/index.md) for more details on how an RRP request is made. Also see the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/contracts) for potential design patterns. diff --git a/docs/reference/airnode/v0.13/deployment-files/templates/aws-env.md b/docs/reference/airnode/v0.13/deployment-files/templates/aws-env.md index 1f642114..0badb741 100644 --- a/docs/reference/airnode/v0.13/deployment-files/templates/aws-env.md +++ b/docs/reference/airnode/v0.13/deployment-files/templates/aws-env.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -The `aws.env` contains AWS credentials from an IAM user. These credentials are -used by the Docker -[deployer image](/reference/airnode/v0.13/docker/deployer-image.md) to deploy an -Airnode to AWS. For more details, see the full description of the -[aws.env](/reference/airnode/v0.13/deployment-files/templates/aws-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `aws.env` contains AWS credentials from an IAM user. These credentials are used by the Docker [deployer image](/reference/airnode/v0.13/docker/deployer-image.md) to deploy an Airnode to AWS. For more details, see the full description of the [aws.env](/reference/airnode/v0.13/deployment-files/templates/aws-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AWS_ACCESS_KEY_ID= diff --git a/docs/reference/airnode/v0.13/deployment-files/templates/config-json.md b/docs/reference/airnode/v0.13/deployment-files/templates/config-json.md index d0bc9c62..bedbfef1 100644 --- a/docs/reference/airnode/v0.13/deployment-files/templates/config-json.md +++ b/docs/reference/airnode/v0.13/deployment-files/templates/config-json.md @@ -19,33 +19,23 @@ tags: # {{$frontmatter.title}} -A template for an Airnode's configuration file. Below are notations to help -explain contents of the template. +A template for an Airnode's configuration file. Below are notations to help explain contents of the template. -- `, , `: The value added is independent from - other fields and a value is needed unless otherwise indicated. These values - are not considered secret unless you want them to be. +- `, , `: The value added is independent from other fields and a value is needed unless otherwise indicated. These values are not considered secret unless you want them to be. -- ``: If two fields contain the same - expression, use the same value in them because they are referencing each - other. Usually these are not considered to be secret. +- ``: If two fields contain the same expression, use the same value in them because they are referencing each other. Usually these are not considered to be secret. -- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to - `secrets.env` though it is not required. +- `${CHAIN_PROVIDER_URL}`: Interpolated values ${} that should be added to `secrets.env` though it is not required. Consider the following relationships. - `ois[0].title` is related to `triggers.rrp[0].oisTitle`. -- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to - ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[0].in` is related to ois[0].endpoints[0].fixedOperationParameters[0].operationParameter.in -- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to - ois[0].endpoints[0].parameters[0].operationParameter.in +- `ois[0].apiSpecifications.paths[path][method].parameters[1].in` is related to ois[0].endpoints[0].parameters[0].operationParameter.in -See -[config.json](/reference/airnode/v0.13/deployment-files/templates/config-json.md) -as a reference while building a config.json file. +See [config.json](/reference/airnode/v0.13/deployment-files/templates/config-json.md) as a reference while building a config.json file. ```json { diff --git a/docs/reference/airnode/v0.13/deployment-files/templates/ois-json.md b/docs/reference/airnode/v0.13/deployment-files/templates/ois-json.md index 3af512ac..2059582c 100644 --- a/docs/reference/airnode/v0.13/deployment-files/templates/ois-json.md +++ b/docs/reference/airnode/v0.13/deployment-files/templates/ois-json.md @@ -19,11 +19,6 @@ tags: # {{$frontmatter.title}} -An [OIS (Oracle Integration Specifications)](/reference/ois/2.2/) JSON object is -part of an Airnode's -[config.json](/reference/airnode/v0.13/deployment-files/templates/config-json.md) -file. There can be more than one OIS object in the `config.json` file that -defines an Airnode. See the [OIS Template](/reference/ois/2.2/template.md) in -the OIS document set. +An [OIS (Oracle Integration Specifications)](/reference/ois/2.2/) JSON object is part of an Airnode's [config.json](/reference/airnode/v0.13/deployment-files/templates/config-json.md) file. There can be more than one OIS object in the `config.json` file that defines an Airnode. See the [OIS Template](/reference/ois/2.2/template.md) in the OIS document set. diff --git a/docs/reference/airnode/v0.13/deployment-files/templates/secrets-env.md b/docs/reference/airnode/v0.13/deployment-files/templates/secrets-env.md index 176bb50c..80f17f3f 100644 --- a/docs/reference/airnode/v0.13/deployment-files/templates/secrets-env.md +++ b/docs/reference/airnode/v0.13/deployment-files/templates/secrets-env.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The `secrets.env` contains the secrets that the respective Airnode deployments -will need. All variables defined in a `secrets.env` can be interpolated inside -`config.json`. For more details, see the full description of the -[secrets.env](/reference/airnode/v0.13/deployment-files/secrets-env.md) file. -Variable names cannot contain dashes (-) or start with a number. +The `secrets.env` contains the secrets that the respective Airnode deployments will need. All variables defined in a `secrets.env` can be interpolated inside `config.json`. For more details, see the full description of the [secrets.env](/reference/airnode/v0.13/deployment-files/secrets-env.md) file. Variable names cannot contain dashes (-) or start with a number. ```sh AIRNODE_WALLET_MNEMONIC="" diff --git a/docs/reference/airnode/v0.13/developers/fees.md b/docs/reference/airnode/v0.13/developers/fees.md index 76061f25..d4bc9a74 100644 --- a/docs/reference/airnode/v0.13/developers/fees.md +++ b/docs/reference/airnode/v0.13/developers/fees.md @@ -19,18 +19,11 @@ tags: # {{$frontmatter.title}} -There are some one-time setup/maintenance costs and some ongoing costs of -calling an Airnode. The Airnode protocol is designed in a way that the requester -assumes all gas costs, including the request fulfillment (response) -transactions. +There are some one-time setup/maintenance costs and some ongoing costs of calling an Airnode. The Airnode protocol is designed in a way that the requester assumes all gas costs, including the request fulfillment (response) transactions. ## Sponsors -Fees are encountered when a sponsor engages in setup activity such as sponsoring -a requester. These are per call transaction gas costs and are relatively small. -The funds come from the wallet mnemonic that the sponsor supplies when calling -certain [admin commands](/reference/airnode/v0.13/packages/admin-cli.md) as -shown below. +Fees are encountered when a sponsor engages in setup activity such as sponsoring a requester. These are per call transaction gas costs and are relatively small. The funds come from the wallet mnemonic that the sponsor supplies when calling certain [admin commands](/reference/airnode/v0.13/packages/admin-cli.md) as shown below. - [sponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#unsponsor-requester) @@ -39,32 +32,18 @@ shown below. ## Airnodes -The fees take the form of transaction gas costs. These are applied when funding -a requester's sponsor wallet for an Airnode and when executing the Airnode in -response to a request. +The fees take the form of transaction gas costs. These are applied when funding a requester's sponsor wallet for an Airnode and when executing the Airnode in response to a request. -- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is - funded manually by a sponsor using their preferred wallet management tool such - as MetaMask. +- Funding a sponsor wallet associated with an Airnode: A sponsor wallet is funded manually by a sponsor using their preferred wallet management tool such as MetaMask. -- [Calling](/reference/airnode/v0.13/developers/index.md) an Airnode: - Transaction gas fees are withdrawn from the sponsor wallet related to the - Airnode being called by a sponsored requester. +- [Calling](/reference/airnode/v0.13/developers/index.md) an Airnode: Transaction gas fees are withdrawn from the sponsor wallet related to the Airnode being called by a sponsored requester. -Learn more about [sponsor wallets](/reference/airnode/v0.13/concepts/sponsor.md) -in the reference section. +Learn more about [sponsor wallets](/reference/airnode/v0.13/concepts/sponsor.md) in the reference section. ## API Provider Fees -Some API providers charge a subscription fee for access to their data. This is a -typical practice and usually requires the requester to create an account on the -provider's website and then subscribe to a level of service offered. These types -of services are usually billed monthly and can be based on an annual rate to -save costs. The subscription (even if free) will most likely involve the use of -a security scheme such as an API key that must be used to access the data. See -[Calling an Airnode](/reference/airnode/v0.13/developers/index.md) to learn more -on how to pass the security credentials to an Airnode. +Some API providers charge a subscription fee for access to their data. This is a typical practice and usually requires the requester to create an account on the provider's website and then subscribe to a level of service offered. These types of services are usually billed monthly and can be based on an annual rate to save costs. The subscription (even if free) will most likely involve the use of a security scheme such as an API key that must be used to access the data. See [Calling an Airnode](/reference/airnode/v0.13/developers/index.md) to learn more on how to pass the security credentials to an Airnode. diff --git a/docs/reference/airnode/v0.13/developers/index.md b/docs/reference/airnode/v0.13/developers/index.md index 0ddb2c1f..fe45e4fe 100644 --- a/docs/reference/airnode/v0.13/developers/index.md +++ b/docs/reference/airnode/v0.13/developers/index.md @@ -19,47 +19,22 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that can push off-chain API data to an on-chain -contract. While dApp developers will find -[dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the -most useful aspect of an Airnode's capabilities, there is the option for -developers to access Airnode data using its request-response protocol (RRP). The -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract facilitates RRP and is designed to be flexible and is meant to -serve a variety of use cases. See the Airnode -[requester examples](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/contracts) -for potential design patterns. +Airnode is a first-party oracle that can push off-chain API data to an on-chain contract. While dApp developers will find [dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/) popular and the most useful aspect of an Airnode's capabilities, there is the option for developers to access Airnode data using its request-response protocol (RRP). The [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract facilitates RRP and is designed to be flexible and is meant to serve a variety of use cases. See the Airnode [requester examples](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/contracts) for potential design patterns. ## It starts with a requester -A requester is a smart contract that can trigger an Airnode RRP request. To do -so, the requester needs to be sponsored and make the request using a matching -sponsor wallet. See -[Requesters and Sponsors](/reference/airnode/v0.13/developers/requesters-sponsors.md) -on how to sponsor a requester and derive the sponsor wallet. +A requester is a smart contract that can trigger an Airnode RRP request. To do so, the requester needs to be sponsored and make the request using a matching sponsor wallet. See [Requesters and Sponsors](/reference/airnode/v0.13/developers/requesters-sponsors.md) on how to sponsor a requester and derive the sponsor wallet. ## A simplified understanding -In the diagram below, any typical smart contract is called a requester if it -makes a request of Airnode's RRP protocol. It makes a request to the on-chain -RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event -logs. The off-chain Airnode then accesses the event logs, gets the API data and -performs a callback to the requester. +In the diagram below, any typical smart contract is called a requester if it makes a request of Airnode's RRP protocol. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event logs. The off-chain Airnode then accesses the event logs, gets the API data and performs a callback to the requester. In summary, the requester will do two things. -- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol - contract, which returns a - [`requestId`](/reference/airnode/v0.13/concepts/request.md#requestid). -- Add a `myFulfill()` function (call it what you like) to your requester where - the off-chain Airnode can send the requested data when ready. The data - includes the same `requestId` as the one returned at the time of making the - request. +- Call `makeFullRequest()` or `makeTemplateRequest()` on the AirnodeRrpV0.sol contract, which returns a [`requestId`](/reference/airnode/v0.13/concepts/request.md#requestid). +- Add a `myFulfill()` function (call it what you like) to your requester where the off-chain Airnode can send the requested data when ready. The data includes the same `requestId` as the one returned at the time of making the request. -In the diagram below a requester makes a request to the on-chain RRP protocol -contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its -run cycle the off-chain Airnode accesses the event logs, gets the requested data -from the the API provider, then performs a callback to the requester. +In the diagram below a requester makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its run cycle the off-chain Airnode accesses the event logs, gets the requested data from the the API provider, then performs a callback to the requester. > > @@ -68,19 +43,13 @@ from the the API provider, then performs a callback to the requester. > 3.

Airnode gathers response data from the API specified in the request.

> 4.

Airnode performs a callback to a named function myFulfill() in myContract.sol via the AirnodeRrpV0.sol function fulfill() with the requested data and the requestId.

-See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn -how to make a RRP request of an Airnode. +See the guide [ Making an RRP Request](/guides/airnode/rrp-request.md) and learn how to make a RRP request of an Airnode. ## A deeper dive -This section, through its detailed illustration, builds on the previous section -([A simplified understanding](/reference/airnode/v0.13/developers/index.md#a-simplified-understanding)) -in an attempt to further illustrate and explain the mechanics of how an Airnode -response to a request made by a requester. +This section, through its detailed illustration, builds on the previous section ([A simplified understanding](/reference/airnode/v0.13/developers/index.md#a-simplified-understanding)) in an attempt to further illustrate and explain the mechanics of how an Airnode response to a request made by a requester. -Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") -deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain -**protocol contract** AirnodeRrpV0.sol. +Airnode RRP consists of two parts: the off-chain **Airnode** (a.k.a. "the node") deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain **protocol contract** AirnodeRrpV0.sol. > > diff --git a/docs/reference/airnode/v0.13/developers/requesters-sponsors.md b/docs/reference/airnode/v0.13/developers/requesters-sponsors.md index e831be62..8e81d916 100644 --- a/docs/reference/airnode/v0.13/developers/requesters-sponsors.md +++ b/docs/reference/airnode/v0.13/developers/requesters-sponsors.md @@ -19,143 +19,80 @@ tags: # {{$frontmatter.title}} -As a dApp developer it helps to understand what a **requester** is and what a -**sponsor** does. They are both important parts of the Airnode ecosystem. This -doc will further define them and walk you through the process of sponsoring a -requester and deriving a sponsor wallet using the admin CLI commands. +As a dApp developer it helps to understand what a **requester** is and what a **sponsor** does. They are both important parts of the Airnode ecosystem. This doc will further define them and walk you through the process of sponsoring a requester and deriving a sponsor wallet using the admin CLI commands. ## What is a Requester? -The term [requester](/reference/airnode/v0.13/concepts/requester.md) is -important to remember. When requester is mentioned, the reference is to your -smart contract that makes a request of an Airnode. +The term [requester](/reference/airnode/v0.13/concepts/requester.md) is important to remember. When requester is mentioned, the reference is to your smart contract that makes a request of an Airnode. > -As an example see the `myContract.sol` contract in the diagram within the -[Overview](/reference/airnode/v0.13/concepts/) doc, it is a requester. +As an example see the `myContract.sol` contract in the diagram within the [Overview](/reference/airnode/v0.13/concepts/) doc, it is a requester. ## What is a Sponsor? -Equally important is the term -[sponsor](/reference/airnode/v0.13/concepts/sponsor.md). A sponsor is an entity -such as yourself, an organization, etc. Sponsors create relationships between -requesters and Airnodes. +Equally important is the term [sponsor](/reference/airnode/v0.13/concepts/sponsor.md). A sponsor is an entity such as yourself, an organization, etc. Sponsors create relationships between requesters and Airnodes. ### Sponsor's Requester/Airnode Relationships -As a sponsor you will use the public address from an account within a mnemonic -you own to "**sponsor a requester**" and then use the public address (known as a -[sponsorAddress](/reference/airnode/v0.13/concepts/sponsor.md#sponsoraddress)) -to "**derive a -[sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet)**" -for an Airnode. This action creates a relationship between a sponsor's requester -and a particular Airnode. You do this because a sponsor is the entity that pays -for the fulfillment of a request, the gas costs the Airnode will incur. These -costs will be withdrawn from the `sponsorWallet` of the Airnode when the -requester calls it. +As a sponsor you will use the public address from an account within a mnemonic you own to "**sponsor a requester**" and then use the public address (known as a [sponsorAddress](/reference/airnode/v0.13/concepts/sponsor.md#sponsoraddress)) to "**derive a [sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet)**" for an Airnode. This action creates a relationship between a sponsor's requester and a particular Airnode. You do this because a sponsor is the entity that pays for the fulfillment of a request, the gas costs the Airnode will incur. These costs will be withdrawn from the `sponsorWallet` of the Airnode when the requester calls it. ::: info sponsorAddress -A [sponsorAddress](/reference/airnode/v0.13/concepts/sponsor.md#sponsoraddress) -is a public address of an account from a mnemonic, usually the default account. -Rather than the default account another account from the mnemonic can be used. -The `sponsorAddress` is used to uniquely identify a sponsor. +A [sponsorAddress](/reference/airnode/v0.13/concepts/sponsor.md#sponsoraddress) is a public address of an account from a mnemonic, usually the default account. Rather than the default account another account from the mnemonic can be used. The `sponsorAddress` is used to uniquely identify a sponsor. ::: -1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester - with the Admin CLI. The CLI will use the default address of the mnemonic - passed as the `sponsorAddress` for the sponsorship unless another account is - specified. +1. In the diagram below a sponsor uses a `sponsorAddress` to sponsor a requester with the Admin CLI. The CLI will use the default address of the mnemonic passed as the `sponsorAddress` for the sponsorship unless another account is specified. -2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the - `sponsorAddress`. +2. Next the sponsor will derive a `sponsorWallet` for an Airnode using the `sponsorAddress`. 3. The requester can now make requests of the Airnode. > -In the above diagram it is possible to use the same sponsorAddress -`(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is -possible to sponsor more than one requester with the same `sponsorAddress`. -However it is important to remember that all requesters can now access all the -Airnodes regardless if they need to. There is no harm in this scenario. +In the above diagram it is possible to use the same sponsorAddress `(0xF4...dDyu9)` to derive other sponsor wallets for other Airnodes. And it is possible to sponsor more than one requester with the same `sponsorAddress`. However it is important to remember that all requesters can now access all the Airnodes regardless if they need to. There is no harm in this scenario. ### Advanced Scenarios - **Two requesters, one Airnode, one sponsorWallet**: - Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) - would access the same Airnode using a single sponsorWallet derived by the - `sponsorAddress`. + Two requesters sponsored with the same `sponsorAddress` (e.g., `0xF4...dDyu9`) would access the same Airnode using a single sponsorWallet derived by the `sponsorAddress`. - **Two requesters, one Airnode, two sponsorWallets**: - Sponsor two different requesters each with a different `sponsorAddress` (e.g., - `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you - can derive two separate sponsorWallets for the same Airnode. Now each - requester will deplete funds from a separate Airnode sponsorWallet when using - the Airnode. + Sponsor two different requesters each with a different `sponsorAddress` (e.g., `0xF4...dDyu9` and `0xG9...fFzc5`). Using the separate sponsorAddresses you can derive two separate sponsorWallets for the same Airnode. Now each requester will deplete funds from a separate Airnode sponsorWallet when using the Airnode. - **One requester, two Airnodes, two sponsorWallets**: - A requester can make requests from two different Airnodes. Sponsor the - requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of - two the Airnodes, using the `sponsorAddress`. Despite the fact that the - sponsorWallet for each Airnode was derived with the same `sponsorAddress` the - sponsorWallets are different since they are derived using the airnode's xpub - plus the `sponsorAddress`. The sponsor must fund both wallets separately using - the unique `sponsorWallet` address of the two sponsorWallets. + A requester can make requests from two different Airnodes. Sponsor the requester with a `sponsorAddress`. Derive two sponsorWallets, one for each of two the Airnodes, using the `sponsorAddress`. Despite the fact that the sponsorWallet for each Airnode was derived with the same `sponsorAddress` the sponsorWallets are different since they are derived using the airnode's xpub plus the `sponsorAddress`. The sponsor must fund both wallets separately using the unique `sponsorWallet` address of the two sponsorWallets. ### Things to Remember -When you sponsor a requester with a `sponsorAddress` you are giving it -permission to use the sponsorWallet (associated with a Airnode) that was derived -using the same `sponsorAddress`. +When you sponsor a requester with a `sponsorAddress` you are giving it permission to use the sponsorWallet (associated with a Airnode) that was derived using the same `sponsorAddress`. -When the requester makes a request to the Airnode, the Airnode will use funds -from the corresponding sponsorWallet to pay gas costs in response to the -request. Therefore the sponsor pays for the fulfillment of the request. +When the requester makes a request to the Airnode, the Airnode will use funds from the corresponding sponsorWallet to pay gas costs in response to the request. Therefore the sponsor pays for the fulfillment of the request. -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/v0.13/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/v0.13/developers/fees.md#api-provider-fees). ## Admin CLI Commands -There are several sponsor and requester related commands in the -[Admin CLI Commands](/reference/airnode/v0.13/packages/admin-cli.md) package. -You can also see a list of available commands using -`npx @api3/airnode-admin --help`. +There are several sponsor and requester related commands in the [Admin CLI Commands](/reference/airnode/v0.13/packages/admin-cli.md) package. You can also see a list of available commands using `npx @api3/airnode-admin --help`. -In the next two sections of this doc you will use two commands from the -`@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor -wallet_. +In the next two sections of this doc you will use two commands from the `@api3/airnode-admin` package to _sponsor a requester_ and to _derive a sponsor wallet_. -1. [sponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#sponsor-requester) - sponsors a requester. -2. [derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address)creates - a sponsor wallet associated with an Airnode. +1. [sponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#sponsor-requester) sponsors a requester. +2. [derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address)creates a sponsor wallet associated with an Airnode. ## How to Sponsor a Requester -To sponsor a requester execute the `sponsor-requester` command using the -parameters detailed in the list below. Your requester should already be deployed -on-chain. This command has transaction gas costs. +To sponsor a requester execute the `sponsor-requester` command using the parameters detailed in the list below. Your requester should already be deployed on-chain. This command has transaction gas costs. -- `providerURL`: A blockchain provider URL (such as Infura) with providerID for - the desired network. -- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to - derive the sponsorAddress from the default address. The sponsorAddress will be - needed to derive a sponsorWallet for an Airnode. +- `providerURL`: A blockchain provider URL (such as Infura) with providerID for the desired network. +- `sponsor-mnemonic`: Used for gas costs to fund the sponsorship and used to derive the sponsorAddress from the default address. The sponsorAddress will be needed to derive a sponsorWallet for an Airnode. - `requester-address`: Address of the requester contract. -- `derivation-path (optional)` (_not used in the example below_): Selects an - alternate account to use from the mnemonic rather than the default account. +- `derivation-path (optional)` (_not used in the example below_): Selects an alternate account to use from the mnemonic rather than the default account. -Executing the command -[sponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#sponsor-requester) -will sponsor a requester and returns the requesterAddress and sponsorAddress. +Executing the command [sponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#sponsor-requester) will sponsor a requester and returns the requesterAddress and sponsorAddress. ::: code-group @@ -181,27 +118,15 @@ npx @api3/airnode-admin sponsor-requester ^ ## How to Derive a Sponsor Wallet -To use a particular Airnode you must _derive a sponsorWallet_. Once the -sponsorWallet is created it must be funded using the public address -(`sponsorWallet` address) returned by the command -`derive-sponsor-wallet-address`. Each Airnode keeps a separate list of -individual sponsorWallets that can access the Airnode. Learn more about a -[sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). +To use a particular Airnode you must _derive a sponsorWallet_. Once the sponsorWallet is created it must be funded using the public address (`sponsorWallet` address) returned by the command `derive-sponsor-wallet-address`. Each Airnode keeps a separate list of individual sponsorWallets that can access the Airnode. Learn more about a [sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). -To derive a sponsorWallet for an Airnode execute the -[derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) -command using the parameters detailed in the list below. There are no -transaction gas costs to do so. +To derive a sponsorWallet for an Airnode execute the [derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) command using the parameters detailed in the list below. There are no transaction gas costs to do so. -- `airnode-xpub`: The extended public address of the Airnode for path - m/44'/60'/0'. +- `airnode-xpub`: The extended public address of the Airnode for path m/44'/60'/0'. - `airnode-address`: The public address of the desired Airnode. -- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) - owned by a sponsor. Usually the sponsorAddress is the one returned when - sponsoring a requester. +- `sponsor-address`: The sponsorAddress (an address of an Ethereum account) owned by a sponsor. Usually the sponsorAddress is the one returned when sponsoring a requester. -The command `derive-sponsor-wallet-address` will return the public address -(`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. +The command `derive-sponsor-wallet-address` will return the public address (`sponsorWallet` address) of the sponsorWallet to be funded by the sponsor. ::: code-group @@ -225,22 +150,15 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ::: -Sponsors need to keep their sponsorWallets topped off if they want Airnodes to -fulfill requests made by their requesters. However this does not cover the cost -of API data that the Airnode serves, see -[API Provider Fees](/reference/airnode/v0.13/developers/fees.md#api-provider-fees). +Sponsors need to keep their sponsorWallets topped off if they want Airnodes to fulfill requests made by their requesters. However this does not cover the cost of API data that the Airnode serves, see [API Provider Fees](/reference/airnode/v0.13/developers/fees.md#api-provider-fees). -If you forget the public address (`sponsorWallet` address) of the sponsorWallet -simply run `derive-sponsor-wallet-address` again. Since the wallet already -exists for the airnodeAddress/sponsorAddress pair it will just return the -address. +If you forget the public address (`sponsorWallet` address) of the sponsorWallet simply run `derive-sponsor-wallet-address` again. Since the wallet already exists for the airnodeAddress/sponsorAddress pair it will just return the address. ## Record Keeping -During and after sponsoring requesters and deriving a sponsorWallet there are a -few things to keep track of. +During and after sponsoring requesters and deriving a sponsorWallet there are a few things to keep track of. | Item | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -248,11 +166,6 @@ few things to keep track of. | sponsor address | The public address of an account derived from a sponsor's mnemonic when sponsoring a requester. Record which `sponsorAddress` was used to create a sponsorWallet for each Airnode. | | sponsor wallet address | Record the `sponsorWallet` address of the sponsorWallet derived for an Airnode. For each Airnode you have derived a sponsorWallet, the Airnode keeps the private key and returns the public address (`sponsorWallet` address) which is used to fund the sponsorWallet. | -You can acquire the public address (`sponsorWallet` address) of a sponsorWallet -later, if you lose it, by running the command `derive-sponsor-wallet-address` -again. Since the sponsorWallet was already created for the -`sponsorAddress/airnodeAddress` pair, the command will only return the public -address for the wallet. However you must use the same `sponsorAddress` used when -the wallet was first created or a new sponsorWallet will be created. +You can acquire the public address (`sponsorWallet` address) of a sponsorWallet later, if you lose it, by running the command `derive-sponsor-wallet-address` again. Since the sponsorWallet was already created for the `sponsorAddress/airnodeAddress` pair, the command will only return the public address for the wallet. However you must use the same `sponsorAddress` used when the wallet was first created or a new sponsorWallet will be created. diff --git a/docs/reference/airnode/v0.13/developers/using-templates.md b/docs/reference/airnode/v0.13/developers/using-templates.md index ae06f063..3cfbbfcb 100644 --- a/docs/reference/airnode/v0.13/developers/using-templates.md +++ b/docs/reference/airnode/v0.13/developers/using-templates.md @@ -19,15 +19,7 @@ tags: # {{$frontmatter.title}} -A request to an Airnode can have many parameters. It is very common for -requester contracts (e.g., a data feed) to make repeated requests with the exact -same parameters. In such instances, it is wasteful to pass all of these -parameters repeatedly. Templates are used to hold a set of parameter values -on-chain that can be used repeatedly when calling -the`makeTemplateRequest()`function in -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). -Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester -pass`templateId`which identifies a template. +A request to an Airnode can have many parameters. It is very common for requester contracts (e.g., a data feed) to make repeated requests with the exact same parameters. In such instances, it is wasteful to pass all of these parameters repeatedly. Templates are used to hold a set of parameter values on-chain that can be used repeatedly when calling the`makeTemplateRequest()`function in [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol). Unlike`makeFullRequest(), makeTemplateRequest()`requires that a requester pass`templateId`which identifies a template. ```solidity function makeTemplateRequest( @@ -40,10 +32,7 @@ function makeTemplateRequest( ) external override returns (bytes32 requestId) { ``` -When a template is used to make a request, both the parameters encoded in -parameters of the template and parameters provided at request-time (if any) will -be used by the Airnode. In case the two include a parameter with the same name, -the one provided at request-time will be used. +When a template is used to make a request, both the parameters encoded in parameters of the template and parameters provided at request-time (if any) will be used by the Airnode. In case the two include a parameter with the same name, the one provided at request-time will be used. The structure of a template, as shown below, is simple. @@ -59,10 +48,6 @@ struct Template { } ``` -See the guide -[Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn -how to create and use a template. Also visit the -[coingecko-template](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations/coingecko-template) -monorepo example demonstrates template requests. +See the guide [Making RRP Template Requests](/guides/airnode/using-rrp-templates.md) and learn how to create and use a template. Also visit the [coingecko-template](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations/coingecko-template) monorepo example demonstrates template requests. diff --git a/docs/reference/airnode/v0.13/developers/verify-airnode-addresses.md b/docs/reference/airnode/v0.13/developers/verify-airnode-addresses.md index c45a69ab..41852f59 100644 --- a/docs/reference/airnode/v0.13/developers/verify-airnode-addresses.md +++ b/docs/reference/airnode/v0.13/developers/verify-airnode-addresses.md @@ -19,18 +19,9 @@ tags: # {{$frontmatter.title}} -An Airnode is owned and operated by an API provider. Every Airnode has a unique -on-chain -[`airnodeAddress`](/reference/airnode/v0.13/concepts/airnode.md#airnodeaddress) -created and known by its API provider. API providers normally announce their -Airnode addresses in the form of a DNS `TXT` record within their DNS -registration, which also serves to prove ownership. An API provider's Airnode -address is the same for all chains. - -The key for the `TXT` record is `chainapi-verification-keys` and is an array of -Airnode addresses owned by the API provider. Below is an example of the Airnode -for -[dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). +An Airnode is owned and operated by an API provider. Every Airnode has a unique on-chain [`airnodeAddress`](/reference/airnode/v0.13/concepts/airnode.md#airnodeaddress) created and known by its API provider. API providers normally announce their Airnode addresses in the form of a DNS `TXT` record within their DNS registration, which also serves to prove ownership. An API provider's Airnode address is the same for all chains. + +The key for the `TXT` record is `chainapi-verification-keys` and is an array of Airnode addresses owned by the API provider. Below is an example of the Airnode for [dxFeed](https://www.digitalocean.com/community/tools/dns?domain=dxfeed.com#TXT-Records). ![dxfeed-txt-record](../assets/images/txt-record-dxfeed.png) diff --git a/docs/reference/airnode/v0.13/docker/admin-cli-image.md b/docs/reference/airnode/v0.13/docker/admin-cli-image.md index 7a6a717d..0e0f317d 100644 --- a/docs/reference/airnode/v0.13/docker/admin-cli-image.md +++ b/docs/reference/airnode/v0.13/docker/admin-cli-image.md @@ -22,24 +22,15 @@ tags: -Use the admin CLI image as an alternative method to execute -[Admin CLI](/reference/airnode/v0.13/packages/admin-cli.md) using npx. Either -method will achieve the same results. The image forgoes downloading the admin -CLI package each time a command is executed using npx. +Use the admin CLI image as an alternative method to execute [Admin CLI](/reference/airnode/v0.13/packages/admin-cli.md) using npx. Either method will achieve the same results. The image forgoes downloading the admin CLI package each time a command is executed using npx. -If you want to build the admin CLI image from the source yourself, you can find -the -[image built instructions](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin/docker) -in the Airnode repository. +If you want to build the admin CLI image from the source yourself, you can find the [image built instructions](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin/docker) in the Airnode repository. -Additional information about the -[admin CLI image](/reference/airnode/v0.13/packages/admin-cli.md#using-docker) -is available in the admin CLI commands doc. +Additional information about the [admin CLI image](/reference/airnode/v0.13/packages/admin-cli.md#using-docker) is available in the admin CLI commands doc. ## Usage -The following example shows the difference between using the docker image versus -npx when executing the `get-sponsor-status` admin CLI command. +The following example shows the difference between using the docker image versus npx when executing the `get-sponsor-status` admin CLI command. ```sh #npx diff --git a/docs/reference/airnode/v0.13/docker/client-image.md b/docs/reference/airnode/v0.13/docker/client-image.md index e319026e..129652df 100644 --- a/docs/reference/airnode/v0.13/docker/client-image.md +++ b/docs/reference/airnode/v0.13/docker/client-image.md @@ -19,29 +19,17 @@ tags: # {{$frontmatter.title}} -Usually the Airnode is deployed on a serverless platform using the -[deployer](/reference/airnode/v0.13/docker/deployer-image.md). However, there is -another option which is to run the Airnode in a docker container on your machine -locally, on premise or cloud hosted. +Usually the Airnode is deployed on a serverless platform using the [deployer](/reference/airnode/v0.13/docker/deployer-image.md). However, there is another option which is to run the Airnode in a docker container on your machine locally, on premise or cloud hosted. -A docker client image has been published on -[Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build -the container from the source yourself, you can find the image and built -instructions in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-node/docker). +A docker client image has been published on [Docker Hub](https://hub.docker.com/r/api3/airnode-client). If you want to build the container from the source yourself, you can find the image and built instructions in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-node/docker). ## Configuration -The Airnode needs two configuration files for its run: `config.json` and -`secrets.env`. These files need to be passed to the Docker container via -volumes. +The Airnode needs two configuration files for its run: `config.json` and `secrets.env`. These files need to be passed to the Docker container via volumes. -The Docker container looks for configuration files mounted internally in the -`/app/config` directory. +The Docker container looks for configuration files mounted internally in the `/app/config` directory. -Your current working directory should contain the configuration files above and -you bind it to the `/app/config` directory for the docker using the `--volume` -parameter. +Your current working directory should contain the configuration files above and you bind it to the `/app/config` directory for the docker using the `--volume` parameter. ::: code-group @@ -73,8 +61,7 @@ $ docker run --volume %cd%:/config:/app/config ... ## Usage -Example directory structure and commands for running the Airnode Docker -container. The below commands are run from the depicted directory. +Example directory structure and commands for running the Airnode Docker container. The below commands are run from the depicted directory. ### Running Airnode @@ -105,18 +92,11 @@ docker run ^ ::: -> If you want to connect Airnode to a blockchain running on localhost, you need -> to make the blockchain accessible from within the docker itself. If you use -> docker for linux you can use `--network="host"` parameter. If you are using -> Docker Desktop (on any platform), connect to -> `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See -> [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). +> If you want to connect Airnode to a blockchain running on localhost, you need to make the blockchain accessible from within the docker itself. If you use docker for linux you can use `--network="host"` parameter. If you are using Docker Desktop (on any platform), connect to `http://host.docker.internal:8545` instead of `http://127.0.0.1:8545`. See [https://stackoverflow.com/a/24326540](https://stackoverflow.com/a/24326540). ### Checking Airnode logs -Logs will be output to the console after running the above command. If you -decide to run Airnode in detached mode with `--detach`, you need to use the -`logs` command, optionally with `--follow`, to access the logs. +Logs will be output to the console after running the above command. If you decide to run Airnode in detached mode with `--detach`, you need to use the `logs` command, optionally with `--follow`, to access the logs. ```bash docker logs airnode diff --git a/docs/reference/airnode/v0.13/docker/deployer-image.md b/docs/reference/airnode/v0.13/docker/deployer-image.md index edcc0c0f..48b51563 100644 --- a/docs/reference/airnode/v0.13/docker/deployer-image.md +++ b/docs/reference/airnode/v0.13/docker/deployer-image.md @@ -19,26 +19,17 @@ tags: # {{$frontmatter.title}} -Use the deployer image to deploy or remove an Airnode with a cloud provider such -as AWS. The simplest way is to use the pre-built packages. If you would rather -build the images yourself see the -[README](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer/docker) -in the deployer package. +Use the deployer image to deploy or remove an Airnode with a cloud provider such as AWS. The simplest way is to use the pre-built packages. If you would rather build the images yourself see the [README](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer/docker) in the deployer package. ::: info Quick Deploy Demos -See the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -guides to quickly deploy and remove a preconfigured Airnode using the deployer -image. +See the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) guides to quickly deploy and remove a preconfigured Airnode using the deployer image. ::: ## Configuration Files -The files `config.json` and `secrets.env` are used to configure the Airnode. The -`aws.env` and `gcp.json` files are used to define environment information the -deployer uses to connect to these cloud providers. +The files `config.json` and `secrets.env` are used to configure the Airnode. The `aws.env` and `gcp.json` files are used to define environment information the deployer uses to connect to these cloud providers. ``` my-airnode @@ -50,22 +41,15 @@ my-airnode ## Cloud Provider Credentials -In order to deploy Airnode to a serverless cloud provider, you need to provide -cloud provider credentials to the Airnode deployer image. The deployer image -currently supports deploying to AWS and GCP. For AWS deployment, see the -[AWS Setup](/reference/airnode/v0.13/understand/configuring.md#aws-setup-aws-deployment-only) -and for GCP deployment, see the -[GCP Setup](/reference/airnode/v0.13/understand/configuring.md#gcp-setup-gcp-deployment-only). +In order to deploy Airnode to a serverless cloud provider, you need to provide cloud provider credentials to the Airnode deployer image. The deployer image currently supports deploying to AWS and GCP. For AWS deployment, see the [AWS Setup](/reference/airnode/v0.13/understand/configuring.md#aws-setup-aws-deployment-only) and for GCP deployment, see the [GCP Setup](/reference/airnode/v0.13/understand/configuring.md#gcp-setup-gcp-deployment-only). ## Deployer Logs -The deployer saves log files by default into the `config/logs/` direcotry, but -this can be changed by passing a `--logs` argument to the command. +The deployer saves log files by default into the `config/logs/` direcotry, but this can be changed by passing a `--logs` argument to the command. ## Deployer Image Commands -Commands are similar for AWS and GCP. Any differences between AWS and GCP are -noted where they exist. +Commands are similar for AWS and GCP. Any differences between AWS and GCP are noted where they exist. - `deploy` - `list` @@ -77,22 +61,16 @@ noted where they exist. ### `deploy` -The [deploy](/reference/airnode/v0.13/packages/deployer.md#deploy) command will -create the Airnode with a cloud provider or update it if it already exists. -Three files are needed to run the deploy command. +The [deploy](/reference/airnode/v0.13/packages/deployer.md#deploy) command will create the Airnode with a cloud provider or update it if it already exists. Three files are needed to run the deploy command. - config.json - secrets.env - aws.env (AWS only) - gcp.json (GCP only) -See -[Deploying an Airnode](/reference/airnode/v0.13/understand/deploying.md#deploy-with-docker) -for deployment commands specific to various operating systems and cloud -providers. +See [Deploying an Airnode](/reference/airnode/v0.13/understand/deploying.md#deploy-with-docker) for deployment commands specific to various operating systems and cloud providers. -Note that a `receipt.json` file will be created upon completion. It contains -some deployment information and is used to remove the Airnode. +Note that a `receipt.json` file will be created upon completion. It contains some deployment information and is used to remove the Airnode. @@ -120,24 +98,14 @@ docker run -it --rm ^ #### Re-deployments -A unique deployment is defined by the value of -[nodeSetting.stage](/reference/airnode/v0.13/deployment-files/config-json.md#stage). -If you deploy again, using the same `nodeSetting.stage` value, then you are -re-deploying or updating the previous deployment. +A unique deployment is defined by the value of [nodeSetting.stage](/reference/airnode/v0.13/deployment-files/config-json.md#stage). If you deploy again, using the same `nodeSetting.stage` value, then you are re-deploying or updating the previous deployment. -By default the deployer will attempt to remove the Airnode should either a -deployment or re-deployment fail. But if either fails (and -[--auto-remove](/reference/airnode/v0.13/packages/deployer.md#deploy) is false) -then the Airnode will not be removed, however it could be left in an unstable -state. You can alter the `deploy` command to change this behavior using the -following. +By default the deployer will attempt to remove the Airnode should either a deployment or re-deployment fail. But if either fails (and [--auto-remove](/reference/airnode/v0.13/packages/deployer.md#deploy) is false) then the Airnode will not be removed, however it could be left in an unstable state. You can alter the `deploy` command to change this behavior using the following. - `--auto-remove true|false`: defaults to true - `--no-auto-remove` -Auto removal is usually recommended for development deployments. For production -deployments, consider changing the value of `nodeSetting.stage` to create a new -deployment and follow-up by removing the previous deployment. +Auto removal is usually recommended for development deployments. For production deployments, consider changing the value of `nodeSetting.stage` to create a new deployment and follow-up by removing the previous deployment. Use the following example to avoid the automatic removal of the Airnode. @@ -150,12 +118,7 @@ api3/airnode-deployer:0.13.0 deploy --auto-remove false ### `list` -Once one or more Airnodes were deployed using the -[deploy](/reference/airnode/v0.13/docker/deployer-image.md#deploy) command -above, the [list](/reference/airnode/v0.13/packages/deployer.md#list) command -can be used to list currently deployed Airnodes. Files for cloud provider -authentication are needed for the command to run correctly: `aws.env` (for AWS) -and/or `gcp.json` (for GCP). +Once one or more Airnodes were deployed using the [deploy](/reference/airnode/v0.13/docker/deployer-image.md#deploy) command above, the [list](/reference/airnode/v0.13/packages/deployer.md#list) command can be used to list currently deployed Airnodes. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -174,9 +137,7 @@ docker run -it --rm ^ ::: -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ::: code-group @@ -197,14 +158,7 @@ docker run -it --rm ^ ### `info` -Retrieve more information about a deployment with the -[info](/reference/airnode/v0.13/packages/deployer.md#info) command. Use the -deployment ID from the -[list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above to -request information about a specific deployment. The retrieved information -include deployment's Airnode address, stage, Airnode version and the update -history. Files for cloud provider authentication are needed for the command to -run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). +Retrieve more information about a deployment with the [info](/reference/airnode/v0.13/packages/deployer.md#info) command. Use the deployment ID from the [list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above to request information about a specific deployment. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) and/or `gcp.json` (for GCP). ::: code-group @@ -225,17 +179,7 @@ docker run -it --rm ^ ### `rollback` -To revert to a previous version of a deployment, use the -[rollback](/reference/airnode/v0.13/packages/deployer.md#rollback) command. -Provide the deployment ID from the -[list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above to -specify which deployment will be changed. Also provide the desired version ID -from the [info](/reference/airnode/v0.13/docker/deployer-image.md#info) command -above to revert to. The -[rollback](/reference/airnode/v0.13/packages/deployer.md#rollback) command will -then fetch the configuration files of the specified version and deploy the -version using its configuration. Check this with the -[info](/reference/airnode/v0.13/docker/deployer-image.md#info) command above. +To revert to a previous version of a deployment, use the [rollback](/reference/airnode/v0.13/packages/deployer.md#rollback) command. Provide the deployment ID from the [list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above to specify which deployment will be changed. Also provide the desired version ID from the [info](/reference/airnode/v0.13/docker/deployer-image.md#info) command above to revert to. The [rollback](/reference/airnode/v0.13/packages/deployer.md#rollback) command will then fetch the configuration files of the specified version and deploy the version using its configuration. Check this with the [info](/reference/airnode/v0.13/docker/deployer-image.md#info) command above. ::: code-group @@ -256,23 +200,7 @@ docker run -it --rm ^ ### `fetch-files` -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the -[fetch-files](/reference/airnode/v0.13/packages/deployer.md#fetch-files) command -to retrieve them. You need to provide the deployment ID from the -[list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above to -specify the desired deployment. By default, the files from the latest version of -this deployment are fetched. Alternatively, you can additionally provide a -deployment version ID from the -[info](/reference/airnode/v0.13/docker/deployer-image.md#info) command above to -specify the desired deployment version. By default, the archive with the files -is stored in the `config` directory **within the Docker container** that is, in -the example below, mapped to your current working directory. You can change the -output directory by providing an `--output-dir` option specifying a different -directory instead. Don't forget to add a mapping for the new output directory so -you'll be able to access the files. Files for cloud provider authentication are -needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for -GCP). +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the [fetch-files](/reference/airnode/v0.13/packages/deployer.md#fetch-files) command to retrieve them. You need to provide the deployment ID from the [list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above to specify the desired deployment. By default, the files from the latest version of this deployment are fetched. Alternatively, you can additionally provide a deployment version ID from the [info](/reference/airnode/v0.13/docker/deployer-image.md#info) command above to specify the desired deployment version. By default, the archive with the files is stored in the `config` directory **within the Docker container** that is, in the example below, mapped to your current working directory. You can change the output directory by providing an `--output-dir` option specifying a different directory instead. Don't forget to add a mapping for the new output directory so you'll be able to access the files. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -293,16 +221,7 @@ docker run -it --rm ^ ### `remove` -A deployed Airnode can be removed via the -[remove](/reference/airnode/v0.13/packages/deployer.md#remove) command. To -remove Airnode, use the deployment ID from the -[list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above. -Airnode's update history, that can be seen by the -[info](/reference/airnode/v0.13/docker/deployer-image.md#info) command, will be -removed as well. Files for cloud provider authentication are needed for the -command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is -the recommended way to remove a deployment, but an alternative is the -`remove-with-receipt` command. +A deployed Airnode can be removed via the [remove](/reference/airnode/v0.13/packages/deployer.md#remove) command. To remove Airnode, use the deployment ID from the [list](/reference/airnode/v0.13/docker/deployer-image.md#list) command above. Airnode's update history, that can be seen by the [info](/reference/airnode/v0.13/docker/deployer-image.md#info) command, will be removed as well. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). This is the recommended way to remove a deployment, but an alternative is the `remove-with-receipt` command. ::: code-group @@ -323,12 +242,7 @@ docker run -it --rm ^ ### `remove-with-receipt` -When an Airnode was deployed using the `deploy` command, a `receipt.json` file -was created. This file is used to remove the Airnode. The -[remove-with-receipt](/reference/airnode/v0.13/packages/deployer.md#remove-with-receipt) -command is identical for AWS and GCP. Files for cloud provider authentication -are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` -(for GCP). +When an Airnode was deployed using the `deploy` command, a `receipt.json` file was created. This file is used to remove the Airnode. The [remove-with-receipt](/reference/airnode/v0.13/packages/deployer.md#remove-with-receipt) command is identical for AWS and GCP. Files for cloud provider authentication are needed for the command to run correctly: `aws.env` (for AWS) or `gcp.json` (for GCP). ::: code-group @@ -349,22 +263,11 @@ docker run -it --rm ^ ## Manual Removal -Optionally you can remove an Airnode manually though it is highly recommended -that you do so using the deployer image's `remove-with-receipt` or `remove` -commands. When removing manually, you will need the Airnode's deployment ID, -`deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., -`production`). They can be found in the -[receipt.json](/reference/airnode/v0.13/deployment-files/receipt-json.md) file -generated when deploying the Airnode. These are included in the element name of -AWS and GCP deployed features. Airnode has a presence in several areas of both -AWS and GCP as listed below. +Optionally you can remove an Airnode manually though it is highly recommended that you do so using the deployer image's `remove-with-receipt` or `remove` commands. When removing manually, you will need the Airnode's deployment ID, `deploymentId` (e.g., `awsef86dfad`) and the Airnode stage name (e.g., `production`). They can be found in the [receipt.json](/reference/airnode/v0.13/deployment-files/receipt-json.md) file generated when deploying the Airnode. These are included in the element name of AWS and GCP deployed features. Airnode has a presence in several areas of both AWS and GCP as listed below. ::: danger Remember -Only delete elements of a feature with the `deploymentId` and `stage` name -contained in the element's name. There can be more than one Airnode. Example: -(airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the -deploymentId and `production` is the stage name. +Only delete elements of a feature with the `deploymentId` and `stage` name contained in the element's name. There can be more than one Airnode. Example: (airnode-**awsef86dfad-production**-run), where `awsef86dfad` is the deploymentId and `production` is the stage name. ::: @@ -376,7 +279,6 @@ deploymentId and `production` is the stage name. -Learn more about AWS or GCP resources that Airnode uses in the -[Cloud Resources](/reference/airnode/v0.13/cloud-resources.md) doc. +Learn more about AWS or GCP resources that Airnode uses in the [Cloud Resources](/reference/airnode/v0.13/cloud-resources.md) doc. diff --git a/docs/reference/airnode/v0.13/docker/index.md b/docs/reference/airnode/v0.13/docker/index.md index 86323fec..08fec93e 100644 --- a/docs/reference/airnode/v0.13/docker/index.md +++ b/docs/reference/airnode/v0.13/docker/index.md @@ -19,31 +19,19 @@ tags: # {{$frontmatter.title}} -Using Docker is the easiest way to both deploy an Airnode to a cloud provider -and to run an Airnode locally. There are two Docker images: the Airnode deployer -image and the Airnode client image. +Using Docker is the easiest way to both deploy an Airnode to a cloud provider and to run an Airnode locally. There are two Docker images: the Airnode deployer image and the Airnode client image. -There is also a docker image wrapping the admin CLI package, as an alternative -to using `npx`. +There is also a docker image wrapping the admin CLI package, as an alternative to using `npx`. -To use these images first install [Docker](https://docs.docker.com/get-docker/) -if it is not present on your system. +To use these images first install [Docker](https://docs.docker.com/get-docker/) if it is not present on your system. -If using a Linux distribution that enforces Selinux policies, allow the Docker -images access to the host directory by -[creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). +If using a Linux distribution that enforces Selinux policies, allow the Docker images access to the host directory by [creating an appropriate rule](https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker). -- The [deployer image](/reference/airnode/v0.13/docker/deployer-image.md) - deploys the node in the form of serverless functions to a serverless cloud - provider (e.g. AWS Lambda). +- The [deployer image](/reference/airnode/v0.13/docker/deployer-image.md) deploys the node in the form of serverless functions to a serverless cloud provider (e.g. AWS Lambda). -- The [client image](/reference/airnode/v0.13/docker/client-image.md) is the - node itself, containerized. The container can be run locally or deployed to a - cloud hosting service (e.g. AWS EC2 or Lightsail). +- The [client image](/reference/airnode/v0.13/docker/client-image.md) is the node itself, containerized. The container can be run locally or deployed to a cloud hosting service (e.g. AWS EC2 or Lightsail). -- The [admin CLI image](/reference/airnode/v0.13/docker/admin-cli-image.md) - wraps the admin CLI package in a docker image to provide an alternative usage - option to the Admin CLI commands (npx). +- The [admin CLI image](/reference/airnode/v0.13/docker/admin-cli-image.md) wraps the admin CLI package in a docker image to provide an alternative usage option to the Admin CLI commands (npx). ## DockerHub diff --git a/docs/reference/airnode/v0.13/index.md b/docs/reference/airnode/v0.13/index.md index 7fdc218c..18ece005 100644 --- a/docs/reference/airnode/v0.13/index.md +++ b/docs/reference/airnode/v0.13/index.md @@ -19,17 +19,9 @@ tags: # {{$frontmatter.title}} -Use the contract addresses listed in the tables below to interact with Airnode -on EVM-compatible blockchains. Additional addresses will be added as contracts -are deployed, but feel free to -[submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a -new deployment. - -The contract addresses listed below are sourced from the Airnode monorepo -[airnode-protocol](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-protocol) -and can be found in its -[deployments](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-protocol/deployments) -directory. +Use the contract addresses listed in the tables below to interact with Airnode on EVM-compatible blockchains. Additional addresses will be added as contracts are deployed, but feel free to [submit a GitHub issue](https://github.com/api3dao/airnode/issues) requesting a new deployment. + +The contract addresses listed below are sourced from the Airnode monorepo [airnode-protocol](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-protocol) and can be found in its [deployments](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-protocol/deployments) directory. ## AirnodeRrpV0 diff --git a/docs/reference/airnode/v0.13/migration.md b/docs/reference/airnode/v0.13/migration.md index 70e75e71..c3794d74 100644 --- a/docs/reference/airnode/v0.13/migration.md +++ b/docs/reference/airnode/v0.13/migration.md @@ -19,13 +19,9 @@ tags: # {{$frontmatter.title}} -The following guide assumes a valid v0.12 `config.json` file. All changes listed -below will need to be implemented in order to migrate to Airnode v0.13.0. This -document is written in a way that will preserve existing behavior with earlier -Airnode versions. +The following guide assumes a valid v0.12 `config.json` file. All changes listed below will need to be implemented in order to migrate to Airnode v0.13.0. This document is written in a way that will preserve existing behavior with earlier Airnode versions. -The document also mentions changes to user facing services related to Airnode, -such as airnode-deployer, airnode-admin, etc., and new features. +The document also mentions changes to user facing services related to Airnode, such as airnode-deployer, airnode-admin, etc., and new features. ## Summary @@ -46,14 +42,6 @@ Updated to "0.13.0" ## New features and updates -- The - [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md#http-gateway) - response has been harmonized so that the API call response, after undergoing - any post-processing, will be present in the `rawValue` field independent of - encoding success or failure. -- Airnode protocol contracts were deployed on the following chains: `linea`, - `linea-goerli-testnet`, `mantle`, `mantle-goerli-testnet`, `base`, - `base-goerli-testnet`, `polygon-zkevm`, and `polygon-zkevm-testnet`. -- In conjunction with the - [OIS bump to v2.2](https://github.com/api3dao/ois/releases), endpoint - parameters now do not have to be mapped to operation parameters. +- The [HTTP Gateway](/reference/airnode/latest/understand/http-gateways.md#http-gateway) response has been harmonized so that the API call response, after undergoing any post-processing, will be present in the `rawValue` field independent of encoding success or failure. +- Airnode protocol contracts were deployed on the following chains: `linea`, `linea-goerli-testnet`, `mantle`, `mantle-goerli-testnet`, `base`, `base-goerli-testnet`, `polygon-zkevm`, and `polygon-zkevm-testnet`. +- In conjunction with the [OIS bump to v2.2](https://github.com/api3dao/ois/releases), endpoint parameters now do not have to be mapped to operation parameters. diff --git a/docs/reference/airnode/v0.13/packages/adapter.md b/docs/reference/airnode/v0.13/packages/adapter.md index 914bb58d..38170b13 100644 --- a/docs/reference/airnode/v0.13/packages/adapter.md +++ b/docs/reference/airnode/v0.13/packages/adapter.md @@ -19,19 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-adapter](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-adapter) -package has multiple responsibilities. It is used for building requests from an -[Oracle Integration Specification (OIS)](/reference/ois/2.2/), executing them, -parsing the responses, but also converting and encoding them for on chain use. +The [airnode-adapter](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-adapter) package has multiple responsibilities. It is used for building requests from an [Oracle Integration Specification (OIS)](/reference/ois/2.2/), executing them, parsing the responses, but also converting and encoding them for on chain use. -It is an internal dependency of Airnode, but can also be used standalone as an -API. +It is an internal dependency of Airnode, but can also be used standalone as an API. ## Installation -You can install `@api3/airnode-adapter` by adding it to the `package.json` file -in your project. +You can install `@api3/airnode-adapter` by adding it to the `package.json` file in your project. ```sh npm install --save @api3/airnode-adapter @@ -39,35 +33,24 @@ npm install --save @api3/airnode-adapter yarn add @api3/airnode-adapter ``` -You shouldn't need to use the adapter package directly. However, you might want -to use its API to double check the conversion or encoding behavior for which you -can install this package and verify your assumptions. +You shouldn't need to use the adapter package directly. However, you might want to use its API to double check the conversion or encoding behavior for which you can install this package and verify your assumptions. ## Conversion -While the adapter package has many responsibilities, many of those can be -treated as implementation details. On the other hand, there are a few important -behaviors to be noted when converting the response values based on the target -type and making the response transaction on chain. +While the adapter package has many responsibilities, many of those can be treated as implementation details. On the other hand, there are a few important behaviors to be noted when converting the response values based on the target type and making the response transaction on chain. Altogether, the response cycle consists of multiple steps 1. A successful API call is made and Airnode receives a response value. -2. The value to be converted is extracted from the response using the - [\_path](/reference/ois/2.2/reserved-parameters.md#path) from the OIS object. -3. This extracted value is converted to the target type. Conversions are - performed internally by the `castValue(value, type)` function. -4. The converted value is encoded to the native solidity type based on the - [\_type](/reference/ois/2.2/reserved-parameters.md#type) from the OIS object. - Encoding is performed internally by the `encodeValue(value, type)` function. +2. The value to be converted is extracted from the response using the [\_path](/reference/ois/2.2/reserved-parameters.md#path) from the OIS object. +3. This extracted value is converted to the target type. Conversions are performed internally by the `castValue(value, type)` function. +4. The converted value is encoded to the native solidity type based on the [\_type](/reference/ois/2.2/reserved-parameters.md#type) from the OIS object. Encoding is performed internally by the `encodeValue(value, type)` function. -If any of the steps above fail, an error is thrown. This will fail the given API -request and the error reason can be found in the logs. +If any of the steps above fail, an error is thrown. This will fail the given API request and the error reason can be found in the logs. -The rest of this section covers the conversion logic for all of the supported -types. +The rest of this section covers the conversion logic for all of the supported types. ### `int256` or `uint256` @@ -86,8 +69,7 @@ const ERROR_VALUES = [ ]; ``` -There are a few special strings and boolean values that are convertible to -`int256` or `uint256`: +There are a few special strings and boolean values that are convertible to `int256` or `uint256`: ```ts const SPECIAL_INT_VALUES = [false, 'false', true, 'true']; @@ -97,11 +79,7 @@ console.log(values); // [0, 0, 1, 1]; ``` -Number strings and numbers will attempt to be converted to -[BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be -multiplied by the value of the -[\_times](/reference/ois/2.2/reserved-parameters.md#times) parameter if it is -present. +Number strings and numbers will attempt to be converted to [BigNumbers](https://mikemcl.github.io/bignumber.js/). The value will also be multiplied by the value of the [\_times](/reference/ois/2.2/reserved-parameters.md#times) parameter if it is present. ```ts const VALID_INT_VALUES = ['123.456', 7777]; @@ -111,17 +89,11 @@ console.log(values); // [new BigNumber(123.456), new BigNumber(7777)]; ``` -Conversion for `int256` and `uint256` is the same - this means that `-123` can -be converted to `uint256`. However, an error will be thrown while encoding. +Conversion for `int256` and `uint256` is the same - this means that `-123` can be converted to `uint256`. However, an error will be thrown while encoding. :::warning Flooring -Beware that any floating point number will be **floored**. This is necessary, -because floating point numbers are not valid in solidity. To mitigate precision -loss, you can use the -[`_times`](/reference/ois/2.2/reserved-parameters.md#times) parameter that is -sufficiently large. For example, if the API response is a USD currency, you -might want to use `_times: "100"` to convert the value to cents. +Beware that any floating point number will be **floored**. This is necessary, because floating point numbers are not valid in solidity. To mitigate precision loss, you can use the [`_times`](/reference/ois/2.2/reserved-parameters.md#times) parameter that is sufficiently large. For example, if the API response is a USD currency, you might want to use `_times: "100"` to convert the value to cents. ::: @@ -144,17 +116,9 @@ All other values are converted to `true`. ### `bytes32` -There is no conversion for `bytes32` - the value is expected to be a valid hex -string representing the encoded 32 bytes value. This means that the encoding -**must** be implemented on the API side. If you want to delegate the encoding to -Airnode, see the documentation for -[`string32`](/reference/airnode/v0.13/packages/adapter.md#string32). +There is no conversion for `bytes32` - the value is expected to be a valid hex string representing the encoded 32 bytes value. This means that the encoding **must** be implemented on the API side. If you want to delegate the encoding to Airnode, see the documentation for [`string32`](/reference/airnode/v0.13/packages/adapter.md#string32). -For example, let's say the API wants to encode the following string -`simple string` with length 13. Its encoding is -0x73696d706c6520737472696e6700000000000000000000000000000000000000. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. +For example, let's say the API wants to encode the following string `simple string` with length 13. Its encoding is 0x73696d706c6520737472696e6700000000000000000000000000000000000000. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. You can use [ethers](https://docs.ethers.io/v5/) to encode these on the API side @@ -166,29 +130,16 @@ console.log(encoded); // 0x73696d706c6520737472696e67000000000000000000000000000 ### `address` -There is no conversion for `address` - the value is expected to be a string -representing a valid address. Valid examples are: +There is no conversion for `address` - the value is expected to be a string representing a valid address. Valid examples are: -- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) - of an address. -- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - - all lowercase address. +- 0x0765baA22F6D4A53847D63B056DC79400b9A592a - [EIP-55 mixed case checksum](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) of an address. +- 0x0765baa22f6d4a53847d63b056dc79400b9a592a - all lowercase address. ### `bytes` -There is no conversion for `bytes` - the value is expected to be a valid hex -string representing the encoded value. This means that the encoding to bytes -**must** be implemented on the API side. If you want to send a string, see the -documentation for -[`string`](/reference/airnode/v0.13/packages/adapter.md#string). +There is no conversion for `bytes` - the value is expected to be a valid hex string representing the encoded value. This means that the encoding to bytes **must** be implemented on the API side. If you want to send a string, see the documentation for [`string`](/reference/airnode/v0.13/packages/adapter.md#string). -For example, let's say the API wants to encode the following string -`this is an example string that is a bit longer`. Its encoding is -0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. -This is the value that should be sent as a response to Airnode request, together -with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these -on the API side. +For example, let's say the API wants to encode the following string `this is an example string that is a bit longer`. Its encoding is 0x7468697320697320616e206578616d706c6520737472696e672074686174206973206120626974206c6f6e676572. This is the value that should be sent as a response to Airnode request, together with the `0x` prefix. Use [ethers](https://docs.ethers.io/v5/) to encode these on the API side. ```js const value = 'this is an example string that is a bit longer'; @@ -198,9 +149,7 @@ console.log(encodedValue); // 0x7468697320697320616e206578616d706c6520737472696e ### `string` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. All other values will be converted to -`string` and before encoded on chain using the `string` type. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. All other values will be converted to `string` and before encoded on chain using the `string` type. ```js const values = [ @@ -220,20 +169,11 @@ const mappedValues = values.map((v) => { ### `string32` -You can pass any value to convert it to string - with the exception of arrays -and objects, which will throw an error. +You can pass any value to convert it to string - with the exception of arrays and objects, which will throw an error. -However, there is one exception, if the stringified value contains more than 31 -characters it will be **trimmed down** to only the first 31 characters during -conversion. +However, there is one exception, if the stringified value contains more than 31 characters it will be **trimmed down** to only the first 31 characters during conversion. -For example, if the API response is the following string -`this is an example string that is a bit longer` with length 46. It will be -first trimmed to 31 characters, string `this is an example string that ` and -afterwards converted to -0x7468697320697320616e206578616d706c6520737472696e6720746861742000. -Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using -the following snippet +For example, if the API response is the following string `this is an example string that is a bit longer` with length 46. It will be first trimmed to 31 characters, string `this is an example string that ` and afterwards converted to 0x7468697320697320616e206578616d706c6520737472696e6720746861742000. Use [ethers](https://docs.ethers.io/v5/) to decode the values off chain using the following snippet ```js const encoded = @@ -244,17 +184,11 @@ console.log(decoded); // "this is an example string that " ### Arrays -Conversion of arrays depends on the primitive type. All values of the array (or -nested array) will be converted according to the rules of the primitive type. +Conversion of arrays depends on the primitive type. All values of the array (or nested array) will be converted according to the rules of the primitive type. For example: -- `int256[]` - has primitive type `int256`. All elements of this array follow - the [`int256`](/reference/airnode/v0.13/packages/adapter.md#int256-or-uint256) - rules. -- `string32[7][][5]` - is a multidimensional array, where some dimensions are - fixed and some not. This is irrelevant though, and all the elements are - converted based on - [`string32`](/reference/airnode/v0.13/packages/adapter.md#string32) rules. +- `int256[]` - has primitive type `int256`. All elements of this array follow the [`int256`](/reference/airnode/v0.13/packages/adapter.md#int256-or-uint256) rules. +- `string32[7][][5]` - is a multidimensional array, where some dimensions are fixed and some not. This is irrelevant though, and all the elements are converted based on [`string32`](/reference/airnode/v0.13/packages/adapter.md#string32) rules. diff --git a/docs/reference/airnode/v0.13/packages/admin-cli.md b/docs/reference/airnode/v0.13/packages/admin-cli.md index 1aaca49a..2e038a23 100644 --- a/docs/reference/airnode/v0.13/packages/admin-cli.md +++ b/docs/reference/airnode/v0.13/packages/admin-cli.md @@ -19,54 +19,26 @@ tags: # {{$frontmatter.title}} -Use the -[airnode-admin](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin) -Admin CLI tool to interact with Airnode across blockchains. There are commands -for both developers (dApp) and API providers. Developers can sponsor -[requester](/reference/airnode/v0.13/concepts/requester.md) contracts and derive -[sponsorWallets](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) for -Airnodes. API providers can build -[Airnodes](/reference/airnode/v0.13/concepts/airnode.md) that serve their API -data to requester contracts. +Use the [airnode-admin](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin) Admin CLI tool to interact with Airnode across blockchains. There are commands for both developers (dApp) and API providers. Developers can sponsor [requester](/reference/airnode/v0.13/concepts/requester.md) contracts and derive [sponsorWallets](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) for Airnodes. API providers can build [Airnodes](/reference/airnode/v0.13/concepts/airnode.md) that serve their API data to requester contracts. ::: warning Transaction Gas Costs -Some commands will incur transaction fees. These are per call transaction gas -costs and are relatively small. See the -[Developer Fees](/reference/airnode/v0.13/developers/fees.md) -doc. +Some commands will incur transaction fees. These are per call transaction gas costs and are relatively small. See the [Developer Fees](/reference/airnode/v0.13/developers/fees.md) doc. ::: -Almost all commands require you to provide a blockchain `providerUrl`. Following -are just two examples of many possibilities. See the -[Chain Providers](/reference/airnode/v0.13/concepts/chain-providers.md) doc for -more information. +Almost all commands require you to provide a blockchain `providerUrl`. Following are just two examples of many possibilities. See the [Chain Providers](/reference/airnode/v0.13/concepts/chain-providers.md) doc for more information. - `https://eth-goerli.gateway.pokt.network/v1/lb/` - `https://sepolia.infura.io/v3/` -The CLI connects to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -or the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract, which addresses are derived from the current chain. You can optionally -specify the contract addresses yourself by providing optional -`airnode-rrp-address` or `requester-authorizer-with-airnode` command argument -with the address of the deployed contract on your targeted chain. - -Commands that require `mnemonic` will make an on-chain transaction. The -application will derive the account from the mnemonic with default ethereum -derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional -parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet -that is associated with the mnemonic is funded on the target chain. The -application will not exit until the transaction is confirmed. +The CLI connects to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) or the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract, which addresses are derived from the current chain. You can optionally specify the contract addresses yourself by providing optional `airnode-rrp-address` or `requester-authorizer-with-airnode` command argument with the address of the deployed contract on your targeted chain. + +Commands that require `mnemonic` will make an on-chain transaction. The application will derive the account from the mnemonic with default ethereum derivation path `m/44'/60'/0'/0/0`. You can override this by using the optional parameter `derivation-path` (`m/44'/60'/0'/0/...`). Make sure that the wallet that is associated with the mnemonic is funded on the target chain. The application will not exit until the transaction is confirmed. ### Using transaction overrides -CLI commands also support the following transaction overrides as optional -arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and -`max-priority-fee` (EIP-1559 transactions) and `nonce`. +CLI commands also support the following transaction overrides as optional arguments: `gas-limit`, `gas-price` (legacy transactions), `max-fee` and `max-priority-fee` (EIP-1559 transactions) and `nonce`. ### Default transaction overrides @@ -115,9 +87,7 @@ docker run api3/airnode-admin:0.13.0 $COMMAND --help ## SDK -You can also use the package programmatically. The SDK exports respective -functions for all CLI commands as well as helper functions for obtaining the -contract instance on the targeted chain. +You can also use the package programmatically. The SDK exports respective functions for all CLI commands as well as helper functions for obtaining the contract instance on the targeted chain. ```js import { sponsorRequester, getAirnodeRrpWithSigner } from '@api3/airnode-admin'; @@ -133,9 +103,7 @@ const airnodeRrp = await getAirnodeRrpWithSigner( const requester = await sponsorRequester(airnodeRrp, requester); ``` -If you plan to use multiple commands it might be tedious to pass the contract -instance to every function call. For this reason there is also class based -`AdminSdk` which you initialize with `AirnodeRrp` contract only once. +If you plan to use multiple commands it might be tedious to pass the contract instance to every function call. For this reason there is also class based `AdminSdk` which you initialize with `AirnodeRrp` contract only once. ```js import { AdminSdk } from '@api3/airnode-admin'; @@ -157,14 +125,11 @@ const requester = await adminSdk.sponsorRequester(requester); adminSdk.airnodeRrp = airnodeRrp.connect(someOtherWallet); ``` -The SDK will also provide TS typings out of the box. Please, refer to the -implementation for more details. +The SDK will also provide TS typings out of the box. Please, refer to the implementation for more details. ### Using transaction overrides -You can also use transaction overrides to customize gas limits and fee settings. -The SDK simply passes the overrides parameter to the contract method so you can -use any overrides supported by the ethers library. +You can also use transaction overrides to customize gas limits and fee settings. The SDK simply passes the overrides parameter to the contract method so you can use any overrides supported by the ethers library. ```js import { ethers } from 'ethers'; @@ -188,14 +153,7 @@ const requester = await adminSdk.sponsorRequester(requester, overrides); ## Sponsors -Commands related to a [sponsor's](/reference/airnode/v0.13/concepts/sponsor.md) -relationships between -[requesters](/reference/airnode/v0.13/concepts/requester.md) and -[sponsorWallets](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) as -well as [templates](/reference/airnode/v0.13/concepts/template.md) used by a -sponsor's requesters. Some of these commands connect to the -[AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) -protocol contract where the signer is sponsor account. +Commands related to a [sponsor's](/reference/airnode/v0.13/concepts/sponsor.md) relationships between [requesters](/reference/airnode/v0.13/concepts/requester.md) and [sponsorWallets](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) as well as [templates](/reference/airnode/v0.13/concepts/template.md) used by a sponsor's requesters. Some of these commands connect to the [AirnodeRrpV0.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/rrp/AirnodeRrpV0.sol) protocol contract where the signer is sponsor account. - [sponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#sponsor-requester) - [unsponsor-requester](/reference/airnode/v0.13/packages/admin-cli.md#unsponsor-requester) @@ -210,39 +168,19 @@ protocol contract where the signer is sponsor account. ### `sponsor-requester` -[Sponsors](/reference/airnode/v0.13/concepts/sponsor.md) a -[requester](/reference/airnode/v0.13/concepts/requester.md) contract so that its -requests can be fulfilled by the -[sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) of -an Airnode. The account derived from the `mnemonic` you provide must belong to -the sponsor. +[Sponsors](/reference/airnode/v0.13/concepts/sponsor.md) a [requester](/reference/airnode/v0.13/concepts/requester.md) contract so that its requests can be fulfilled by the [sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) of an Airnode. The account derived from the `mnemonic` you provide must belong to the sponsor. -Sponsoring a requester and using the returned `sponsorAddress` to derive a -`sponsorWallet` for an Airnode creates a -[relationship](/reference/airnode/v0.13/concepts/sponsor.md) between the -requester and the Airnode, see the -[`derive-sponsor-wallet-address`](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Sponsoring a requester and using the returned `sponsorAddress` to derive a `sponsorWallet` for an Airnode creates a [relationship](/reference/airnode/v0.13/concepts/sponsor.md) between the requester and the Airnode, see the [`derive-sponsor-wallet-address`](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a - `sponsorAddress` as the default account of the mnemonic unless a - `derivation-path` is specified. It's also used to pay gas costs from the - mnemonic's default account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to derive a `sponsorAddress` as the default account of the mnemonic unless a `derivation-path` is specified. It's also used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to sponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. If this parameter is not provided, it will be deduced from - the current chain. If there is no RRP address found for the given chain an - error is thrown. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. If this parameter is not provided, it will be deduced from the current chain. If there is no RRP address found for the given chain an error is thrown. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -265,29 +203,17 @@ npx @api3/airnode-admin sponsor-requester ^ ### `unsponsor-requester` -Removes the sponsorship of a -[requester](/reference/airnode/v0.13/concepts/requester.md) contract so that its -requests can no longer be fulfilled by the -[sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). The -account derived from the `mnemonic` you provide here has to belong to the -sponsor. +Removes the sponsorship of a [requester](/reference/airnode/v0.13/concepts/requester.md) contract so that its requests can no longer be fulfilled by the [sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). The account derived from the `mnemonic` you provide here has to belong to the sponsor. - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used - to sponsor the requester. Used to pay gas costs from the mnemonic's default - account unless a `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Must be the mnemonic used to sponsor the requester. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `requester-address`: The contract address of the requester to unsponsor. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -310,17 +236,12 @@ npx @api3/airnode-admin unsponsor-requester ^ ### `get-sponsor-status` -Returns the sponsor status for a given -[sponsor](/reference/airnode/v0.13/concepts/sponsor.md) and -[requester](/reference/airnode/v0.13/concepts/requester.md) (`true` if -sponsored, `false` otherwise). +Returns the sponsor status for a given [sponsor](/reference/airnode/v0.13/concepts/sponsor.md) and [requester](/reference/airnode/v0.13/concepts/requester.md) (`true` if sponsored, `false` otherwise). - `provider-url`: A valid blockchain provider URL. -- `sponsor-address`: The `sponsorAddress` returned when the requester was - sponsored. +- `sponsor-address`: The `sponsorAddress` returned when the requester was sponsored. - `requester-address`: The requester contract address. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -342,16 +263,9 @@ npx @api3/airnode-admin get-sponsor-status ^ ### `derive-sponsor-wallet-address` -Derives the address of the wallet designated by an Airnode for a -[sponsor](/reference/airnode/v0.13/concepts/sponsor.md), which is called the -[sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). -This command will error if `airnode-xpub` does not belong to the HDNode with the -path `m/44'/60'/0'` of the Airnode wallet. See the -[`derive-airnode-xpub`](/reference/airnode/v0.13/packages/admin-cli.md#derive-airnode-xpub) -command. +Derives the address of the wallet designated by an Airnode for a [sponsor](/reference/airnode/v0.13/concepts/sponsor.md), which is called the [sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). This command will error if `airnode-xpub` does not belong to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. See the [`derive-airnode-xpub`](/reference/airnode/v0.13/packages/admin-cli.md#derive-airnode-xpub) command. -- `airnode-xpub`: The extended public address of the Airnode for path - `m/44'/60'/0'`. +- `airnode-xpub`: The extended public address of the Airnode for path `m/44'/60'/0'`. - `airnode-address`: The public address of the Airnode. - `sponsor-address`: The address of the sponsor account. @@ -375,27 +289,17 @@ npx @api3/airnode-admin derive-sponsor-wallet-address ^ ### `create-template` -Reads a file, uses its contents to create a -[template](/reference/airnode/v0.13/concepts/template.md) and returns a -`template-id`. Also see -[Using Templates](/reference/airnode/v0.13/developers/using-templates.md) for an -example template file. +Reads a file, uses its contents to create a [template](/reference/airnode/v0.13/concepts/template.md) and returns a `template-id`. Also see [Using Templates](/reference/airnode/v0.13/developers/using-templates.md) for an example template file. - `provider-url`: A valid blockchain provider URL. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. - `template-file-path`: Path to the template file to create on-chain. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -418,20 +322,11 @@ npx @api3/airnode-admin create-template ^ ### `create-inline-template` -It is possible to inline Airnode templates inside config.json in a `templates` -section. These templates need to be published on chain, but inlining them inside -config provides more clarity which templates can be used for template requests -and also saves a blockchain call . +It is possible to inline Airnode templates inside config.json in a `templates` section. These templates need to be published on chain, but inlining them inside config provides more clarity which templates can be used for template requests and also saves a blockchain call . -The command reads a template file, uses its contents to create a -[template](/reference/airnode/v0.13/concepts/template.md) and returns the data -necessary to inline the template inside config. See -[Using Templates](/reference/airnode/v0.13/developers/using-templates.md) for an -example template file. +The command reads a template file, uses its contents to create a [template](/reference/airnode/v0.13/concepts/template.md) and returns the data necessary to inline the template inside config. See [Using Templates](/reference/airnode/v0.13/developers/using-templates.md) for an example template file. -This command does **not** create a template on chain. Be sure to use the -[create-template](/reference/airnode/v0.13/packages/admin-cli.md#create-template) -command on chain before making template requests. +This command does **not** create a template on chain. Be sure to use the [create-template](/reference/airnode/v0.13/packages/admin-cli.md#create-template) command on chain before making template requests. - `template-file-path`: Path to the template file to create on-chain. @@ -451,13 +346,11 @@ npx @api3/airnode-admin create-inline-template ^ ### `get-template` -Returns the [template](/reference/airnode/v0.13/concepts/template.md) for the -given `template-id`. +Returns the [template](/reference/airnode/v0.13/concepts/template.md) for the given `template-id`. - `provider-url`: A valid blockchain provider URL. - `template-id`: The id of a template to return. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -477,50 +370,28 @@ npx @api3/airnode-admin get-template ^ ### `request-withdrawal` -Requests a -[withdrawal](/reference/airnode/v0.13/concepts/sponsor.md#withdrawals) from a -[sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) -managed by an Airnode. +Requests a [withdrawal](/reference/airnode/v0.13/concepts/sponsor.md#withdrawals) from a [sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) managed by an Airnode. -The funds will be returned to the account derived from the `sponsor-mnemonic`. -This account must belong to a -[sponsor](/reference/airnode/v0.13/concepts/sponsor.md) for the specified -[sponsor wallet address](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) -in the command. +The funds will be returned to the account derived from the `sponsor-mnemonic`. This account must belong to a [sponsor](/reference/airnode/v0.13/concepts/sponsor.md) for the specified [sponsor wallet address](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) in the command. -After the request is made, it needs to be fulfilled by Airnode, so the return -value of this command is only a `withdrawal-request-id` which you can use to -call -[check-withdrawal-request](/reference/airnode/v0.13/packages/admin-cli.md#check-withdrawal-request) -to see whether the request was processed or not. +After the request is made, it needs to be fulfilled by Airnode, so the return value of this command is only a `withdrawal-request-id` which you can use to call [check-withdrawal-request](/reference/airnode/v0.13/packages/admin-cli.md#check-withdrawal-request) to see whether the request was processed or not. ::: warning Withdrawal Priority -Airnode will drop any pending API calls associated with a `sponsorWallet` once a -withdrawal is requested. +Airnode will drop any pending API calls associated with a `sponsorWallet` once a withdrawal is requested. ::: - `provider-url`: A valid blockchain provider URL. -- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from - the mnemonic's default account unless a `derivation-path` is specified. - Withdrawn funds will be added to this mnemonic's default address unless a - `derivation-path` is specified. +- `sponsor-mnemonic`: A wallet owned by the sponsor. Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. Withdrawn funds will be added to this mnemonic's default address unless a `derivation-path` is specified. - `airnode-address`: The public address of the Airnode. -- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw - from. This address was returned by the `derive-sponsor-wallet-address` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. -- `derivation-path (optional)` : The destination address of the `mnemonic` - parameter to add the withdrawn funds to if the default address is not desired. +- `sponsor-wallet-address`: The pubic address of the sponsorWallet to withdraw from. This address was returned by the `derive-sponsor-wallet-address` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. +- `derivation-path (optional)` : The destination address of the `mnemonic` parameter to add the withdrawn funds to if the default address is not desired. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -545,17 +416,11 @@ npx @api3/airnode-admin request-withdrawal ^ ### `check-withdrawal-request` -Checks the status of the -[withdrawal](/reference/airnode/v0.13/concepts/sponsor.md#withdrawals) request -with the given `withdrawal-request-id` from the -[request withdrawal command](/reference/airnode/v0.13/packages/admin-cli.md#request-withdrawal) -above. +Checks the status of the [withdrawal](/reference/airnode/v0.13/concepts/sponsor.md#withdrawals) request with the given `withdrawal-request-id` from the [request withdrawal command](/reference/airnode/v0.13/packages/admin-cli.md#request-withdrawal) above. - `provider-url`: A valid blockchain provider URL. -- `withdrawal-request-id`: This id was returned by the `request-withdrawal` - command. -- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol - protocol contract. +- `withdrawal-request-id`: This id was returned by the `request-withdrawal` command. +- `airnode-rrp-address (optional)`: The public address of the AirnodeRrpV0.sol protocol contract. ::: code-group @@ -575,16 +440,7 @@ npx @api3/airnode-admin check-withdrawal-request ^ ### `verify-airnode-xpub` -Verifies that the `airnode-xpub` belongs to the HDNode with the path -`m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode -address can be derived with provided Airnode -[xpub](/reference/airnode/v0.13/concepts/airnode.md#xpub) with default -derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. -This command will most likely be used by a -[sponsor](/reference/airnode/v0.13/concepts/sponsor.md) to verify that the xpub -belongs to the Airnode before calling the -[derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Verifies that the `airnode-xpub` belongs to the HDNode with the path `m/44'/60'/0'` of the Airnode wallet. This command checks that the Airnode address can be derived with provided Airnode [xpub](/reference/airnode/v0.13/concepts/airnode.md#xpub) with default derivation path `m/44'/60'/0'/0/0` and compares it with the `airnode-address`. This command will most likely be used by a [sponsor](/reference/airnode/v0.13/concepts/sponsor.md) to verify that the xpub belongs to the Airnode before calling the [derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) command. ::: code-group @@ -604,9 +460,7 @@ npx @api3/airnode-admin verify-airnode-xpub ^ ## Airnodes -Helper commands for a previously deployed Airnode. Some of these commands -connect to the AirnodeRrpV0.sol protocol contract where the signer must be the -Airnode wallet. +Helper commands for a previously deployed Airnode. Some of these commands connect to the AirnodeRrpV0.sol protocol contract where the signer must be the Airnode wallet. - [derive-airnode-xpub](/reference/airnode/v0.13/packages/admin-cli.md#derive-airnode-xpub) - [derive-endpoint-id](/reference/airnode/v0.13/packages/admin-cli.md#derive-endpoint-id) @@ -615,13 +469,7 @@ Airnode wallet. ### `derive-airnode-xpub` -Derives the Airnode extended public key -([xpub](/reference/airnode/v0.13/concepts/airnode.md#xpub)). This xpub must be -announced via off-chain channels because it will be needed to derive a -[sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) -address. See the -[derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) -command. +Derives the Airnode extended public key ([xpub](/reference/airnode/v0.13/concepts/airnode.md#xpub)). This xpub must be announced via off-chain channels because it will be needed to derive a [sponsorWallet](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet) address. See the [derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address) command. - `airnode-mnemonic`: The Airnode mnemonic for which the xpub is to be derived. @@ -639,15 +487,10 @@ npx @api3/airnode-admin derive-airnode-xpub --airnode-mnemonic "nature about sal ### `derive-endpoint-id` -Derives an -[endpointId](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) -from the OIS title and the endpoint's name as described in the -[endpoint](/reference/airnode/v0.13/concepts/endpoint.md) documentation. Add the -`endpointId` to the config.json file (`triggers.rrp[n].endpointId`). +Derives an [endpointId](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) from the OIS title and the endpoint's name as described in the [endpoint](/reference/airnode/v0.13/concepts/endpoint.md) documentation. Add the `endpointId` to the config.json file (`triggers.rrp[n].endpointId`). - `ois-title`: The title of the OIS from config.json (`ois.title`). -- `endpoint-name`: The name of the endpoint from config.json - (`triggers.rrp[n].endpointName`). +- `endpoint-name`: The name of the endpoint from config.json (`triggers.rrp[n].endpointName`). ::: code-group @@ -667,12 +510,7 @@ npx @api3/airnode-admin derive-endpoint-id ^ ### `generate-airnode-mnemonic` -Generates a unique mnemonic which can be used to create an -[airnode wallet](/reference/airnode/v0.13/concepts/airnode.md#mnemonic). In -addition to the mnemonic, this command will also display the corresponding -[airnode address](/reference/airnode/v0.13/concepts/airnode.md#airnodeaddress) -and its extended public key -([xpub](/reference/airnode/v0.13/concepts/airnode.md#xpub)). +Generates a unique mnemonic which can be used to create an [airnode wallet](/reference/airnode/v0.13/concepts/airnode.md#mnemonic). In addition to the mnemonic, this command will also display the corresponding [airnode address](/reference/airnode/v0.13/concepts/airnode.md#airnodeaddress) and its extended public key ([xpub](/reference/airnode/v0.13/concepts/airnode.md#xpub)). ```sh npx @api3/airnode-admin generate-airnode-mnemonic @@ -680,9 +518,7 @@ npx @api3/airnode-admin generate-airnode-mnemonic ### `generate-mnemonic` -Generates a unique mnemonic which can be used to create a wallet. In addition to -the mnemonic, this command will also display the corresponding default wallet -(path:m/44'/60'/0'/0/0) address. +Generates a unique mnemonic which can be used to create a wallet. In addition to the mnemonic, this command will also display the corresponding default wallet (path:m/44'/60'/0'/0/0) address. ```sh npx @api3/airnode-admin generate-mnemonic @@ -690,12 +526,7 @@ npx @api3/airnode-admin generate-mnemonic ### `derive-airnode-address` -Derives the -[airnode address](/reference/airnode/v0.13/concepts/airnode.md#airnodeaddress) -which is the identifier of the particular Airnode on chain. The address is the -default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this -identifier for many other admin CLI commands, such as -[derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address). +Derives the [airnode address](/reference/airnode/v0.13/concepts/airnode.md#airnodeaddress) which is the identifier of the particular Airnode on chain. The address is the default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this identifier for many other admin CLI commands, such as [derive-sponsor-wallet-address](/reference/airnode/v0.13/packages/admin-cli.md#derive-sponsor-wallet-address). - `airnode-mnemonic`: A mnemonic used to generate the airnode address. @@ -715,18 +546,11 @@ npx @api3/airnode-admin derive-airnode-address ^ ## RequesterAuthorizerWithAirnode -RequesterAuthorizerWithAirnode contract was written by API3 as an -[authorizer](/reference/airnode/v0.13/concepts/authorizers.md) contract that can -be used by any Airnode. Airnode owners can use this contract in addition to -authorizer contracts they have written themselves. +RequesterAuthorizerWithAirnode contract was written by API3 as an [authorizer](/reference/airnode/v0.13/concepts/authorizers.md) contract that can be used by any Airnode. Airnode owners can use this contract in addition to authorizer contracts they have written themselves. -This authorizer contract can whitelist -[requesters](/reference/airnode/v0.13/concepts/requester.md) where each Airnode -is administered by themselves. +This authorizer contract can whitelist [requesters](/reference/airnode/v0.13/concepts/requester.md) where each Airnode is administered by themselves. -These commands connect to the -[RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) -contract. +These commands connect to the [RequesterAuthorizerWithAirnode.sol](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-protocol/contracts/authorizers/RequesterAuthorizerWithAirnode.sol) contract. - [set-whitelist-expiration](/reference/airnode/v0.13/packages/admin-cli.md#set-whitelist-expiration) - [extend-whitelist-expiration](/reference/airnode/v0.13/packages/admin-cli.md#extend-whitelist-expiration) @@ -736,32 +560,20 @@ contract. ### `set-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration setter to set the -whitelisting expiration of a requester for the Airnode–endpoint pair. This can -hasten expiration in the case the new expiration timestamp is prior to a -previously set timestamp. +Called by the Airnode wallet or a whitelist expiration setter to set the whitelisting expiration of a requester for the Airnode–endpoint pair. This can hasten expiration in the case the new expiration timestamp is prior to a previously set timestamp. -- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a - `derivation-path` is specified. The mnemonic must be at least an Admin or - Airnode wallet. +- `mnemonic`: Used to pay gas costs from the mnemonic's default account unless a `derivation-path` is specified. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -790,31 +602,20 @@ npx @api3/airnode-admin set-whitelist-expiration ^ ### `extend-whitelist-expiration` -Called by the Airnode wallet or a whitelist expiration extender to extend the -whitelist expiration of a requester for the Airnode–endpoint pair. This command -expects that the new expiration timestamp is later then the previously set -timestamp. +Called by the Airnode wallet or a whitelist expiration extender to extend the whitelist expiration of a requester for the Airnode–endpoint pair. This command expects that the new expiration timestamp is later then the previously set timestamp. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -843,34 +644,21 @@ npx @api3/airnode-admin extend-whitelist-expiration ^ ### `set-indefinite-whitelist-status` -Called by the Airnode wallet or an indefinite whitelister to whitelist a -requester indefinitely for the Airnode–endpoint pair. This command can be used -to make whitelisting permanent in cases where it is needed to allow requests -even beyond the expiration period. +Called by the Airnode wallet or an indefinite whitelister to whitelist a requester indefinitely for the Airnode–endpoint pair. This command can be used to make whitelisting permanent in cases where it is needed to allow requests even beyond the expiration period. -- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The - mnemonic must be at least an Admin or Airnode wallet. The default address of - the mnemonic will be used unless a derivation-path is provided. +- `mnemonic`: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. The default address of the mnemonic will be used unless a derivation-path is provided. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `expiration-timestamp`: A unix formatted timestamp. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. -- `derivation-path (optional)`: Selects an alternate account to use from the - mnemonic rather than the default. -- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be - whitelisted indefinitely or not. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. +- `derivation-path (optional)`: Selects an alternate account to use from the mnemonic rather than the default. +- `indefinite-whitelist-status`: Whether the Airnode-endpoint pair should be whitelisted indefinitely or not. - `gas-limit` (optional): The gas limit to use for the transaction. -- `gas-price` (optional): The gas price (in gwei) to use for the transaction - (only for legacy transactions). -- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the - transaction (only for EIP-1559 transactions). -- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to - use for the transaction (only for EIP-1559 transactions). +- `gas-price` (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions). +- `max-fee` (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). +- `max-priority-fee` (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions). - `nonce` (optional): The nonce to use for the transaction. ::: code-group @@ -899,17 +687,13 @@ npx @api3/airnode-admin set-indefinite-whitelist-status ^ ### `get-whitelist-status` -Called to get the detailed whitelist status of a requester for the -Airnode–endpoint pair. +Called to get the detailed whitelist status of a requester for the Airnode–endpoint pair. - `provider-url`: A valid blockchain provider URL. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. -- `requester-authorizer-with-airnode (optional)`: The authorizer contract - address. +- `requester-authorizer-with-airnode (optional)`: The authorizer contract address. ::: code-group @@ -937,9 +721,7 @@ Called to check if a requester is whitelisted to use the Airnode–endpoint pair - `provider-url`: A valid blockchain provider URL. - `requester-authorizer-with-airnode`: The authorizer contract address. -- `endpoint-id`: The - [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) - for which permission is granted (from OIS). +- `endpoint-id`: The [`endpointId`](/reference/airnode/v0.13/deployment-files/config-json.md#triggers) for which permission is granted (from OIS). - `requester-address`: The public address of the requester contract. - `airnode-address`: The public address of the Airnode. @@ -967,8 +749,6 @@ npx @api3/airnode-admin is-requester-whitelisted ^ ## More Examples -You can find more examples in the -[test directory](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin/test) -of the `@api3-dao/airnode/package/admin` repo. +You can find more examples in the [test directory](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin/test) of the `@api3-dao/airnode/package/admin` repo. diff --git a/docs/reference/airnode/v0.13/packages/airnode-abi.md b/docs/reference/airnode/v0.13/packages/airnode-abi.md index fc4d867e..aec2fcd3 100644 --- a/docs/reference/airnode/v0.13/packages/airnode-abi.md +++ b/docs/reference/airnode/v0.13/packages/airnode-abi.md @@ -19,29 +19,15 @@ tags: # {{$frontmatter.title}} -The -[airnode-abi](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-abi) -package is a unique way to encode and decode parameters for use with Airnode. -Parameters are provided with encoding types, names and values. The types are -shortened and grouped with a version as the "header". The name/value pairs are -then grouped and encoded as the rest of the body. - -An advantage of encoding parameters this way is that parameters can be decoded -natively using the language(s) of the specific blockchain. In the case of EVM -blockchains, this means that parameters can be encoded as well as decoded in -Solidity (or Vyper), without any additional requirements. - -You can find additional documentation in -[Airnode ABI Specifications](/reference/airnode/v0.13/specifications/airnode-abi.md) -doc. +The [airnode-abi](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-abi) package is a unique way to encode and decode parameters for use with Airnode. Parameters are provided with encoding types, names and values. The types are shortened and grouped with a version as the "header". The name/value pairs are then grouped and encoded as the rest of the body. + +An advantage of encoding parameters this way is that parameters can be decoded natively using the language(s) of the specific blockchain. In the case of EVM blockchains, this means that parameters can be encoded as well as decoded in Solidity (or Vyper), without any additional requirements. + +You can find additional documentation in [Airnode ABI Specifications](/reference/airnode/v0.13/specifications/airnode-abi.md) doc. ## Installation -You can install -[@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) -with either -[npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) -or [Yarn](https://yarnpkg.com/en/docs/install) +You can install [@api3/airnode-abi](https://www.npmjs.com/package/@api3/airnode-abi?activeTab=dependencies) with either [npm](https://docs.npmjs.com/getting-started/installing-node#install-npm--manage-npm-versions) or [Yarn](https://yarnpkg.com/en/docs/install) ```sh # npm @@ -57,16 +43,13 @@ yarn add @api3/airnode-abi Accepts an array of objects with the following required keys: -1. `type` - The full list of accepted types can be found in the - [Airnode ABI](/reference/airnode/v0.13/specifications/airnode-abi.md#type-encodings) - specifications doc. +1. `type` - The full list of accepted types can be found in the [Airnode ABI](/reference/airnode/v0.13/specifications/airnode-abi.md#type-encodings) specifications doc. 2. `name` 3. `value` -It is important to note that numeric values (`int256` and `uint256`) should be -submitted as **strings** in order to preserve precision. +It is important to note that numeric values (`int256` and `uint256`) should be submitted as **strings** in order to preserve precision. ```ts import { encode } from '@api3/airnode-abi'; @@ -83,11 +66,9 @@ console.log(encodedData); ## `decode` -Returns an object where the keys are the "names" and the values are the "values" -from the initial encoding. +Returns an object where the keys are the "names" and the values are the "values" from the initial encoding. -It is important to note that `int256` and `uint256` will be decoded back to -strings. +It is important to note that `int256` and `uint256` will be decoded back to strings. ```ts import { decode } from '@api3/airnode-abi'; diff --git a/docs/reference/airnode/v0.13/packages/deployer.md b/docs/reference/airnode/v0.13/packages/deployer.md index c0abca59..92ef156f 100644 --- a/docs/reference/airnode/v0.13/packages/deployer.md +++ b/docs/reference/airnode/v0.13/packages/deployer.md @@ -19,22 +19,11 @@ tags: # {{$frontmatter.title}} -The -[airnode-deployer](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer) -package is used primarily by the -[Docker Images](/reference/airnode/v0.13/docker/). This CLI tool provides the -underlying commands used by the Docker images when deploying an Airnode. API -providers are strongly encouraged to use the -[Docker Images](/reference/airnode/v0.13/docker/) when deploying an Airnode and -not the deployer CLI commands. +The [airnode-deployer](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer) package is used primarily by the [Docker Images](/reference/airnode/v0.13/docker/). This CLI tool provides the underlying commands used by the Docker images when deploying an Airnode. API providers are strongly encouraged to use the [Docker Images](/reference/airnode/v0.13/docker/) when deploying an Airnode and not the deployer CLI commands. ## Usage -The deployer's commands can be run using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), -installing a global npm package or by manually building the airnode-deployer -package. Using npx is the simplest method to interact with the deployer manually -if you do not wish to use the Docker images. +The deployer's commands can be run using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx), installing a global npm package or by manually building the airnode-deployer package. Using npx is the simplest method to interact with the deployer manually if you do not wish to use the Docker images. - [Using npx](/reference/airnode/v0.13/packages/deployer.md#using-npx) - [Global Package](/reference/airnode/v0.13/packages/deployer.md#global-package) @@ -42,9 +31,7 @@ if you do not wish to use the Docker images. ### Using npx -The airnode-deployer package can be run as an npm package using npx. This allows -you to run deployer commands without installing the deployer npm package or -having to manually build the airnode-deployer package yourself. +The airnode-deployer package can be run as an npm package using npx. This allows you to run deployer commands without installing the deployer npm package or having to manually build the airnode-deployer package yourself. ```sh npx @api3/airnode-deployer deploy \ @@ -56,8 +43,7 @@ npx @api3/airnode-deployer deploy \ ### Global Package -The airnode-deployer package can be installed globally with yarn or npm. If -installed using yarn make sure yarn bin is added to `PATH`. +The airnode-deployer package can be installed globally with yarn or npm. If installed using yarn make sure yarn bin is added to `PATH`. ```sh yarn global add @api3/airnode-deployer @@ -120,27 +106,18 @@ cp config/secrets.env.example config/secrets.env ## Credentials -When using the `airnode-deployer` Docker image, AWS or GCP credentials are -loaded automatically. Conversely, when using the deployer CLI directly, you will -need to first load AWS or GCP credentials into the environment manually as -described below. +When using the `airnode-deployer` Docker image, AWS or GCP credentials are loaded automatically. Conversely, when using the deployer CLI directly, you will need to first load AWS or GCP credentials into the environment manually as described below. ### AWS Credentials For AWS, there are two options: -1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` - (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their - appropriate values. -2. Populate the AWS `credentials` file. See the AWS documentation for the - [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) - as well as its - [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). +1. Set the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN` as well, if using temporary credentials) to their appropriate values. +2. Populate the AWS `credentials` file. See the AWS documentation for the [expected file format](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds) as well as its [default location](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). ### GCP Credentials -Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of -the `gcp.json` credentials file. +Set the environmental variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the `gcp.json` credentials file. ## Commands @@ -153,33 +130,20 @@ the `gcp.json` credentials file. ### Airnode Deployment -When creating or updating an Airnode the `config.json` and `secrets.env` files -are needed. You can use the provided example -[config.json](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-deployer/config/config.example.json) -and -[secrets.env](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-deployer/config/secrets.example.env) -templates to get started quickly, but you will need to edit these with your own -API details and secrets. +When creating or updating an Airnode the `config.json` and `secrets.env` files are needed. You can use the provided example [config.json](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-deployer/config/config.example.json) and [secrets.env](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-deployer/config/secrets.example.env) templates to get started quickly, but you will need to edit these with your own API details and secrets. -Make sure `config.json` and `secrets.env` are available in the path for the -`--configuration` argument. +Make sure `config.json` and `secrets.env` are available in the path for the `--configuration` argument. #### deploy -When executed, the `deploy` command defaults to creating a `receipt.json` file -in the `config/` directory, although a different path can be specified using the -path and name with the `--receipt` argument. The receipt contains metadata about -the deployment and can be used to remove the Airnode. +When executed, the `deploy` command defaults to creating a `receipt.json` file in the `config/` directory, although a different path can be specified using the path and name with the `--receipt` argument. The receipt contains metadata about the deployment and can be used to remove the Airnode. -By default the deployer will save logs into the `config/logs/` directory. This -can be changed with the `--logs` argument. +By default the deployer will save logs into the `config/logs/` directory. This can be changed with the `--logs` argument. -If the deployment isn't successful, the command will try to automatically remove -deployed resources. You can disable this by running the deploy command with a -`--no-auto-remove` argument. +If the deployment isn't successful, the command will try to automatically remove deployed resources. You can disable this by running the deploy command with a `--no-auto-remove` argument. ```bash # Deploys an Airnode instance using the config.json and @@ -207,19 +171,15 @@ airnode-deployer deploy \ --logs config/logs/ ``` -See how [deploy](/reference/airnode/v0.13/docker/deployer-image.md#deploy) is -used via the AWS/GCP deployer image. +See how [deploy](/reference/airnode/v0.13/docker/deployer-image.md#deploy) is used via the AWS/GCP deployer image. ### Listing Airnodes -Once you've already deployed one or more Airnode, you can list your currently -deployed instances using the `list` command. +Once you've already deployed one or more Airnode, you can list your currently deployed instances using the `list` command. #### list -By default, the deployer will attempt to list Airnode instances from all the -supported cloud providers. You can use the `--cloud-providers` option to select -just the cloud providers you want the deployer to list from. +By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the `--cloud-providers` option to select just the cloud providers you want the deployer to list from. ```bash # Lists deployed Airnode instances @@ -239,14 +199,11 @@ airnode-deployer list airnode-deployer list --cloud-providers gcp ``` -See how [list](/reference/airnode/v0.13/docker/deployer-image.md#list) is used -via the AWS/GCP deployer image. +See how [list](/reference/airnode/v0.13/docker/deployer-image.md#list) is used via the AWS/GCP deployer image. ### Fetching deployment information -You can use the `info` command to retrieve information about existing -deployments. The retrieved information include deployment's Airnode address, -stage, Airnode version and the update history. +You can use the `info` command to retrieve information about existing deployments. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history. #### info @@ -266,8 +223,7 @@ Options: airnode-deployer info aws2c6ef2b3 ``` -See how [info](/reference/airnode/v0.13/docker/deployer-image.md#info) is used -via the AWS/GCP deployer image. +See how [info](/reference/airnode/v0.13/docker/deployer-image.md#info) is used via the AWS/GCP deployer image. ### Reverting to a previous version @@ -294,14 +250,11 @@ Options: airnode-deployer rollback aws808e2a22 5bbcd317 ``` -See how [rollback](/reference/airnode/v0.13/docker/deployer-image.md#rollback) -is used via the AWS/GCP deployer image. +See how [rollback](/reference/airnode/v0.13/docker/deployer-image.md#rollback) is used via the AWS/GCP deployer image. ### Fetching deployment files -During the Airnode deployment, your `config.json` and `secrets.env` are uploaded -to the cloud provider of your choosing. You can use the `fetch-files` command to -retrieve them. +During the Airnode deployment, your `config.json` and `secrets.env` are uploaded to the cloud provider of your choosing. You can use the `fetch-files` command to retrieve them. #### fetch-files @@ -320,19 +273,14 @@ Options: airnode-deployer fetch-files aws2c6ef2b3 ``` -See how -[fetch-files](/reference/airnode/v0.13/docker/deployer-image.md#fetch-files) is -used via the AWS/GCP deployer image. +See how [fetch-files](/reference/airnode/v0.13/docker/deployer-image.md#fetch-files) is used via the AWS/GCP deployer image. ### Airnode Removal An Airnode can be removed in two different ways: -- **Best:** With `remove`, which uses the deployment ID found either in the - [deployment receipt file](/reference/airnode/v0.13/deployment-files/receipt-json.md) - or via the `list` command. -- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt - created when the Airnode was deployed. +- **Best:** With `remove`, which uses the deployment ID found either in the [deployment receipt file](/reference/airnode/v0.13/deployment-files/receipt-json.md) or via the `list` command. +- **Alternate:** With `remove-with-receipt`, which uses the deployment receipt created when the Airnode was deployed. #### remove @@ -352,8 +300,7 @@ Options: airnode-deployer remove aws2c6ef2b3 ``` -See how [remove](/reference/airnode/v0.13/docker/deployer-image.md#remove) is -used via the AWS/GCP deployer image. +See how [remove](/reference/airnode/v0.13/docker/deployer-image.md#remove) is used via the AWS/GCP deployer image. #### remove-with-receipt @@ -376,8 +323,6 @@ airnode-deployer remove-with-receipt \ --logs config/logs/ ``` -See how -[remove-with-receipt](/reference/airnode/v0.13/docker/deployer-image.md#remove-with-receipt) -is used via the AWS/GCP deployer image. +See how [remove-with-receipt](/reference/airnode/v0.13/docker/deployer-image.md#remove-with-receipt) is used via the AWS/GCP deployer image. diff --git a/docs/reference/airnode/v0.13/packages/index.md b/docs/reference/airnode/v0.13/packages/index.md index aa006f74..9d6eb133 100644 --- a/docs/reference/airnode/v0.13/packages/index.md +++ b/docs/reference/airnode/v0.13/packages/index.md @@ -19,13 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode is a fully-serverless oracle node that is designed specifically for API -providers to operate their own oracles. Its code base is a monorepo managed -using [Lerna](https://github.com/lerna/lerna). The -[Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.13/packages) has -several packages. Some of these packages are used by dApp developers and API -providers to interact with or to build Airnode. A few are simply used for -internal Airnode development. +Airnode is a fully-serverless oracle node that is designed specifically for API providers to operate their own oracles. Its code base is a monorepo managed using [Lerna](https://github.com/lerna/lerna). The [Airnode monorepo](https://github.com/api3dao/airnode/tree/v0.13/packages) has several packages. Some of these packages are used by dApp developers and API providers to interact with or to build Airnode. A few are simply used for internal Airnode development. - [airnode-adapter](/reference/airnode/v0.13/packages/adapter.md) - [airnode-admin](/reference/airnode/v0.13/packages/admin-cli.md) @@ -36,49 +30,30 @@ internal Airnode development. **Read about each package in the monorepo.** -Airnode packages are cross platform, available as npm packages or docker -containers. You should also be able to clone, build and use the packages on any -platform. However there is no guarantee that the development only features (e.g. -test or examples) will work out of the box. It is recommend to use UNIX based -systems for development. If you are using Windows, consider -[WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). +Airnode packages are cross platform, available as npm packages or docker containers. You should also be able to clone, build and use the packages on any platform. However there is no guarantee that the development only features (e.g. test or examples) will work out of the box. It is recommend to use UNIX based systems for development. If you are using Windows, consider [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install). -- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-adapter) - The module that makes an API call, processes the response and returns a single - value. +- [airnode-adapter:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-adapter) The module that makes an API call, processes the response and returns a single value. -- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin) - A package/CLI tool to interact with the Airnode contracts across chains. +- [airnode-admin:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-admin) A package/CLI tool to interact with the Airnode contracts across chains. -- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-abi) - Encoding and decoding utilities for Airnode according to the - [Airnode ABI specifications](/reference/airnode/v0.13/specifications/airnode-abi.md). +- [airnode-abi:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-abi) Encoding and decoding utilities for Airnode according to the [Airnode ABI specifications](/reference/airnode/v0.13/specifications/airnode-abi.md). -- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer) - Tools to automate Airnode deployment. +- [airnode-deployer:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer) Tools to automate Airnode deployment. -- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples) - A public list of examples showcasing the features of Airnode. +- [airnode-examples:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples) A public list of examples showcasing the features of Airnode. -- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-node) - The node part of Airnode that allows for connecting multiple blockchains to - the rest of the world. +- [airnode-node:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-node) The node part of Airnode that allows for connecting multiple blockchains to the rest of the world. -- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-operation) - Development and testing utilities for the core parts of Airnode. +- [airnode-operation:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-operation) Development and testing utilities for the core parts of Airnode. -- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-protocol) - Contracts that implement Airnode RRP (request–response protocol). +- [**airnode-protocol**:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-protocol) Contracts that implement Airnode RRP (request–response protocol). -- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-validator) - A package that can be used to validate Airnode configuration. +- [airnode-validator:](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-validator) A package that can be used to validate Airnode configuration. ## OIS -The `airnode-ois` monorepo package was removed from the Airnode repo and is now -in its own repo (`ois`) starting with Airnode `v0.8`. +The `airnode-ois` monorepo package was removed from the Airnode repo and is now in its own repo (`ois`) starting with Airnode `v0.8`. -- [ois:](https://github.com/api3dao/ois/tree/v2.2.1) Types for - [Oracle Integration Specification (OIS)](/reference/ois/2.2/specification.md). +- [ois:](https://github.com/api3dao/ois/tree/v2.2.1) Types for [Oracle Integration Specification (OIS)](/reference/ois/2.2/specification.md). diff --git a/docs/reference/airnode/v0.13/packages/validator.md b/docs/reference/airnode/v0.13/packages/validator.md index b4313961..62bed42f 100644 --- a/docs/reference/airnode/v0.13/packages/validator.md +++ b/docs/reference/airnode/v0.13/packages/validator.md @@ -19,26 +19,13 @@ tags: # {{$frontmatter.title}} -The -[airnode-validator](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-validator) -is used internally by the [Docker Images](/reference/airnode/v0.13/docker/) to -validate the -[configuration files](/reference/airnode/v0.13/understand/configuring.md) you -provide when deploying an Airnode. - -However, validator can also be used as a standalone package to verify the -correctness of the configuration files without deploying the Airnode. The -recommended way is to use the -[validator CLI](/reference/airnode/v0.13/packages/validator.md#cli-usage), but -for advanced use cases you can use the -[validator SDK](/reference/airnode/v0.13/packages/validator.md#sdk-usage). +The [airnode-validator](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-validator) is used internally by the [Docker Images](/reference/airnode/v0.13/docker/) to validate the [configuration files](/reference/airnode/v0.13/understand/configuring.md) you provide when deploying an Airnode. + +However, validator can also be used as a standalone package to verify the correctness of the configuration files without deploying the Airnode. The recommended way is to use the [validator CLI](/reference/airnode/v0.13/packages/validator.md#cli-usage), but for advanced use cases you can use the [validator SDK](/reference/airnode/v0.13/packages/validator.md#sdk-usage). ## CLI Usage -The simplest way to run the CLI is using -[npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). -Alternatively, you can install the validator package as a dependency in your -project. +The simplest way to run the CLI is using [npx](https://www.codingninjas.com/codestudio/library/difference-between-npm-and-npx). Alternatively, you can install the validator package as a dependency in your project. ```sh npx @api3/airnode-validator --config "config.json" --secrets "secrets.env" @@ -58,8 +45,7 @@ npx airnode-validator --config "config.json" --secrets "secrets.env" ### Examples -Assuming the configurations files inside current working directory are valid, -executing: +Assuming the configurations files inside current working directory are valid, executing: ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "valid-secrets.env" @@ -71,8 +57,7 @@ yields: ✔ The configuration is valid ``` -When there is an error during validation, the command prints out the error and -fails with a non zero status code. +When there is an error during validation, the command prints out the error and fails with a non zero status code. ```sh npx @api3/airnode-validator --config "valid-config.json" --secrets "non-existent-secrets.env" @@ -86,26 +71,17 @@ yields: ## SDK Usage -The validator package contains an API that can be used to validate Airnode -configuration files programatically. +The validator package contains an API that can be used to validate Airnode configuration files programatically. The following functions can be used: -- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` and validates the interpolated configuration. Expects both `config` - and `secrets` to be JSON objects. -- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a - JSON object. -- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be - a JSON object. -- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be - a JSON object. -- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into - `config` but does not perform any validation afterwards. Use this function - only when you can guarantee that the configuration is valid. - -Validator has also full TypeScript support. All of these functions return a -typed object. +- `parseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` and validates the interpolated configuration. Expects both `config` and `secrets` to be JSON objects. +- `parseConfig(config)` - Validates the `config`. Expects the `config` to be a JSON object. +- `parseSecrets(secrets)` - Validates the `secrets`. Expects the `secrets` to be a JSON object. +- `parseReceipt(receipt)` - Validates the `receipt`. Expects the `receipt` to be a JSON object. +- `unsafeParseConfigWithSecrets(config, secrets)` - Interpolates `secrets` into `config` but does not perform any validation afterwards. Use this function only when you can guarantee that the configuration is valid. + +Validator has also full TypeScript support. All of these functions return a typed object. ### Examples @@ -148,7 +124,6 @@ if (parseResult.success) { ## Build Manually -See the build instructions for the validator in the -[airnode package repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-validator). +See the build instructions for the validator in the [airnode package repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-validator). diff --git a/docs/reference/airnode/v0.13/specifications/airnode-abi.md b/docs/reference/airnode/v0.13/specifications/airnode-abi.md index 1e501c50..45b402e2 100644 --- a/docs/reference/airnode/v0.13/specifications/airnode-abi.md +++ b/docs/reference/airnode/v0.13/specifications/airnode-abi.md @@ -19,39 +19,23 @@ tags: # {{$frontmatter.title}} -[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) -is used to encode different types of data while interacting with Ethereum -contracts. As a result, both Solidity and modules such as -[web3.js](https://web3js.readthedocs.io/) and -[ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality -as a first-class citizen. This makes using contract ABI for encoding API call -parameters a very attractive option. - -Although encoding API call parameters using contract ABI has many advantages, it -cannot be used for this purpose directly. Quoting from the -[Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): - -> The encoding is not self describing and thus requires a schema in order to -> decode. - -This means that when passing API call parameters (of type `bytes`), you would -also need to pass a list of the types for these parameters, which is cumbersome -and it is not clear how these types would be encoded. As a solution, Airnode -uses _Airnode ABI specifications_, an extension of contract ABI specifications -that includes a header that keeps the schema. +[Contract application binary interface (ABI)](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html) is used to encode different types of data while interacting with Ethereum contracts. As a result, both Solidity and modules such as [web3.js](https://web3js.readthedocs.io/) and [ethers.js](https://docs.ethers.io/) treat ABI encoding–decoding functionality as a first-class citizen. This makes using contract ABI for encoding API call parameters a very attractive option. + +Although encoding API call parameters using contract ABI has many advantages, it cannot be used for this purpose directly. Quoting from the [Solidity docs](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html): + +> The encoding is not self describing and thus requires a schema in order to decode. + +This means that when passing API call parameters (of type `bytes`), you would also need to pass a list of the types for these parameters, which is cumbersome and it is not clear how these types would be encoded. As a solution, Airnode uses _Airnode ABI specifications_, an extension of contract ABI specifications that includes a header that keeps the schema. ## Header -The Airnode ABI specifications header is of type `bytes32` and acts as the -schema (i.e., describes the types of the API call parameters). The header is -encoded in UTF-8 for ease of use. Here is an example: +The Airnode ABI specifications header is of type `bytes32` and acts as the schema (i.e., describes the types of the API call parameters). The header is encoded in UTF-8 for ease of use. Here is an example: ``` "1BSasbiuBa" ``` -The first character, `1`, represents the encoding version. Each following -character represents the type of an API call parameter. +The first character, `1`, represents the encoding version. Each following character represents the type of an API call parameter. ### Type encodings @@ -68,20 +52,11 @@ i: int256 f: bool ``` -Note that dynamically-sized types are represented with uppercase letters and -statically-sized types are represented with lowercase letters. Another thing to -notice is that `s` represents `string32`, but this is an artificial type and it -is not part of -[solidity types](https://docs.soliditylang.org/en/latest/types.html). This type -is instead represented on chain as `bytes32`. The reasons for this are explained -in depth in -[string32 details](/reference/airnode/v0.13/specifications/airnode-abi.md#string32) -section. +Note that dynamically-sized types are represented with uppercase letters and statically-sized types are represented with lowercase letters. Another thing to notice is that `s` represents `string32`, but this is an artificial type and it is not part of [solidity types](https://docs.soliditylang.org/en/latest/types.html). This type is instead represented on chain as `bytes32`. The reasons for this are explained in depth in [string32 details](/reference/airnode/v0.13/specifications/airnode-abi.md#string32) section. ## Encoding format -Airnode ABI specifications has the following encoding format (which is somewhat -similar to [SDS](https://github.com/antirez/sds)): +Airnode ABI specifications has the following encoding format (which is somewhat similar to [SDS](https://github.com/antirez/sds)): ``` [------------------------][-----------------------------------------] @@ -125,14 +100,11 @@ bytes memory parameters = abi.encode( ); ``` -Note that you do not need to add an external library to the contract, and -`abi.encode()` is fairly cheap in terms of gas usage (compared to alternative -encoding methods). +Note that you do not need to add an external library to the contract, and `abi.encode()` is fairly cheap in terms of gas usage (compared to alternative encoding methods). ## Example decoding -If you know the schema of the encoded parameters, then decode them on-chain. For -example, if the schema is `(bytes,string)`: +If you know the schema of the encoded parameters, then decode them on-chain. For example, if the schema is `(bytes,string)`: ```solidity ( @@ -142,17 +114,13 @@ example, if the schema is `(bytes,string)`: ) = abi.decode(parameters, (bytes32,bytes32,bytes,bytes32,string)); ``` -Note that this disregards the header and hard codes the schema into the code. It -is also possible to parse the header on-chain and decode accordingly, yet that -would be a lot more complex. +Note that this disregards the header and hard codes the schema into the code. It is also possible to parse the header on-chain and decode accordingly, yet that would be a lot more complex. ## Details ### `string32` -A parameter being of type `string32` (encoded as characted `s` in the ABI -specification schema header) implies that the parameter is UTF-8 encoded text. -For example, if the parameter is +A parameter being of type `string32` (encoded as characted `s` in the ABI specification schema header) implies that the parameter is UTF-8 encoded text. For example, if the parameter is ``` 0x68656c6c6f000000000000000000000000000000000000000000000000000000 @@ -164,9 +132,7 @@ Airnode will decode it as "hello" ``` -and feed that to the API, which is what the user would want to do in most cases. -This becomes a problem if the parameter is not encoded text, but for example a -hash such as: +and feed that to the API, which is what the user would want to do in most cases. This becomes a problem if the parameter is not encoded text, but for example a hash such as: ``` 0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71 @@ -179,15 +145,11 @@ If this hash is encoded as a `string32` type, Airnode will decode it as: !Õ$B˜±=/¡>q ``` -which is probably not what the user is looking for. For these use cases, the -user should use the -[`bytes32`](/reference/airnode/v0.13/specifications/airnode-abi.md#bytes32) type -instead. +which is probably not what the user is looking for. For these use cases, the user should use the [`bytes32`](/reference/airnode/v0.13/specifications/airnode-abi.md#bytes32) type instead. ### `bytes32` -To encode a `bytes32` hash on chain, use the `bytes32` type which is represented -by `b` in the ABI header schema. +To encode a `bytes32` hash on chain, use the `bytes32` type which is represented by `b` in the ABI header schema. ```solidity bytes memory parameters = abi.encode( @@ -202,46 +164,27 @@ When decoded by Airnode, the value would be the hash itself: "0x1fd36c61981313c0c155d33ffac0325bd7c00d21d52442981bb13d2fa13e8f71" ``` -If you want to store 32 byte string values on chain, use the -[`string32`](/reference/airnode/v0.13/specifications/airnode-abi.md#string32) -type instead. +If you want to store 32 byte string values on chain, use the [`string32`](/reference/airnode/v0.13/specifications/airnode-abi.md#string32) type instead. ### `bool` -The `bool` type, encoded as character `f` using the ABI specification schema can -be used to encode a boolean value. The header symbol is `f`, because character -`b` was already reserved for bytes encodings. So we chose letter `f` as bool -values are commonly used to represent "boolean flags". +The `bool` type, encoded as character `f` using the ABI specification schema can be used to encode a boolean value. The header symbol is `f`, because character `b` was already reserved for bytes encodings. So we chose letter `f` as bool values are commonly used to represent "boolean flags". ### Omitted types -`array` and `tuple` are omitted because they are not suitable to be used as API -parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because -they are padded to 32 bytes by the ABI encoder anyway (meaning that the user -should simply typecast these to the 32-byte versions). +`array` and `tuple` are omitted because they are not suitable to be used as API parameters. `uint8-uint128`, `int8-int128`, `bytes1-bytes31` are omitted because they are padded to 32 bytes by the ABI encoder anyway (meaning that the user should simply typecast these to the 32-byte versions). ### Size limit -The header can encode up to 31 parameters (and 1 byte is used to encode the -encoding version). This is far more than what would be needed in practice, and -thus is tolerated to avoid a more complex solution. +The header can encode up to 31 parameters (and 1 byte is used to encode the encoding version). This is far more than what would be needed in practice, and thus is tolerated to avoid a more complex solution. ### Padding -[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) -is used so that you can decode the values later on. This means that each -parameter will be padded with zeros to complete them to 32 bytes. Although this -padding increases gas costs, ABI encoding/decoding functions being cheap -balances this. Furthermore, the -[template](/reference/airnode/v0.13/concepts/template.md) pattern used in the -protocols allows for the referencing of these encoded parameters without -explicitly passing them in requests, making the increased cost induced by -padding irrelevant in most cases. +[Strict encoding mode](https://docs.soliditylang.org/en/v0.6.12/abi-spec.html#strict-encoding-mode) is used so that you can decode the values later on. This means that each parameter will be padded with zeros to complete them to 32 bytes. Although this padding increases gas costs, ABI encoding/decoding functions being cheap balances this. Furthermore, the [template](/reference/airnode/v0.13/concepts/template.md) pattern used in the protocols allows for the referencing of these encoded parameters without explicitly passing them in requests, making the increased cost induced by padding irrelevant in most cases. ## `@api3/airnode-abi` -Encode and decode parameters with the -[airnode-abi](/reference/airnode/v0.13/packages/airnode-abi.md) package. +Encode and decode parameters with the [airnode-abi](/reference/airnode/v0.13/packages/airnode-abi.md) package. ```js import { encode } from '@api3/airnode-abi'; @@ -258,13 +201,6 @@ console.log('ENCODED:', encodedData); console.log('\nDECODED:', decoded); ``` -See the package doc -[airnode-abi](/reference/airnode/v0.13/packages/airnode-abi.md) for more -information on how to encode and decode with Airnode ABI off-chain. Also see -code samples in the -[examples](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples) -package. Lastly see the file -[request-utils.ts](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) -for example syntax on encoding parameters. +See the package doc [airnode-abi](/reference/airnode/v0.13/packages/airnode-abi.md) for more information on how to encode and decode with Airnode ABI off-chain. Also see code samples in the [examples](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples) package. Lastly see the file [request-utils.ts](https://github.com/api3dao/airnode/blob/v0.13/packages/airnode-examples/integrations/coingecko/request-utils.ts#L9) for example syntax on encoding parameters. diff --git a/docs/reference/airnode/v0.13/specifications/ois.md b/docs/reference/airnode/v0.13/specifications/ois.md index c52a1123..033e6b4c 100644 --- a/docs/reference/airnode/v0.13/specifications/ois.md +++ b/docs/reference/airnode/v0.13/specifications/ois.md @@ -19,13 +19,8 @@ tags: # {{$frontmatter.title}} -The `ois` JSON object, in the `config.json` file that defines an Airnode, is an -integral part of an Airnode's understanding of an API's specification and its -endpoints. OIS provide a description of API endpoints and maps Airnode endpoints -to them. There can be more than one OIS object in the `config.json` file as -Airnode can serve endpoints from more than one API. - -Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/2.2/) -in its versioned document set. +The `ois` JSON object, in the `config.json` file that defines an Airnode, is an integral part of an Airnode's understanding of an API's specification and its endpoints. OIS provide a description of API endpoints and maps Airnode endpoints to them. There can be more than one OIS object in the `config.json` file as Airnode can serve endpoints from more than one API. + +Learn more about [Oracle Integration Specifications (OIS)](/reference/ois/2.2/) in its versioned document set. diff --git a/docs/reference/airnode/v0.13/specifications/reserved-parameters.md b/docs/reference/airnode/v0.13/specifications/reserved-parameters.md index af549469..361cbfd2 100644 --- a/docs/reference/airnode/v0.13/specifications/reserved-parameters.md +++ b/docs/reference/airnode/v0.13/specifications/reserved-parameters.md @@ -19,10 +19,6 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an Airnode's defined endpoints in an -[Oracle Integration Specifications (OIS)](/reference/ois/2.2/) object. They do -not map to operation parameters and are used by Airnode for special purposes. -See the [Reserved Parameters](/reference/ois/2.2/reserved-parameters.md) doc in -the OIS document set for an in-depth explanation. +Reserved parameters are part of an Airnode's defined endpoints in an [Oracle Integration Specifications (OIS)](/reference/ois/2.2/) object. They do not map to operation parameters and are used by Airnode for special purposes. See the [Reserved Parameters](/reference/ois/2.2/reserved-parameters.md) doc in the OIS document set for an in-depth explanation. diff --git a/docs/reference/airnode/v0.13/understand/api-integration.md b/docs/reference/airnode/v0.13/understand/api-integration.md index 4b119634..fd0846ca 100644 --- a/docs/reference/airnode/v0.13/understand/api-integration.md +++ b/docs/reference/airnode/v0.13/understand/api-integration.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -A successful integration of an API with an Airnode requires the mapping of each -other's interface. This is accomplished using an OIS -([Oracle Integration Specifications](/reference/ois/2.2/specification.md)) json -object, found in the config.json file, designed to with three basic steps. +A successful integration of an API with an Airnode requires the mapping of each other's interface. This is accomplished using an OIS ([Oracle Integration Specifications](/reference/ois/2.2/specification.md)) json object, found in the config.json file, designed to with three basic steps. 1. API operations are specified 1. Airnode endpoints are specified @@ -34,60 +31,36 @@ object, found in the config.json file, designed to with three basic steps. > >

The OIS object in config.json contains mapping information of API operations to Airnode endpoint definitions.

-OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode -endpoints. When a requester contract calls one of the AirnodeRrpV0.sol -contract's request functions, such as `makeFullRequest(..., callData)`, the -callData is communicated to the off-chain Airnode which uses OIS mappings to -translate the callData into a valid HTTP request for the appropriate API -operation. +OIS is a mapping of API operations, such as `GET /coins/{id}`, to Airnode endpoints. When a requester contract calls one of the AirnodeRrpV0.sol contract's request functions, such as `makeFullRequest(..., callData)`, the callData is communicated to the off-chain Airnode which uses OIS mappings to translate the callData into a valid HTTP request for the appropriate API operation. -OIS borrows formatting from -[OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). -If you have experience with OAS, OIS will seem familiar. +OIS borrows formatting from [OAS OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). If you have experience with OAS, OIS will seem familiar. ::: info OAS -It is not recommended to refer to OAS for help while creating your OIS object. -OIS only borrows formatting practices from OAS. Everything needed to create an -OIS object is in these docs. +It is not recommended to refer to OAS for help while creating your OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: **Tips while reading ths page.** -- Open the [OIS template](/reference/ois/2.2/template.md) in another browser - window to follow along. -- View an example of an Airnode - [config.json](/reference/airnode/v0.13/deployment-files/examples/config-json.md) - file. +- Open the [OIS template](/reference/ois/2.2/template.md) in another browser window to follow along. +- View an example of an Airnode [config.json](/reference/airnode/v0.13/deployment-files/examples/config-json.md) file. ## OIS Template -OIS is a json object that is added to an Airnode's -[config.json](/reference/airnode/v0.13/deployment-files/templates/config-json.md) -file as the (`ois`) _key_, sometimes called a _field_. Try using the -[OIS template](/reference/ois/2.2/template.md) to construct an OIS and add it to -the Airnode's config.json file later. +OIS is a json object that is added to an Airnode's [config.json](/reference/airnode/v0.13/deployment-files/templates/config-json.md) file as the (`ois`) _key_, sometimes called a _field_. Try using the [OIS template](/reference/ois/2.2/template.md) to construct an OIS and add it to the Airnode's config.json file later. -In the OIS template, there are some fields that contain `{FILL_*}`. This means -that the value added is independent from other fields. On the other hand, if two -fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), -you must use the same value in them, because they are referencing each other. +In the OIS template, there are some fields that contain `{FILL_*}`. This means that the value added is independent from other fields. On the other hand, if two fields contain the same expression (e.g., `{FILL_OPERATION_PARAMETER_1_NAME}`), you must use the same value in them, because they are referencing each other. -OIS uses a simplified version of the OAS. This means that if you have the -OpenAPI specifications of the API that you are going to integrate, you are about -80% done, because you can copy paste entire sections (but be sure to make the -necessary modifications to conform to the OIS format). +OIS uses a simplified version of the OAS. This means that if you have the OpenAPI specifications of the API that you are going to integrate, you are about 80% done, because you can copy paste entire sections (but be sure to make the necessary modifications to conform to the OIS format). -The remainder of this page will assume you do not have the OpenAPI -specifications of the API that you will be integrating. +The remainder of this page will assume you do not have the OpenAPI specifications of the API that you will be integrating. ## 1. Specify OIS Definitions -Start building an OIS by adding three descriptive fields to the root of the OIS -json object. +Start building an OIS by adding three descriptive fields to the root of the OIS json object. ```json { @@ -100,20 +73,15 @@ json object. ### oisFormat -A specific version of the -[OIS Specification](/reference/ois/2.2/specification.md#_1-oisformat) to be -used. For Airnode `v0.13`, the proper OIS version is `2.2.1`. +A specific version of the [OIS Specification](/reference/ois/2.2/specification.md#_1-oisformat) to be used. For Airnode `v0.13`, the proper OIS version is `2.2.1`. ### title -This is a unique title of the OIS. Note that an Airnode can be configured with -more than one OIS object and uses the title as the OIS identifier. +This is a unique title of the OIS. Note that an Airnode can be configured with more than one OIS object and uses the title as the OIS identifier. ### version -This is the version of the OIS which allows for version-control of the OIS -integration. It is recommended to use [semver](https://semver.org/) versioning. -The initial version could be `0.1.0`. +This is the version of the OIS which allows for version-control of the OIS integration. It is recommended to use [semver](https://semver.org/) versioning. The initial version could be `0.1.0`. @@ -134,15 +102,11 @@ The `apiSpecifications` field is used to describe the API and its operations. ### Servers -The first step of specifying an API is to enter its _baseURL_ in the -`apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed -in the `apiSpecifications.servers` array. A warning is raised during conversion -if servers has multiple elements. This baseURL will apply to all operations. +The first step of specifying an API is to enter its _baseURL_ in the `apiSpecifications.servers[0].url` field. Only one object (i.e., url) is allowed in the `apiSpecifications.servers` array. A warning is raised during conversion if servers has multiple elements. This baseURL will apply to all operations. #### Choosing a Base URL -Consider the following full URL to execute an API operation that returns all -know tokens. +Consider the following full URL to execute an API operation that returns all know tokens. @@ -164,16 +128,11 @@ or > > **path:** `/data` -Because the call will be made to <`baseURL+path`> both will result in the same -full URL. +Because the call will be made to <`baseURL+path`> both will result in the same full URL. -Set the baseURL as the section of the full URL that you expect to be shared by -all operations. From the examples above it is recommended to use -`https://www.myapi.com`, in case additional paths starting with `/v2` get added -to the API in the future. As you can tell, API integration requires many -subjective choices, and is more art than science. +Set the baseURL as the section of the full URL that you expect to be shared by all operations. From the examples above it is recommended to use `https://www.myapi.com`, in case additional paths starting with `/v2` get added to the API in the future. As you can tell, API integration requires many subjective choices, and is more art than science. ```json "apiSpecifications": { @@ -188,20 +147,15 @@ subjective choices, and is more art than science. ### Paths -The _paths_ field defines all the API operations much like an OpenAPI -Specification file. +The _paths_ field defines all the API operations much like an OpenAPI Specification file. _What is an API operation?_ -> An API operation is specified as a unique combination of a _**path**_ and an -> HTTP _**method**_. `GET /token/{id}` +> An API operation is specified as a unique combination of a _**path**_ and an HTTP _**method**_. `GET /token/{id}` #### Operations -In the examples below, `GET` refers to an -[HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). -This implies that you could have another API operation that can be specified -using a different method but the same path. +In the examples below, `GET` refers to an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). This implies that you could have another API operation that can be specified using a different method but the same path. > path: /data > @@ -211,18 +165,11 @@ using a different method but the same path. > > method: POST -Therefore, a path is not enough to specify an API operation by itself, you must -also provide a method. If a new path is needed then it must be a new object in -paths with its own methods. Currently only the GET and POST methods are -supported by Airnode. +Therefore, a path is not enough to specify an API operation by itself, you must also provide a method. If a new path is needed then it must be a new object in paths with its own methods. Currently only the GET and POST methods are supported by Airnode. -With regards to the [OIS template](/reference/ois/2.2/template.md), the name of -the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., -`/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the -operation to integrate (e.g., `get`). The method must be lowercase. +With regards to the [OIS template](/reference/ois/2.2/template.md), the name of the element (denoted as `{FILL_PATH}`) should be replaced with the path (e.g., `/data`). Similarly, `{FILL_METHOD}` should be replaced with the method of the operation to integrate (e.g., `get`). The method must be lowercase. -The following example illustrates three operations, `GET /data`, `POST /data`, -`GET /tokens`. +The following example illustrates three operations, `GET /data`, `POST /data`, `GET /tokens`. ```json "paths": { @@ -244,27 +191,16 @@ The following example illustrates three operations, `GET /data`, `POST /data`, #### Parameters (operation) -After specifying the path and method of an API operation, the final step is to -specify its parameters. Each parameter is an object in the -`apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` -and `name`. `in` tells where the parameter goes in the HTTP request and `name` -tells the name that the parameter value will be sent under. Currently Airnode -supports the following parameter types for use with `in`. +After specifying the path and method of an API operation, the final step is to specify its parameters. Each parameter is an object in the `apiSpecifications.paths.{PATH}.{METHOD}.parameters` array, with the fields `in` and `name`. `in` tells where the parameter goes in the HTTP request and `name` tells the name that the parameter value will be sent under. Currently Airnode supports the following parameter types for use with `in`. - query - header - path - cookie -When integrating a POST method, define the body parameters with `in: query`. -Airnode will convert all `query` types into the `requestBody`. Note that only -the non-nested application/json content-type is supported. +When integrating a POST method, define the body parameters with `in: query`. Airnode will convert all `query` types into the `requestBody`. Note that only the non-nested application/json content-type is supported. -It is not necessary to specify all API operation parameters, but only the ones -the on-chain requester will need to be able to provide (see Airnode endpoint -[parameters](/reference/airnode/v0.13/understand/api-integration.md#parameters)), -and the ones needed to hard-code a value for (see Airnode endpoint -[fixed operation parameters](/reference/airnode/v0.13/understand/api-integration.md#fixedoperationparameters)). +It is not necessary to specify all API operation parameters, but only the ones the on-chain requester will need to be able to provide (see Airnode endpoint [parameters](/reference/airnode/v0.13/understand/api-integration.md#parameters)), and the ones needed to hard-code a value for (see Airnode endpoint [fixed operation parameters](/reference/airnode/v0.13/understand/api-integration.md#fixedoperationparameters)). ```json "paths": { @@ -287,8 +223,7 @@ and the ones needed to hard-code a value for (see Airnode endpoint _Example: Get a token_ -The `GET /token/{id}` returns a token using the token's `id` which is a `path` -parameter. +The `GET /token/{id}` returns a token using the token's `id` which is a `path` parameter. | Method | Path | in | name | | ------ | ----------- | ---- | ---- | @@ -296,11 +231,7 @@ parameter. _Example: Create a token_ -The `POST /token` operation accepts three parameters. The name and description -of the token are placed in the type `query` and will be moved by Airnode to the -requestBody upon calling the API operation. The third is a `header` parameter -that describes the Content-Type of the request such as `application/json` or -`application/x-www-form-urlencoded`. +The `POST /token` operation accepts three parameters. The name and description of the token are placed in the type `query` and will be moved by Airnode to the requestBody upon calling the API operation. The third is a `header` parameter that describes the Content-Type of the request such as `application/json` or `application/x-www-form-urlencoded`. | Method | Path | in | name | | ------ | ------ | ------ | ----------- | @@ -310,9 +241,7 @@ that describes the Content-Type of the request such as `application/json` or _Example: Get all tokens_ -The `GET /tokens` returns a list of all tokens. The list count can be limited -using the `limit' parameter which the API operation considers as optional since -it will not return an error if omitted. +The `GET /tokens` returns a list of all tokens. The list count can be limited using the `limit' parameter which the API operation considers as optional since it will not return an error if omitted. > `GET /tokens` returns all tokens. > @@ -326,66 +255,25 @@ it will not return an error if omitted. ## 3. Specifying Airnode Endpoints -An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It -maps to an API operation, but the nature of this mapping is customizable. It is -the integrator's job to define what this service is. - -For example, if an API operation returns an asset price given its ticker (e.g., -`BTC`), specify the endpoint such that the requester provides the ticker as a -parameter. The resulting endpoint would be a general one that returns prices for -any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price -will be returned (using -[fixed operation parameters](/reference/airnode/v0.13/understand/api-integration.md#fixedoperationparameters)), -which would make the endpoint a specific one that only returns the BTC price. - -The recommended endpoint definition pattern is to create an Airnode endpoint for -each API operation, and allow the requesters to provide all operation parameters -themselves. This results in optimal flexibility, and essentially allows the -requesters to use the entire API functionality on-chain. Normally, competitor -oracle integrations strive to hard-code as many API parameters as possible -because passing these parameters on-chain results in a gas cost overhead. -However, the Airnode protocol uses -[templates](/reference/airnode/v0.13/concepts/template.md) (not to be confused -with the OIS template used for this guide), which allow requesters to specify a -large number of endpoint parameters at no additional gas cost. - -Note that there are some cases where you may not want to map endpoints to API -operations one-to-one. For example, an API operation can have a `header` -parameter, `Accept`, that can take the values `application/json` or -`application/xml` to determine how to format the data that the API will respond -to the call. Airnode expects responses to be in JSON format, and thus -hard-coding this parameter as `JSON` would be more suitable than letting the -requester decide, as there is only one valid choice. Again, the integrator's job -is to be aware of these subtleties and use judgement. +An Airnode endpoint is a service that Airnode exposes to on-chain requesters. It maps to an API operation, but the nature of this mapping is customizable. It is the integrator's job to define what this service is. + +For example, if an API operation returns an asset price given its ticker (e.g., `BTC`), specify the endpoint such that the requester provides the ticker as a parameter. The resulting endpoint would be a general one that returns prices for any kind of asset. On the other hand, hardcoding `BTC` as the asset whose price will be returned (using [fixed operation parameters](/reference/airnode/v0.13/understand/api-integration.md#fixedoperationparameters)), which would make the endpoint a specific one that only returns the BTC price. + +The recommended endpoint definition pattern is to create an Airnode endpoint for each API operation, and allow the requesters to provide all operation parameters themselves. This results in optimal flexibility, and essentially allows the requesters to use the entire API functionality on-chain. Normally, competitor oracle integrations strive to hard-code as many API parameters as possible because passing these parameters on-chain results in a gas cost overhead. However, the Airnode protocol uses [templates](/reference/airnode/v0.13/concepts/template.md) (not to be confused with the OIS template used for this guide), which allow requesters to specify a large number of endpoint parameters at no additional gas cost. + +Note that there are some cases where you may not want to map endpoints to API operations one-to-one. For example, an API operation can have a `header` parameter, `Accept`, that can take the values `application/json` or `application/xml` to determine how to format the data that the API will respond to the call. Airnode expects responses to be in JSON format, and thus hard-coding this parameter as `JSON` would be more suitable than letting the requester decide, as there is only one valid choice. Again, the integrator's job is to be aware of these subtleties and use judgement. ### Endpoints array -The field `endpoints` is an array, with each row representing an Airnode -endpoint. The first field to fill in is `name`. Make sure that it is descriptive -and unique from other endpoint names. If you are integrating API operations to -Airnode endpoints one-to-one, using the API operation path as the endpoint name -is a decent choice (i.e., `/token`). Note that you would also add the method to -this name if there were multiple operations with different methods for a single -path (i.e., `GET/token`). +The field `endpoints` is an array, with each row representing an Airnode endpoint. The first field to fill in is `name`. Make sure that it is descriptive and unique from other endpoint names. If you are integrating API operations to Airnode endpoints one-to-one, using the API operation path as the endpoint name is a decent choice (i.e., `/token`). Note that you would also add the method to this name if there were multiple operations with different methods for a single path (i.e., `GET/token`). -The next step is to fill in `operation` object. Here, you need to enter the -`path` and `method` of an API operation you have defined in -`apiSpecifications.paths`, resulting in the Airnode endpoint calling the now -linked API operation. +The next step is to fill in `operation` object. Here, you need to enter the `path` and `method` of an API operation you have defined in `apiSpecifications.paths`, resulting in the Airnode endpoint calling the now linked API operation. #### fixedOperationParameters -It is not uncommon to hard-code API parameters (recall the `Accept` operation -parameter in the above example). Such hard-coded parameters are called -`fixedOperationParameters`. +It is not uncommon to hard-code API parameters (recall the `Accept` operation parameter in the above example). Such hard-coded parameters are called `fixedOperationParameters`. -In the OIS template there is a fixed operation parameter under -`endpoints[n].fixedOperationParameters`, and it refers to the first API -operation parameter. This means that whenever the Airnode receives a request for -this endpoint, the respective API call will be made with that API operation -parameter set to -endpoints[n].fixedOperationParameters[n].value. -The requester does not supply a value for `fixedOperationParameters`. +In the OIS template there is a fixed operation parameter under `endpoints[n].fixedOperationParameters`, and it refers to the first API operation parameter. This means that whenever the Airnode receives a request for this endpoint, the respective API call will be made with that API operation parameter set to endpoints[n].fixedOperationParameters[n].value. The requester does not supply a value for `fixedOperationParameters`. ```json "fixedOperationParameters": [ @@ -400,31 +288,17 @@ The requester does not supply a value for `fixedOperationParameters`. ``` -An Airnode endpoint can have multiple `fixedOperationParameters`. An API -operation parameter cannot be in both `endpoints[n].fixedOperationParameters` -and `endpoints[n].parameters`. +An Airnode endpoint can have multiple `fixedOperationParameters`. An API operation parameter cannot be in both `endpoints[n].fixedOperationParameters` and `endpoints[n].parameters`. #### reservedParameters -The requester can provide some parameters that are not mapped to API operation -parameters. These parameters are called "reserved parameters", and their names -start with an underscore. See the -[related OIS docs](/reference/ois/2.2/specification.md#_5-4-reservedparameters) -for more information. +The requester can provide some parameters that are not mapped to API operation parameters. These parameters are called "reserved parameters", and their names start with an underscore. See the [related OIS docs](/reference/ois/2.2/specification.md#_5-4-reservedparameters) for more information. -The current list of reserved parameters are `_type`, `_path`, `_times`, -`_gasPrice`, and `_minConfirmations`. See -[Reserved Parameters](/reference/ois/2.2/reserved-parameters.md) in the OIS -document set to understand what each of these parameters are for. +The current list of reserved parameters are `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. See [Reserved Parameters](/reference/ois/2.2/reserved-parameters.md) in the OIS document set to understand what each of these parameters are for. #### parameters -Airnode endpoint -[parameters](/reference/ois/2.2/specification.md#_5-5-parameters) map to API -operation [parameters](/reference/ois/2.2/specification.md#_4-2-1-parameters) -that the requester is allowed to provide values for. It refers to an API -operation through its field `operationParameter`. You can also provide `default` -values for endpoint parameters, though this is not recommended in most cases. +Airnode endpoint [parameters](/reference/ois/2.2/specification.md#_5-5-parameters) map to API operation [parameters](/reference/ois/2.2/specification.md#_4-2-1-parameters) that the requester is allowed to provide values for. It refers to an API operation through its field `operationParameter`. You can also provide `default` values for endpoint parameters, though this is not recommended in most cases. ```json // apiSpecifications.paths...parameters[1] @@ -460,27 +334,14 @@ Mapping between API parameters and endpoint parameters. │ │ ] ``` -Endpoint parameters have a `name` field, which does not have to be the same as -the API operation parameter that they map to. As a separate note, an Airnode -endpoint can have multiple parameters. +Endpoint parameters have a `name` field, which does not have to be the same as the API operation parameter that they map to. As a separate note, an Airnode endpoint can have multiple parameters. ## Conclusion -The API operations and Airnode endpoints are now specified. Each Airnode -endpoint maps to an API operation, and each Airnode endpoint parameter or -fixedOperationParameter maps to an API operation parameter. The resulting OIS -includes no user-specific information, which means that you can share it for -others to easily provide the same services (for example, to set up a third-party -oracle network). - -Note that there was some subjectivity while defining the Airnode endpoints. This -means that two different OISes can exist for the same exact API, differing based -on how the integrators designed the interface that the requester will use. -However, in most cases, one would simply map API operations to Airnode endpoints -directly, and let the requester provide all API operation parameters through the -Airnode endpoint parameters. - -Now that you have an OIS object, the next step is -[API Security](/reference/airnode/v0.13/understand/api-security.md). +The API operations and Airnode endpoints are now specified. Each Airnode endpoint maps to an API operation, and each Airnode endpoint parameter or fixedOperationParameter maps to an API operation parameter. The resulting OIS includes no user-specific information, which means that you can share it for others to easily provide the same services (for example, to set up a third-party oracle network). + +Note that there was some subjectivity while defining the Airnode endpoints. This means that two different OISes can exist for the same exact API, differing based on how the integrators designed the interface that the requester will use. However, in most cases, one would simply map API operations to Airnode endpoints directly, and let the requester provide all API operation parameters through the Airnode endpoint parameters. + +Now that you have an OIS object, the next step is [API Security](/reference/airnode/v0.13/understand/api-security.md). diff --git a/docs/reference/airnode/v0.13/understand/api-security.md b/docs/reference/airnode/v0.13/understand/api-security.md index 77402e50..87651944 100644 --- a/docs/reference/airnode/v0.13/understand/api-security.md +++ b/docs/reference/airnode/v0.13/understand/api-security.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Airnode can pass along security information (schemes) when making calls to API -operations. There are two groups of security schemes. +Airnode can pass along security information (schemes) when making calls to API operations. There are two groups of security schemes. - [Airnode Authentication](/reference/airnode/v0.13/concepts/airnode-auth.md) - [Relayed Meta Data Authentication](/reference/airnode/v0.13/concepts/relay-meta-auth.md) @@ -31,8 +30,7 @@ operations. There are two groups of security schemes. > 1.

The Airnode uses Airnode Authentication Security Schemes to authenticate itself to an API operation of which the values are known only by the Airnode.

> 2.

The Airnode uses Relayed Meta Data Security Schemes to forward known information from the requester's request to an API operation.

-Security schemes are declared by the required `type` property inside the -security scheme definition. The following security scheme types are supported. +Security schemes are declared by the required `type` property inside the security scheme definition. The following security scheme types are supported. - Airnode Authentication Security Schemes - apiKey @@ -46,22 +44,16 @@ security scheme definition. The following security scheme types are supported. - relaySponsorWalletAddress - relayRequestId -It is important to note that the security schemes in any given OIS object apply -to all endpoints/API operations in the OIS object. If different security schemes -are required by a mix of endpoints/API operations, then more than one OIS object -will be required grouping endpoint/API operations based on their security needs. +It is important to note that the security schemes in any given OIS object apply to all endpoints/API operations in the OIS object. If different security schemes are required by a mix of endpoints/API operations, then more than one OIS object will be required grouping endpoint/API operations based on their security needs. ## Airnode Authentication Security Schemes -An Airnode can use the following security scheme types to authenticate itself to -API operations. +An Airnode can use the following security scheme types to authenticate itself to API operations. - [apiKey](/reference/airnode/v0.13/understand/api-security.md#apikey) - [http](/reference/airnode/v0.13/understand/api-security.md#http) -A security scheme requires a unique name within the OIS object for which it -exists. This name groups the security scheme values for `in`, `type`, and` name` -as shown in the two code examples below. +A security scheme requires a unique name within the OIS object for which it exists. This name groups the security scheme values for `in`, `type`, and` name` as shown in the two code examples below. - `securitySchemes.` - `security.` @@ -69,18 +61,12 @@ as shown in the two code examples below. ### apiKey -The `apiKey` security scheme type allows you to define an API key the Airnode -will send to API operations. It is an object which consists of the following -fields: +The `apiKey` security scheme type allows you to define an API key the Airnode will send to API operations. It is an object which consists of the following fields: - `type` must be `apiKey` -- `in` can be one of the `query`, `header` or `cookie`. This value specifies how - the value will be sent to an API operation. When using the `query` option, the - API key will be sent in the request body for POST requests and in query string - for GET requests. +- `in` can be one of the `query`, `header` or `cookie`. This value specifies how the value will be sent to an API operation. When using the `query` option, the API key will be sent in the request body for POST requests and in query string for GET requests. -- `name` is the name of the API key that should be sent to an API. For example - "X-Api-Key". +- `name` is the name of the API key that should be sent to an API. For example "X-Api-Key". ```json "ois": [ @@ -108,11 +94,7 @@ fields: ] │ ``` -The value of the `apiKey` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `apiKey` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json "apiCredentials": [ │ @@ -126,11 +108,7 @@ file. ### http -The `http` security scheme type is used to define either a `basic` or `bearer` -authentication scheme. This security scheme will always be sent in the headers. -The security scheme value should be base64 encoded value "username:password" for -`basic` auth and the encoded token for `bearer` auth. It is an object which -consists of the following fields: +The `http` security scheme type is used to define either a `basic` or `bearer` authentication scheme. This security scheme will always be sent in the headers. The security scheme value should be base64 encoded value "username:password" for `basic` auth and the encoded token for `bearer` auth. It is an object which consists of the following fields: - `type` must be `http` - `scheme` is either `basic` or `bearer` @@ -144,11 +122,7 @@ consists of the following fields: } ``` -The value of the `http` goes in the `apiCredentials` field of `config.json` -designated by the proper `oisTitle` and `securitySchemeName` values, which is -not part of the `ois` object, it exists in the root level of the `config.json` -file. Normally the value is accessed using interpolation from the `secrets.env` -file. +The value of the `http` goes in the `apiCredentials` field of `config.json` designated by the proper `oisTitle` and `securitySchemeName` values, which is not part of the `ois` object, it exists in the root level of the `config.json` file. Normally the value is accessed using interpolation from the `secrets.env` file. ```json { @@ -160,19 +134,13 @@ file. ::: info Authentication Tutorial -The -[authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates authentication. +The [authenticated-coinmarketcap](/guides/airnode/monorepo-examples.md) monorepo example demonstrates authentication. ::: ## Relayed Meta Data Security Schemes -In addition to authenticating itself, Airnode can "relay" security information -about a request to an API operation. This is different then the authorization of -requesters using -[Authorizers](/reference/airnode/v0.13/understand/apply-auth.md) to access the -Airnode. +In addition to authenticating itself, Airnode can "relay" security information about a request to an API operation. This is different then the authorization of requesters using [Authorizers](/reference/airnode/v0.13/understand/apply-auth.md) to access the Airnode. - [relayRequesterAddress](/reference/airnode/v0.13/understand/api-security.md#relayrequesteraddress) - [relayChainId](/reference/airnode/v0.13/understand/api-security.md#relaychainid) @@ -181,29 +149,19 @@ Airnode. - [relaySponsorWalletAddress](/reference/airnode/v0.13/understand/api-security.md#relaysponsorwalletaddress) - [relayRequestId](/reference/airnode/v0.13/understand/api-security.md#relayrequestid) -For relayed meta data security schemes do not provide any values in -[apiCredentials](/reference/airnode/v0.13/deployment-files/config-json.md#apicredentials) -as they are extracted from the request by Airnode. +For relayed meta data security schemes do not provide any values in [apiCredentials](/reference/airnode/v0.13/deployment-files/config-json.md#apicredentials) as they are extracted from the request by Airnode. -Note that Airnode relays this metadata to an API operation and does not perform -any additional processing logic. The API provider must implement any desired -logic in the API operation for any desired security checks. See -[Relayed Meta Data Authentication](/reference/airnode/v0.13/concepts/relay-meta-auth.md) -for overview of its usage. +Note that Airnode relays this metadata to an API operation and does not perform any additional processing logic. The API provider must implement any desired logic in the API operation for any desired security checks. See [Relayed Meta Data Authentication](/reference/airnode/v0.13/concepts/relay-meta-auth.md) for overview of its usage. ::: info Relay Metadata Tutorial -The -[relay-security-schemes](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates how to relay request metadata like chain ID and -sponsor address to the API endpoint. +The [relay-security-schemes](/guides/airnode/monorepo-examples.md) monorepo example demonstrates how to relay request metadata like chain ID and sponsor address to the API endpoint. ::: ### relayRequesterAddress -The `relayRequesterAddress` security scheme type instructs Airnode to forward -the [requester](/reference/airnode/v0.13/concepts/requester.md) address. +The `relayRequesterAddress` security scheme type instructs Airnode to forward the [requester](/reference/airnode/v0.13/concepts/requester.md) address. ```json { @@ -215,8 +173,7 @@ the [requester](/reference/airnode/v0.13/concepts/requester.md) address. ### relayChainId -The `relayChainId` security scheme type instructs Airnode to forward the chain's -ID. +The `relayChainId` security scheme type instructs Airnode to forward the chain's ID. ```json { @@ -228,8 +185,7 @@ ID. ### relayChainType -The `relayChainType` security scheme type instructs Airnode to forward the -chain's type. +The `relayChainType` security scheme type instructs Airnode to forward the chain's type. ```json { @@ -241,8 +197,7 @@ chain's type. ### relaySponsorAddress -The `relaySponsorAddress` security scheme type instructs Airnode to forward the -[sponsor address](/reference/airnode/v0.13/concepts/sponsor.md#sponsoraddress). +The `relaySponsorAddress` security scheme type instructs Airnode to forward the [sponsor address](/reference/airnode/v0.13/concepts/sponsor.md#sponsoraddress). ```json { @@ -254,9 +209,7 @@ The `relaySponsorAddress` security scheme type instructs Airnode to forward the ### relaySponsorWalletAddress -The `relaySponsorWalletAddress` security scheme type instructs Airnode to -forward the -[sponsor wallet address](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). +The `relaySponsorWalletAddress` security scheme type instructs Airnode to forward the [sponsor wallet address](/reference/airnode/v0.13/concepts/sponsor.md#sponsorwallet). ```json { @@ -268,8 +221,7 @@ forward the ### relayRequestId -The `relayRequestId` security scheme type instructs Airnode to forward the -[id of the request](/reference/airnode/v0.13/concepts/request.md#requestid). +The `relayRequestId` security scheme type instructs Airnode to forward the [id of the request](/reference/airnode/v0.13/concepts/request.md#requestid). ```json { @@ -279,10 +231,7 @@ The `relayRequestId` security scheme type instructs Airnode to forward the } ``` -The following example shows how to set up relayed meta data to forward the -`relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that -unlike the Airnode authentication security scheme, no values are stored in -`apiCredentials` as Airnode passes these known values to the API operation. +The following example shows how to set up relayed meta data to forward the `relayRequestId` and `relayChainId` from Airnode to an AP operation. Note that unlike the Airnode authentication security scheme, no values are stored in `apiCredentials` as Airnode passes these known values to the API operation. ```json "ois": [ @@ -318,29 +267,19 @@ unlike the Airnode authentication security scheme, no values are stored in ::: info Remember -The relayed meta data security schemes do not require a supplied value. Values -will be provided (relayed) by Airnode depending on the particular request. +The relayed meta data security schemes do not require a supplied value. Values will be provided (relayed) by Airnode depending on the particular request. ::: ## Example -OIS security is inspired by OAS security practices. This is implemented using -the security schemes and security field. All supported security schemes are -described in detail in the -[Airnode Authentication Security Schemes](/reference/airnode/v0.13/understand/api-security.md#airnode-authentication-security-schemes) -and -[Relayed Meta Data Security Schemes](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes) -sections above. The following example is related to _Airnode Authentication -Security Schemes_. Working with security schemes can be described in three -steps. +OIS security is inspired by OAS security practices. This is implemented using the security schemes and security field. All supported security schemes are described in detail in the [Airnode Authentication Security Schemes](/reference/airnode/v0.13/understand/api-security.md#airnode-authentication-security-schemes) and [Relayed Meta Data Security Schemes](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes) sections above. The following example is related to _Airnode Authentication Security Schemes_. Working with security schemes can be described in three steps. 1. [Define the security schemes for an OIS](/reference/airnode/v0.13/understand/api-security.md#step-1-define-the-security-schemes-for-an-ois) 2. [Turn on the defined security schemes](/reference/airnode/v0.13/understand/api-security.md#step-2-turn-on-the-defined-security-schemes) 3. [Specify the values for the defined security schemes](/reference/airnode/v0.13/understand/api-security.md#step-3-specify-the-values-for-the-defined-security-schemes) -Following is an example of a partial `config.json` which demonstrates the usage -of security scheme and security field. +Following is an example of a partial `config.json` which demonstrates the usage of security scheme and security field. ```json { @@ -377,60 +316,34 @@ of security scheme and security field. ### Step #1: Define the security schemes for an OIS -Use -ois[n].apiSpecifications.components.securitySchemes -to define the security schemes the API operation requires. Consider the partial -`config.json` above that declares a security scheme named `requiresXApiKey`. -This scheme declares that the API requires an API key that must exist in the -HTTP header named `X-api-key`. +Use ois[n].apiSpecifications.components.securitySchemes to define the security schemes the API operation requires. Consider the partial `config.json` above that declares a security scheme named `requiresXApiKey`. This scheme declares that the API requires an API key that must exist in the HTTP header named `X-api-key`. ### Step #2: Turn on the defined security schemes -When the scheme is defined, it is not turned on by default. You need to -explicitly list the security schemes you intend to use in the `security` field -located in `ois[n].apiSpecifications.security` object. The keys in this object -are the names of security schemes to be used. Use empty array (`[]`) as its -value. +When the scheme is defined, it is not turned on by default. You need to explicitly list the security schemes you intend to use in the `security` field located in `ois[n].apiSpecifications.security` object. The keys in this object are the names of security schemes to be used. Use empty array (`[]`) as its value. -_Be aware that this step seems like extra work since there is no reason to -define a security scheme that will not be used. However, Airnode may support -[more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) -logic in the future and using `[]` allows its implementation without a breaking -change._ +_Be aware that this step seems like extra work since there is no reason to define a security scheme that will not be used. However, Airnode may support [more complex authentication](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object) logic in the future and using `[]` allows its implementation without a breaking change._ ### Step #3: Specify the values for the defined security schemes -After defining and turning on a security scheme, it may be unclear what provides -the value and how it is set. +After defining and turning on a security scheme, it may be unclear what provides the value and how it is set. -The authentication schemes are intended to be common for the whole OIS and set -by the API provider using `apiCredentials` which is part of `config.json`. The -`apiCredentials` is an array which specifies the values for all security schemes -in all OIS definitions. Each element of this array contains the following fields +The authentication schemes are intended to be common for the whole OIS and set by the API provider using `apiCredentials` which is part of `config.json`. The `apiCredentials` is an array which specifies the values for all security schemes in all OIS definitions. Each element of this array contains the following fields - `oisTitle` is the title of the OIS for the particular security scheme - `securitySchemeName` is the name of the security scheme -- `securitySchemeValue` is the actual value that should be used by Airnode when - making the API request. This value is usually a secret and it is recommended - to interpolate it from `secrets.env`. +- `securitySchemeValue` is the actual value that should be used by Airnode when making the API request. This value is usually a secret and it is recommended to interpolate it from `secrets.env`. ## Using Different Security Schemes -Currently, if you want different API operations to use different security -schemes they must be grouped in different OIS objects based on their common -security schemes. For example, your API has four operations, three require an -API key in the HTTP header, another (public `/ping` endpoint) requires no -security. +Currently, if you want different API operations to use different security schemes they must be grouped in different OIS objects based on their common security schemes. For example, your API has four operations, three require an API key in the HTTP header, another (public `/ping` endpoint) requires no security. -- The first three API operations might be in the `ois[0]` object with a security - scheme named _requiresXApiKey_ of type _apiKey_ as shown above. -- The /ping API operation would be in `ois[1]` which would not have any - `component.securitySchemes` and `security` would be an empty array. +- The first three API operations might be in the `ois[0]` object with a security scheme named _requiresXApiKey_ of type _apiKey_ as shown above. +- The /ping API operation would be in `ois[1]` which would not have any `component.securitySchemes` and `security` would be an empty array. ## Multiple Security Schemes -You can use multiple security schemes (e.g., an API key goes in the header, and -an additional secret goes in the query). +You can use multiple security schemes (e.g., an API key goes in the header, and an additional secret goes in the query). ```json // inside ois[n].apiSpecifications. @@ -456,7 +369,6 @@ an additional secret goes in the query). ## No Security -If the API you are integrating is publicly accessible, you can set both the -`security schemes` and `security` fields to empty objects. +If the API you are integrating is publicly accessible, you can set both the `security schemes` and `security` fields to empty objects. diff --git a/docs/reference/airnode/v0.13/understand/apply-auth.md b/docs/reference/airnode/v0.13/understand/apply-auth.md index 2101f1f1..25b5d3a6 100644 --- a/docs/reference/airnode/v0.13/understand/apply-auth.md +++ b/docs/reference/airnode/v0.13/understand/apply-auth.md @@ -19,51 +19,29 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using [Authorizers](/reference/airnode/v0.13/concepts/authorizers.md). -This method is on-chain and requires some blockchain knowledge by an API -provider. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizers](/reference/airnode/v0.13/concepts/authorizers.md). This method is on-chain and requires some blockchain knowledge by an API provider. ## What is an authorizer? -An [Authorizer](/reference/airnode/v0.13/concepts/authorizers.md) is a contract -which typically checks for a single condition ("has the requester made their -monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers -can be combined to enforce more complex policies. If any of the authorizers in -the list gives access, the request will considered to be authorized. From a -logical standpoint, the authorization outcomes get *OR*ed. +An [Authorizer](/reference/airnode/v0.13/concepts/authorizers.md) is a contract which typically checks for a single condition ("has the requester made their monthly payment", "is this `requesterAddress` whitelisted", etc.). Authorizers can be combined to enforce more complex policies. If any of the authorizers in the list gives access, the request will considered to be authorized. From a logical standpoint, the authorization outcomes get *OR*ed. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: ## How to implement authorizers. -When you deploy your Airnode a receipt file is generated which contains the -Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use -`airnodeAddress` and an `endpointId` to make requests to your Airnode's -endpoints. However, rather than serve them publicly, you may want to: +When you deploy your Airnode a receipt file is generated which contains the Airnode's `airnodeAddress`. Sponsors (via their sponsored requesters) use `airnodeAddress` and an `endpointId` to make requests to your Airnode's endpoints. However, rather than serve them publicly, you may want to: -- Only serve your own - [requester contracts](/reference/airnode/v0.13/developers/requesters-sponsors.md). +- Only serve your own [requester contracts](/reference/airnode/v0.13/developers/requesters-sponsors.md). - Only serve sponsors who have made a subscription payment. - Only serve sponsors who have gone through KYC. -The `chains[n].authorizers` object within `config.json` enables requests to be -authorized in a variety of ways and even across chains. Currently, the -authorizers include `requesterEndpointAuthorizers`, -`crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and -`crossChainRequesterAuthorizersWithErc721`. +The `chains[n].authorizers` object within `config.json` enables requests to be authorized in a variety of ways and even across chains. Currently, the authorizers include `requesterEndpointAuthorizers`, `crossChainRequesterAuthorizers`, `requesterAuthorizersWithErc721`, and `crossChainRequesterAuthorizersWithErc721`. -Note that when all `chains[n].authorizers` values are empty arrays, all requests -are authorized, but still can be filtered by using -[Relayed Meta Data Security Schemes](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes). +Note that when all `chains[n].authorizers` values are empty arrays, all requests are authorized, but still can be filtered by using [Relayed Meta Data Security Schemes](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes). Below are examples of how to use the authorizers. @@ -122,23 +100,11 @@ Below are examples of how to use the authorizers. ## Using `RequesterAuthorizerWithAirnode` -A common use case for an authorizer is the -[RequesterAuthorizerWithAirnode](/reference/airnode/v0.13/concepts/authorizers.md#requesterauthorizerwithairnode) -authorizer contract developed for Airnode operators to use right out-of-the-box. -It allows the whitelisting of requester contracts (with or without expiration -timestamps) on a per endpoint basis. Endpoints are declared in the -`ois.endpoints` field of the `config.json` file. This is the most common use -case and can be implemented with the following steps: - -1. Add the RequesterAuthorizerWithAirnode - [authorizer contract address](/reference/airnode/v0.13/#requesterauthorizerwithairnode) - to the array `chains[n].authorizers.requesterEndpointAuthorizers`. -2. After your Airnode is deployed, call the Admin CLI command - [set-whitelist-expiration](/reference/airnode/v0.13/packages/admin-cli.md#set-whitelist-expiration) - to add the desired requester contract addresses to the whitelist maintained - by RequesterAuthorizerWithAirnode. - -Once implemented, only requester contract addresses you have added to -RequesterAuthorizerWithAirnode will have access to your Airnode. +A common use case for an authorizer is the [RequesterAuthorizerWithAirnode](/reference/airnode/v0.13/concepts/authorizers.md#requesterauthorizerwithairnode) authorizer contract developed for Airnode operators to use right out-of-the-box. It allows the whitelisting of requester contracts (with or without expiration timestamps) on a per endpoint basis. Endpoints are declared in the `ois.endpoints` field of the `config.json` file. This is the most common use case and can be implemented with the following steps: + +1. Add the RequesterAuthorizerWithAirnode [authorizer contract address](/reference/airnode/v0.13/#requesterauthorizerwithairnode) to the array `chains[n].authorizers.requesterEndpointAuthorizers`. +2. After your Airnode is deployed, call the Admin CLI command [set-whitelist-expiration](/reference/airnode/v0.13/packages/admin-cli.md#set-whitelist-expiration) to add the desired requester contract addresses to the whitelist maintained by RequesterAuthorizerWithAirnode. + +Once implemented, only requester contract addresses you have added to RequesterAuthorizerWithAirnode will have access to your Airnode. diff --git a/docs/reference/airnode/v0.13/understand/configuring.md b/docs/reference/airnode/v0.13/understand/configuring.md index 5bf734bc..a2fccff9 100644 --- a/docs/reference/airnode/v0.13/understand/configuring.md +++ b/docs/reference/airnode/v0.13/understand/configuring.md @@ -19,12 +19,7 @@ tags: # {{$frontmatter.title}} -An Airnode is deployed or redeployed using configuration values from its -`config.json` and `secrets.env` files. The `config.json` specifies the -[Oracle Integration Specifications OIS](/reference/ois/2.2/specification.md) and -other specific configuration details. The `secrets.env` file holds secrets, such -as API keys and chain provider URLs, which are referenced within the config.json -file using interpolation. +An Airnode is deployed or redeployed using configuration values from its `config.json` and `secrets.env` files. The `config.json` specifies the [Oracle Integration Specifications OIS](/reference/ois/2.2/specification.md) and other specific configuration details. The `secrets.env` file holds secrets, such as API keys and chain provider URLs, which are referenced within the config.json file using interpolation. > > @@ -41,11 +36,7 @@ The following example files are useful while reading this doc. ## Creating `config.json` -Use the -[config.json template](/reference/airnode/v0.13/deployment-files/templates/config-json.md) -to build your own Airnode configuration file or alter the -[config.json example](/reference/airnode/v0.13/deployment-files/examples/config-json.md) -file. There are six root level fields in `config.json`. +Use the [config.json template](/reference/airnode/v0.13/deployment-files/templates/config-json.md) to build your own Airnode configuration file or alter the [config.json example](/reference/airnode/v0.13/deployment-files/examples/config-json.md) file. There are six root level fields in `config.json`. - [chains](/reference/airnode/v0.13/understand/configuring.md#chains) - [nodeSettings](/reference/airnode/v0.13/understand/configuring.md#nodesettings) @@ -56,15 +47,7 @@ file. There are six root level fields in `config.json`. ### chains -Each row in the `chains` array represents an Ethereum blockchain the Airnode -will serve as identified by the `id`. Currently Airnode only supports Ethereum -blockchains as denoted by `type: "evm"`. There are several supported -blockchains, see them in the -[Airnode contract addresses](/reference/airnode/v0.13/) doc. You can use -multiple chain providers for each chain and declare multiple chains each with -one of more chain providers. See -[Chains Providers](/reference/airnode/v0.13/concepts/chain-providers.md) in -_Concepts and Definitions_. +Each row in the `chains` array represents an Ethereum blockchain the Airnode will serve as identified by the `id`. Currently Airnode only supports Ethereum blockchains as denoted by `type: "evm"`. There are several supported blockchains, see them in the [Airnode contract addresses](/reference/airnode/v0.13/) doc. You can use multiple chain providers for each chain and declare multiple chains each with one of more chain providers. See [Chains Providers](/reference/airnode/v0.13/concepts/chain-providers.md) in _Concepts and Definitions_. Below is a simple chain array with a single chain provider. @@ -128,42 +111,26 @@ Below is a simple chain array with a single chain provider. ::: info Idiosyncrasies -See the dedicated -[Chain Idiosyncrasies](/reference/airnode/v0.13/chain-idiosyncrasies.md) -page for chain-specific configuration considerations. +See the dedicated [Chain Idiosyncrasies](/reference/airnode/v0.13/chain-idiosyncrasies.md) page for chain-specific configuration considerations. ::: #### Considerations: Gas Price Oracle -The gas price oracle strategies are applied in the order that they are listed. -Airnode supports four strategies: `latestBlockPercentileGasPrice`, -`providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and -`constantGasPrice`. The only required strategy is `constantGasPrice` and it is -recommended to place it as the last strategy in the list as it should be the -final fallback for the Airnode to use if all other strategies fail. For more -detail on these strategies, see the -[Gas Price Strategies](/reference/airnode/v0.13/concepts/gas-prices.md) page. +The gas price oracle strategies are applied in the order that they are listed. Airnode supports four strategies: `latestBlockPercentileGasPrice`, `providerRecommendedGasPrice`, `providerRecommendedEip1559GasPrice` and `constantGasPrice`. The only required strategy is `constantGasPrice` and it is recommended to place it as the last strategy in the list as it should be the final fallback for the Airnode to use if all other strategies fail. For more detail on these strategies, see the [Gas Price Strategies](/reference/airnode/v0.13/concepts/gas-prices.md) page. #### Considerations: Concurrency -If you set the `maxConcurrency` field to value X, then Airnode will guarantee -that: +If you set the `maxConcurrency` field to value X, then Airnode will guarantee that: - At most X api calls are made to the API -- At most X transactions (made by blockchain providers) will be made by the - blockchain providers of the respective chain +- At most X transactions (made by blockchain providers) will be made by the blockchain providers of the respective chain -When doing this, Airnode will calculate the total number of requests reported by -all blockchain providers. If this number exceeds the maximum concurrency limit, -Airnode will start processing the oldest request from the blockchain providers -until the number of processed requests reaches the limit. All other requests are -dropped and will be processed in the next Airnode run. +When doing this, Airnode will calculate the total number of requests reported by all blockchain providers. If this number exceeds the maximum concurrency limit, Airnode will start processing the oldest request from the blockchain providers until the number of processed requests reaches the limit. All other requests are dropped and will be processed in the next Airnode run. Note that this request dropping happens for each **chain** separately. -For example, if `maxConcurrency` is set to 5 and there are three providers (A, B -and C) and they reported the following requests: +For example, if `maxConcurrency` is set to 5 and there are three providers (A, B and C) and they reported the following requests: - A1, A2, A3, A4 and A5 - B1, B2 and B3 @@ -173,17 +140,13 @@ The above example results in the following requests: A1, A2, B1, B2, and C1. ::: warning -Note, that this limit only applies to the requests initiated on chain. For -example, requests initiated using HTTP gateway are not included in this limit. -Also note that, this limit is configured per chain and the limits of different -chains are unrelated to each other. +Note, that this limit only applies to the requests initiated on chain. For example, requests initiated using HTTP gateway are not included in this limit. Also note that, this limit is configured per chain and the limits of different chains are unrelated to each other. ::: #### References: `chains` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [authorizers](/reference/airnode/v0.13/deployment-files/config-json.md#authorizers) - [id](/reference/airnode/v0.13/deployment-files/config-json.md#id) @@ -233,26 +196,15 @@ The `nodeSettings` field holds node-specific (Airnode) configuration parameters. #### Considerations: Cloud Providers -Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are -supported cloud providers for hosting Airnode. Note that while many fields -within `nodeSettings` are required by both, there are some cloud provider -specific fields. For example, `cloudProvider.projectId` is only required with -GCP. Also note that not all cloud provider regions can be deployed to; see the -[cloudProvider.region reference](/reference/airnode/v0.13/deployment-files/config-json.md#cloudprovider-region) -for more information. +Currently, Amazon Web Services (AWS) and Google Cloud Platform (GCP) are supported cloud providers for hosting Airnode. Note that while many fields within `nodeSettings` are required by both, there are some cloud provider specific fields. For example, `cloudProvider.projectId` is only required with GCP. Also note that not all cloud provider regions can be deployed to; see the [cloudProvider.region reference](/reference/airnode/v0.13/deployment-files/config-json.md#cloudprovider-region) for more information. #### Considerations: Gateways -Airnode offers two gateways for accessing provider HTTP endpoints without using -the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information -on each of these see the -[HTTP Gateways](/reference/airnode/v0.13/understand/http-gateways.md) -documentation. Also note that that distinct API keys must be used for each. +Airnode offers two gateways for accessing provider HTTP endpoints without using the blockchain: `httpGateway` and `httpSignedDataGateway`. For more information on each of these see the [HTTP Gateways](/reference/airnode/v0.13/understand/http-gateways.md) documentation. Also note that that distinct API keys must be used for each. #### References: `nodeSettings` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [cloudProvider](/reference/airnode/v0.13/deployment-files/config-json.md#cloudprovider) - [cloudProvider.type](/reference/airnode/v0.13/deployment-files/config-json.md#cloudprovider-type) @@ -279,15 +231,9 @@ Files section: ### triggers -The `triggers` field allow exposes Airnode endpoints from an OIS selectively for -the RRP protocol or via the HTTP gateway. For example, an OIS object may include -10 endpoints, but only two are desired for RRP and all 10 for the gateway. +The `triggers` field allow exposes Airnode endpoints from an OIS selectively for the RRP protocol or via the HTTP gateway. For example, an OIS object may include 10 endpoints, but only two are desired for RRP and all 10 for the gateway. -List the endpoints to serve with the request–response protocol (RRP) under -`triggers.rrp`. List the endpoints to serve with the HTTP gateway under -`triggers.http`. List the endpoints which can be used to get the signed data in -`triggers.httpSignedData`. In most cases create a trigger for each endpoint in -your OIS object. +List the endpoints to serve with the request–response protocol (RRP) under `triggers.rrp`. List the endpoints to serve with the HTTP gateway under `triggers.http`. List the endpoints which can be used to get the signed data in `triggers.httpSignedData`. In most cases create a trigger for each endpoint in your OIS object. ```json "triggers": { @@ -318,65 +264,38 @@ your OIS object. #### Considerations: triggers -The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived -from the `oisTitle` and `endpointName` using the CLI command -[derive-endpoint-id](/reference/airnode/v0.13/packages/admin-cli.md#derive-endpoint-id). -Remember that an Airnode's config.json file can have more than one OIS object -and that these endpoints can be triggers for `rrp`, `http`, and/or -`httpSignedData` as desired. +The `endpointId` required for `rrp`, `http`, and `httpSignedData` can be derived from the `oisTitle` and `endpointName` using the CLI command [derive-endpoint-id](/reference/airnode/v0.13/packages/admin-cli.md#derive-endpoint-id). Remember that an Airnode's config.json file can have more than one OIS object and that these endpoints can be triggers for `rrp`, `http`, and/or `httpSignedData` as desired. #### Considerations: cached responses -When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API -responses on the local filesystem per request ID. This only applies to -blockchain requests. The flow is: +When setting `triggers.rrp[n].cacheResponses` to `true`, Airnode caches API responses on the local filesystem per request ID. This only applies to blockchain requests. The flow is: 1. A request is received from the Blockchain. 1. The Airnode does an HTTP/S call to a remote API based on the request. -1. [with caching enabled] Airnode stores the response on the local filesystem by - request ID. -1. Airnode then follows the usual process of extracting the response, - post-processing it and sending the response back on chain as a fulfillment - callback. -1. After all current requests are processed, Airnode then exits until the next - cycle (the next minute). -1. If during the next cycle, if the Airnode gets the same request and it isn't - fulfilled, it will try and fulfill the request again. Ordinarily, without - caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with - caching enabled it will fulfill the response using the cached API response - value. - -Clearance of the local filesystem cache is dependant on the environment Airnode -runs in. As a guideline: +1. [with caching enabled] Airnode stores the response on the local filesystem by request ID. +1. Airnode then follows the usual process of extracting the response, post-processing it and sending the response back on chain as a fulfillment callback. +1. After all current requests are processed, Airnode then exits until the next cycle (the next minute). +1. If during the next cycle, if the Airnode gets the same request and it isn't fulfilled, it will try and fulfill the request again. Ordinarily, without caching enabled, it would follow steps 1, 2 and 4 (as shown above), but with caching enabled it will fulfill the response using the cached API response value. + +Clearance of the local filesystem cache is dependant on the environment Airnode runs in. As a guideline: - AWS Lambda persists for 2.5 hours. - Google Cloud persistence is completely arbitrary. - Docker persists as long as the container remains running. -If the local filesystem is cleared, the cache is lost and if a repeat request is -received after the cache has been cleared, Airnode will repeat the API call. -Airnode self-clears cached data after the data has reached 1 hour's age. +If the local filesystem is cleared, the cache is lost and if a repeat request is received after the cache has been cleared, Airnode will repeat the API call. Airnode self-clears cached data after the data has reached 1 hour's age. -Furthermore, as an example: "if an Airnode AWS Lambda environment/container" -(since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours -and Airnode gets a request, that request will only be cached until the container -resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. +Furthermore, as an example: "if an Airnode AWS Lambda environment/container" (since this example of 2.5 hrs is specific to AWS) has been "warm" for 2.4 hours and Airnode gets a request, that request will only be cached until the container resets, in this case 2.5 hours - 2.4 hours = 0.1 hours. -As described above, caching on serverless infrastructure is unreliable and if -request caching is mission critical, Airnode should be run in a Docker container -with a persistent `/tmp` directory. +As described above, caching on serverless infrastructure is unreliable and if request caching is mission critical, Airnode should be run in a Docker container with a persistent `/tmp` directory. -Caching is useful for non-idempotent API operations like random number -generators. Consider the following use-case: +Caching is useful for non-idempotent API operations like random number generators. Consider the following use-case: -> Random Numbers: in the absence of caching, a malicious blockchain provider can -> selectively block fulfillments containing numbers they don't like, allowing -> them to improve their odds of winning in a random-number betting game. +> Random Numbers: in the absence of caching, a malicious blockchain provider can selectively block fulfillments containing numbers they don't like, allowing them to improve their odds of winning in a random-number betting game. #### References: `triggers` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [rrp](/reference/airnode/v0.13/deployment-files/config-json.md#rrp) - [rrp[n].endpointId](/reference/airnode/v0.13/deployment-files/config-json.md#rrp-n-endpointid) @@ -394,13 +313,11 @@ Files section: ### templates -The templates field allows you to specify templates to be used to make template -requests. The array can be left empty if no templates will be used. +The templates field allows you to specify templates to be used to make template requests. The array can be left empty if no templates will be used. #### References: templates -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [templateId](/reference/airnode/v0.13/deployment-files/config-json.md#templateid) - [endpointId](/reference/airnode/v0.13/deployment-files/config-json.md#endpointid) @@ -408,23 +325,11 @@ Files section: ### ois -The `ois` field is a list OIS objects that Airnode will be serving. This means -that a single instance of an Airnode can serve multiple APIs. You can simply -copy paste OIS objects that you will be serving into the `ois` list. Use the -previous guide -[API Integration](/reference/airnode/v0.13/understand/api-integration.md) to -create an OIS object. The full specification is available in the -[Oracle Integration Specifications (OIS)](/reference/ois/2.2/) documentation. +The `ois` field is a list OIS objects that Airnode will be serving. This means that a single instance of an Airnode can serve multiple APIs. You can simply copy paste OIS objects that you will be serving into the `ois` list. Use the previous guide [API Integration](/reference/airnode/v0.13/understand/api-integration.md) to create an OIS object. The full specification is available in the [Oracle Integration Specifications (OIS)](/reference/ois/2.2/) documentation. ### apiCredentials -Each entry in `apiCredentials` maps to a security scheme defined in an OIS -(`ois[n].components.securitySchemes.{securitySchemeName}` and -`ois[n].security`), where `oisTitle` is the `title` field of the related OIS, -and `securitySchemeName` is the name of the respective security scheme. These -would be `myOisTitle` and `mySecurityScheme` in the example below. -`securitySchemeValue` is the value used for the authentication with the security -scheme (e.g., the API key). +Each entry in `apiCredentials` maps to a security scheme defined in an OIS (`ois[n].components.securitySchemes.{securitySchemeName}` and `ois[n].security`), where `oisTitle` is the `title` field of the related OIS, and `securitySchemeName` is the name of the respective security scheme. These would be `myOisTitle` and `mySecurityScheme` in the example below. `securitySchemeValue` is the value used for the authentication with the security scheme (e.g., the API key). If no security scheme is needed, leave the `apiCredentials` array empty. @@ -461,14 +366,11 @@ If no security scheme is needed, leave the `apiCredentials` array empty. #### Considerations: apiCredentials -Currently Airnode supports the following security scheme types when making API -calls: `apiKey` and `http`. For more detail, visit the previous section on -[API Security](/reference/airnode/v0.13/understand/api-security.md). +Currently Airnode supports the following security scheme types when making API calls: `apiKey` and `http`. For more detail, visit the previous section on [API Security](/reference/airnode/v0.13/understand/api-security.md). #### References: `apiCredentials` -The links below offer additional details for each field from the Deployment -Files section: +The links below offer additional details for each field from the Deployment Files section: - [oisTitle](/reference/airnode/v0.13/deployment-files/config-json.md#oistitle) - [securitySchemeName](/reference/airnode/v0.13/deployment-files/config-json.md#securityschemename) @@ -476,10 +378,7 @@ Files section: ## Creating `secrets.env` -The `secrets.env` file contains values (secrets) such as blockchain provider -urls, chain provider urls, etc. These secrets are embedded in -[config.json](/reference/airnode/v0.13/deployment-files/config-json.md) using -interpolation. +The `secrets.env` file contains values (secrets) such as blockchain provider urls, chain provider urls, etc. These secrets are embedded in [config.json](/reference/airnode/v0.13/deployment-files/config-json.md) using interpolation. ```json // Sample interpolation value from config.json @@ -493,25 +392,15 @@ interpolation. HEARTBEAT_API_KEY="d714a900-3b9e-4e4d-8eae-756ef06a8836" ``` -Use the -[secrets.env](/reference/airnode/v0.13/deployment-files/templates/secrets-env.md) -template and refer to -[Reference > Deployment Files > secrets.env](/reference/airnode/v0.13/deployment-files/secrets-env.md) -as needed. +Use the [secrets.env](/reference/airnode/v0.13/deployment-files/templates/secrets-env.md) template and refer to [Reference > Deployment Files > secrets.env](/reference/airnode/v0.13/deployment-files/secrets-env.md) as needed. ## AWS setup (AWS deployment only) -When it is time to deploy the Airnode to AWS, the Docker -[deployer image](/reference/airnode/v0.13/docker/deployer-image.md) will need -the AWS credentials to build the node on AWS Lambda. +When it is time to deploy the Airnode to AWS, the Docker [deployer image](/reference/airnode/v0.13/docker/deployer-image.md) will need the AWS credentials to build the node on AWS Lambda. ### Creating `aws.env` (AWS only) -Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It -explains how to create an IAM user and get security credentials. Put them in the -`aws.env` file as shown below. See an -[example file](/reference/airnode/v0.13/deployment-files/templates/aws-env.md) -in the reference section. +Follow [this video](https://www.youtube.com/watch?v=KngM5bfpttA) if needed. It explains how to create an IAM user and get security credentials. Put them in the `aws.env` file as shown below. See an [example file](/reference/airnode/v0.13/deployment-files/templates/aws-env.md) in the reference section. - Variable names cannot contain dashes (-) or start with a number. @@ -522,46 +411,26 @@ AWS_SECRET_ACCESS_KEY=ABC7...89 ## GCP setup (GCP deployment only) -When it is time to deploy the Airnode to GCP, the Docker -[deployer image](/reference/airnode/v0.13/docker/deployer-image.md) will need -the GCP project ID to build the Airnode. +When it is time to deploy the Airnode to GCP, the Docker [deployer image](/reference/airnode/v0.13/docker/deployer-image.md) will need the GCP project ID to build the Airnode. ### Creating a GCP project -First -[create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) -under which will the Airnode be deployed. Once the project is created, insert -its -[projectId](/reference/airnode/v0.13/deployment-files/config-json.md#cloudprovider) -into the `config.json` file. +First [create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) under which will the Airnode be deployed. Once the project is created, insert its [projectId](/reference/airnode/v0.13/deployment-files/config-json.md#cloudprovider) into the `config.json` file. ### Enable required API -In order for Airnode to deploy successfully, enable -[App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) -for the GCP project. After enabling it, wait a few minutes before the deployment -itself so the change will take place. +In order for Airnode to deploy successfully, enable [App Engine Admin API](https://console.cloud.google.com/apis/library/appengine.googleapis.com) for the GCP project. After enabling it, wait a few minutes before the deployment itself so the change will take place. ### Creating a Service Account -Create a new service account from the -[Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) -menu. Grant this service account access to the project by adding a role `Owner` -during the creation process. +Create a new service account from the [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) menu. Grant this service account access to the project by adding a role `Owner` during the creation process. -Once the account is created, add a new access key of type JSON for this account. -Download the key file as `gcp.json` into the root of your project. +Once the account is created, add a new access key of type JSON for this account. Download the key file as `gcp.json` into the root of your project. ## Summary -In this guide you created the `config.json`, `secrets.env` and obtained cloud -provider credentials required to deploy an Airnode to a cloud provider. Note -that `config.json` is user-specific and therefore it is not much use to others. +In this guide you created the `config.json`, `secrets.env` and obtained cloud provider credentials required to deploy an Airnode to a cloud provider. Note that `config.json` is user-specific and therefore it is not much use to others. -The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider -urls and security credentials, so they should be kept secret. Make sure that you -do not push your credentials to a repository or otherwise expose them as these -credentials can be used to gain access to your Airnode's private key, AWS -account or GCP account. +The `secrets.env`, `aws.env` and `gcp.json` files contains keys, chain provider urls and security credentials, so they should be kept secret. Make sure that you do not push your credentials to a repository or otherwise expose them as these credentials can be used to gain access to your Airnode's private key, AWS account or GCP account. diff --git a/docs/reference/airnode/v0.13/understand/deploying.md b/docs/reference/airnode/v0.13/understand/deploying.md index a3f87972..beeb0cbc 100644 --- a/docs/reference/airnode/v0.13/understand/deploying.md +++ b/docs/reference/airnode/v0.13/understand/deploying.md @@ -19,49 +19,21 @@ tags: # {{$frontmatter.title}} -After integrating an API -([API Integration](/reference/airnode/v0.13/understand/api-integration.md)) and -creating the configuration files -([Configuring Airnode](/reference/airnode/v0.13/understand/configuring.md)), the -next step is to deploy the Airnode. +After integrating an API ([API Integration](/reference/airnode/v0.13/understand/api-integration.md)) and creating the configuration files ([Configuring Airnode](/reference/airnode/v0.13/understand/configuring.md)), the next step is to deploy the Airnode. ## Deploy with Docker -The recommended way to deploy Airnode is by using the Docker -[deployer image](/reference/airnode/v0.13/docker/deployer-image.md). This image -is simply a wrapper around the -[deployer CLI](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer). -Try the -[Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) -tutorial if you wish to become familiar with the deployer image first. There are -also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a -[client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as -well as several repo based examples in the -[Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.13.0/packages/airnode-examples) -package. - -The deployer interacts with a cloud provider to deploy Airnode programmatically, -without requiring you to click through a lot of ever-changing graphical -interfaces. For it to do so, a cloud project setup and credentials are required -and was discussed in -[Configuring an Airnode](/reference/airnode/v0.13/understand/configuring.md#aws-setup-aws-deployment-only). -There is additional guidance in the AWS and GCP quick start tutorials mentioned -above. +The recommended way to deploy Airnode is by using the Docker [deployer image](/reference/airnode/v0.13/docker/deployer-image.md). This image is simply a wrapper around the [deployer CLI](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-deployer). Try the [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/) tutorial if you wish to become familiar with the deployer image first. There are also tutorials for [GCP](/guides/airnode/deploy-airnode/deploy-gcp/) and a [client Docker container](/guides/airnode/deploy-airnode/deploy-container/) as well as several repo based examples in the [Airnode monorepo example](https://github.com/api3dao/airnode/tree/v0.13.0/packages/airnode-examples) package. + +The deployer interacts with a cloud provider to deploy Airnode programmatically, without requiring you to click through a lot of ever-changing graphical interfaces. For it to do so, a cloud project setup and credentials are required and was discussed in [Configuring an Airnode](/reference/airnode/v0.13/understand/configuring.md#aws-setup-aws-deployment-only). There is additional guidance in the AWS and GCP quick start tutorials mentioned above. ## Install Docker -The [deployer image](/reference/airnode/v0.13/docker/deployer-image.md) is -containerized as a Docker image. This will deploy the Airnode to the cloud -provider without the worry of installing dependencies and is the recommended way -to do a deployment. If you do not already have docker installed go to the -[Docker website](https://docs.docker.com/get-docker/) and install it. +The [deployer image](/reference/airnode/v0.13/docker/deployer-image.md) is containerized as a Docker image. This will deploy the Airnode to the cloud provider without the worry of installing dependencies and is the recommended way to do a deployment. If you do not already have docker installed go to the [Docker website](https://docs.docker.com/get-docker/) and install it. ## Deployment -At this point a project should resemble the following. The `config.json`, -`secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to -GCP) files should be ready to go. Other files and folders added to the project -are expected and are ignored by the deployer image. +At this point a project should resemble the following. The `config.json`, `secrets.env`, `aws.env` (if deploying to AWS) and `gcp.json` (if deploying to GCP) files should be ready to go. Other files and folders added to the project are expected and are ignored by the deployer image. ::: code-group @@ -84,13 +56,7 @@ my-airnode -From the root of the project directory run the Docker image command -[deploy](/reference/airnode/v0.13/docker/deployer-image.md#deploy) as shown -below to deploy the Airnode. When the deployment has completed a `receipt.json` -file will be written to the project directory, which is mounted to the -`/app/config` directory within the container. This file contains important -configuration information about the Airnode and is needed to remove the Airnode -should the need arise. +From the root of the project directory run the Docker image command [deploy](/reference/airnode/v0.13/docker/deployer-image.md#deploy) as shown below to deploy the Airnode. When the deployment has completed a `receipt.json` file will be written to the project directory, which is mounted to the `/app/config` directory within the container. This file contains important configuration information about the Airnode and is needed to remove the Airnode should the need arise.

@@ -114,10 +80,7 @@ docker run -it --rm ^ ### receipt.json -The `receipt.json` file is a product of a deployment attempt. It contains -Airnode configuration and deployment information and is used to remove the -Airnode. The field `success` is important in that it specifies whether the -deployment was successful or not. +The `receipt.json` file is a product of a deployment attempt. It contains Airnode configuration and deployment information and is used to remove the Airnode. The field `success` is important in that it specifies whether the deployment was successful or not. ```json { @@ -142,9 +105,7 @@ deployment was successful or not. ## Testing with HTTP Gateway -If you opted to enable the HTTP Gateway it can be used to test the Airnode while -bypassing the chain it was deployed to. There are examples that detail how to do -this. +If you opted to enable the HTTP Gateway it can be used to test the Airnode while bypassing the chain it was deployed to. There are examples that detail how to do this. - [HTTP Gateways](/reference/airnode/v0.13/understand/http-gateways.md#using-curl) - [Deploying an Airnode on AWS](/guides/airnode/deploy-airnode/deploy-aws/#_5-test-the-airnode) @@ -153,15 +114,10 @@ this. ## Make an RRP request of the Airnode -Once the Airnode is deployed, see -[Calling an Airnode](/reference/airnode/v0.13/developers/index.md) to learn how -requests are made using the request-response protocol (RRP). +Once the Airnode is deployed, see [Calling an Airnode](/reference/airnode/v0.13/developers/index.md) to learn how requests are made using the request-response protocol (RRP). ## Removing the Airnode -If you would like to remove a deployed Airnode, see the Docker image commands -for [remove](/reference/airnode/v0.13/docker/deployer-image.md#remove) or -[remove-with-receipt](/reference/airnode/v0.13/docker/deployer-image.md#remove-with-receipt) -instructions. +If you would like to remove a deployed Airnode, see the Docker image commands for [remove](/reference/airnode/v0.13/docker/deployer-image.md#remove) or [remove-with-receipt](/reference/airnode/v0.13/docker/deployer-image.md#remove-with-receipt) instructions. diff --git a/docs/reference/airnode/v0.13/understand/heartbeat.md b/docs/reference/airnode/v0.13/understand/heartbeat.md index bc43fa94..738cdd8a 100644 --- a/docs/reference/airnode/v0.13/understand/heartbeat.md +++ b/docs/reference/airnode/v0.13/understand/heartbeat.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -At the end of an Airnode's run (every minute), Airnode can make an HTTP POST -request to a specified URL. This is both to signal that the Airnode is alive and -working (useful especially right after the deployment) and also as a -notification every time it runs (self-operates). +At the end of an Airnode's run (every minute), Airnode can make an HTTP POST request to a specified URL. This is both to signal that the Airnode is alive and working (useful especially right after the deployment) and also as a notification every time it runs (self-operates). > > @@ -31,8 +28,7 @@ notification every time it runs (self-operates). > 3.

A response is sent to each request.

> 4.

Finally Airnode makes a request to the heartbeat URL (HTTP POST). This could be to an operation within the API Airnode supports or to any cloud REST endpoint such as a monitoring service.

-Turn on the optional heartbeat functionality by setting all fields in the -`config.json` section for `nodeSettings.heartbeat`. +Turn on the optional heartbeat functionality by setting all fields in the `config.json` section for `nodeSettings.heartbeat`. ```json{12-16} { @@ -95,8 +91,7 @@ The table below illustrates the parameters passed to the Heartbeat URL. | oev_gateway_url | body | string | | signature | body | string | -Below is an example of what is included in the request body. Note that -`airnode-heartbeat-api-key` can be found in the request header and not the body. +Below is an example of what is included in the request body. Note that `airnode-heartbeat-api-key` can be found in the request header and not the body. ```json { @@ -117,18 +112,13 @@ Below is an example of what is included in the request body. Note that The method by which the heartbeat payload is generated is as follows: -- An object is marshalled to JSON - this object contains multiple fields as - shown above. -- The Airnode's mnemonic (using the default EVM derivation path to derive a key) - is used to sign the payload. +- An object is marshalled to JSON - this object contains multiple fields as shown above. +- The Airnode's mnemonic (using the default EVM derivation path to derive a key) is used to sign the payload. - The payload and signature are included in a new object and marshalled to JSON. -The reason this nested JSON approach has been used is to prevent subtle -inconsistencies between JSON marshallers in different languages causing the -signature to not match the payload. +The reason this nested JSON approach has been used is to prevent subtle inconsistencies between JSON marshallers in different languages causing the signature to not match the payload. -The airnode's public key can be recovered from this signature and be used, -generally, to verify the authenticity of the payload. +The airnode's public key can be recovered from this signature and be used, generally, to verify the authenticity of the payload. The overall content to the heartbeat URL is as follows: diff --git a/docs/reference/airnode/v0.13/understand/http-gateways.md b/docs/reference/airnode/v0.13/understand/http-gateways.md index 98548619..91edd280 100644 --- a/docs/reference/airnode/v0.13/understand/http-gateways.md +++ b/docs/reference/airnode/v0.13/understand/http-gateways.md @@ -19,35 +19,24 @@ tags: # {{$frontmatter.title}} -As part of the Airnode deployment you can decide to deploy two different HTTP -Gateways. +As part of the Airnode deployment you can decide to deploy two different HTTP Gateways. - HTTP Gateway: testing - HTTP Signed Data Gateway: production use ## Gateway Differences -Both gateways are setup identically. The differences are in their purpose and -response. +Both gateways are setup identically. The differences are in their purpose and response. > ### HTTP Gateway -The regular HTTP gateway is strictly for testing purposes. Using a simple tool -like CURL you can test that endpoints in the Airnode configuration are working -properly without accessing the blockchain. +The regular HTTP gateway is strictly for testing purposes. Using a simple tool like CURL you can test that endpoints in the Airnode configuration are working properly without accessing the blockchain. -In order to facilitate configuration and testing of parameters, HTTP gateway -requests have the following differences in handling when compared to blockchain -requests or requests to the HTTP signed data gateway: +In order to facilitate configuration and testing of parameters, HTTP gateway requests have the following differences in handling when compared to blockchain requests or requests to the HTTP signed data gateway: -1. When a request's API call is successful but then that response fails - extraction and encoding, data are still returned. This is in contrast to the - other types of requests for which only an error would be returned. The API - call response, after undergoing any - [post-processing](/reference/ois/2.2/processing.md), will be present in the - `rawValue` field independent of encoding success or failure: +1. When a request's API call is successful but then that response fails extraction and encoding, data are still returned. This is in contrast to the other types of requests for which only an error would be returned. The API call response, after undergoing any [post-processing](/reference/ois/2.2/processing.md), will be present in the `rawValue` field independent of encoding success or failure: ```json { @@ -55,29 +44,19 @@ requests or requests to the HTTP signed data gateway: } ``` -2. Reserved parameters are inaccessible in response pre/post processing. This is - only relevant if reserved parameters are being _modified_ in pre/post - processing (advanced use case). +2. Reserved parameters are inaccessible in response pre/post processing. This is only relevant if reserved parameters are being _modified_ in pre/post processing (advanced use case). ### HTTP Signed Data Gateway -The HTTP signed data gateway is used for production purposes. While it is -executed in a similar way as the HTTP gateway, its response is signed and does -not contain a `rawValue` field. This gateway is executed by an off-chain code -source that may in turn push data to a blockchain. +The HTTP signed data gateway is used for production purposes. While it is executed in a similar way as the HTTP gateway, its response is signed and does not contain a `rawValue` field. This gateway is executed by an off-chain code source that may in turn push data to a blockchain. ## Setup -Enable either gateway in the `config.json` file fields -`nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. +Enable either gateway in the `config.json` file fields `nodeSettings.httpGateway` and `nodeSettings.httpSignedDataGateway`. - **enabled**: A boolean to enable/disable the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless function instance serving gateway requests. When - omitted, there is no maximum concurrency set. This field is ignored for - Airnode client gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless function instance serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -101,10 +80,7 @@ Enable either gateway in the `config.json` file fields }, ``` -Add the desired endpoints a gateway can respond to in the `triggers.http[n]` -and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need -to match. It could be practical to test all endpoints but only serve certain -endpoints using the HTTP signed data gateway or via RRP. +Add the desired endpoints a gateway can respond to in the `triggers.http[n]` and/or `triggers.httpSignedData[n]` arrays. The corresponding arrays do not need to match. It could be practical to test all endpoints but only serve certain endpoints using the HTTP signed data gateway or via RRP. ```json // in config.json @@ -134,50 +110,28 @@ endpoints using the HTTP signed data gateway or via RRP. ## Gateway URLs -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URLs should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URLs should be kept secret. -The gateway URLs are also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/v0.13/understand/heartbeat.md) to a specified -heartbeat URL. +The gateway URLs are also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/v0.13/understand/heartbeat.md) to a specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated for each gateway (when enabled) when Airnode is -deployed. The URL including, the secret `UUID` path parameter, is displayed on -the terminal at the end of an Airnode deployment using the -[Docker image](/reference/airnode/v0.13/docker/deployer-image.md). +A gateway URL is generated for each gateway (when enabled) when Airnode is deployed. The URL including, the secret `UUID` path parameter, is displayed on the terminal at the end of an Airnode deployment using the [Docker image](/reference/airnode/v0.13/docker/deployer-image.md). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for both gateways, which is exposed on the host machine. -Doing so will make the gateways API accessible like a regular web server running -on the machine. Each gateway has a separate endpoint as shown below. Note the -`PORT` which is exposed as part of the Airnode client container. See the -[Airnode client usage](/reference/airnode/v0.13/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for both gateways, which is exposed on the host machine. Doing so will make the gateways API accessible like a regular web server running on the machine. Each gateway has a separate endpoint as shown below. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/v0.13/docker/client-image.md#usage) for more details. -- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Gateway -- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - - Gateway URL for the HTTP Signed Data Gateway +- `http://localhost:/http-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Gateway +- `http://localhost:/http-signed-data/01234567-abcd-abcd-abcd-012345678abc/` - Gateway URL for the HTTP Signed Data Gateway ## Using CURL -In order to execute an endpoint served by either gateway, the following are -required as part of the CURL call. +In order to execute an endpoint served by either gateway, the following are required as part of the CURL call. -- Make a POST request with the `endpointId` as a path parameter. An `endpointId` - can found in config.json under `triggers.http.endpointId` or - `triggers.httpSignedData.endpointId`. +- Make a POST request with the `endpointId` as a path parameter. An `endpointId` can found in config.json under `triggers.http.endpointId` or `triggers.httpSignedData.endpointId`. - Add the `Content-Type` header, set to `application/json`. - Place the parameters/encodedParameters in the request body. @@ -192,15 +146,11 @@ required as part of the CURL call. | \* parameters
HTTP Gateway
| body | `-d '{"parameters": {"param1": "myValue", "param2": 5}}'` | | \* encodedParameters
HTTP Signed Data Gateway
| body | `-d '{"encodedParameters": "0x3173737300....000"}'` | -\* Parameters for the gateways are named differently. The HTTP signed data -gateway requires that the `encodedParameters` be encoded using -[Airnode ABI](/reference/airnode/v0.13/specifications/airnode-abi.md). +\* Parameters for the gateways are named differently. The HTTP signed data gateway requires that the `encodedParameters` be encoded using [Airnode ABI](/reference/airnode/v0.13/specifications/airnode-abi.md). ### Request -Replace `` in the examples below with the URL displayed in the -terminal at the end of an Airnode deployment using a -[Docker image](/reference/airnode/v0.13/docker/). +Replace `` in the examples below with the URL displayed in the terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/v0.13/docker/). ::: code-group diff --git a/docs/reference/airnode/v0.13/understand/index.md b/docs/reference/airnode/v0.13/understand/index.md index d105381d..d670c12b 100644 --- a/docs/reference/airnode/v0.13/understand/index.md +++ b/docs/reference/airnode/v0.13/understand/index.md @@ -19,17 +19,11 @@ tags: # {{$frontmatter.title}} -Airnode is a first-party oracle that pushes off-chain API data on-chain via data -feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs -off-chain as a background component of the API3 ecosystem. **Understanding -Airnode** is a progression of pages that provides a detailed understanding of -the capabilities and functionality of Airnode. +Airnode is a first-party oracle that pushes off-chain API data on-chain via data feeds (dAPIs) or using its request-response protocol (RRP). Airnode runs off-chain as a background component of the API3 ecosystem. **Understanding Airnode** is a progression of pages that provides a detailed understanding of the capabilities and functionality of Airnode. ## Project Folder -A typical Airnode project folder contains files used to define the Airnode. Show -below are typical project folders for each of AWS, GCP, and container -deployments. +A typical Airnode project folder contains files used to define the Airnode. Show below are typical project folders for each of AWS, GCP, and container deployments. ::: code-group @@ -55,12 +49,7 @@ my-airnode ::: code-group -Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the -files in the -[Templates](/reference/airnode/v0.13/deployment-files/templates/config-json.md) -as an aid to create all but the `gcp.json` files. Also see the -[Examples](/reference/airnode/v0.13/deployment-files/examples/config-json.md) -for demonstration purposes. +Both AWS and GCP have a platform specific file `aws.env` and `gcp.json`. Use the files in the [Templates](/reference/airnode/v0.13/deployment-files/templates/config-json.md) as an aid to create all but the `gcp.json` files. Also see the [Examples](/reference/airnode/v0.13/deployment-files/examples/config-json.md) for demonstration purposes. ## Configuration files @@ -69,57 +58,40 @@ for demonstration purposes. - `aws.env`: AWS credentials. - `gcp.json`: GCP project information. -The diagrams below depict the configuration files needed for a successful -deployment of an Airnode to AWS, GCP, and a Docker Container. +The diagrams below depict the configuration files needed for a successful deployment of an Airnode to AWS, GCP, and a Docker Container. ### AWS -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **aws.env**: Contains AWS credentials required by the Docker deployer image. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### GCP -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. 3. **gcp.json**: GCP project file. -4. **deployer image**: Docker image that deploys the Airnode using its deploy - command. +4. **deployer image**: Docker image that deploys the Airnode using its deploy command. ### Container -1. **config.json**: Contains the Airnode's configuration. It contains an - important element, called OIS, that maps an API to Airnode endpoints. +1. **config.json**: Contains the Airnode's configuration. It contains an important element, called OIS, that maps an API to Airnode endpoints. 2. **secrets.env**: Contains values that should not be exposed in config.json. -3. **client image**: The Docker client image that contains the Airnode and runs - with the provided configuration. +3. **client image**: The Docker client image that contains the Airnode and runs with the provided configuration. ## Deploying -There are two ways to deploy and run an Airnode. The most popular is with a -cloud provider such as AWS or GCP. Use the Docker -[Airnode Deployer Image](/reference/airnode/v0.13/docker/deployer-image.md) for -these type of deployments. - -The second method is to run a containerized Airnode hosted internally or with a -cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker -[Airnode Client Image](/reference/airnode/v0.13/docker/client-image.md) for this -type of deployment. - -Try the guide AWS -[Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) -as a quick introduction to an Airnode deployment. Also be sure to visit -[ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an -Airnode. +There are two ways to deploy and run an Airnode. The most popular is with a cloud provider such as AWS or GCP. Use the Docker [Airnode Deployer Image](/reference/airnode/v0.13/docker/deployer-image.md) for these type of deployments. + +The second method is to run a containerized Airnode hosted internally or with a cloud provider service (e.g. AWS, EC2, or Lightsail). Use the Docker [Airnode Client Image](/reference/airnode/v0.13/docker/client-image.md) for this type of deployment. + +Try the guide AWS [Deploying Airnode via AWS](/guides/airnode/deploy-airnode/deploy-aws/index.md) as a quick introduction to an Airnode deployment. Also be sure to visit [ChainAPI](https://chainapi.com) and try its user-friendly UI that deploys an Airnode. diff --git a/docs/reference/airnode/v0.13/understand/monitor.md b/docs/reference/airnode/v0.13/understand/monitor.md index 2c7912fe..f7f5a88a 100644 --- a/docs/reference/airnode/v0.13/understand/monitor.md +++ b/docs/reference/airnode/v0.13/understand/monitor.md @@ -19,43 +19,24 @@ tags: # {{$frontmatter.title}} -Airnode logs or log groups are named similarly in AWS and GCP and include the -following hyphen-separated components: `airnode`, ``, -``, and ``, for example, -`airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages -or request types and the logs they contain are as follows: - -- `startCoordinator`: Logs for chain provider initialization and request - fetching +Airnode logs or log groups are named similarly in AWS and GCP and include the following hyphen-separated components: `airnode`, ``, ``, and ``, for example, `airnode-9e62180-tutorial-startCoordinator`. The possible Airnode cycle stages or request types and the logs they contain are as follows: + +- `startCoordinator`: Logs for chain provider initialization and request fetching - `run`: Logs of API calls and withdrawals originating from blockchain requests -- `httpReq`: Logs for - [HTTP gateway requests](/reference/airnode/v0.13/understand/http-gateways.md#http-gateway) -- `httpSignedReq`: Logs for - [HTTP signed data gateway requests](/reference/airnode/v0.13/understand/http-gateways.md) -- `signOevReq`: Logs for - [OEV gateway requests](/reference/airnode/v0.13/understand/oev-gateway.md) +- `httpReq`: Logs for [HTTP gateway requests](/reference/airnode/v0.13/understand/http-gateways.md#http-gateway) +- `httpSignedReq`: Logs for [HTTP signed data gateway requests](/reference/airnode/v0.13/understand/http-gateways.md) +- `signOevReq`: Logs for [OEV gateway requests](/reference/airnode/v0.13/understand/oev-gateway.md) ### AWS -Airnode logs are available in -[CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. -Note that for the HTTP gateways, AWS generates a unique `requestId` for each -request. These should not be confused with the `requestId` of a request -originating from a blockchain. +Airnode logs are available in [CloudWatch](https://console.aws.amazon.com/cloudwatch) under Logs > Log groups. Note that for the HTTP gateways, AWS generates a unique `requestId` for each request. These should not be confused with the `requestId` of a request originating from a blockchain. ### GCP -Airnode logs are available in the -[Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to -query or stream logs by the "Cloud Function" Resource Type and then by "Function -Name" in order to view a specific request type or Airnode cycle stage. +Airnode logs are available in the [Logs Explorer](https://console.cloud.google.com/logs/). It can be convenient to query or stream logs by the "Cloud Function" Resource Type and then by "Function Name" in order to view a specific request type or Airnode cycle stage. ## Local Airnode Client -Running the `airnode-client` Docker image will output container logs to the -command line. These logs are also available through the Docker interface e.g. -under Containers within Docker Desktop. See the Docker -[client image](/reference/airnode/v0.13/docker/client-image.md) for more -information. +Running the `airnode-client` Docker image will output container logs to the command line. These logs are also available through the Docker interface e.g. under Containers within Docker Desktop. See the Docker [client image](/reference/airnode/v0.13/docker/client-image.md) for more information. diff --git a/docs/reference/airnode/v0.13/understand/oev-gateway.md b/docs/reference/airnode/v0.13/understand/oev-gateway.md index 07a76063..1c0e5a84 100644 --- a/docs/reference/airnode/v0.13/understand/oev-gateway.md +++ b/docs/reference/airnode/v0.13/understand/oev-gateway.md @@ -19,23 +19,15 @@ tags: # {{$frontmatter.title}} -OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The -data is signed by the Airnode so that only the searcher who won the auction can -use it to update the data feed. You can learn more about OEV at -https://api3.org. +OEV gateway is used in the OEV flow to sign the data won in the OEV auction. The data is signed by the Airnode so that only the searcher who won the auction can use it to update the data feed. You can learn more about OEV at https://api3.org. ## Setup -Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` -section. +Enable the gateway in the `config.json` file via `nodeSettings.oevGateway` section. - **enabled**: A boolean to enable/disable for the gateway. -- **maxConcurrency**: (optional) A number higher than zero that represents the - maximum number of serverless functions serving gateway requests. When omitted, - there is no maximum concurrency set. This field is ignored for Airnode client - gateways. -- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an - empty array to disable CORS. +- **maxConcurrency**: (optional) A number higher than zero that represents the maximum number of serverless functions serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways. +- **corsOrigins**: A list of allowed origins, `['*']` to allow all origins or an empty array to disable CORS. ```json "nodeSettings": { @@ -56,44 +48,25 @@ section. ## Gateway URL -The gateway implementation is different depending on how Airnode is deployed. -When deployed on a cloud provider, the serverless gateway is used. Inside -Airnode client, the gateway is implemented via a simple web server inside the -docker container. There are subtle differences in both how the gateways work and -what the gateway URLs look like. +The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and what the gateway URLs look like. -The deployer generates a secret `UUID` path parameter which ensures that the -endpoints are not openly accessible. Therefore, the gateway URL should be kept -secret. +The deployer generates a secret `UUID` path parameter which ensures that the endpoints are not openly accessible. Therefore, the gateway URL should be kept secret. -The gateway URL is also available as part of the payload sent from Airnode's -[heartbeat](/reference/airnode/v0.13/understand/heartbeat.md) to your specified -heartbeat URL. +The gateway URL is also available as part of the payload sent from Airnode's [heartbeat](/reference/airnode/v0.13/understand/heartbeat.md) to your specified heartbeat URL. ### When deployed on a cloud provider -A gateway URL is generated when Airnode is deployed. You can see the URLs -including the secret `UUID` path parameter, displayed on your terminal at the -end of an Airnode deployment using a -[Docker image](/reference/airnode/v0.13/docker/). +A gateway URL is generated when Airnode is deployed. You can see the URLs including the secret `UUID` path parameter, displayed on your terminal at the end of an Airnode deployment using a [Docker image](/reference/airnode/v0.13/docker/). ### When using Airnode client -Airnode client can be used to run Airnode as a docker container locally. There -is a common web server for the gateway, which is exposed on the host machine. -Doing so will make the gateway API accessible like a regular web server running -on the machine. Note the `PORT` which is exposed as part of the Airnode client -container. See the -[Airnode client usage](/reference/airnode/v0.13/docker/client-image.md#usage) -for more details. +Airnode client can be used to run Airnode as a docker container locally. There is a common web server for the gateway, which is exposed on the host machine. Doing so will make the gateway API accessible like a regular web server running on the machine. Note the `PORT` which is exposed as part of the Airnode client container. See the [Airnode client usage](/reference/airnode/v0.13/docker/client-image.md#usage) for more details. -- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - - Gateway URL for the OEV Gateway +- `http://localhost:/sign-oev/01234567-abcd-abcd-abcd-012345678abc` - Gateway URL for the OEV Gateway ## Usage -In order to execute the processing on the gateway, it needs to receive a -properly constructed HTTP request: +In order to execute the processing on the gateway, it needs to receive a properly constructed HTTP request: - It must be a `POST` request - It must contain a `Content-Type` header, set to `application/json`. @@ -136,8 +109,7 @@ where: - `updateId` - Auction update ID. - `bidderAddress` - Blockchain address of the winning searcher. - `bidAmount` - Bid amount that won the auction. -- `beacons` - A list of beacon data to be signed. It can contain two types: full - beacon data, only beacon metadata +- `beacons` - A list of beacon data to be signed. It can contain two types: full beacon data, only beacon metadata - `airnodeAddress` - Airnode address identifying a beacon - `endpointId` - Endpoint ID identifying a beacon - `encodedParameters` - Parameters in their encoded form identifying a beacon @@ -181,8 +153,6 @@ curl --location '' \ ] ``` -The gateway will return a list of signatures. There is a signature for each -beacon within the data feed that is served by the given Airnode, returned in the -same order as they are specified in the request body. +The gateway will return a list of signatures. There is a signature for each beacon within the data feed that is served by the given Airnode, returned in the same order as they are specified in the request body. diff --git a/docs/reference/airnode/v0.13/understand/using-authorizations.md b/docs/reference/airnode/v0.13/understand/using-authorizations.md index 4b665d23..ed069d77 100644 --- a/docs/reference/airnode/v0.13/understand/using-authorizations.md +++ b/docs/reference/airnode/v0.13/understand/using-authorizations.md @@ -19,39 +19,22 @@ tags: # {{$frontmatter.title}} -An Airnode can authorize smart contracts (know as requesters) access to its -endpoints using -[Authorizations](/reference/airnode/v0.13/concepts/authorizations.md). This -method is off-chain and requires no blockchain knowledge by an API provider. It -is different than -[Authorizers](/reference/airnode/v0.13/concepts/authorizers.md) which is an -on-chain auth scheme. +An Airnode can authorize smart contracts (know as requesters) access to its endpoints using [Authorizations](/reference/airnode/v0.13/concepts/authorizations.md). This method is off-chain and requires no blockchain knowledge by an API provider. It is different than [Authorizers](/reference/airnode/v0.13/concepts/authorizers.md) which is an on-chain auth scheme. ::: info Alternative: Relayed Meta Data -As an alternative to authorizers and authorizations, an API provider can use -[Relayed Meta Data](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes) -to authenticate a request. This approach is off-chain and requires no blockchain -knowledge by the API provider. Note that it is possible to use authorizers, -authorizations, and relayed meta data together. +As an alternative to authorizers and authorizations, an API provider can use [Relayed Meta Data](/reference/airnode/v0.13/understand/api-security.md#relayed-meta-data-security-schemes) to authenticate a request. This approach is off-chain and requires no blockchain knowledge by the API provider. Note that it is possible to use authorizers, authorizations, and relayed meta data together. ::: -Authorizations use scheme types that hard-code access to an Airnode's endpoints -in the same file that defines the Airnode, its `config.json` file. These -hard-coded values are endpointId/address pairs that the Airnode will use to -allow access to its endpoints by requesters (smart contracts). +Authorizations use scheme types that hard-code access to an Airnode's endpoints in the same file that defines the Airnode, its `config.json` file. These hard-coded values are endpointId/address pairs that the Airnode will use to allow access to its endpoints by requesters (smart contracts). -Nothing in _authorizers_ can supersede permissions granted by _authorizations_ -as the latter takes precedence. -Currently there is only one _authorizations_ scheme type, -`requesterEndpointAuthorizations`. +Nothing in _authorizers_ can supersede permissions granted by _authorizations_ as the latter takes precedence. +Currently there is only one _authorizations_ scheme type, `requesterEndpointAuthorizations`. ## requesterEndpointAuthorizations -Currently `requesterEndpointAuthorizations` is the only scheme type available -for _authorizations_. It defines a list of endpointIds each with a array of -requester addresses that can access them. +Currently `requesterEndpointAuthorizations` is the only scheme type available for _authorizations_. It defines a list of endpointIds each with a array of requester addresses that can access them. ```json { diff --git a/docs/reference/airnode/v0.13/versions.md b/docs/reference/airnode/v0.13/versions.md index d167720f..d6c30bab 100644 --- a/docs/reference/airnode/v0.13/versions.md +++ b/docs/reference/airnode/v0.13/versions.md @@ -19,11 +19,7 @@ tags: # {{$frontmatter.title}} -The latest version of Airnode is `v0.13.x`. See -[releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for -all Airnode versions. Below is a list of Airnode versions included in this -documentation website. Each can be accessed via the Airnode selector at the top -of the left sidebar under Reference. +The latest version of Airnode is `v0.13.x`. See [releases](https://github.com/api3dao/airnode/releases) in the Airnode repo for all Airnode versions. Below is a list of Airnode versions included in this documentation website. Each can be accessed via the Airnode selector at the top of the left sidebar under Reference. | | | ------- | @@ -33,9 +29,7 @@ of the left sidebar under Reference. ## Other Versions -Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their -documentation is available at -[https://old-docs.api3.org](https://old-docs.api3.org). +Prior to version `v0.11.x` there are several `v0.x` versions of Airnode. Their documentation is available at [https://old-docs.api3.org](https://old-docs.api3.org). | | | --------------------------------------------------------- | diff --git a/docs/reference/ois/2.0/index.md b/docs/reference/ois/2.0/index.md index d1c79d68..4c50017a 100644 --- a/docs/reference/ois/2.0/index.md +++ b/docs/reference/ois/2.0/index.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -OIS (or Oracle Integration Specifications) is a JSON object that describes an -API specification and defines Airnode endpoints linked to API operations (a.k.a. -endpoints). It is one of five root level objects in a `config.json` file that -defines an Airnode. +OIS (or Oracle Integration Specifications) is a JSON object that describes an API specification and defines Airnode endpoints linked to API operations (a.k.a. endpoints). It is one of five root level objects in a `config.json` file that defines an Airnode. - chains - nodeSettings @@ -30,14 +27,9 @@ defines an Airnode. - ois - apiCredentials -For more information about the config.json file see the -[Deployment Files](/reference/airnode/v0.11/deployment-files/config-json.md) -section in the Airnode document set. +For more information about the config.json file see the [Deployment Files](/reference/airnode/v0.11/deployment-files/config-json.md) section in the Airnode document set. -In the diagram below, an Airnode exposes its endpoints to the on-chain -AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to -an API operation. It should be noted that Airnode can have more than one -endpoint that maps to the same API operation. +In the diagram below, an Airnode exposes its endpoints to the on-chain AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to an API operation. It should be noted that Airnode can have more than one endpoint that maps to the same API operation. > > @@ -47,18 +39,11 @@ endpoint that maps to the same API operation. ## API Mapping Examples -The following are three possible Airnode to API operation mapping examples. -Mapping details are better documented in the next doc -[Specification](/reference/ois/2.0/specification.md). +The following are three possible Airnode to API operation mapping examples. Mapping details are better documented in the next doc [Specification](/reference/ois/2.0/specification.md). ### Simple Airnode Endpoint -An API has a simple operation the returns the current value of an on-chain token -`GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint -will only mimic the API operation. To do so, the Airnode will declare its -endpoint to have one parameter, `id`. Airnode will accept an `id` argument from -an on-chain request and move its value to the API operation's path parameter -named `id`. +An API has a simple operation the returns the current value of an on-chain token `GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint will only mimic the API operation. To do so, the Airnode will declare its endpoint to have one parameter, `id`. Airnode will accept an `id` argument from an on-chain request and move its value to the API operation's path parameter named `id`. ```json // ois.apiSpecifications (API operations) @@ -97,25 +82,11 @@ named `id`. ### Fixed Operation Parameters Airnode Endpoint -An API may have an operation that returns a crypto coin in either a summary or -detail form. The API operation has two parameters, `coinId` in the path and -`includeDetails` in the query. The Airnode (by design) will not allow the -details of the coin to be returned, only the summary. Therefore the Airnode will -require a requester to pass a `coinId` but will ignore the `includeDetails` -parameter if passed. The Airnode will always set the `includeDetails` query -parameter to false regardless of what a requester sends when it calls the API -operation. It does so using a `fixedOperationParameters` when calling the API -operation. +An API may have an operation that returns a crypto coin in either a summary or detail form. The API operation has two parameters, `coinId` in the path and `includeDetails` in the query. The Airnode (by design) will not allow the details of the coin to be returned, only the summary. Therefore the Airnode will require a requester to pass a `coinId` but will ignore the `includeDetails` parameter if passed. The Airnode will always set the `includeDetails` query parameter to false regardless of what a requester sends when it calls the API operation. It does so using a `fixedOperationParameters` when calling the API operation. ### Two Airnode Endpoints - One API Operation -An Airnode may wish to create two Airnode endpoints mapped to a single API -operation whereas the requester does not pass any argument. While the API -operation returns any token value based on a path parameter `id`, Airnode will -only allow one particular token per Airnode endpoint. This is done using -`fixedOperationParameters` rather than normal `parameters`. By applying a -`value` to `fixedOperationParameters` for each Airnode endpoint, only the token -in the `value` can be returned to the requester. +An Airnode may wish to create two Airnode endpoints mapped to a single API operation whereas the requester does not pass any argument. While the API operation returns any token value based on a path parameter `id`, Airnode will only allow one particular token per Airnode endpoint. This is done using `fixedOperationParameters` rather than normal `parameters`. By applying a `value` to `fixedOperationParameters` for each Airnode endpoint, only the token in the `value` can be returned to the requester. ```json "endpoints": [ diff --git a/docs/reference/ois/2.0/processing.md b/docs/reference/ois/2.0/processing.md index b8dcfcc3..3bf7ffd1 100644 --- a/docs/reference/ois/2.0/processing.md +++ b/docs/reference/ois/2.0/processing.md @@ -19,54 +19,30 @@ tags: # {{$frontmatter.title}} -The processing schema accepts an array of processing snippets (user defined -code) which are chained. The first snippet receives parameters submitted as part -of a template or on-chain request. The output of this snippet is passed to the -second snippet and so on. +The processing schema accepts an array of processing snippets (user defined code) which are chained. The first snippet receives parameters submitted as part of a template or on-chain request. The output of this snippet is passed to the second snippet and so on. -Airnode executes snippets for `preProcessingSpecifications` and -`postProcessingSpecifications` during its run cycle. The following describes the -work flow Airnode uses: +Airnode executes snippets for `preProcessingSpecifications` and `postProcessingSpecifications` during its run cycle. The following describes the work flow Airnode uses: 1. Run `preProcessingSpecifications` 2. Airnode calls requested OIS endpoint 3. Run `postProcessingSpecifications` 4. Airnode encodes the response values defined by reservedParameters -The processing schema is the same for both -[`preProcessingSpecifications`](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) -and -[`postProcessingSpecifications`](/reference/ois/2.0/specification.md#_5-10-postprocessingspecifications). -Snippets for both specifications follow this schema: - -- `environment` - Currently one of `Node` or `Node async`. Both options - interpret the code as JavaScript and execute in Node.js. The async version can - use asynchronous code. The code snippet is expected to call `resolve(output)` - with the output value as an argument. Airnode will use the resolved value as - the input to subsequent snippets (if defined). +The processing schema is the same for both [`preProcessingSpecifications`](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) and [`postProcessingSpecifications`](/reference/ois/2.0/specification.md#_5-10-postprocessingspecifications). Snippets for both specifications follow this schema: + +- `environment` - Currently one of `Node` or `Node async`. Both options interpret the code as JavaScript and execute in Node.js. The async version can use asynchronous code. The code snippet is expected to call `resolve(output)` with the output value as an argument. Airnode will use the resolved value as the input to subsequent snippets (if defined). - `value` - The processing code written as a string. -- `timeoutMs` - The maximum duration that this snippet can run. In case the - timeout is exceeded an error is thrown. +- `timeoutMs` - The maximum duration that this snippet can run. In case the timeout is exceeded an error is thrown. -Try the [Post processing](/guides/airnode/post-processing/) guide to further -understand pre/post processing. +Try the [Post processing](/guides/airnode/post-processing/) guide to further understand pre/post processing. ## Input and Output -The processing snippet receives an `input` value which is either the initial -value or the output value from the previous processing snippet. The snippet must -create a variable `output` which will be used for the next processing snippet. -The processing snippet can use most Node.js built-in modules. Refer to the -source code of Airnode to understand how processing works and what modules are -made available to the snippet code. Modules cannot be imported directly in cloud -environments. +The processing snippet receives an `input` value which is either the initial value or the output value from the previous processing snippet. The snippet must create a variable `output` which will be used for the next processing snippet. The processing snippet can use most Node.js built-in modules. Refer to the source code of Airnode to understand how processing works and what modules are made available to the snippet code. Modules cannot be imported directly in cloud environments. ## Interpolation -Note, that config.json supports interpolation of secrets via the JavaScript -string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with -the string interpolation inside the processing snippets. In order to use the -interpolation in snippets, you need to escape the interpolation. +Note, that config.json supports interpolation of secrets via the JavaScript string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with the string interpolation inside the processing snippets. In order to use the interpolation in snippets, you need to escape the interpolation. For example, the following code: @@ -87,57 +63,27 @@ should be escaped inside the `config.json` like this: ## Error Handling and Security -Processing code is expected to be trustworthy as it is specified by the Airnode -operator. Processing is an advanced feature that carries great security risks. -It is therefore advised that developers using the processing feature familiarize -themselves with the Airnode sources prior to developing any processing code -snippets. +Processing code is expected to be trustworthy as it is specified by the Airnode operator. Processing is an advanced feature that carries great security risks. It is therefore advised that developers using the processing feature familiarize themselves with the Airnode sources prior to developing any processing code snippets. -Processing code executes in a constrained execution environment resembling -Node.js. Some resources may not be available, for example the `require` -statement. Therefore code should be tested thoroughly in the target environment -(e.g. Lambda and/or Docker client). For example, authentication implemented in -pre-processing should always be executed at the end of the respective processing -chain and special care should be taken to avoid leakage of secrets. +Processing code executes in a constrained execution environment resembling Node.js. Some resources may not be available, for example the `require` statement. Therefore code should be tested thoroughly in the target environment (e.g. Lambda and/or Docker client). For example, authentication implemented in pre-processing should always be executed at the end of the respective processing chain and special care should be taken to avoid leakage of secrets. ## Skip the API call -Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on -either (or both) pre-processing or post-processing to acquire a value for the -Airnode to place on-chain. +Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on either (or both) pre-processing or post-processing to acquire a value for the Airnode to place on-chain. -Instead of calling an API, Airnode uses the output of -`preProcessingSpecifications`, `postProcessingSpecifications`, or both. The -field `operation` must be undefined, `fixedOperationParameters` must be an empty -array and one of `preProcessingSpecifications` or `postProcessingSpecifications` -must be defined and not be an empty array. +Instead of calling an API, Airnode uses the output of `preProcessingSpecifications`, `postProcessingSpecifications`, or both. The field `operation` must be undefined, `fixedOperationParameters` must be an empty array and one of `preProcessingSpecifications` or `postProcessingSpecifications` must be defined and not be an empty array. ### Use case: random number -An Airnode endpoint that places a random number on-chain. Rather than calling an -API, the Airnode will derive a random number during its execution of a -pre-process specification. A requester would make a request of this Airnode -endpoint without parameters. The Airnode endpoint simply sets the random number -on-chain in response to the request using a `preProcessingSpecifications` -specification. Example #1 below implements this use case. +An Airnode endpoint that places a random number on-chain. Rather than calling an API, the Airnode will derive a random number during its execution of a pre-process specification. A requester would make a request of this Airnode endpoint without parameters. The Airnode endpoint simply sets the random number on-chain in response to the request using a `preProcessingSpecifications` specification. Example #1 below implements this use case. ### Example #1 -This example creates an Airnode endpoint named `generateRandomNumber` with no -parameters. Because there isn't an -[operation field](/reference/ois/2.0/specification.md#_5-2-operation) defined -for this Airnode endpoint, a call to an API will not be made. The Airnode will -instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) -array. - -To implement the use case mentioned above, the -[operation field](/reference/ois/2.0/specification.md#_5-2-operation) will be -undefined, `fixedOperationParameters` will be an empty array, and -`preProcessingSpecifications` will be defined with a single specification. - -- A requester makes a request of the Airnode endpoint `generateRandomNumber` - without any parameters. +This example creates an Airnode endpoint named `generateRandomNumber` with no parameters. Because there isn't an [operation field](/reference/ois/2.0/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) array. + +To implement the use case mentioned above, the [operation field](/reference/ois/2.0/specification.md#_5-2-operation) will be undefined, `fixedOperationParameters` will be an empty array, and `preProcessingSpecifications` will be defined with a single specification. + +- A requester makes a request of the Airnode endpoint `generateRandomNumber` without any parameters. - Airnode runs the specification in `preProcessingSpecifications[0]`. - The specification generates a random number. - The reserved parameter named `randomNumber` now holds the random number. @@ -175,15 +121,7 @@ endpoints: [ ### Example #2 -The code below is unrelated to the -[use case](/reference/ois/2.0/processing.md#use-case-random-number) mentioned -earlier. This example creates an Airnode endpoint named -`endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there -isn't an [operation field](/reference/ois/2.0/specification.md#_5-2-operation) -defined for this Airnode endpoint, a call to an API will not be made. The -Airnode will instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) -array. +The code below is unrelated to the [use case](/reference/ois/2.0/processing.md#use-case-random-number) mentioned earlier. This example creates an Airnode endpoint named `endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there isn't an [operation field](/reference/ois/2.0/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) array. - A requester passes the number `5` in the parameter named `numberToSum`. - Airnode runs the specification in `preProcessingSpecifications[0]`. diff --git a/docs/reference/ois/2.0/reserved-parameters.md b/docs/reference/ois/2.0/reserved-parameters.md index de68d152..0f534d58 100644 --- a/docs/reference/ois/2.0/reserved-parameters.md +++ b/docs/reference/ois/2.0/reserved-parameters.md @@ -19,63 +19,36 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an OIS object as part of the `endpoints` field -(Airnode endpoints) and warrant a more in-depth explanation. They are part of an -Airnode's defined endpoints in an OIS object but do not map to operation -parameters (API parameters). They are used by Airnode for special purposes. - -A requester can pass request parameters either by referencing a -[template](/reference/airnode/v0.11/concepts/template.md) that contains them, or -as an argument of the request-making methods of -[AirnodeRrpV0.sol](/reference/airnode/v0.11/concepts/#airnoderrpv0-sol). In -either case, these parameters are encoded using the -[AirnodeRrpV0 ABI](/reference/airnode/v0.11/specifications/airnode-abi.md). -There are two types of parameters which are part of the OIS object: - -1. [Endpoint parameters](/reference/ois/2.0/specification.md#_5-5-parameters) - - Airnode endpoint parameters are mapped to API operation parameters. -2. [Reserved parameters](/reference/ois/2.0/specification.md#_5-4-reservedparameters) - - Reserved parameters perform a specific operation related to the request or on - the response before fulfilling the request. Reserved parameter names start - with `_`. Depending on the configuration, they may be overridden by a - parameter supplied by a requester. +Reserved parameters are part of an OIS object as part of the `endpoints` field (Airnode endpoints) and warrant a more in-depth explanation. They are part of an Airnode's defined endpoints in an OIS object but do not map to operation parameters (API parameters). They are used by Airnode for special purposes. + +A requester can pass request parameters either by referencing a [template](/reference/airnode/v0.11/concepts/template.md) that contains them, or as an argument of the request-making methods of [AirnodeRrpV0.sol](/reference/airnode/v0.11/concepts/#airnoderrpv0-sol). In either case, these parameters are encoded using the [AirnodeRrpV0 ABI](/reference/airnode/v0.11/specifications/airnode-abi.md). There are two types of parameters which are part of the OIS object: + +1. [Endpoint parameters](/reference/ois/2.0/specification.md#_5-5-parameters) - Airnode endpoint parameters are mapped to API operation parameters. +2. [Reserved parameters](/reference/ois/2.0/specification.md#_5-4-reservedparameters) - Reserved parameters perform a specific operation related to the request or on the response before fulfilling the request. Reserved parameter names start with `_`. Depending on the configuration, they may be overridden by a parameter supplied by a requester. ## `_type` -Signifies what Solidity type the API response will be encoded to before -fulfillment. +Signifies what Solidity type the API response will be encoded to before fulfillment. -Support is provided for most common -[Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), -but the following are not supported. +Support is provided for most common [Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), but the following are not supported. - Custom bits integer types - e.g. `uint32` or `uint8` - Fixed point decimal numbers - e.g. `fixed128x18` or `ufixed128x18` - Custom fixed size bytes - e.g. `bytes4` - Tuples - e.g. `(int256, string)` -On top of supported solidity types, there is support for a few "artificial" -types created for special purposes that would otherwise be hard or impossible to -represent. +On top of supported solidity types, there is support for a few "artificial" types created for special purposes that would otherwise be hard or impossible to represent. - [`string32`](/reference/ois/2.0/reserved-parameters.md#string32-encoded-to-bytes32-on-chain) - [`timestamp`](/reference/ois/2.0/reserved-parameters.md#timestamp-encoded-to-uint256-on-chain) -You can also encode multiple values for one single API call - but this impacts -all of the reserved parameters and is explained in the -[Encoding Multiple Values](/reference/ois/2.0/reserved-parameters.md#encoding-multiple-values) -section below. +You can also encode multiple values for one single API call - but this impacts all of the reserved parameters and is explained in the [Encoding Multiple Values](/reference/ois/2.0/reserved-parameters.md#encoding-multiple-values) section below. ### Conversion and encoding behavior -Before the API response value is encoded for on chain use, it is parsed and -converted. The conversion behaviors for any given type is explained in depth in -the -[adapter package docs](/reference/airnode/v0.11/packages/adapter.md#conversion). +Before the API response value is encoded for on chain use, it is parsed and converted. The conversion behaviors for any given type is explained in depth in the [adapter package docs](/reference/airnode/v0.11/packages/adapter.md#conversion). -The converted value is then encoded internally by -[ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) -using the following +The converted value is then encoded internally by [ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) using the following ```js ethers.utils.defaultAbiCoder.encode([solidityType], [value]); @@ -93,54 +66,35 @@ ethers.utils.defaultAbiCoder.encode([solidityType], [value]); #### string32 (encoded to `bytes32` on chain) -The `string32` is an artificial type that is not supported by solidity. It is -instead encoded to `bytes32` and provides a cheaper alternative to the regular -`string` type for values with less than 32 characters. +The `string32` is an artificial type that is not supported by solidity. It is instead encoded to `bytes32` and provides a cheaper alternative to the regular `string` type for values with less than 32 characters. ::: warning Limitations -While using `string32` is more efficient, decoding the original string from -`bytes32` on chain is both difficult and expensive. Also bear in mind that this -type is able to encode only strings shorter than 32 characters. If the value is -longer, it will be trimmed and only first 31 characters will be encoded. +While using `string32` is more efficient, decoding the original string from `bytes32` on chain is both difficult and expensive. Also bear in mind that this type is able to encode only strings shorter than 32 characters. If the value is longer, it will be trimmed and only first 31 characters will be encoded. ::: #### timestamp (encoded to `uint256` on chain) -The `timestamp` is an artificial type that is not supported by solidity. It is -instead encoded to `uint256` and specifies the UNIX timestamp value at the time -when the transaction was encoded. You can use this value on chain to check the -"freshness" of the Airnode response. This might be useful in certain scenarios, -because Airnode cannot guarantee when a particular transaction will be mined on -chain. +The `timestamp` is an artificial type that is not supported by solidity. It is instead encoded to `uint256` and specifies the UNIX timestamp value at the time when the transaction was encoded. You can use this value on chain to check the "freshness" of the Airnode response. This might be useful in certain scenarios, because Airnode cannot guarantee when a particular transaction will be mined on chain. -When using the `timestamp` type, the corresponding `_path` and `_times` -variables must be empty strings or not provided. +When using the `timestamp` type, the corresponding `_path` and `_times` variables must be empty strings or not provided. #### Arrays -Apart from the primitives defined above as well as all "artificial" types we -created, you are free to use arrays with any of the above. Multidimensional -arrays are supported as well. Solidity allows you to define fixed size arrays, -which are more gas efficient to encode and you can use those as well. +Apart from the primitives defined above as well as all "artificial" types we created, you are free to use arrays with any of the above. Multidimensional arrays are supported as well. Solidity allows you to define fixed size arrays, which are more gas efficient to encode and you can use those as well. For example - `int256[]` - regular integer array - `uint256[8]` - unsigned integer array with 8 elements - `int256[][]` - 2 dimensional integer array -- `string32[]` - is an array of `string32` values, which will be encoded to - `bytes32[]` on chain -- `string[2][][3]` - 3 dimensional string array, where first dimension contains - 3 elements, second unboundedly many and last dimension only 2. Note that this - [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) - compared to C-style languages +- `string32[]` - is an array of `string32` values, which will be encoded to `bytes32[]` on chain +- `string[2][][3]` - 3 dimensional string array, where first dimension contains 3 elements, second unboundedly many and last dimension only 2. Note that this [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) compared to C-style languages ## `_path` -Assuming that the API response will be a JSON object, defines the field to be -used to fulfill the request using dot notation. For example, if the API returns +Assuming that the API response will be a JSON object, defines the field to be used to fulfill the request using dot notation. For example, if the API returns ``` { @@ -159,15 +113,11 @@ used to fulfill the request using dot notation. For example, if the API returns and `_path` is `field1.fieldA.1`, the response will be `valueA2`. -If the response is a literal value (i.e., not a JSON object) and `_path` is not -provided or is an empty string (needed for -[encoding multiple values](/reference/ois/2.0/reserved-parameters.md#encoding-multiple-values)), -Airnode will use the API response itself to fulfill the request. +If the response is a literal value (i.e., not a JSON object) and `_path` is not provided or is an empty string (needed for [encoding multiple values](/reference/ois/2.0/reserved-parameters.md#encoding-multiple-values)), Airnode will use the API response itself to fulfill the request. ::: warning Beware the separator -Make sure the keys in the path of the API response do not contain `.`, because -it will be incorrectly considered as a separator. +Make sure the keys in the path of the API response do not contain `.`, because it will be incorrectly considered as a separator. ``` { @@ -175,18 +125,13 @@ it will be incorrectly considered as a separator. } ``` -A `_path` defined as `"strange.key"` will not work. As workaround you can -[escape the separator](/reference/ois/2.0/reserved-parameters.md#escaping-separators). +A `_path` defined as `"strange.key"` will not work. As workaround you can [escape the separator](/reference/ois/2.0/reserved-parameters.md#escaping-separators). ::: ### Escaping Separators -In rare cases, when the `_path` to the API response would contain `,` or `.` -(comma or a dot) things get a bit complicated. Those symbols have a very -specific meaning when parsing the reserved parameters and they need to be -escaped if they are to be considered as literals. If the API provider response -looks like the following: +In rare cases, when the `_path` to the API response would contain `,` or `.` (comma or a dot) things get a bit complicated. Those symbols have a very specific meaning when parsing the reserved parameters and they need to be escaped if they are to be considered as literals. If the API provider response looks like the following: ``` { @@ -198,9 +143,7 @@ Then escape the symbols, in this case `_path="very\\,strange\\.key"`. ## `_times` -If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided -Airnode multiplies the value returned by the API with the `_times` parameter -before fulfilling the request. For example, if the API returns: +If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided Airnode multiplies the value returned by the API with the `_times` parameter before fulfilling the request. For example, if the API returns: ``` { @@ -217,29 +160,15 @@ _path: data _times: "100" ``` -the request will be fulfilled with the value `123`. Note that the number gets -multiplied by `100`, and then gets floored. This is because the result of the -multiplication is [cast](/reference/airnode/v0.11/packages/adapter.md) to -`int256` afterwards. +the request will be fulfilled with the value `123`. Note that the number gets multiplied by `100`, and then gets floored. This is because the result of the multiplication is [cast](/reference/airnode/v0.11/packages/adapter.md) to `int256` afterwards. -Make sure to pass the `_times` parameter as string. Airnode will convert this -string to number internally. You can also pass and empty string `""` to `_times` -parameter - this has the same effect as if the `_times` parameter was not -provided. However, this is important when -[encoding multiple values](/reference/ois/2.0/reserved-parameters.md#encoding-multiple-values). +Make sure to pass the `_times` parameter as string. Airnode will convert this string to number internally. You can also pass and empty string `""` to `_times` parameter - this has the same effect as if the `_times` parameter was not provided. However, this is important when [encoding multiple values](/reference/ois/2.0/reserved-parameters.md#encoding-multiple-values). -The `_times` parameter also works in conjunction with arrays and -multidimensional arrays. All elements of the API response array will be -multiplied before they are encoded. +The `_times` parameter also works in conjunction with arrays and multidimensional arrays. All elements of the API response array will be multiplied before they are encoded. ## `_gasPrice` -The `_gasPrice` reserved parameter enables a requester to override -[Airnode gas price strategies](/reference/airnode/v0.11/concepts/gas-prices.md) -with a specified gas price when Airnode -[fulfills](/reference/airnode/v0.11/concepts/request.md#fulfill) the request. -The recommended implementation is to have the `_gasPrice` reserved parameter -without a `default` or `fixed` value as shown in the abbreviated snippet below: +The `_gasPrice` reserved parameter enables a requester to override [Airnode gas price strategies](/reference/airnode/v0.11/concepts/gas-prices.md) with a specified gas price when Airnode [fulfills](/reference/airnode/v0.11/concepts/request.md#fulfill) the request. The recommended implementation is to have the `_gasPrice` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -251,10 +180,7 @@ without a `default` or `fixed` value as shown in the abbreviated snippet below: } ``` -This allows requesters to specify the gas price via a parameter in their -request. The value, in `wei`, should be -[encoded](/reference/airnode/v0.11/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the gas price via a parameter in their request. The value, in `wei`, should be [encoded](/reference/airnode/v0.11/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; @@ -268,19 +194,11 @@ encode([ ]); ``` -Note that if a requester specifies a `_gasPrice` as a parameter in a request but -the Airnode's configuration does not include the `_gasPrice` reserved parameter, -the requester's gas price will be ignored. +Note that if a requester specifies a `_gasPrice` as a parameter in a request but the Airnode's configuration does not include the `_gasPrice` reserved parameter, the requester's gas price will be ignored. ## `_minConfirmations` -The `_minConfirmations` reserved parameter enables a requester to override the -default minimum number of block confirmations set by the Airnode for that chain -in -[config.json](/reference/airnode/v0.11/deployment-files/config-json.md#minconfirmations). -The recommended implementation is to have the `_minConfirmations` reserved -parameter without a `default` or `fixed` value as shown in the abbreviated -snippet below: +The `_minConfirmations` reserved parameter enables a requester to override the default minimum number of block confirmations set by the Airnode for that chain in [config.json](/reference/airnode/v0.11/deployment-files/config-json.md#minconfirmations). The recommended implementation is to have the `_minConfirmations` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -292,29 +210,20 @@ snippet below: } ``` -This allows requesters to specify the minimum number of block confirmations via -a parameter in their request. The value should be -[encoded](/reference/airnode/v0.11/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the minimum number of block confirmations via a parameter in their request. The value should be [encoded](/reference/airnode/v0.11/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; encode([{ name: '_minConfirmations', type: 'string32', value: '1' }]); ``` -In order to respond to requests in the same nonce order as they are received -when requests specify different `_minConfirmations` values, the maximum -`_minConfirmations` value of all requests in the queue for a given sponsor is -applied to all requests. +In order to respond to requests in the same nonce order as they are received when requests specify different `_minConfirmations` values, the maximum `_minConfirmations` value of all requests in the queue for a given sponsor is applied to all requests. -Note that if a requester specifies a `_minConfirmations` as a parameter in a -request but the Airnode's configuration does not include the `_minConfirmations` -reserved parameter, the requester's minimum confirmations value will be ignored. +Note that if a requester specifies a `_minConfirmations` as a parameter in a request but the Airnode's configuration does not include the `_minConfirmations` reserved parameter, the requester's minimum confirmations value will be ignored. ## Encoding Multiple Values -Solidity has support for decoding and "destructuring" multiple values. For -example: +Solidity has support for decoding and "destructuring" multiple values. For example: ```solidity function decodeMultipleParameters(bytes calldata data) @@ -326,11 +235,7 @@ function decodeMultipleParameters(bytes calldata data) } ``` -The example above demonstrates the decoding on chain of three values of types -`string`, `uint256` and `address` respectively. You can instruct Airnode to -encode these values using the `_type`, `_path`, and `_times` reserved parameters -by separating the values using `,` (comma). For example using the following -combination of reserved parameters: +The example above demonstrates the decoding on chain of three values of types `string`, `uint256` and `address` respectively. You can instruct Airnode to encode these values using the `_type`, `_path`, and `_times` reserved parameters by separating the values using `,` (comma). For example using the following combination of reserved parameters: ```js { @@ -340,10 +245,7 @@ combination of reserved parameters: } ``` -Airnode will split the reserved parameters by `,` into "split values" and ensure -they all contain the same number of them. It will extract and convert each of -the "split values". Notice, that an `""` (empty string) is used to specify that -a certain reserved parameter should not be used for a certain "split value". +Airnode will split the reserved parameters by `,` into "split values" and ensure they all contain the same number of them. It will extract and convert each of the "split values". Notice, that an `""` (empty string) is used to specify that a certain reserved parameter should not be used for a certain "split value". For example, let's say the API response looks like this: @@ -357,23 +259,15 @@ For example, let's say the API response looks like this: Airnode will extract and convert each of the "split values" separately -1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` - results in `"some string"` -2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` - results in `12345670` -3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` - results in `"0xe021...8a74"` +1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` results in `"some string"` +2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` results in `12345670` +3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` results in `"0xe021...8a74"` -All of these values are then together encoded to single bytes value that can be -sent on chain. You can use -[testing gateway](/reference/airnode/v0.11/understand/deploying.md#testing-with-http-gateway) -to inspect the raw API response, casting results and the final encoded value. +All of these values are then together encoded to single bytes value that can be sent on chain. You can use [testing gateway](/reference/airnode/v0.11/understand/deploying.md#testing-with-http-gateway) to inspect the raw API response, casting results and the final encoded value. ::: info Multiple Reserved Parameters Tutorial -The -[weather-multi-value](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates encoding of multiple values of different types. +The [weather-multi-value](/guides/airnode/monorepo-examples.md) monorepo example demonstrates encoding of multiple values of different types. ::: diff --git a/docs/reference/ois/2.0/specification.md b/docs/reference/ois/2.0/specification.md index 4f24a4f5..bc5e853f 100644 --- a/docs/reference/ois/2.0/specification.md +++ b/docs/reference/ois/2.0/specification.md @@ -19,34 +19,21 @@ tags: # {{$frontmatter.title}} -The Oracle Integration Specification (OIS) is based on -[Open API specification (OAS)](https://swagger.io/specification/), but there are -some differences, be sure to focus on the following documentation when working -on an OIS file. +The Oracle Integration Specification (OIS) is based on [Open API specification (OAS)](https://swagger.io/specification/), but there are some differences, be sure to focus on the following documentation when working on an OIS file. ::: warning OAS -It is not recommended to refer to OAS for help while creating an OIS object. OIS -only borrows formatting practices from OAS. Everything needed to create an OIS -object is in these docs. +It is not recommended to refer to OAS for help while creating an OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: -For an overview that explains how Airnode maps its endpoints to API provider -operations, see -[API integration](/reference/airnode/v0.11/understand/api-integration.md). Also -see the medium article -[Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) -for an overview of OIS. +For an overview that explains how Airnode maps its endpoints to API provider operations, see [API integration](/reference/airnode/v0.11/understand/api-integration.md). Also see the medium article [Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) for an overview of OIS. -- Fields denoted by (\*) are for documentation purposes and not used by an - Airnode. +- Fields denoted by (\*) are for documentation purposes and not used by an Airnode. - The OIS fields should be reviewed and customized by the integrating party. -- All URLs are absolute (i.e., - [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) - are not supported). +- All URLs are absolute (i.e., [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) are not supported). ## OIS Object Summary @@ -58,8 +45,7 @@ An OIS has five root fields (keys). 1. [apiSpecifications](/reference/ois/2.0/specification.md#_4-apispecifications) 1. [endpoints](/reference/ois/2.0/specification.md#_5-endpoints) -`apiSpecifications` describe the API's operations which are mapped to the -`endpoints` that Airnode exposes on-chain. +`apiSpecifications` describe the API's operations which are mapped to the `endpoints` that Airnode exposes on-chain. ```json { @@ -77,21 +63,17 @@ An OIS has five root fields (keys). ## 1. `oisFormat` -(Required) The OIS format version followed while generating the specifications. -See [Versions](/reference/ois/2.0/versions) for a list of OIS versions used by -each Airnode version. +(Required) The OIS format version followed while generating the specifications. See [Versions](/reference/ois/2.0/versions) for a list of OIS versions used by each Airnode version. ## 2. `title` -(Required) The OIS title. Title field is at most 64 characters, can only include -alphanumeric characters, hyphens, underscores and whitespaces. +(Required) The OIS title. Title field is at most 64 characters, can only include alphanumeric characters, hyphens, underscores and whitespaces. ## 3. `version` -(Required) A user defined version for the OIS object. Not to be confused with -the `oisFormat` version which defines an OIS formatting version. +(Required) A user defined version for the OIS object. Not to be confused with the `oisFormat` version which defines an OIS formatting version. ## 4. `apiSpecifications` @@ -139,21 +121,18 @@ the `oisFormat` version which defines an OIS formatting version. ### 4.1. `servers` -(Required) An array of objects containing the base URL of the API. Only one -object (i.e., base URL) is allowed in the array. Applies to all API operations. +(Required) An array of objects containing the base URL of the API. Only one object (i.e., base URL) is allowed in the array. Applies to all API operations. ### 4.2. `paths` -(Required) An object where an API's operations are defined by `{path}.{method}` -(i.e. `paths./myPath.get`) each with a `parameters` array. +(Required) An object where an API's operations are defined by `{path}.{method}` (i.e. `paths./myPath.get`) each with a `parameters` array. #### 4.2.1. `parameters` -(Required) A list of the API operation's parameters, each with the following -fields: +(Required) A list of the API operation's parameters, each with the following fields: - `name` - `in` @@ -177,9 +156,7 @@ the non-nested application/json content-type is supported.

### 4.3. `components` -(Required) An object where -[security schemes](/reference/airnode/v0.11/understand/api-security.md) can be -found under `securitySchemes.{securitySchemeName}` with the following elements: +(Required) An object where [security schemes](/reference/airnode/v0.11/understand/api-security.md) can be found under `securitySchemes.{securitySchemeName}` with the following elements: - `type` - `name` @@ -195,8 +172,7 @@ Allowed values: - Used by an API operation to authenticate Airnode. - `apiKey` - `http` -- Allows an API operation to acquire information about the requester and/or the - chain. +- Allows an API operation to acquire information about the requester and/or the chain. - `relayRequesterAddress` - `relaySponsorAddress` - `relaySponsorWalletAddress` @@ -222,9 +198,7 @@ Allowed values: `query`, `header`, `cookie` #### 4.3.4. `scheme` -(Only if `type` is http) The name of the HTTP Authorization scheme to be used in -the -[Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). +(Only if `type` is http) The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). Allowed values: (`basic` and `bearer`). @@ -241,20 +215,9 @@ Allowed values: (`basic` and `bearer`). ### 4.4. `security` -(Required) An object containing all security schemes required by an API call. -Applies to all operations. A security scheme can contain information required by -the API to authenticate Airnode as well as information about the requester -(relay information) the API may also require. Read more about security schemes -in the [API Security](/reference/airnode/v0.11/understand/api-security.md) -section of the _Build an Airnode_ guide and the -[Airnode Authentication](/reference/airnode/v0.11/concepts/airnode-auth.md) -section of _Concepts and Definitions_. - -The `security` object maintains the names of all the security schemes used. Each -security scheme in `security` maps to an empty list. The empty list will be used -by future versions of Airnode for individual endpoint authentication. The -`components.securitySchemes.{name}` object defines the security schemes. Unlike -OAS `security` is an object, not an array. +(Required) An object containing all security schemes required by an API call. Applies to all operations. A security scheme can contain information required by the API to authenticate Airnode as well as information about the requester (relay information) the API may also require. Read more about security schemes in the [API Security](/reference/airnode/v0.11/understand/api-security.md) section of the _Build an Airnode_ guide and the [Airnode Authentication](/reference/airnode/v0.11/concepts/airnode-auth.md) section of _Concepts and Definitions_. + +The `security` object maintains the names of all the security schemes used. Each security scheme in `security` maps to an empty list. The empty list will be used by future versions of Airnode for individual endpoint authentication. The `components.securitySchemes.{name}` object defines the security schemes. Unlike OAS `security` is an object, not an array. ```json // OIS object @@ -273,8 +236,7 @@ OAS `security` is an object, not an array. } ``` -The `apiCredential` object (which is not part of the OIS object) holds -credentials needed by the security scheme if any. +The `apiCredential` object (which is not part of the OIS object) holds credentials needed by the security scheme if any. ```json // config.json root object. @@ -292,41 +254,30 @@ credentials needed by the security scheme if any. ::: warning Please note: -Currently Airnode reads the security schemes from `component.securitySchemes` -and not `security`. Using the `security` field now (in conjunction with -`component.securitySchemes`) provides for a smooth transition to future releases -of Airnode with regards to security scheme implementation. This will allow -assigning of security schemes to individual API operations. Currently security -schemes are assign to the entire API. +Currently Airnode reads the security schemes from `component.securitySchemes` and not `security`. Using the `security` field now (in conjunction with `component.securitySchemes`) provides for a smooth transition to future releases of Airnode with regards to security scheme implementation. This will allow assigning of security schemes to individual API operations. Currently security schemes are assign to the entire API. ::: ## 5. `endpoints` -(Required) A list of objects, each specifying an Airnode endpoint with the -following fields: +(Required) A list of objects, each specifying an Airnode endpoint with the following fields: ::: info Please Note -Fields denoted by \* are for documentation purposes and not used by Airnode -node. +Fields denoted by \* are for documentation purposes and not used by Airnode node. ::: - 5.1. [name](/reference/ois/2.0/specification.md#_5-1-name) - 5.2. [operation](/reference/ois/2.0/specification.md#_5-2-operation) -- 5.3. - [fixedOperationParameters](/reference/ois/2.0/specification.md#_5-3-fixedoperationparameters) -- 5.4. - [reservedParameters](/reference/ois/2.0/specification.md#_5-4-reservedparameters) +- 5.3. [fixedOperationParameters](/reference/ois/2.0/specification.md#_5-3-fixedoperationparameters) +- 5.4. [reservedParameters](/reference/ois/2.0/specification.md#_5-4-reservedparameters) - 5.5. [parameters](/reference/ois/2.0/specification.md#_5-5-parameters) - 5.6. [summary \*](/reference/ois/2.0/specification.md#_5-6-summary) - 5.7. [description \*](/reference/ois/2.0/specification.md#_5-7-description) - 5.8. [externalDocs \*](/reference/ois/2.0/specification.md#_5-8-externaldocs) -- 5.9. - [preProcessingSpecifications](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) -- 5.10. - [postProcessingSpecifications](/reference/ois/2.0/specification.md#_5-10-postprocessingspecifications) +- 5.9. [preProcessingSpecifications](/reference/ois/2.0/specification.md#_5-9-preprocessingspecifications) +- 5.10. [postProcessingSpecifications](/reference/ois/2.0/specification.md#_5-10-postprocessingspecifications) ```json // endpoints @@ -407,18 +358,12 @@ operation.--> ### 5.2. `operation` -(Required: when calling an API) An object that refers to an API operation -defined in `apiSpecifications.paths`. The following elements must be defined: +(Required: when calling an API) An object that refers to an API operation defined in `apiSpecifications.paths`. The following elements must be defined: - `path` - `method` -The `operation` field must be omitted if the intent is _not_ to call an API but -rather return a value from the -[Pre/Post Processing](/reference/ois/2.0/processing.md) capabilities of Airnode. -See -[Skip the API provider call](/reference/ois/2.0/processing.md#skip-the-api-call) -for more information. +The `operation` field must be omitted if the intent is _not_ to call an API but rather return a value from the [Pre/Post Processing](/reference/ois/2.0/processing.md) capabilities of Airnode. See [Skip the API provider call](/reference/ois/2.0/processing.md#skip-the-api-call) for more information. #### 5.2.1. `path` @@ -438,18 +383,14 @@ respective API operation.--> ### 5.3. `fixedOperationParameters` -(Required) A list of objects specifying the fixed parameters for an API -operation. While required, the -[fixedOperationParameters](/reference/airnode/v0.11/understand/api-integration.md#fixedoperationparameters) -array can be left empty. Each object has the following elements: +(Required) A list of objects specifying the fixed parameters for an API operation. While required, the [fixedOperationParameters](/reference/airnode/v0.11/understand/api-integration.md#fixedoperationparameters) array can be left empty. Each object has the following elements: - `operationParameter` - `value` #### 5.3.1. `operationParameter` -(Required) An object that refers to a parameter of an API operation with the -following elements: +(Required) An object that refers to a parameter of an API operation with the following elements: - `name` - `in` @@ -464,52 +405,35 @@ following elements: #### 5.3.2. `value` -(Required) The value to be used for the respective parameter of an API operation -that cannot be overridden by the requester. +(Required) The value to be used for the respective parameter of an API operation that cannot be overridden by the requester. ### 5.4. `reservedParameters` -A list of objects that specify reserved Airnode endpoint parameters that do not -map to any API operation parameters, but are used for special purposes by the -Airnode. See the -[Reserved Parameters](/reference/ois/2.0/reserved-parameters.md) doc for an -in-depth explanation and -[reservedParameters](/reference/airnode/v0.11/understand/api-integration.md#reservedparameters). -Each object has the following elements: +A list of objects that specify reserved Airnode endpoint parameters that do not map to any API operation parameters, but are used for special purposes by the Airnode. See the [Reserved Parameters](/reference/ois/2.0/reserved-parameters.md) doc for an in-depth explanation and [reservedParameters](/reference/airnode/v0.11/understand/api-integration.md#reservedparameters). Each object has the following elements: - `name` - `fixed` - `default` -Note that if a reserved parameter object does not include a `fixed` value, a -requester can, or may be expected to, supply this value as a parameter. A value -supplied by a requester overrides a `default`. See the -[\_gasPrice](/reference/ois/2.0/reserved-parameters.md#gasprice) reserved -parameter description for an example. +Note that if a reserved parameter object does not include a `fixed` value, a requester can, or may be expected to, supply this value as a parameter. A value supplied by a requester overrides a `default`. See the [\_gasPrice](/reference/ois/2.0/reserved-parameters.md#gasprice) reserved parameter description for an example. #### 5.4.1. `name` (Required) The name of the reserved parameter. Always starts with `_`. -Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and -`_minConfirmations`. +Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. #### 5.4.2. `fixed` -(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. -Cannot be used together with `default`. +(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. Cannot be used together with `default`. #### 5.4.3. `default` -(Optional) The default value for the reserved parameter. Used when no value is -provided by a requester. Cannot be used together with `fixed`. +(Optional) The default value for the reserved parameter. Used when no value is provided by a requester. Cannot be used together with `fixed`. ### 5.5. `parameters` -(Optional) A list of objects that specify Airnode endpoint -[parameters](/reference/airnode/v0.11/understand/api-integration.md#parameters) -that map to an particular API operation's parameters. Each object has the -following elements: +(Optional) A list of objects that specify Airnode endpoint [parameters](/reference/airnode/v0.11/understand/api-integration.md#parameters) that map to an particular API operation's parameters. Each object has the following elements: - `operationParameter` - `name` @@ -520,8 +444,7 @@ following elements: #### 5.5.1. `operationParameter` -(Required) An object that refers to a parameter of an API operation, has the -following elements: +(Required) An object that refers to a parameter of an API operation, has the following elements: - `name` - `in` @@ -536,16 +459,14 @@ following elements: #### 5.5.2. `name` -(Required) The name of the Airnode endpoint parameter. Is not allowed to start -with `_`. +(Required) The name of the Airnode endpoint parameter. Is not allowed to start with `_`. #### 5.5.3. `default` -(Optional) The default value for the Airnode endpoint parameter. Used when no -value is provided. +(Optional) The default value for the Airnode endpoint parameter. Used when no value is provided. @@ -591,11 +512,9 @@ corresponding operation parameter.--> ### 5.9. `preProcessingSpecifications` \* -(Optional) Defines the preprocessing code that can be used to modify the -endpoint parameter before making the API request defined by an Airnode endpoint. +(Optional) Defines the preprocessing code that can be used to modify the endpoint parameter before making the API request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/2.0/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/2.0/processing.md) doc for additional details. #### Example @@ -622,11 +541,9 @@ additional details. ### 5.10. `postProcessingSpecifications` \* -(Optional) Defines the post-processing code that can be used to modify the API -response from the request defined by an Airnode endpoint. +(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/2.0/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/2.0/processing.md) doc for additional details. #### Example diff --git a/docs/reference/ois/2.0/template.md b/docs/reference/ois/2.0/template.md index 2d0103c5..33242059 100644 --- a/docs/reference/ois/2.0/template.md +++ b/docs/reference/ois/2.0/template.md @@ -19,19 +19,11 @@ tags: # {{$frontmatter.title}} -An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's -`config.json` file. +An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's `config.json` file. -In the OIS template, there are some fields that contain . This means -that the value you will be replacing this with is independent from the other -fields. On the other hand, if two fields contain the same expression (e.g., -``), you must use the same value in them, -because they are referencing each other. +In the OIS template, there are some fields that contain . This means that the value you will be replacing this with is independent from the other fields. On the other hand, if two fields contain the same expression (e.g., ``), you must use the same value in them, because they are referencing each other. -The file below is a basic template for OIS. Note, that it might look differently -for your particular use case. You can also check out the OISes created for the -examples in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations). +The file below is a basic template for OIS. Note, that it might look differently for your particular use case. You can also check out the OISes created for the examples in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.11/packages/airnode-examples/integrations). ```json { diff --git a/docs/reference/ois/2.0/versions.md b/docs/reference/ois/2.0/versions.md index 7f4e63fe..856db4ec 100644 --- a/docs/reference/ois/2.0/versions.md +++ b/docs/reference/ois/2.0/versions.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Be sure to use the correct OIS version for the Airnode version you are -deploying. +Be sure to use the correct OIS version for the Airnode version you are deploying. | Airnode version | Latest compatible OIS version | | ------------------- | -------------------------------------------- | @@ -32,10 +31,8 @@ deploying. | 0.8.x | [1.1.2](https://old-docs.api3.org/ois/v1.1/) | | 0.2.x through 0.7.x | [1.0.0](https://old-docs.api3.org/ois/v1.0/) | -Documentation for versions `v1.0.0` through `v1.4.0` are available on the -[legacy documentation site](https://old-docs.api3.org). +Documentation for versions `v1.0.0` through `v1.4.0` are available on the [legacy documentation site](https://old-docs.api3.org). -See GitHub [releases](https://github.com/api3dao/ois/releases) for more -information about the changes in each version. +See GitHub [releases](https://github.com/api3dao/ois/releases) for more information about the changes in each version. diff --git a/docs/reference/ois/2.1/index.md b/docs/reference/ois/2.1/index.md index 832b9410..f60f9ea6 100644 --- a/docs/reference/ois/2.1/index.md +++ b/docs/reference/ois/2.1/index.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -OIS (or Oracle Integration Specifications) is a JSON object that describes an -API specification and defines Airnode endpoints linked to API operations (a.k.a. -endpoints). It is one of five root level objects in a `config.json` file that -defines an Airnode. +OIS (or Oracle Integration Specifications) is a JSON object that describes an API specification and defines Airnode endpoints linked to API operations (a.k.a. endpoints). It is one of five root level objects in a `config.json` file that defines an Airnode. - chains - nodeSettings @@ -30,14 +27,9 @@ defines an Airnode. - ois - apiCredentials -For more information about the config.json file see the -[Deployment Files](/reference/airnode/v0.12/deployment-files/config-json.md) -section in the Airnode document set. +For more information about the config.json file see the [Deployment Files](/reference/airnode/v0.12/deployment-files/config-json.md) section in the Airnode document set. -In the diagram below, an Airnode exposes its endpoints to the on-chain -AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to -an API operation. It should be noted that Airnode can have more than one -endpoint that maps to the same API operation. +In the diagram below, an Airnode exposes its endpoints to the on-chain AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to an API operation. It should be noted that Airnode can have more than one endpoint that maps to the same API operation. > > @@ -47,18 +39,11 @@ endpoint that maps to the same API operation. ## API Mapping Examples -The following are three possible Airnode to API operation mapping examples. -Mapping details are better documented in the next doc -[Specification](/reference/ois/2.1/specification.md). +The following are three possible Airnode to API operation mapping examples. Mapping details are better documented in the next doc [Specification](/reference/ois/2.1/specification.md). ### Simple Airnode Endpoint -An API has a simple operation the returns the current value of an on-chain token -`GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint -will only mimic the API operation. To do so, the Airnode will declare its -endpoint to have one parameter, `id`. Airnode will accept an `id` argument from -an on-chain request and move its value to the API operation's path parameter -named `id`. +An API has a simple operation the returns the current value of an on-chain token `GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint will only mimic the API operation. To do so, the Airnode will declare its endpoint to have one parameter, `id`. Airnode will accept an `id` argument from an on-chain request and move its value to the API operation's path parameter named `id`. ```json // ois.apiSpecifications (API operations) @@ -97,25 +82,11 @@ named `id`. ### Fixed Operation Parameters Airnode Endpoint -An API may have an operation that returns a crypto coin in either a summary or -detail form. The API operation has two parameters, `coinId` in the path and -`includeDetails` in the query. The Airnode (by design) will not allow the -details of the coin to be returned, only the summary. Therefore the Airnode will -require a requester to pass a `coinId` but will ignore the `includeDetails` -parameter if passed. The Airnode will always set the `includeDetails` query -parameter to false regardless of what a requester sends when it calls the API -operation. It does so using a `fixedOperationParameters` when calling the API -operation. +An API may have an operation that returns a crypto coin in either a summary or detail form. The API operation has two parameters, `coinId` in the path and `includeDetails` in the query. The Airnode (by design) will not allow the details of the coin to be returned, only the summary. Therefore the Airnode will require a requester to pass a `coinId` but will ignore the `includeDetails` parameter if passed. The Airnode will always set the `includeDetails` query parameter to false regardless of what a requester sends when it calls the API operation. It does so using a `fixedOperationParameters` when calling the API operation. ### Two Airnode Endpoints - One API Operation -An Airnode may wish to create two Airnode endpoints mapped to a single API -operation whereas the requester does not pass any argument. While the API -operation returns any token value based on a path parameter `id`, Airnode will -only allow one particular token per Airnode endpoint. This is done using -`fixedOperationParameters` rather than normal `parameters`. By applying a -`value` to `fixedOperationParameters` for each Airnode endpoint, only the token -in the `value` can be returned to the requester. +An Airnode may wish to create two Airnode endpoints mapped to a single API operation whereas the requester does not pass any argument. While the API operation returns any token value based on a path parameter `id`, Airnode will only allow one particular token per Airnode endpoint. This is done using `fixedOperationParameters` rather than normal `parameters`. By applying a `value` to `fixedOperationParameters` for each Airnode endpoint, only the token in the `value` can be returned to the requester. ```json "endpoints": [ diff --git a/docs/reference/ois/2.1/processing.md b/docs/reference/ois/2.1/processing.md index 7a7c729b..b53a6874 100644 --- a/docs/reference/ois/2.1/processing.md +++ b/docs/reference/ois/2.1/processing.md @@ -19,70 +19,40 @@ tags: # {{$frontmatter.title}} -The processing schema accepts an array of processing snippets (user defined -code) which are chained. The first snippet receives parameters submitted as part -of a template or on-chain request. The output of this snippet is passed to the -second snippet and so on. +The processing schema accepts an array of processing snippets (user defined code) which are chained. The first snippet receives parameters submitted as part of a template or on-chain request. The output of this snippet is passed to the second snippet and so on. -Airnode executes snippets for `preProcessingSpecifications` and -`postProcessingSpecifications` during its run cycle. The following describes the -work flow Airnode uses: +Airnode executes snippets for `preProcessingSpecifications` and `postProcessingSpecifications` during its run cycle. The following describes the work flow Airnode uses: 1. Run `preProcessingSpecifications` 2. Airnode calls requested OIS endpoint 3. Run `postProcessingSpecifications` 4. Airnode encodes the response values defined by reservedParameters -The processing schema is the same for both -[`preProcessingSpecifications`](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) -and -[`postProcessingSpecifications`](/reference/ois/2.1/specification.md#_5-10-postprocessingspecifications). -Snippets for both specifications follow this schema: - -- `environment` - Currently one of `Node` or `Node async`. Both options - interpret the code as JavaScript and execute in Node.js. The async version can - use asynchronous code. The code snippet is expected to call `resolve(output)` - with the output value as an argument. Airnode will use the resolved value as - the input to subsequent snippets (if defined). +The processing schema is the same for both [`preProcessingSpecifications`](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) and [`postProcessingSpecifications`](/reference/ois/2.1/specification.md#_5-10-postprocessingspecifications). Snippets for both specifications follow this schema: + +- `environment` - Currently one of `Node` or `Node async`. Both options interpret the code as JavaScript and execute in Node.js. The async version can use asynchronous code. The code snippet is expected to call `resolve(output)` with the output value as an argument. Airnode will use the resolved value as the input to subsequent snippets (if defined). - `value` - The processing code written as a string. -- `timeoutMs` - The maximum duration that this snippet can run. In case the - timeout is exceeded an error is thrown. +- `timeoutMs` - The maximum duration that this snippet can run. In case the timeout is exceeded an error is thrown. -Try the [Post processing](/guides/airnode/post-processing/) guide to further -understand pre/post processing. +Try the [Post processing](/guides/airnode/post-processing/) guide to further understand pre/post processing. ## Input and Output -The processing snippet receives an `input` value which is either the initial -value or the output value from the previous processing snippet. The snippet must -create a variable `output` which will be used for the next processing snippet. -The processing snippet can use most Node.js built-in modules. Refer to the -source code of Airnode to understand how processing works and what modules are -made available to the snippet code. Modules cannot be imported directly in cloud -environments. +The processing snippet receives an `input` value which is either the initial value or the output value from the previous processing snippet. The snippet must create a variable `output` which will be used for the next processing snippet. The processing snippet can use most Node.js built-in modules. Refer to the source code of Airnode to understand how processing works and what modules are made available to the snippet code. Modules cannot be imported directly in cloud environments. ## Accessing endpoint parameters -Endpoint parameters, with the exception of reserved parameters, are accessible -within pre-processing and post-processing via the immutable `endpointParameters` -object. For example, if there was a parameter named `myParameter` defined in the -`endpoints[n].parameters` array, its value could be accessed using -`endpointParameters.myParameter` within pre-processing and post-processing code -snippets. +Endpoint parameters, with the exception of reserved parameters, are accessible within pre-processing and post-processing via the immutable `endpointParameters` object. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing and post-processing code snippets. ::: info Accessing reserved parameters -Note that reserved parameters are inaccessible in both pre-processing and -post-processing. +Note that reserved parameters are inaccessible in both pre-processing and post-processing. ::: ## Interpolation -Note, that config.json supports interpolation of secrets via the JavaScript -string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with -the string interpolation inside the processing snippets. In order to use the -interpolation in snippets, you need to escape the interpolation. +Note, that config.json supports interpolation of secrets via the JavaScript string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with the string interpolation inside the processing snippets. In order to use the interpolation in snippets, you need to escape the interpolation. For example, the following code: @@ -103,57 +73,27 @@ should be escaped inside the `config.json` like this: ## Error Handling and Security -Processing code is expected to be trustworthy as it is specified by the Airnode -operator. Processing is an advanced feature that carries great security risks. -It is therefore advised that developers using the processing feature familiarize -themselves with the Airnode sources prior to developing any processing code -snippets. +Processing code is expected to be trustworthy as it is specified by the Airnode operator. Processing is an advanced feature that carries great security risks. It is therefore advised that developers using the processing feature familiarize themselves with the Airnode sources prior to developing any processing code snippets. -Processing code executes in a constrained execution environment resembling -Node.js. Some resources may not be available, for example the `require` -statement. Therefore code should be tested thoroughly in the target environment -(e.g. Lambda and/or Docker client). For example, authentication implemented in -pre-processing should always be executed at the end of the respective processing -chain and special care should be taken to avoid leakage of secrets. +Processing code executes in a constrained execution environment resembling Node.js. Some resources may not be available, for example the `require` statement. Therefore code should be tested thoroughly in the target environment (e.g. Lambda and/or Docker client). For example, authentication implemented in pre-processing should always be executed at the end of the respective processing chain and special care should be taken to avoid leakage of secrets. ## Skip the API call -Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on -either (or both) pre-processing or post-processing to acquire a value for the -Airnode to place on-chain. +Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on either (or both) pre-processing or post-processing to acquire a value for the Airnode to place on-chain. -Instead of calling an API, Airnode uses the output of -`preProcessingSpecifications`, `postProcessingSpecifications`, or both. The -field `operation` must be undefined, `fixedOperationParameters` must be an empty -array and one of `preProcessingSpecifications` or `postProcessingSpecifications` -must be defined and not be an empty array. +Instead of calling an API, Airnode uses the output of `preProcessingSpecifications`, `postProcessingSpecifications`, or both. The field `operation` must be undefined, `fixedOperationParameters` must be an empty array and one of `preProcessingSpecifications` or `postProcessingSpecifications` must be defined and not be an empty array. ### Use case: random number -An Airnode endpoint that places a random number on-chain. Rather than calling an -API, the Airnode will derive a random number during its execution of a -pre-process specification. A requester would make a request of this Airnode -endpoint without parameters. The Airnode endpoint simply sets the random number -on-chain in response to the request using a `preProcessingSpecifications` -specification. Example #1 below implements this use case. +An Airnode endpoint that places a random number on-chain. Rather than calling an API, the Airnode will derive a random number during its execution of a pre-process specification. A requester would make a request of this Airnode endpoint without parameters. The Airnode endpoint simply sets the random number on-chain in response to the request using a `preProcessingSpecifications` specification. Example #1 below implements this use case. ### Example #1 -This example creates an Airnode endpoint named `generateRandomNumber` with no -parameters. Because there isn't an -[operation field](/reference/ois/2.1/specification.md#_5-2-operation) defined -for this Airnode endpoint, a call to an API will not be made. The Airnode will -instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) -array. - -To implement the use case mentioned above, the -[operation field](/reference/ois/2.1/specification.md#_5-2-operation) will be -undefined, `fixedOperationParameters` will be an empty array, and -`preProcessingSpecifications` will be defined with a single specification. - -- A requester makes a request of the Airnode endpoint `generateRandomNumber` - without any parameters. +This example creates an Airnode endpoint named `generateRandomNumber` with no parameters. Because there isn't an [operation field](/reference/ois/2.1/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) array. + +To implement the use case mentioned above, the [operation field](/reference/ois/2.1/specification.md#_5-2-operation) will be undefined, `fixedOperationParameters` will be an empty array, and `preProcessingSpecifications` will be defined with a single specification. + +- A requester makes a request of the Airnode endpoint `generateRandomNumber` without any parameters. - Airnode runs the specification in `preProcessingSpecifications[0]`. - The specification generates a random number. - The reserved parameter named `randomNumber` now holds the random number. @@ -191,15 +131,7 @@ endpoints: [ ### Example #2 -The code below is unrelated to the -[use case](/reference/ois/2.1/processing.md#use-case-random-number) mentioned -earlier. This example creates an Airnode endpoint named -`endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there -isn't an [operation field](/reference/ois/2.1/specification.md#_5-2-operation) -defined for this Airnode endpoint, a call to an API will not be made. The -Airnode will instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) -array. +The code below is unrelated to the [use case](/reference/ois/2.1/processing.md#use-case-random-number) mentioned earlier. This example creates an Airnode endpoint named `endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there isn't an [operation field](/reference/ois/2.1/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) array. - A requester passes the number `5` in the parameter named `numberToSum`. - Airnode runs the specification in `preProcessingSpecifications[0]`. diff --git a/docs/reference/ois/2.1/reserved-parameters.md b/docs/reference/ois/2.1/reserved-parameters.md index 2e21fdfd..9e72f6c8 100644 --- a/docs/reference/ois/2.1/reserved-parameters.md +++ b/docs/reference/ois/2.1/reserved-parameters.md @@ -19,63 +19,36 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an OIS object as part of the `endpoints` field -(Airnode endpoints) and warrant a more in-depth explanation. They are part of an -Airnode's defined endpoints in an OIS object but do not map to operation -parameters (API parameters). They are used by Airnode for special purposes. - -A requester can pass request parameters either by referencing a -[template](/reference/airnode/v0.12/concepts/template.md) that contains them, or -as an argument of the request-making methods of -[AirnodeRrpV0.sol](/reference/airnode/v0.12/concepts/#airnoderrpv0-sol). In -either case, these parameters are encoded using the -[AirnodeRrpV0 ABI](/reference/airnode/v0.12/specifications/airnode-abi.md). -There are two types of parameters which are part of the OIS object: - -1. [Endpoint parameters](/reference/ois/2.1/specification.md#_5-5-parameters) - - Airnode endpoint parameters are mapped to API operation parameters. -2. [Reserved parameters](/reference/ois/2.1/specification.md#_5-4-reservedparameters) - - Reserved parameters perform a specific operation related to the request or on - the response before fulfilling the request. Reserved parameter names start - with `_`. Depending on the configuration, they may be overridden by a - parameter supplied by a requester. +Reserved parameters are part of an OIS object as part of the `endpoints` field (Airnode endpoints) and warrant a more in-depth explanation. They are part of an Airnode's defined endpoints in an OIS object but do not map to operation parameters (API parameters). They are used by Airnode for special purposes. + +A requester can pass request parameters either by referencing a [template](/reference/airnode/v0.12/concepts/template.md) that contains them, or as an argument of the request-making methods of [AirnodeRrpV0.sol](/reference/airnode/v0.12/concepts/#airnoderrpv0-sol). In either case, these parameters are encoded using the [AirnodeRrpV0 ABI](/reference/airnode/v0.12/specifications/airnode-abi.md). There are two types of parameters which are part of the OIS object: + +1. [Endpoint parameters](/reference/ois/2.1/specification.md#_5-5-parameters) - Airnode endpoint parameters are mapped to API operation parameters. +2. [Reserved parameters](/reference/ois/2.1/specification.md#_5-4-reservedparameters) - Reserved parameters perform a specific operation related to the request or on the response before fulfilling the request. Reserved parameter names start with `_`. Depending on the configuration, they may be overridden by a parameter supplied by a requester. ## `_type` -Signifies what Solidity type the API response will be encoded to before -fulfillment. +Signifies what Solidity type the API response will be encoded to before fulfillment. -Support is provided for most common -[Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), -but the following are not supported. +Support is provided for most common [Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), but the following are not supported. - Custom bits integer types - e.g. `uint32` or `uint8` - Fixed point decimal numbers - e.g. `fixed128x18` or `ufixed128x18` - Custom fixed size bytes - e.g. `bytes4` - Tuples - e.g. `(int256, string)` -On top of supported solidity types, there is support for a few "artificial" -types created for special purposes that would otherwise be hard or impossible to -represent. +On top of supported solidity types, there is support for a few "artificial" types created for special purposes that would otherwise be hard or impossible to represent. - [`string32`](/reference/ois/2.1/reserved-parameters.md#string32-encoded-to-bytes32-on-chain) - [`timestamp`](/reference/ois/2.1/reserved-parameters.md#timestamp-encoded-to-uint256-on-chain) -You can also encode multiple values for one single API call - but this impacts -all of the reserved parameters and is explained in the -[Encoding Multiple Values](/reference/ois/2.1/reserved-parameters.md#encoding-multiple-values) -section below. +You can also encode multiple values for one single API call - but this impacts all of the reserved parameters and is explained in the [Encoding Multiple Values](/reference/ois/2.1/reserved-parameters.md#encoding-multiple-values) section below. ### Conversion and encoding behavior -Before the API response value is encoded for on chain use, it is parsed and -converted. The conversion behaviors for any given type is explained in depth in -the -[adapter package docs](/reference/airnode/v0.12/packages/adapter.md#conversion). +Before the API response value is encoded for on chain use, it is parsed and converted. The conversion behaviors for any given type is explained in depth in the [adapter package docs](/reference/airnode/v0.12/packages/adapter.md#conversion). -The converted value is then encoded internally by -[ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) -using the following +The converted value is then encoded internally by [ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) using the following ```js ethers.utils.defaultAbiCoder.encode([solidityType], [value]); @@ -93,54 +66,35 @@ ethers.utils.defaultAbiCoder.encode([solidityType], [value]); #### string32 (encoded to `bytes32` on chain) -The `string32` is an artificial type that is not supported by solidity. It is -instead encoded to `bytes32` and provides a cheaper alternative to the regular -`string` type for values with less than 32 characters. +The `string32` is an artificial type that is not supported by solidity. It is instead encoded to `bytes32` and provides a cheaper alternative to the regular `string` type for values with less than 32 characters. ::: warning Limitations -While using `string32` is more efficient, decoding the original string from -`bytes32` on chain is both difficult and expensive. Also bear in mind that this -type is able to encode only strings shorter than 32 characters. If the value is -longer, it will be trimmed and only first 31 characters will be encoded. +While using `string32` is more efficient, decoding the original string from `bytes32` on chain is both difficult and expensive. Also bear in mind that this type is able to encode only strings shorter than 32 characters. If the value is longer, it will be trimmed and only first 31 characters will be encoded. ::: #### timestamp (encoded to `uint256` on chain) -The `timestamp` is an artificial type that is not supported by solidity. It is -instead encoded to `uint256` and specifies the UNIX timestamp value at the time -when the transaction was encoded. You can use this value on chain to check the -"freshness" of the Airnode response. This might be useful in certain scenarios, -because Airnode cannot guarantee when a particular transaction will be mined on -chain. +The `timestamp` is an artificial type that is not supported by solidity. It is instead encoded to `uint256` and specifies the UNIX timestamp value at the time when the transaction was encoded. You can use this value on chain to check the "freshness" of the Airnode response. This might be useful in certain scenarios, because Airnode cannot guarantee when a particular transaction will be mined on chain. -When using the `timestamp` type, the corresponding `_path` and `_times` -variables must be empty strings or not provided. +When using the `timestamp` type, the corresponding `_path` and `_times` variables must be empty strings or not provided. #### Arrays -Apart from the primitives defined above as well as all "artificial" types we -created, you are free to use arrays with any of the above. Multidimensional -arrays are supported as well. Solidity allows you to define fixed size arrays, -which are more gas efficient to encode and you can use those as well. +Apart from the primitives defined above as well as all "artificial" types we created, you are free to use arrays with any of the above. Multidimensional arrays are supported as well. Solidity allows you to define fixed size arrays, which are more gas efficient to encode and you can use those as well. For example - `int256[]` - regular integer array - `uint256[8]` - unsigned integer array with 8 elements - `int256[][]` - 2 dimensional integer array -- `string32[]` - is an array of `string32` values, which will be encoded to - `bytes32[]` on chain -- `string[2][][3]` - 3 dimensional string array, where first dimension contains - 3 elements, second unboundedly many and last dimension only 2. Note that this - [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) - compared to C-style languages +- `string32[]` - is an array of `string32` values, which will be encoded to `bytes32[]` on chain +- `string[2][][3]` - 3 dimensional string array, where first dimension contains 3 elements, second unboundedly many and last dimension only 2. Note that this [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) compared to C-style languages ## `_path` -Assuming that the API response will be a JSON object, defines the field to be -used to fulfill the request using dot notation. For example, if the API returns +Assuming that the API response will be a JSON object, defines the field to be used to fulfill the request using dot notation. For example, if the API returns ``` { @@ -159,15 +113,11 @@ used to fulfill the request using dot notation. For example, if the API returns and `_path` is `field1.fieldA.1`, the response will be `valueA2`. -If the response is a literal value (i.e., not a JSON object) and `_path` is not -provided or is an empty string (needed for -[encoding multiple values](/reference/ois/2.1/reserved-parameters.md#encoding-multiple-values)), -Airnode will use the API response itself to fulfill the request. +If the response is a literal value (i.e., not a JSON object) and `_path` is not provided or is an empty string (needed for [encoding multiple values](/reference/ois/2.1/reserved-parameters.md#encoding-multiple-values)), Airnode will use the API response itself to fulfill the request. ::: warning Beware the separator -Make sure the keys in the path of the API response do not contain `.`, because -it will be incorrectly considered as a separator. +Make sure the keys in the path of the API response do not contain `.`, because it will be incorrectly considered as a separator. ``` { @@ -175,18 +125,13 @@ it will be incorrectly considered as a separator. } ``` -A `_path` defined as `"strange.key"` will not work. As workaround you can -[escape the separator](/reference/ois/2.1/reserved-parameters.md#escaping-separators). +A `_path` defined as `"strange.key"` will not work. As workaround you can [escape the separator](/reference/ois/2.1/reserved-parameters.md#escaping-separators). ::: ### Escaping Separators -In rare cases, when the `_path` to the API response would contain `,` or `.` -(comma or a dot) things get a bit complicated. Those symbols have a very -specific meaning when parsing the reserved parameters and they need to be -escaped if they are to be considered as literals. If the API provider response -looks like the following: +In rare cases, when the `_path` to the API response would contain `,` or `.` (comma or a dot) things get a bit complicated. Those symbols have a very specific meaning when parsing the reserved parameters and they need to be escaped if they are to be considered as literals. If the API provider response looks like the following: ``` { @@ -198,9 +143,7 @@ Then escape the symbols, in this case `_path="very\\,strange\\.key"`. ## `_times` -If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided -Airnode multiplies the value returned by the API with the `_times` parameter -before fulfilling the request. For example, if the API returns: +If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided Airnode multiplies the value returned by the API with the `_times` parameter before fulfilling the request. For example, if the API returns: ``` { @@ -217,29 +160,15 @@ _path: data _times: "100" ``` -the request will be fulfilled with the value `123`. Note that the number gets -multiplied by `100`, and then gets floored. This is because the result of the -multiplication is [cast](/reference/airnode/v0.12/packages/adapter.md) to -`int256` afterwards. +the request will be fulfilled with the value `123`. Note that the number gets multiplied by `100`, and then gets floored. This is because the result of the multiplication is [cast](/reference/airnode/v0.12/packages/adapter.md) to `int256` afterwards. -Make sure to pass the `_times` parameter as string. Airnode will convert this -string to number internally. You can also pass and empty string `""` to `_times` -parameter - this has the same effect as if the `_times` parameter was not -provided. However, this is important when -[encoding multiple values](/reference/ois/2.1/reserved-parameters.md#encoding-multiple-values). +Make sure to pass the `_times` parameter as string. Airnode will convert this string to number internally. You can also pass and empty string `""` to `_times` parameter - this has the same effect as if the `_times` parameter was not provided. However, this is important when [encoding multiple values](/reference/ois/2.1/reserved-parameters.md#encoding-multiple-values). -The `_times` parameter also works in conjunction with arrays and -multidimensional arrays. All elements of the API response array will be -multiplied before they are encoded. +The `_times` parameter also works in conjunction with arrays and multidimensional arrays. All elements of the API response array will be multiplied before they are encoded. ## `_gasPrice` -The `_gasPrice` reserved parameter enables a requester to override -[Airnode gas price strategies](/reference/airnode/v0.12/concepts/gas-prices.md) -with a specified gas price when Airnode -[fulfills](/reference/airnode/v0.12/concepts/request.md#fulfill) the request. -The recommended implementation is to have the `_gasPrice` reserved parameter -without a `default` or `fixed` value as shown in the abbreviated snippet below: +The `_gasPrice` reserved parameter enables a requester to override [Airnode gas price strategies](/reference/airnode/v0.12/concepts/gas-prices.md) with a specified gas price when Airnode [fulfills](/reference/airnode/v0.12/concepts/request.md#fulfill) the request. The recommended implementation is to have the `_gasPrice` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -251,10 +180,7 @@ without a `default` or `fixed` value as shown in the abbreviated snippet below: } ``` -This allows requesters to specify the gas price via a parameter in their -request. The value, in `wei`, should be -[encoded](/reference/airnode/v0.12/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the gas price via a parameter in their request. The value, in `wei`, should be [encoded](/reference/airnode/v0.12/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; @@ -268,19 +194,11 @@ encode([ ]); ``` -Note that if a requester specifies a `_gasPrice` as a parameter in a request but -the Airnode's configuration does not include the `_gasPrice` reserved parameter, -the requester's gas price will be ignored. +Note that if a requester specifies a `_gasPrice` as a parameter in a request but the Airnode's configuration does not include the `_gasPrice` reserved parameter, the requester's gas price will be ignored. ## `_minConfirmations` -The `_minConfirmations` reserved parameter enables a requester to override the -default minimum number of block confirmations set by the Airnode for that chain -in -[config.json](/reference/airnode/v0.12/deployment-files/config-json.md#minconfirmations). -The recommended implementation is to have the `_minConfirmations` reserved -parameter without a `default` or `fixed` value as shown in the abbreviated -snippet below: +The `_minConfirmations` reserved parameter enables a requester to override the default minimum number of block confirmations set by the Airnode for that chain in [config.json](/reference/airnode/v0.12/deployment-files/config-json.md#minconfirmations). The recommended implementation is to have the `_minConfirmations` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -292,29 +210,20 @@ snippet below: } ``` -This allows requesters to specify the minimum number of block confirmations via -a parameter in their request. The value should be -[encoded](/reference/airnode/v0.12/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the minimum number of block confirmations via a parameter in their request. The value should be [encoded](/reference/airnode/v0.12/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; encode([{ name: '_minConfirmations', type: 'string32', value: '1' }]); ``` -In order to respond to requests in the same nonce order as they are received -when requests specify different `_minConfirmations` values, the maximum -`_minConfirmations` value of all requests in the queue for a given sponsor is -applied to all requests. +In order to respond to requests in the same nonce order as they are received when requests specify different `_minConfirmations` values, the maximum `_minConfirmations` value of all requests in the queue for a given sponsor is applied to all requests. -Note that if a requester specifies a `_minConfirmations` as a parameter in a -request but the Airnode's configuration does not include the `_minConfirmations` -reserved parameter, the requester's minimum confirmations value will be ignored. +Note that if a requester specifies a `_minConfirmations` as a parameter in a request but the Airnode's configuration does not include the `_minConfirmations` reserved parameter, the requester's minimum confirmations value will be ignored. ## Encoding Multiple Values -Solidity has support for decoding and "destructuring" multiple values. For -example: +Solidity has support for decoding and "destructuring" multiple values. For example: ```solidity function decodeMultipleParameters(bytes calldata data) @@ -326,11 +235,7 @@ function decodeMultipleParameters(bytes calldata data) } ``` -The example above demonstrates the decoding on chain of three values of types -`string`, `uint256` and `address` respectively. You can instruct Airnode to -encode these values using the `_type`, `_path`, and `_times` reserved parameters -by separating the values using `,` (comma). For example using the following -combination of reserved parameters: +The example above demonstrates the decoding on chain of three values of types `string`, `uint256` and `address` respectively. You can instruct Airnode to encode these values using the `_type`, `_path`, and `_times` reserved parameters by separating the values using `,` (comma). For example using the following combination of reserved parameters: ```js { @@ -340,10 +245,7 @@ combination of reserved parameters: } ``` -Airnode will split the reserved parameters by `,` into "split values" and ensure -they all contain the same number of them. It will extract and convert each of -the "split values". Notice, that an `""` (empty string) is used to specify that -a certain reserved parameter should not be used for a certain "split value". +Airnode will split the reserved parameters by `,` into "split values" and ensure they all contain the same number of them. It will extract and convert each of the "split values". Notice, that an `""` (empty string) is used to specify that a certain reserved parameter should not be used for a certain "split value". For example, let's say the API response looks like this: @@ -357,23 +259,15 @@ For example, let's say the API response looks like this: Airnode will extract and convert each of the "split values" separately -1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` - results in `"some string"` -2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` - results in `12345670` -3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` - results in `"0xe021...8a74"` +1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` results in `"some string"` +2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` results in `12345670` +3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` results in `"0xe021...8a74"` -All of these values are then together encoded to single bytes value that can be -sent on chain. You can use -[testing gateway](/reference/airnode/v0.12/understand/deploying.md#testing-with-http-gateway) -to inspect the raw API response, casting results and the final encoded value. +All of these values are then together encoded to single bytes value that can be sent on chain. You can use [testing gateway](/reference/airnode/v0.12/understand/deploying.md#testing-with-http-gateway) to inspect the raw API response, casting results and the final encoded value. ::: info Multiple Reserved Parameters Tutorial -The -[weather-multi-value](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates encoding of multiple values of different types. +The [weather-multi-value](/guides/airnode/monorepo-examples.md) monorepo example demonstrates encoding of multiple values of different types. ::: diff --git a/docs/reference/ois/2.1/specification.md b/docs/reference/ois/2.1/specification.md index fc635cb5..8f413e38 100644 --- a/docs/reference/ois/2.1/specification.md +++ b/docs/reference/ois/2.1/specification.md @@ -19,34 +19,21 @@ tags: # {{$frontmatter.title}} -The Oracle Integration Specification (OIS) is based on -[Open API specification (OAS)](https://swagger.io/specification/), but there are -some differences, be sure to focus on the following documentation when working -on an OIS file. +The Oracle Integration Specification (OIS) is based on [Open API specification (OAS)](https://swagger.io/specification/), but there are some differences, be sure to focus on the following documentation when working on an OIS file. ::: warning OAS -It is not recommended to refer to OAS for help while creating an OIS object. OIS -only borrows formatting practices from OAS. Everything needed to create an OIS -object is in these docs. +It is not recommended to refer to OAS for help while creating an OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: -For an overview that explains how Airnode maps its endpoints to API provider -operations, see -[API integration](/reference/airnode/v0.12/understand/api-integration.md). Also -see the medium article -[Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) -for an overview of OIS. +For an overview that explains how Airnode maps its endpoints to API provider operations, see [API integration](/reference/airnode/v0.12/understand/api-integration.md). Also see the medium article [Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) for an overview of OIS. -- Fields denoted by (\*) are for documentation purposes and not used by an - Airnode. +- Fields denoted by (\*) are for documentation purposes and not used by an Airnode. - The OIS fields should be reviewed and customized by the integrating party. -- All URLs are absolute (i.e., - [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) - are not supported). +- All URLs are absolute (i.e., [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) are not supported). ## OIS Object Summary @@ -58,8 +45,7 @@ An OIS has five root fields (keys). 1. [apiSpecifications](/reference/ois/2.1/specification.md#_4-apispecifications) 1. [endpoints](/reference/ois/2.1/specification.md#_5-endpoints) -`apiSpecifications` describe the API's operations which are mapped to the -`endpoints` that Airnode exposes on-chain. +`apiSpecifications` describe the API's operations which are mapped to the `endpoints` that Airnode exposes on-chain. ```json { @@ -77,21 +63,17 @@ An OIS has five root fields (keys). ## 1. `oisFormat` -(Required) The OIS format version followed while generating the specifications. -See [Versions](/reference/ois/2.1/versions) for a list of OIS versions used by -each Airnode version. +(Required) The OIS format version followed while generating the specifications. See [Versions](/reference/ois/2.1/versions) for a list of OIS versions used by each Airnode version. ## 2. `title` -(Required) The OIS title. Title field is at most 64 characters, can only include -alphanumeric characters, hyphens, underscores and whitespaces. +(Required) The OIS title. Title field is at most 64 characters, can only include alphanumeric characters, hyphens, underscores and whitespaces. ## 3. `version` -(Required) A user defined version for the OIS object. Not to be confused with -the `oisFormat` version which defines an OIS formatting version. +(Required) A user defined version for the OIS object. Not to be confused with the `oisFormat` version which defines an OIS formatting version. ## 4. `apiSpecifications` @@ -139,21 +121,18 @@ the `oisFormat` version which defines an OIS formatting version. ### 4.1. `servers` -(Required) An array of objects containing the base URL of the API. Only one -object (i.e., base URL) is allowed in the array. Applies to all API operations. +(Required) An array of objects containing the base URL of the API. Only one object (i.e., base URL) is allowed in the array. Applies to all API operations. ### 4.2. `paths` -(Required) An object where an API's operations are defined by `{path}.{method}` -(i.e. `paths./myPath.get`) each with a `parameters` array. +(Required) An object where an API's operations are defined by `{path}.{method}` (i.e. `paths./myPath.get`) each with a `parameters` array. #### 4.2.1. `parameters` -(Required) A list of the API operation's parameters, each with the following -fields: +(Required) A list of the API operation's parameters, each with the following fields: - `name` - `in` @@ -177,9 +156,7 @@ the non-nested application/json content-type is supported.

### 4.3. `components` -(Required) An object where -[security schemes](/reference/airnode/v0.12/understand/api-security.md) can be -found under `securitySchemes.{securitySchemeName}` with the following elements: +(Required) An object where [security schemes](/reference/airnode/v0.12/understand/api-security.md) can be found under `securitySchemes.{securitySchemeName}` with the following elements: - `type` - `name` @@ -195,8 +172,7 @@ Allowed values: - Used by an API operation to authenticate Airnode. - `apiKey` - `http` -- Allows an API operation to acquire information about the requester and/or the - chain. +- Allows an API operation to acquire information about the requester and/or the chain. - `relayRequesterAddress` - `relaySponsorAddress` - `relaySponsorWalletAddress` @@ -222,9 +198,7 @@ Allowed values: `query`, `header`, `cookie` #### 4.3.4. `scheme` -(Only if `type` is http) The name of the HTTP Authorization scheme to be used in -the -[Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). +(Only if `type` is http) The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). Allowed values: (`basic` and `bearer`). @@ -241,20 +215,9 @@ Allowed values: (`basic` and `bearer`). ### 4.4. `security` -(Required) An object containing all security schemes required by an API call. -Applies to all operations. A security scheme can contain information required by -the API to authenticate Airnode as well as information about the requester -(relay information) the API may also require. Read more about security schemes -in the [API Security](/reference/airnode/v0.12/understand/api-security.md) -section of the _Build an Airnode_ guide and the -[Airnode Authentication](/reference/airnode/v0.12/concepts/airnode-auth.md) -section of _Concepts and Definitions_. - -The `security` object maintains the names of all the security schemes used. Each -security scheme in `security` maps to an empty list. The empty list will be used -by future versions of Airnode for individual endpoint authentication. The -`components.securitySchemes.{name}` object defines the security schemes. Unlike -OAS `security` is an object, not an array. +(Required) An object containing all security schemes required by an API call. Applies to all operations. A security scheme can contain information required by the API to authenticate Airnode as well as information about the requester (relay information) the API may also require. Read more about security schemes in the [API Security](/reference/airnode/v0.12/understand/api-security.md) section of the _Build an Airnode_ guide and the [Airnode Authentication](/reference/airnode/v0.12/concepts/airnode-auth.md) section of _Concepts and Definitions_. + +The `security` object maintains the names of all the security schemes used. Each security scheme in `security` maps to an empty list. The empty list will be used by future versions of Airnode for individual endpoint authentication. The `components.securitySchemes.{name}` object defines the security schemes. Unlike OAS `security` is an object, not an array. ```json // OIS object @@ -273,8 +236,7 @@ OAS `security` is an object, not an array. } ``` -The `apiCredential` object (which is not part of the OIS object) holds -credentials needed by the security scheme if any. +The `apiCredential` object (which is not part of the OIS object) holds credentials needed by the security scheme if any. ```json // config.json root object. @@ -292,41 +254,30 @@ credentials needed by the security scheme if any. ::: warning Please note: -Currently Airnode reads the security schemes from `component.securitySchemes` -and not `security`. Using the `security` field now (in conjunction with -`component.securitySchemes`) provides for a smooth transition to future releases -of Airnode with regards to security scheme implementation. This will allow -assigning of security schemes to individual API operations. Currently security -schemes are assign to the entire API. +Currently Airnode reads the security schemes from `component.securitySchemes` and not `security`. Using the `security` field now (in conjunction with `component.securitySchemes`) provides for a smooth transition to future releases of Airnode with regards to security scheme implementation. This will allow assigning of security schemes to individual API operations. Currently security schemes are assign to the entire API. ::: ## 5. `endpoints` -(Required) A list of objects, each specifying an Airnode endpoint with the -following fields: +(Required) A list of objects, each specifying an Airnode endpoint with the following fields: ::: info Please Note -Fields denoted by \* are for documentation purposes and not used by Airnode -node. +Fields denoted by \* are for documentation purposes and not used by Airnode node. ::: - 5.1. [name](/reference/ois/2.1/specification.md#_5-1-name) - 5.2. [operation](/reference/ois/2.1/specification.md#_5-2-operation) -- 5.3. - [fixedOperationParameters](/reference/ois/2.1/specification.md#_5-3-fixedoperationparameters) -- 5.4. - [reservedParameters](/reference/ois/2.1/specification.md#_5-4-reservedparameters) +- 5.3. [fixedOperationParameters](/reference/ois/2.1/specification.md#_5-3-fixedoperationparameters) +- 5.4. [reservedParameters](/reference/ois/2.1/specification.md#_5-4-reservedparameters) - 5.5. [parameters](/reference/ois/2.1/specification.md#_5-5-parameters) - 5.6. [summary \*](/reference/ois/2.1/specification.md#_5-6-summary) - 5.7. [description \*](/reference/ois/2.1/specification.md#_5-7-description) - 5.8. [externalDocs \*](/reference/ois/2.1/specification.md#_5-8-externaldocs) -- 5.9. - [preProcessingSpecifications](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) -- 5.10. - [postProcessingSpecifications](/reference/ois/2.1/specification.md#_5-10-postprocessingspecifications) +- 5.9. [preProcessingSpecifications](/reference/ois/2.1/specification.md#_5-9-preprocessingspecifications) +- 5.10. [postProcessingSpecifications](/reference/ois/2.1/specification.md#_5-10-postprocessingspecifications) ```json // endpoints @@ -407,18 +358,12 @@ operation.--> ### 5.2. `operation` -(Required: when calling an API) An object that refers to an API operation -defined in `apiSpecifications.paths`. The following elements must be defined: +(Required: when calling an API) An object that refers to an API operation defined in `apiSpecifications.paths`. The following elements must be defined: - `path` - `method` -The `operation` field must be omitted if the intent is _not_ to call an API but -rather return a value from the -[Pre/Post Processing](/reference/ois/2.1/processing.md) capabilities of Airnode. -See -[Skip the API provider call](/reference/ois/2.1/processing.md#skip-the-api-call) -for more information. +The `operation` field must be omitted if the intent is _not_ to call an API but rather return a value from the [Pre/Post Processing](/reference/ois/2.1/processing.md) capabilities of Airnode. See [Skip the API provider call](/reference/ois/2.1/processing.md#skip-the-api-call) for more information. #### 5.2.1. `path` @@ -438,18 +383,14 @@ respective API operation.--> ### 5.3. `fixedOperationParameters` -(Required) A list of objects specifying the fixed parameters for an API -operation. While required, the -[fixedOperationParameters](/reference/airnode/v0.12/understand/api-integration.md#fixedoperationparameters) -array can be left empty. Each object has the following elements: +(Required) A list of objects specifying the fixed parameters for an API operation. While required, the [fixedOperationParameters](/reference/airnode/v0.12/understand/api-integration.md#fixedoperationparameters) array can be left empty. Each object has the following elements: - `operationParameter` - `value` #### 5.3.1. `operationParameter` -(Required) An object that refers to a parameter of an API operation with the -following elements: +(Required) An object that refers to a parameter of an API operation with the following elements: - `name` - `in` @@ -464,54 +405,35 @@ following elements: #### 5.3.2. `value` -(Required) The value to be used for the respective parameter of an API operation -that cannot be overridden by the requester. This is allowed to be any type, -including an object; for example, the following specifies an array containing -multiple primitives: `["finalized", false]`. +(Required) The value to be used for the respective parameter of an API operation that cannot be overridden by the requester. This is allowed to be any type, including an object; for example, the following specifies an array containing multiple primitives: `["finalized", false]`. ### 5.4. `reservedParameters` -A list of objects that specify reserved Airnode endpoint parameters that do not -map to any API operation parameters, but are used for special purposes by the -Airnode. See the -[Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) doc for an -in-depth explanation and -[reservedParameters](/reference/airnode/v0.12/understand/api-integration.md#reservedparameters). -Each object has the following elements: +A list of objects that specify reserved Airnode endpoint parameters that do not map to any API operation parameters, but are used for special purposes by the Airnode. See the [Reserved Parameters](/reference/ois/2.1/reserved-parameters.md) doc for an in-depth explanation and [reservedParameters](/reference/airnode/v0.12/understand/api-integration.md#reservedparameters). Each object has the following elements: - `name` - `fixed` - `default` -Note that if a reserved parameter object does not include a `fixed` value, a -requester can, or may be expected to, supply this value as a parameter. A value -supplied by a requester overrides a `default`. See the -[\_gasPrice](/reference/ois/2.1/reserved-parameters.md#gasprice) reserved -parameter description for an example. +Note that if a reserved parameter object does not include a `fixed` value, a requester can, or may be expected to, supply this value as a parameter. A value supplied by a requester overrides a `default`. See the [\_gasPrice](/reference/ois/2.1/reserved-parameters.md#gasprice) reserved parameter description for an example. #### 5.4.1. `name` (Required) The name of the reserved parameter. Always starts with `_`. -Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and -`_minConfirmations`. +Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. #### 5.4.2. `fixed` -(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. -Cannot be used together with `default`. +(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. Cannot be used together with `default`. #### 5.4.3. `default` -(Optional) The default value for the reserved parameter. Used when no value is -provided by a requester. Cannot be used together with `fixed`. +(Optional) The default value for the reserved parameter. Used when no value is provided by a requester. Cannot be used together with `fixed`. ### 5.5. `parameters` -(Optional) A list of objects that specify Airnode endpoint -[parameters](/reference/airnode/v0.12/understand/api-integration.md#parameters) -that map to an particular API operation's parameters. Each object has the -following elements: +(Optional) A list of objects that specify Airnode endpoint [parameters](/reference/airnode/v0.12/understand/api-integration.md#parameters) that map to an particular API operation's parameters. Each object has the following elements: - `operationParameter` - `name` @@ -522,8 +444,7 @@ following elements: #### 5.5.1. `operationParameter` -(Required) An object that refers to a parameter of an API operation, has the -following elements: +(Required) An object that refers to a parameter of an API operation, has the following elements: - `name` - `in` @@ -538,16 +459,14 @@ following elements: #### 5.5.2. `name` -(Required) The name of the Airnode endpoint parameter. Is not allowed to start -with `_`. +(Required) The name of the Airnode endpoint parameter. Is not allowed to start with `_`. #### 5.5.3. `default` -(Optional) The default value for the Airnode endpoint parameter. Used when no -value is provided. +(Optional) The default value for the Airnode endpoint parameter. Used when no value is provided. @@ -593,11 +512,9 @@ corresponding operation parameter.--> ### 5.9. `preProcessingSpecifications` \* -(Optional) Defines the preprocessing code that can be used to modify the -endpoint parameter before making the API request defined by an Airnode endpoint. +(Optional) Defines the preprocessing code that can be used to modify the endpoint parameter before making the API request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/2.1/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/2.1/processing.md) doc for additional details. #### Example @@ -624,11 +541,9 @@ additional details. ### 5.10. `postProcessingSpecifications` \* -(Optional) Defines the post-processing code that can be used to modify the API -response from the request defined by an Airnode endpoint. +(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/2.1/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/2.1/processing.md) doc for additional details. #### Example diff --git a/docs/reference/ois/2.1/template.md b/docs/reference/ois/2.1/template.md index 269d98ce..721b63ec 100644 --- a/docs/reference/ois/2.1/template.md +++ b/docs/reference/ois/2.1/template.md @@ -19,19 +19,11 @@ tags: # {{$frontmatter.title}} -An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's -`config.json` file. +An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's `config.json` file. -In the OIS template, there are some fields that contain . This means -that the value you will be replacing this with is independent from the other -fields. On the other hand, if two fields contain the same expression (e.g., -``), you must use the same value in them, -because they are referencing each other. +In the OIS template, there are some fields that contain . This means that the value you will be replacing this with is independent from the other fields. On the other hand, if two fields contain the same expression (e.g., ``), you must use the same value in them, because they are referencing each other. -The file below is a basic template for OIS. Note, that it might look differently -for your particular use case. You can also check out the OISes created for the -examples in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/integrations). +The file below is a basic template for OIS. Note, that it might look differently for your particular use case. You can also check out the OISes created for the examples in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.12/packages/airnode-examples/integrations). ```json { diff --git a/docs/reference/ois/2.1/versions.md b/docs/reference/ois/2.1/versions.md index eabfa115..e8b2003d 100644 --- a/docs/reference/ois/2.1/versions.md +++ b/docs/reference/ois/2.1/versions.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Be sure to use the correct OIS version for the Airnode version you are -deploying. +Be sure to use the correct OIS version for the Airnode version you are deploying. | Airnode version | Latest compatible OIS version | | ------------------- | -------------------------------------------- | @@ -32,10 +31,8 @@ deploying. | 0.8.x | [1.1.2](https://old-docs.api3.org/ois/v1.1/) | | 0.2.x through 0.7.x | [1.0.0](https://old-docs.api3.org/ois/v1.0/) | -Documentation for versions `v1.0.0` through `v1.4.0` are available on the -[legacy documentation site](https://old-docs.api3.org). +Documentation for versions `v1.0.0` through `v1.4.0` are available on the [legacy documentation site](https://old-docs.api3.org). -See GitHub [releases](https://github.com/api3dao/ois/releases) for more -information about the changes in each version. +See GitHub [releases](https://github.com/api3dao/ois/releases) for more information about the changes in each version. diff --git a/docs/reference/ois/2.2/index.md b/docs/reference/ois/2.2/index.md index 562d5511..03766f16 100644 --- a/docs/reference/ois/2.2/index.md +++ b/docs/reference/ois/2.2/index.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -OIS (or Oracle Integration Specifications) is a JSON object that describes an -API specification and defines Airnode endpoints linked to API operations (a.k.a. -endpoints). It is one of five root level objects in a `config.json` file that -defines an Airnode. +OIS (or Oracle Integration Specifications) is a JSON object that describes an API specification and defines Airnode endpoints linked to API operations (a.k.a. endpoints). It is one of five root level objects in a `config.json` file that defines an Airnode. - chains - nodeSettings @@ -30,14 +27,9 @@ defines an Airnode. - ois - apiCredentials -For more information about the config.json file see the -[Deployment Files](/reference/airnode/v0.13/deployment-files/config-json.md) -section in the Airnode document set. +For more information about the config.json file see the [Deployment Files](/reference/airnode/v0.13/deployment-files/config-json.md) section in the Airnode document set. -In the diagram below, an Airnode exposes its endpoints to the on-chain -AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to -an API operation. It should be noted that Airnode can have more than one -endpoint that maps to the same API operation. +In the diagram below, an Airnode exposes its endpoints to the on-chain AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to an API operation. It should be noted that Airnode can have more than one endpoint that maps to the same API operation. > > @@ -47,18 +39,11 @@ endpoint that maps to the same API operation. ## API Mapping Examples -The following are three possible Airnode to API operation mapping examples. -Mapping details are better documented in the next doc -[Specification](/reference/ois/2.2/specification.md). +The following are three possible Airnode to API operation mapping examples. Mapping details are better documented in the next doc [Specification](/reference/ois/2.2/specification.md). ### Simple Airnode Endpoint -An API has a simple operation the returns the current value of an on-chain token -`GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint -will only mimic the API operation. To do so, the Airnode will declare its -endpoint to have one parameter, `id`. Airnode will accept an `id` argument from -an on-chain request and move its value to the API operation's path parameter -named `id`. +An API has a simple operation the returns the current value of an on-chain token `GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint will only mimic the API operation. To do so, the Airnode will declare its endpoint to have one parameter, `id`. Airnode will accept an `id` argument from an on-chain request and move its value to the API operation's path parameter named `id`. ```json // ois.apiSpecifications (API operations) @@ -97,25 +82,11 @@ named `id`. ### Fixed Operation Parameters Airnode Endpoint -An API may have an operation that returns a crypto coin in either a summary or -detail form. The API operation has two parameters, `coinId` in the path and -`includeDetails` in the query. The Airnode (by design) will not allow the -details of the coin to be returned, only the summary. Therefore the Airnode will -require a requester to pass a `coinId` but will ignore the `includeDetails` -parameter if passed. The Airnode will always set the `includeDetails` query -parameter to false regardless of what a requester sends when it calls the API -operation. It does so using a `fixedOperationParameters` when calling the API -operation. +An API may have an operation that returns a crypto coin in either a summary or detail form. The API operation has two parameters, `coinId` in the path and `includeDetails` in the query. The Airnode (by design) will not allow the details of the coin to be returned, only the summary. Therefore the Airnode will require a requester to pass a `coinId` but will ignore the `includeDetails` parameter if passed. The Airnode will always set the `includeDetails` query parameter to false regardless of what a requester sends when it calls the API operation. It does so using a `fixedOperationParameters` when calling the API operation. ### Two Airnode Endpoints - One API Operation -An Airnode may wish to create two Airnode endpoints mapped to a single API -operation whereas the requester does not pass any argument. While the API -operation returns any token value based on a path parameter `id`, Airnode will -only allow one particular token per Airnode endpoint. This is done using -`fixedOperationParameters` rather than normal `parameters`. By applying a -`value` to `fixedOperationParameters` for each Airnode endpoint, only the token -in the `value` can be returned to the requester. +An Airnode may wish to create two Airnode endpoints mapped to a single API operation whereas the requester does not pass any argument. While the API operation returns any token value based on a path parameter `id`, Airnode will only allow one particular token per Airnode endpoint. This is done using `fixedOperationParameters` rather than normal `parameters`. By applying a `value` to `fixedOperationParameters` for each Airnode endpoint, only the token in the `value` can be returned to the requester. ```json "endpoints": [ diff --git a/docs/reference/ois/2.2/processing.md b/docs/reference/ois/2.2/processing.md index 93e1be47..efe30cd8 100644 --- a/docs/reference/ois/2.2/processing.md +++ b/docs/reference/ois/2.2/processing.md @@ -19,70 +19,40 @@ tags: # {{$frontmatter.title}} -The processing schema accepts an array of processing snippets (user defined -code) which are chained. The first snippet receives parameters submitted as part -of a template or on-chain request. The output of this snippet is passed to the -second snippet and so on. +The processing schema accepts an array of processing snippets (user defined code) which are chained. The first snippet receives parameters submitted as part of a template or on-chain request. The output of this snippet is passed to the second snippet and so on. -Airnode executes snippets for `preProcessingSpecifications` and -`postProcessingSpecifications` during its run cycle. The following describes the -work flow Airnode uses: +Airnode executes snippets for `preProcessingSpecifications` and `postProcessingSpecifications` during its run cycle. The following describes the work flow Airnode uses: 1. Run `preProcessingSpecifications` 2. Airnode calls requested OIS endpoint 3. Run `postProcessingSpecifications` 4. Airnode encodes the response values defined by reservedParameters -The processing schema is the same for both -[`preProcessingSpecifications`](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) -and -[`postProcessingSpecifications`](/reference/ois/2.2/specification.md#_5-10-postprocessingspecifications). -Snippets for both specifications follow this schema: - -- `environment` - Currently one of `Node` or `Node async`. Both options - interpret the code as JavaScript and execute in Node.js. The async version can - use asynchronous code. The code snippet is expected to call `resolve(output)` - with the output value as an argument. Airnode will use the resolved value as - the input to subsequent snippets (if defined). +The processing schema is the same for both [`preProcessingSpecifications`](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) and [`postProcessingSpecifications`](/reference/ois/2.2/specification.md#_5-10-postprocessingspecifications). Snippets for both specifications follow this schema: + +- `environment` - Currently one of `Node` or `Node async`. Both options interpret the code as JavaScript and execute in Node.js. The async version can use asynchronous code. The code snippet is expected to call `resolve(output)` with the output value as an argument. Airnode will use the resolved value as the input to subsequent snippets (if defined). - `value` - The processing code written as a string. -- `timeoutMs` - The maximum duration that this snippet can run. In case the - timeout is exceeded an error is thrown. +- `timeoutMs` - The maximum duration that this snippet can run. In case the timeout is exceeded an error is thrown. -Try the [Post processing](/guides/airnode/post-processing/) guide to further -understand pre/post processing. +Try the [Post processing](/guides/airnode/post-processing/) guide to further understand pre/post processing. ## Input and Output -The processing snippet receives an `input` value which is either the initial -value or the output value from the previous processing snippet. The snippet must -create a variable `output` which will be used for the next processing snippet. -The processing snippet can use most Node.js built-in modules. Refer to the -source code of Airnode to understand how processing works and what modules are -made available to the snippet code. Modules cannot be imported directly in cloud -environments. +The processing snippet receives an `input` value which is either the initial value or the output value from the previous processing snippet. The snippet must create a variable `output` which will be used for the next processing snippet. The processing snippet can use most Node.js built-in modules. Refer to the source code of Airnode to understand how processing works and what modules are made available to the snippet code. Modules cannot be imported directly in cloud environments. ## Accessing endpoint parameters -Endpoint parameters, with the exception of reserved parameters, are accessible -within pre-processing and post-processing via the immutable `endpointParameters` -object. For example, if there was a parameter named `myParameter` defined in the -`endpoints[n].parameters` array, its value could be accessed using -`endpointParameters.myParameter` within pre-processing and post-processing code -snippets. +Endpoint parameters, with the exception of reserved parameters, are accessible within pre-processing and post-processing via the immutable `endpointParameters` object. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing and post-processing code snippets. ::: info Accessing reserved parameters -Note that reserved parameters are inaccessible in both pre-processing and -post-processing. +Note that reserved parameters are inaccessible in both pre-processing and post-processing. ::: ## Interpolation -Note, that config.json supports interpolation of secrets via the JavaScript -string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with -the string interpolation inside the processing snippets. In order to use the -interpolation in snippets, you need to escape the interpolation. +Note, that config.json supports interpolation of secrets via the JavaScript string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with the string interpolation inside the processing snippets. In order to use the interpolation in snippets, you need to escape the interpolation. For example, the following code: @@ -103,57 +73,27 @@ should be escaped inside the `config.json` like this: ## Error Handling and Security -Processing code is expected to be trustworthy as it is specified by the Airnode -operator. Processing is an advanced feature that carries great security risks. -It is therefore advised that developers using the processing feature familiarize -themselves with the Airnode sources prior to developing any processing code -snippets. +Processing code is expected to be trustworthy as it is specified by the Airnode operator. Processing is an advanced feature that carries great security risks. It is therefore advised that developers using the processing feature familiarize themselves with the Airnode sources prior to developing any processing code snippets. -Processing code executes in a constrained execution environment resembling -Node.js. Some resources may not be available, for example the `require` -statement. Therefore code should be tested thoroughly in the target environment -(e.g. Lambda and/or Docker client). For example, authentication implemented in -pre-processing should always be executed at the end of the respective processing -chain and special care should be taken to avoid leakage of secrets. +Processing code executes in a constrained execution environment resembling Node.js. Some resources may not be available, for example the `require` statement. Therefore code should be tested thoroughly in the target environment (e.g. Lambda and/or Docker client). For example, authentication implemented in pre-processing should always be executed at the end of the respective processing chain and special care should be taken to avoid leakage of secrets. ## Skip the API call -Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on -either (or both) pre-processing or post-processing to acquire a value for the -Airnode to place on-chain. +Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on either (or both) pre-processing or post-processing to acquire a value for the Airnode to place on-chain. -Instead of calling an API, Airnode uses the output of -`preProcessingSpecifications`, `postProcessingSpecifications`, or both. The -field `operation` must be undefined, `fixedOperationParameters` must be an empty -array and one of `preProcessingSpecifications` or `postProcessingSpecifications` -must be defined and not be an empty array. +Instead of calling an API, Airnode uses the output of `preProcessingSpecifications`, `postProcessingSpecifications`, or both. The field `operation` must be undefined, `fixedOperationParameters` must be an empty array and one of `preProcessingSpecifications` or `postProcessingSpecifications` must be defined and not be an empty array. ### Use case: random number -An Airnode endpoint that places a random number on-chain. Rather than calling an -API, the Airnode will derive a random number during its execution of a -pre-process specification. A requester would make a request of this Airnode -endpoint without parameters. The Airnode endpoint simply sets the random number -on-chain in response to the request using a `preProcessingSpecifications` -specification. Example #1 below implements this use case. +An Airnode endpoint that places a random number on-chain. Rather than calling an API, the Airnode will derive a random number during its execution of a pre-process specification. A requester would make a request of this Airnode endpoint without parameters. The Airnode endpoint simply sets the random number on-chain in response to the request using a `preProcessingSpecifications` specification. Example #1 below implements this use case. ### Example #1 -This example creates an Airnode endpoint named `generateRandomNumber` with no -parameters. Because there isn't an -[operation field](/reference/ois/2.2/specification.md#_5-2-operation) defined -for this Airnode endpoint, a call to an API will not be made. The Airnode will -instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) -array. - -To implement the use case mentioned above, the -[operation field](/reference/ois/2.2/specification.md#_5-2-operation) will be -undefined, `fixedOperationParameters` will be an empty array, and -`preProcessingSpecifications` will be defined with a single specification. - -- A requester makes a request of the Airnode endpoint `generateRandomNumber` - without any parameters. +This example creates an Airnode endpoint named `generateRandomNumber` with no parameters. Because there isn't an [operation field](/reference/ois/2.2/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) array. + +To implement the use case mentioned above, the [operation field](/reference/ois/2.2/specification.md#_5-2-operation) will be undefined, `fixedOperationParameters` will be an empty array, and `preProcessingSpecifications` will be defined with a single specification. + +- A requester makes a request of the Airnode endpoint `generateRandomNumber` without any parameters. - Airnode runs the specification in `preProcessingSpecifications[0]`. - The specification generates a random number. - The reserved parameter named `randomNumber` now holds the random number. @@ -191,15 +131,7 @@ endpoints: [ ### Example #2 -The code below is unrelated to the -[use case](/reference/ois/2.2/processing.md#use-case-random-number) mentioned -earlier. This example creates an Airnode endpoint named -`endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there -isn't an [operation field](/reference/ois/2.2/specification.md#_5-2-operation) -defined for this Airnode endpoint, a call to an API will not be made. The -Airnode will instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) -array. +The code below is unrelated to the [use case](/reference/ois/2.2/processing.md#use-case-random-number) mentioned earlier. This example creates an Airnode endpoint named `endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there isn't an [operation field](/reference/ois/2.2/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) array. - A requester passes the number `5` in the parameter named `numberToSum`. - Airnode runs the specification in `preProcessingSpecifications[0]`. diff --git a/docs/reference/ois/2.2/reserved-parameters.md b/docs/reference/ois/2.2/reserved-parameters.md index 9b1fdc6c..183f012a 100644 --- a/docs/reference/ois/2.2/reserved-parameters.md +++ b/docs/reference/ois/2.2/reserved-parameters.md @@ -19,63 +19,36 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an OIS object as part of the `endpoints` field -(Airnode endpoints) and warrant a more in-depth explanation. They are part of an -Airnode's defined endpoints in an OIS object but do not map to operation -parameters (API parameters). They are used by Airnode for special purposes. - -A requester can pass request parameters either by referencing a -[template](/reference/airnode/v0.13/concepts/template.md) that contains them, or -as an argument of the request-making methods of -[AirnodeRrpV0.sol](/reference/airnode/v0.13/concepts/#airnoderrpv0-sol). In -either case, these parameters are encoded using the -[AirnodeRrpV0 ABI](/reference/airnode/v0.13/specifications/airnode-abi.md). -There are two types of parameters which are part of the OIS object: - -1. [Endpoint parameters](/reference/ois/2.2/specification.md#_5-5-parameters) - - Airnode endpoint parameters are mapped to API operation parameters. -2. [Reserved parameters](/reference/ois/2.2/specification.md#_5-4-reservedparameters) - - Reserved parameters perform a specific operation related to the request or on - the response before fulfilling the request. Reserved parameter names start - with `_`. Depending on the configuration, they may be overridden by a - parameter supplied by a requester. +Reserved parameters are part of an OIS object as part of the `endpoints` field (Airnode endpoints) and warrant a more in-depth explanation. They are part of an Airnode's defined endpoints in an OIS object but do not map to operation parameters (API parameters). They are used by Airnode for special purposes. + +A requester can pass request parameters either by referencing a [template](/reference/airnode/v0.13/concepts/template.md) that contains them, or as an argument of the request-making methods of [AirnodeRrpV0.sol](/reference/airnode/v0.13/concepts/#airnoderrpv0-sol). In either case, these parameters are encoded using the [AirnodeRrpV0 ABI](/reference/airnode/v0.13/specifications/airnode-abi.md). There are two types of parameters which are part of the OIS object: + +1. [Endpoint parameters](/reference/ois/2.2/specification.md#_5-5-parameters) - Airnode endpoint parameters are mapped to API operation parameters. +2. [Reserved parameters](/reference/ois/2.2/specification.md#_5-4-reservedparameters) - Reserved parameters perform a specific operation related to the request or on the response before fulfilling the request. Reserved parameter names start with `_`. Depending on the configuration, they may be overridden by a parameter supplied by a requester. ## `_type` -Signifies what Solidity type the API response will be encoded to before -fulfillment. +Signifies what Solidity type the API response will be encoded to before fulfillment. -Support is provided for most common -[Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), -but the following are not supported. +Support is provided for most common [Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), but the following are not supported. - Custom bits integer types - e.g. `uint32` or `uint8` - Fixed point decimal numbers - e.g. `fixed128x18` or `ufixed128x18` - Custom fixed size bytes - e.g. `bytes4` - Tuples - e.g. `(int256, string)` -On top of supported solidity types, there is support for a few "artificial" -types created for special purposes that would otherwise be hard or impossible to -represent. +On top of supported solidity types, there is support for a few "artificial" types created for special purposes that would otherwise be hard or impossible to represent. - [`string32`](/reference/ois/2.2/reserved-parameters.md#string32-encoded-to-bytes32-on-chain) - [`timestamp`](/reference/ois/2.2/reserved-parameters.md#timestamp-encoded-to-uint256-on-chain) -You can also encode multiple values for one single API call - but this impacts -all of the reserved parameters and is explained in the -[Encoding Multiple Values](/reference/ois/2.2/reserved-parameters.md#encoding-multiple-values) -section below. +You can also encode multiple values for one single API call - but this impacts all of the reserved parameters and is explained in the [Encoding Multiple Values](/reference/ois/2.2/reserved-parameters.md#encoding-multiple-values) section below. ### Conversion and encoding behavior -Before the API response value is encoded for on chain use, it is parsed and -converted. The conversion behaviors for any given type is explained in depth in -the -[adapter package docs](/reference/airnode/v0.13/packages/adapter.md#conversion). +Before the API response value is encoded for on chain use, it is parsed and converted. The conversion behaviors for any given type is explained in depth in the [adapter package docs](/reference/airnode/v0.13/packages/adapter.md#conversion). -The converted value is then encoded internally by -[ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) -using the following +The converted value is then encoded internally by [ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) using the following ```js ethers.utils.defaultAbiCoder.encode([solidityType], [value]); @@ -93,54 +66,35 @@ ethers.utils.defaultAbiCoder.encode([solidityType], [value]); #### string32 (encoded to `bytes32` on chain) -The `string32` is an artificial type that is not supported by solidity. It is -instead encoded to `bytes32` and provides a cheaper alternative to the regular -`string` type for values with less than 32 characters. +The `string32` is an artificial type that is not supported by solidity. It is instead encoded to `bytes32` and provides a cheaper alternative to the regular `string` type for values with less than 32 characters. ::: warning Limitations -While using `string32` is more efficient, decoding the original string from -`bytes32` on chain is both difficult and expensive. Also bear in mind that this -type is able to encode only strings shorter than 32 characters. If the value is -longer, it will be trimmed and only first 31 characters will be encoded. +While using `string32` is more efficient, decoding the original string from `bytes32` on chain is both difficult and expensive. Also bear in mind that this type is able to encode only strings shorter than 32 characters. If the value is longer, it will be trimmed and only first 31 characters will be encoded. ::: #### timestamp (encoded to `uint256` on chain) -The `timestamp` is an artificial type that is not supported by solidity. It is -instead encoded to `uint256` and specifies the UNIX timestamp value at the time -when the transaction was encoded. You can use this value on chain to check the -"freshness" of the Airnode response. This might be useful in certain scenarios, -because Airnode cannot guarantee when a particular transaction will be mined on -chain. +The `timestamp` is an artificial type that is not supported by solidity. It is instead encoded to `uint256` and specifies the UNIX timestamp value at the time when the transaction was encoded. You can use this value on chain to check the "freshness" of the Airnode response. This might be useful in certain scenarios, because Airnode cannot guarantee when a particular transaction will be mined on chain. -When using the `timestamp` type, the corresponding `_path` and `_times` -variables must be empty strings or not provided. +When using the `timestamp` type, the corresponding `_path` and `_times` variables must be empty strings or not provided. #### Arrays -Apart from the primitives defined above as well as all "artificial" types we -created, you are free to use arrays with any of the above. Multidimensional -arrays are supported as well. Solidity allows you to define fixed size arrays, -which are more gas efficient to encode and you can use those as well. +Apart from the primitives defined above as well as all "artificial" types we created, you are free to use arrays with any of the above. Multidimensional arrays are supported as well. Solidity allows you to define fixed size arrays, which are more gas efficient to encode and you can use those as well. For example - `int256[]` - regular integer array - `uint256[8]` - unsigned integer array with 8 elements - `int256[][]` - 2 dimensional integer array -- `string32[]` - is an array of `string32` values, which will be encoded to - `bytes32[]` on chain -- `string[2][][3]` - 3 dimensional string array, where first dimension contains - 3 elements, second unboundedly many and last dimension only 2. Note that this - [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) - compared to C-style languages +- `string32[]` - is an array of `string32` values, which will be encoded to `bytes32[]` on chain +- `string[2][][3]` - 3 dimensional string array, where first dimension contains 3 elements, second unboundedly many and last dimension only 2. Note that this [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) compared to C-style languages ## `_path` -Assuming that the API response will be a JSON object, defines the field to be -used to fulfill the request using dot notation. For example, if the API returns +Assuming that the API response will be a JSON object, defines the field to be used to fulfill the request using dot notation. For example, if the API returns ``` { @@ -159,15 +113,11 @@ used to fulfill the request using dot notation. For example, if the API returns and `_path` is `field1.fieldA.1`, the response will be `valueA2`. -If the response is a literal value (i.e., not a JSON object) and `_path` is not -provided or is an empty string (needed for -[encoding multiple values](/reference/ois/2.2/reserved-parameters.md#encoding-multiple-values)), -Airnode will use the API response itself to fulfill the request. +If the response is a literal value (i.e., not a JSON object) and `_path` is not provided or is an empty string (needed for [encoding multiple values](/reference/ois/2.2/reserved-parameters.md#encoding-multiple-values)), Airnode will use the API response itself to fulfill the request. ::: warning Beware the separator -Make sure the keys in the path of the API response do not contain `.`, because -it will be incorrectly considered as a separator. +Make sure the keys in the path of the API response do not contain `.`, because it will be incorrectly considered as a separator. ``` { @@ -175,18 +125,13 @@ it will be incorrectly considered as a separator. } ``` -A `_path` defined as `"strange.key"` will not work. As workaround you can -[escape the separator](/reference/ois/2.2/reserved-parameters.md#escaping-separators). +A `_path` defined as `"strange.key"` will not work. As workaround you can [escape the separator](/reference/ois/2.2/reserved-parameters.md#escaping-separators). ::: ### Escaping Separators -In rare cases, when the `_path` to the API response would contain `,` or `.` -(comma or a dot) things get a bit complicated. Those symbols have a very -specific meaning when parsing the reserved parameters and they need to be -escaped if they are to be considered as literals. If the API provider response -looks like the following: +In rare cases, when the `_path` to the API response would contain `,` or `.` (comma or a dot) things get a bit complicated. Those symbols have a very specific meaning when parsing the reserved parameters and they need to be escaped if they are to be considered as literals. If the API provider response looks like the following: ``` { @@ -198,9 +143,7 @@ Then escape the symbols, in this case `_path="very\\,strange\\.key"`. ## `_times` -If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided -Airnode multiplies the value returned by the API with the `_times` parameter -before fulfilling the request. For example, if the API returns: +If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided Airnode multiplies the value returned by the API with the `_times` parameter before fulfilling the request. For example, if the API returns: ``` { @@ -217,29 +160,15 @@ _path: data _times: "100" ``` -the request will be fulfilled with the value `123`. Note that the number gets -multiplied by `100`, and then gets floored. This is because the result of the -multiplication is [cast](/reference/airnode/v0.13/packages/adapter.md) to -`int256` afterwards. +the request will be fulfilled with the value `123`. Note that the number gets multiplied by `100`, and then gets floored. This is because the result of the multiplication is [cast](/reference/airnode/v0.13/packages/adapter.md) to `int256` afterwards. -Make sure to pass the `_times` parameter as string. Airnode will convert this -string to number internally. You can also pass and empty string `""` to `_times` -parameter - this has the same effect as if the `_times` parameter was not -provided. However, this is important when -[encoding multiple values](/reference/ois/2.2/reserved-parameters.md#encoding-multiple-values). +Make sure to pass the `_times` parameter as string. Airnode will convert this string to number internally. You can also pass and empty string `""` to `_times` parameter - this has the same effect as if the `_times` parameter was not provided. However, this is important when [encoding multiple values](/reference/ois/2.2/reserved-parameters.md#encoding-multiple-values). -The `_times` parameter also works in conjunction with arrays and -multidimensional arrays. All elements of the API response array will be -multiplied before they are encoded. +The `_times` parameter also works in conjunction with arrays and multidimensional arrays. All elements of the API response array will be multiplied before they are encoded. ## `_gasPrice` -The `_gasPrice` reserved parameter enables a requester to override -[Airnode gas price strategies](/reference/airnode/v0.13/concepts/gas-prices.md) -with a specified gas price when Airnode -[fulfills](/reference/airnode/v0.13/concepts/request.md#fulfill) the request. -The recommended implementation is to have the `_gasPrice` reserved parameter -without a `default` or `fixed` value as shown in the abbreviated snippet below: +The `_gasPrice` reserved parameter enables a requester to override [Airnode gas price strategies](/reference/airnode/v0.13/concepts/gas-prices.md) with a specified gas price when Airnode [fulfills](/reference/airnode/v0.13/concepts/request.md#fulfill) the request. The recommended implementation is to have the `_gasPrice` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -251,10 +180,7 @@ without a `default` or `fixed` value as shown in the abbreviated snippet below: } ``` -This allows requesters to specify the gas price via a parameter in their -request. The value, in `wei`, should be -[encoded](/reference/airnode/v0.13/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the gas price via a parameter in their request. The value, in `wei`, should be [encoded](/reference/airnode/v0.13/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; @@ -268,19 +194,11 @@ encode([ ]); ``` -Note that if a requester specifies a `_gasPrice` as a parameter in a request but -the Airnode's configuration does not include the `_gasPrice` reserved parameter, -the requester's gas price will be ignored. +Note that if a requester specifies a `_gasPrice` as a parameter in a request but the Airnode's configuration does not include the `_gasPrice` reserved parameter, the requester's gas price will be ignored. ## `_minConfirmations` -The `_minConfirmations` reserved parameter enables a requester to override the -default minimum number of block confirmations set by the Airnode for that chain -in -[config.json](/reference/airnode/v0.13/deployment-files/config-json.md#minconfirmations). -The recommended implementation is to have the `_minConfirmations` reserved -parameter without a `default` or `fixed` value as shown in the abbreviated -snippet below: +The `_minConfirmations` reserved parameter enables a requester to override the default minimum number of block confirmations set by the Airnode for that chain in [config.json](/reference/airnode/v0.13/deployment-files/config-json.md#minconfirmations). The recommended implementation is to have the `_minConfirmations` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -292,29 +210,20 @@ snippet below: } ``` -This allows requesters to specify the minimum number of block confirmations via -a parameter in their request. The value should be -[encoded](/reference/airnode/v0.13/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the minimum number of block confirmations via a parameter in their request. The value should be [encoded](/reference/airnode/v0.13/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; encode([{ name: '_minConfirmations', type: 'string32', value: '1' }]); ``` -In order to respond to requests in the same nonce order as they are received -when requests specify different `_minConfirmations` values, the maximum -`_minConfirmations` value of all requests in the queue for a given sponsor is -applied to all requests. +In order to respond to requests in the same nonce order as they are received when requests specify different `_minConfirmations` values, the maximum `_minConfirmations` value of all requests in the queue for a given sponsor is applied to all requests. -Note that if a requester specifies a `_minConfirmations` as a parameter in a -request but the Airnode's configuration does not include the `_minConfirmations` -reserved parameter, the requester's minimum confirmations value will be ignored. +Note that if a requester specifies a `_minConfirmations` as a parameter in a request but the Airnode's configuration does not include the `_minConfirmations` reserved parameter, the requester's minimum confirmations value will be ignored. ## Encoding Multiple Values -Solidity has support for decoding and "destructuring" multiple values. For -example: +Solidity has support for decoding and "destructuring" multiple values. For example: ```solidity function decodeMultipleParameters(bytes calldata data) @@ -326,11 +235,7 @@ function decodeMultipleParameters(bytes calldata data) } ``` -The example above demonstrates the decoding on chain of three values of types -`string`, `uint256` and `address` respectively. You can instruct Airnode to -encode these values using the `_type`, `_path`, and `_times` reserved parameters -by separating the values using `,` (comma). For example using the following -combination of reserved parameters: +The example above demonstrates the decoding on chain of three values of types `string`, `uint256` and `address` respectively. You can instruct Airnode to encode these values using the `_type`, `_path`, and `_times` reserved parameters by separating the values using `,` (comma). For example using the following combination of reserved parameters: ```js { @@ -340,10 +245,7 @@ combination of reserved parameters: } ``` -Airnode will split the reserved parameters by `,` into "split values" and ensure -they all contain the same number of them. It will extract and convert each of -the "split values". Notice, that an `""` (empty string) is used to specify that -a certain reserved parameter should not be used for a certain "split value". +Airnode will split the reserved parameters by `,` into "split values" and ensure they all contain the same number of them. It will extract and convert each of the "split values". Notice, that an `""` (empty string) is used to specify that a certain reserved parameter should not be used for a certain "split value". For example, let's say the API response looks like this: @@ -357,23 +259,15 @@ For example, let's say the API response looks like this: Airnode will extract and convert each of the "split values" separately -1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` - results in `"some string"` -2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` - results in `12345670` -3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` - results in `"0xe021...8a74"` +1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` results in `"some string"` +2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` results in `12345670` +3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` results in `"0xe021...8a74"` -All of these values are then together encoded to single bytes value that can be -sent on chain. You can use -[testing gateway](/reference/airnode/v0.13/understand/deploying.md#testing-with-http-gateway) -to inspect the raw API response, casting results and the final encoded value. +All of these values are then together encoded to single bytes value that can be sent on chain. You can use [testing gateway](/reference/airnode/v0.13/understand/deploying.md#testing-with-http-gateway) to inspect the raw API response, casting results and the final encoded value. ::: info Multiple Reserved Parameters Tutorial -The -[weather-multi-value](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates encoding of multiple values of different types. +The [weather-multi-value](/guides/airnode/monorepo-examples.md) monorepo example demonstrates encoding of multiple values of different types. ::: diff --git a/docs/reference/ois/2.2/specification.md b/docs/reference/ois/2.2/specification.md index c9a2c0eb..44256ba6 100644 --- a/docs/reference/ois/2.2/specification.md +++ b/docs/reference/ois/2.2/specification.md @@ -19,34 +19,21 @@ tags: # {{$frontmatter.title}} -The Oracle Integration Specification (OIS) is based on -[Open API specification (OAS)](https://swagger.io/specification/), but there are -some differences, be sure to focus on the following documentation when working -on an OIS file. +The Oracle Integration Specification (OIS) is based on [Open API specification (OAS)](https://swagger.io/specification/), but there are some differences, be sure to focus on the following documentation when working on an OIS file. ::: warning OAS -It is not recommended to refer to OAS for help while creating an OIS object. OIS -only borrows formatting practices from OAS. Everything needed to create an OIS -object is in these docs. +It is not recommended to refer to OAS for help while creating an OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: -For an overview that explains how Airnode maps its endpoints to API provider -operations, see -[API integration](/reference/airnode/v0.13/understand/api-integration.md). Also -see the medium article -[Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) -for an overview of OIS. +For an overview that explains how Airnode maps its endpoints to API provider operations, see [API integration](/reference/airnode/v0.13/understand/api-integration.md). Also see the medium article [Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) for an overview of OIS. -- Fields denoted by (\*) are for documentation purposes and not used by an - Airnode. +- Fields denoted by (\*) are for documentation purposes and not used by an Airnode. - The OIS fields should be reviewed and customized by the integrating party. -- All URLs are absolute (i.e., - [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) - are not supported). +- All URLs are absolute (i.e., [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) are not supported). ## OIS Object Summary @@ -58,8 +45,7 @@ An OIS has five root fields (keys). 1. [apiSpecifications](/reference/ois/2.2/specification.md#_4-apispecifications) 1. [endpoints](/reference/ois/2.2/specification.md#_5-endpoints) -`apiSpecifications` describe the API's operations which are mapped to the -`endpoints` that Airnode exposes on-chain. +`apiSpecifications` describe the API's operations which are mapped to the `endpoints` that Airnode exposes on-chain. ```json { @@ -77,21 +63,17 @@ An OIS has five root fields (keys). ## 1. `oisFormat` -(Required) The OIS format version followed while generating the specifications. -See [Versions](/reference/ois/2.2/versions) for a list of OIS versions used by -each Airnode version. +(Required) The OIS format version followed while generating the specifications. See [Versions](/reference/ois/2.2/versions) for a list of OIS versions used by each Airnode version. ## 2. `title` -(Required) The OIS title. Title field is at most 64 characters, can only include -alphanumeric characters, hyphens, underscores and whitespaces. +(Required) The OIS title. Title field is at most 64 characters, can only include alphanumeric characters, hyphens, underscores and whitespaces. ## 3. `version` -(Required) A user defined version for the OIS object. Not to be confused with -the `oisFormat` version which defines an OIS formatting version. +(Required) A user defined version for the OIS object. Not to be confused with the `oisFormat` version which defines an OIS formatting version. ## 4. `apiSpecifications` @@ -139,21 +121,18 @@ the `oisFormat` version which defines an OIS formatting version. ### 4.1. `servers` -(Required) An array of objects containing the base URL of the API. Only one -object (i.e., base URL) is allowed in the array. Applies to all API operations. +(Required) An array of objects containing the base URL of the API. Only one object (i.e., base URL) is allowed in the array. Applies to all API operations. ### 4.2. `paths` -(Required) An object where an API's operations are defined by `{path}.{method}` -(i.e. `paths./myPath.get`) each with a `parameters` array. +(Required) An object where an API's operations are defined by `{path}.{method}` (i.e. `paths./myPath.get`) each with a `parameters` array. #### 4.2.1. `parameters` -(Required) A list of the API operation's parameters, each with the following -fields: +(Required) A list of the API operation's parameters, each with the following fields: - `name` - `in` @@ -177,9 +156,7 @@ the non-nested application/json content-type is supported.

### 4.3. `components` -(Required) An object where -[security schemes](/reference/airnode/v0.13/understand/api-security.md) can be -found under `securitySchemes.{securitySchemeName}` with the following elements: +(Required) An object where [security schemes](/reference/airnode/v0.13/understand/api-security.md) can be found under `securitySchemes.{securitySchemeName}` with the following elements: - `type` - `name` @@ -195,8 +172,7 @@ Allowed values: - Used by an API operation to authenticate Airnode. - `apiKey` - `http` -- Allows an API operation to acquire information about the requester and/or the - chain. +- Allows an API operation to acquire information about the requester and/or the chain. - `relayRequesterAddress` - `relaySponsorAddress` - `relaySponsorWalletAddress` @@ -222,9 +198,7 @@ Allowed values: `query`, `header`, `cookie` #### 4.3.4. `scheme` -(Only if `type` is http) The name of the HTTP Authorization scheme to be used in -the -[Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). +(Only if `type` is http) The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). Allowed values: (`basic` and `bearer`). @@ -241,20 +215,9 @@ Allowed values: (`basic` and `bearer`). ### 4.4. `security` -(Required) An object containing all security schemes required by an API call. -Applies to all operations. A security scheme can contain information required by -the API to authenticate Airnode as well as information about the requester -(relay information) the API may also require. Read more about security schemes -in the [API Security](/reference/airnode/v0.13/understand/api-security.md) -section of the _Build an Airnode_ guide and the -[Airnode Authentication](/reference/airnode/v0.13/concepts/airnode-auth.md) -section of _Concepts and Definitions_. - -The `security` object maintains the names of all the security schemes used. Each -security scheme in `security` maps to an empty list. The empty list will be used -by future versions of Airnode for individual endpoint authentication. The -`components.securitySchemes.{name}` object defines the security schemes. Unlike -OAS `security` is an object, not an array. +(Required) An object containing all security schemes required by an API call. Applies to all operations. A security scheme can contain information required by the API to authenticate Airnode as well as information about the requester (relay information) the API may also require. Read more about security schemes in the [API Security](/reference/airnode/v0.13/understand/api-security.md) section of the _Build an Airnode_ guide and the [Airnode Authentication](/reference/airnode/v0.13/concepts/airnode-auth.md) section of _Concepts and Definitions_. + +The `security` object maintains the names of all the security schemes used. Each security scheme in `security` maps to an empty list. The empty list will be used by future versions of Airnode for individual endpoint authentication. The `components.securitySchemes.{name}` object defines the security schemes. Unlike OAS `security` is an object, not an array. ```json // OIS object @@ -273,8 +236,7 @@ OAS `security` is an object, not an array. } ``` -The `apiCredential` object (which is not part of the OIS object) holds -credentials needed by the security scheme if any. +The `apiCredential` object (which is not part of the OIS object) holds credentials needed by the security scheme if any. ```json // config.json root object. @@ -292,41 +254,30 @@ credentials needed by the security scheme if any. ::: warning Please note: -Currently Airnode reads the security schemes from `component.securitySchemes` -and not `security`. Using the `security` field now (in conjunction with -`component.securitySchemes`) provides for a smooth transition to future releases -of Airnode with regards to security scheme implementation. This will allow -assigning of security schemes to individual API operations. Currently security -schemes are assign to the entire API. +Currently Airnode reads the security schemes from `component.securitySchemes` and not `security`. Using the `security` field now (in conjunction with `component.securitySchemes`) provides for a smooth transition to future releases of Airnode with regards to security scheme implementation. This will allow assigning of security schemes to individual API operations. Currently security schemes are assign to the entire API. ::: ## 5. `endpoints` -(Required) A list of objects, each specifying an Airnode endpoint with the -following fields: +(Required) A list of objects, each specifying an Airnode endpoint with the following fields: ::: info Please Note -Fields denoted by \* are for documentation purposes and not used by Airnode -node. +Fields denoted by \* are for documentation purposes and not used by Airnode node. ::: - 5.1. [name](/reference/ois/2.2/specification.md#_5-1-name) - 5.2. [operation](/reference/ois/2.2/specification.md#_5-2-operation) -- 5.3. - [fixedOperationParameters](/reference/ois/2.2/specification.md#_5-3-fixedoperationparameters) -- 5.4. - [reservedParameters](/reference/ois/2.2/specification.md#_5-4-reservedparameters) +- 5.3. [fixedOperationParameters](/reference/ois/2.2/specification.md#_5-3-fixedoperationparameters) +- 5.4. [reservedParameters](/reference/ois/2.2/specification.md#_5-4-reservedparameters) - 5.5. [parameters](/reference/ois/2.2/specification.md#_5-5-parameters) - 5.6. [summary \*](/reference/ois/2.2/specification.md#_5-6-summary) - 5.7. [description \*](/reference/ois/2.2/specification.md#_5-7-description) - 5.8. [externalDocs \*](/reference/ois/2.2/specification.md#_5-8-externaldocs) -- 5.9. - [preProcessingSpecifications](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) -- 5.10. - [postProcessingSpecifications](/reference/ois/2.2/specification.md#_5-10-postprocessingspecifications) +- 5.9. [preProcessingSpecifications](/reference/ois/2.2/specification.md#_5-9-preprocessingspecifications) +- 5.10. [postProcessingSpecifications](/reference/ois/2.2/specification.md#_5-10-postprocessingspecifications) ```json // endpoints @@ -407,18 +358,12 @@ operation.--> ### 5.2. `operation` -(Required: when calling an API) An object that refers to an API operation -defined in `apiSpecifications.paths`. The following elements must be defined: +(Required: when calling an API) An object that refers to an API operation defined in `apiSpecifications.paths`. The following elements must be defined: - `path` - `method` -The `operation` field must be omitted if the intent is _not_ to call an API but -rather return a value from the -[Pre/Post Processing](/reference/ois/2.2/processing.md) capabilities of Airnode. -See -[Skip the API provider call](/reference/ois/2.2/processing.md#skip-the-api-call) -for more information. +The `operation` field must be omitted if the intent is _not_ to call an API but rather return a value from the [Pre/Post Processing](/reference/ois/2.2/processing.md) capabilities of Airnode. See [Skip the API provider call](/reference/ois/2.2/processing.md#skip-the-api-call) for more information. #### 5.2.1. `path` @@ -438,18 +383,14 @@ respective API operation.--> ### 5.3. `fixedOperationParameters` -(Required) A list of objects specifying the fixed parameters for an API -operation. While required, the -[fixedOperationParameters](/reference/airnode/v0.13/understand/api-integration.md#fixedoperationparameters) -array can be left empty. Each object has the following elements: +(Required) A list of objects specifying the fixed parameters for an API operation. While required, the [fixedOperationParameters](/reference/airnode/v0.13/understand/api-integration.md#fixedoperationparameters) array can be left empty. Each object has the following elements: - `operationParameter` - `value` #### 5.3.1. `operationParameter` -(Required) An object that refers to a parameter of an API operation with the -following elements: +(Required) An object that refers to a parameter of an API operation with the following elements: - `name` - `in` @@ -464,54 +405,35 @@ following elements: #### 5.3.2. `value` -(Required) The value to be used for the respective parameter of an API operation -that cannot be overridden by the requester. This is allowed to be any type, -including an object; for example, the following specifies an array containing -multiple primitives: `["finalized", false]`. +(Required) The value to be used for the respective parameter of an API operation that cannot be overridden by the requester. This is allowed to be any type, including an object; for example, the following specifies an array containing multiple primitives: `["finalized", false]`. ### 5.4. `reservedParameters` -A list of objects that specify reserved Airnode endpoint parameters that do not -map to any API operation parameters, but are used for special purposes by the -Airnode. See the -[Reserved Parameters](/reference/ois/2.2/reserved-parameters.md) doc for an -in-depth explanation and -[reservedParameters](/reference/airnode/v0.13/understand/api-integration.md#reservedparameters). -Each object has the following elements: +A list of objects that specify reserved Airnode endpoint parameters that do not map to any API operation parameters, but are used for special purposes by the Airnode. See the [Reserved Parameters](/reference/ois/2.2/reserved-parameters.md) doc for an in-depth explanation and [reservedParameters](/reference/airnode/v0.13/understand/api-integration.md#reservedparameters). Each object has the following elements: - `name` - `fixed` - `default` -Note that if a reserved parameter object does not include a `fixed` value, a -requester can, or may be expected to, supply this value as a parameter. A value -supplied by a requester overrides a `default`. See the -[\_gasPrice](/reference/ois/2.2/reserved-parameters.md#gasprice) reserved -parameter description for an example. +Note that if a reserved parameter object does not include a `fixed` value, a requester can, or may be expected to, supply this value as a parameter. A value supplied by a requester overrides a `default`. See the [\_gasPrice](/reference/ois/2.2/reserved-parameters.md#gasprice) reserved parameter description for an example. #### 5.4.1. `name` (Required) The name of the reserved parameter. Always starts with `_`. -Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and -`_minConfirmations`. +Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. #### 5.4.2. `fixed` -(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. -Cannot be used together with `default`. +(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. Cannot be used together with `default`. #### 5.4.3. `default` -(Optional) The default value for the reserved parameter. Used when no value is -provided by a requester. Cannot be used together with `fixed`. +(Optional) The default value for the reserved parameter. Used when no value is provided by a requester. Cannot be used together with `fixed`. ### 5.5. `parameters` -(Optional) A list of objects that specify Airnode endpoint -[parameters](/reference/airnode/v0.13/understand/api-integration.md#parameters) -that map to an particular API operation's parameters. Each object has the -following elements: +(Optional) A list of objects that specify Airnode endpoint [parameters](/reference/airnode/v0.13/understand/api-integration.md#parameters) that map to an particular API operation's parameters. Each object has the following elements: - `operationParameter` - `name` @@ -522,9 +444,7 @@ following elements: #### 5.5.1. `operationParameter` -(Optional) An object that refers to a parameter of an API operation and has the -below elements. Note that if omitted, the `parameter` will not be included as -part of the request to the API endpoint. +(Optional) An object that refers to a parameter of an API operation and has the below elements. Note that if omitted, the `parameter` will not be included as part of the request to the API endpoint. - `name` - `in` @@ -539,16 +459,14 @@ part of the request to the API endpoint. #### 5.5.2. `name` -(Required) The name of the Airnode endpoint parameter. Is not allowed to start -with `_`. +(Required) The name of the Airnode endpoint parameter. Is not allowed to start with `_`. #### 5.5.3. `default` -(Optional) The default value for the Airnode endpoint parameter. Used when no -value is provided. +(Optional) The default value for the Airnode endpoint parameter. Used when no value is provided. @@ -594,11 +512,9 @@ corresponding operation parameter.--> ### 5.9. `preProcessingSpecifications` \* -(Optional) Defines the preprocessing code that can be used to modify the -endpoint parameter before making the API request defined by an Airnode endpoint. +(Optional) Defines the preprocessing code that can be used to modify the endpoint parameter before making the API request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/2.2/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/2.2/processing.md) doc for additional details. #### Example @@ -625,11 +541,9 @@ additional details. ### 5.10. `postProcessingSpecifications` \* -(Optional) Defines the post-processing code that can be used to modify the API -response from the request defined by an Airnode endpoint. +(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/2.2/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/2.2/processing.md) doc for additional details. #### Example diff --git a/docs/reference/ois/2.2/template.md b/docs/reference/ois/2.2/template.md index 03b54035..eead51c1 100644 --- a/docs/reference/ois/2.2/template.md +++ b/docs/reference/ois/2.2/template.md @@ -19,19 +19,11 @@ tags: # {{$frontmatter.title}} -An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's -`config.json` file. +An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's `config.json` file. -In the OIS template, there are some fields that contain . This means -that the value you will be replacing this with is independent from the other -fields. On the other hand, if two fields contain the same expression (e.g., -``), you must use the same value in them, -because they are referencing each other. +In the OIS template, there are some fields that contain . This means that the value you will be replacing this with is independent from the other fields. On the other hand, if two fields contain the same expression (e.g., ``), you must use the same value in them, because they are referencing each other. -The file below is a basic template for OIS. Note, that it might look differently -for your particular use case. You can also check out the OISes created for the -examples in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations). +The file below is a basic template for OIS. Note, that it might look differently for your particular use case. You can also check out the OISes created for the examples in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations). ```json { diff --git a/docs/reference/ois/2.2/versions.md b/docs/reference/ois/2.2/versions.md index e5cc683e..f0e7409c 100644 --- a/docs/reference/ois/2.2/versions.md +++ b/docs/reference/ois/2.2/versions.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Be sure to use the correct OIS version for the Airnode version you are -deploying. +Be sure to use the correct OIS version for the Airnode version you are deploying. | Airnode version | Latest compatible OIS version | | ------------------- | -------------------------------------------- | @@ -33,10 +32,8 @@ deploying. | 0.8.x | [1.1.2](https://old-docs.api3.org/ois/v1.1/) | | 0.2.x through 0.7.x | [1.0.0](https://old-docs.api3.org/ois/v1.0/) | -Documentation for versions `v1.0.0` through `v1.4.0` are available on the -[legacy documentation site](https://old-docs.api3.org). +Documentation for versions `v1.0.0` through `v1.4.0` are available on the [legacy documentation site](https://old-docs.api3.org). -See GitHub [releases](https://github.com/api3dao/ois/releases) for more -information about the changes in each version. +See GitHub [releases](https://github.com/api3dao/ois/releases) for more information about the changes in each version. diff --git a/docs/reference/ois/latest/index.md b/docs/reference/ois/latest/index.md index 7b2ebc20..d11e377d 100644 --- a/docs/reference/ois/latest/index.md +++ b/docs/reference/ois/latest/index.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -OIS (or Oracle Integration Specifications) is a JSON object that describes an -API specification and defines Airnode endpoints linked to API operations (a.k.a. -endpoints). It is one of five root level objects in a `config.json` file that -defines an Airnode. +OIS (or Oracle Integration Specifications) is a JSON object that describes an API specification and defines Airnode endpoints linked to API operations (a.k.a. endpoints). It is one of five root level objects in a `config.json` file that defines an Airnode. - chains - nodeSettings @@ -30,14 +27,9 @@ defines an Airnode. - ois - apiCredentials -For more information about the config.json file see the -[Deployment Files](/reference/airnode/latest/deployment-files/config-json.md) -section in the Airnode document set. +For more information about the config.json file see the [Deployment Files](/reference/airnode/latest/deployment-files/config-json.md) section in the Airnode document set. -In the diagram below, an Airnode exposes its endpoints to the on-chain -AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to -an API operation. It should be noted that Airnode can have more than one -endpoint that maps to the same API operation. +In the diagram below, an Airnode exposes its endpoints to the on-chain AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to an API operation. It should be noted that Airnode can have more than one endpoint that maps to the same API operation. > > @@ -47,18 +39,11 @@ endpoint that maps to the same API operation. ## API Mapping Examples -The following are three possible Airnode to API operation mapping examples. -Mapping details are better documented in the next doc -[Specification](/reference/ois/latest/specification.md). +The following are three possible Airnode to API operation mapping examples. Mapping details are better documented in the next doc [Specification](/reference/ois/latest/specification.md). ### Simple Airnode Endpoint -An API has a simple operation the returns the current value of an on-chain token -`GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint -will only mimic the API operation. To do so, the Airnode will declare its -endpoint to have one parameter, `id`. Airnode will accept an `id` argument from -an on-chain request and move its value to the API operation's path parameter -named `id`. +An API has a simple operation the returns the current value of an on-chain token `GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint will only mimic the API operation. To do so, the Airnode will declare its endpoint to have one parameter, `id`. Airnode will accept an `id` argument from an on-chain request and move its value to the API operation's path parameter named `id`. ```json // ois.apiSpecifications (API operations) @@ -97,25 +82,11 @@ named `id`. ### Fixed Operation Parameters Airnode Endpoint -An API may have an operation that returns a crypto coin in either a summary or -detail form. The API operation has two parameters, `coinId` in the path and -`includeDetails` in the query. The Airnode (by design) will not allow the -details of the coin to be returned, only the summary. Therefore the Airnode will -require a requester to pass a `coinId` but will ignore the `includeDetails` -parameter if passed. The Airnode will always set the `includeDetails` query -parameter to false regardless of what a requester sends when it calls the API -operation. It does so using a `fixedOperationParameters` when calling the API -operation. +An API may have an operation that returns a crypto coin in either a summary or detail form. The API operation has two parameters, `coinId` in the path and `includeDetails` in the query. The Airnode (by design) will not allow the details of the coin to be returned, only the summary. Therefore the Airnode will require a requester to pass a `coinId` but will ignore the `includeDetails` parameter if passed. The Airnode will always set the `includeDetails` query parameter to false regardless of what a requester sends when it calls the API operation. It does so using a `fixedOperationParameters` when calling the API operation. ### Two Airnode Endpoints - One API Operation -An Airnode may wish to create two Airnode endpoints mapped to a single API -operation whereas the requester does not pass any argument. While the API -operation returns any token value based on a path parameter `id`, Airnode will -only allow one particular token per Airnode endpoint. This is done using -`fixedOperationParameters` rather than normal `parameters`. By applying a -`value` to `fixedOperationParameters` for each Airnode endpoint, only the token -in the `value` can be returned to the requester. +An Airnode may wish to create two Airnode endpoints mapped to a single API operation whereas the requester does not pass any argument. While the API operation returns any token value based on a path parameter `id`, Airnode will only allow one particular token per Airnode endpoint. This is done using `fixedOperationParameters` rather than normal `parameters`. By applying a `value` to `fixedOperationParameters` for each Airnode endpoint, only the token in the `value` can be returned to the requester. ```json "endpoints": [ diff --git a/docs/reference/ois/latest/processing.md b/docs/reference/ois/latest/processing.md index 9899c57a..ad8197f4 100644 --- a/docs/reference/ois/latest/processing.md +++ b/docs/reference/ois/latest/processing.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Processing allows Airnode operators to define custom logic that executes before -or after an API call. This feature is useful for multiple use cases, including: +Processing allows Airnode operators to define custom logic that executes before or after an API call. This feature is useful for multiple use cases, including: - Authentication - Data transformation @@ -30,152 +29,85 @@ or after an API call. This feature is useful for multiple use cases, including: ## Processing versions -OIS specification has two versions of pre/post processing. Both versions serve -the same use cases, but the second version is more flexible and convenient. -Users are encouraged to use the second version. +OIS specification has two versions of pre/post processing. Both versions serve the same use cases, but the second version is more flexible and convenient. Users are encouraged to use the second version. ### v1 -The processing schema accepts an array of processing snippets (user defined -code) which are chained. The first snippet receives parameters submitted as part -of a template or on-chain request. The output of this snippet is passed to the -second snippet and so on. +The processing schema accepts an array of processing snippets (user defined code) which are chained. The first snippet receives parameters submitted as part of a template or on-chain request. The output of this snippet is passed to the second snippet and so on. -Airnode executes snippets for `preProcessingSpecifications` and -`postProcessingSpecifications` during its run cycle. The following describes the -work flow Airnode uses: +Airnode executes snippets for `preProcessingSpecifications` and `postProcessingSpecifications` during its run cycle. The following describes the work flow Airnode uses: 1. Run `preProcessingSpecifications` 2. Airnode calls requested OIS endpoint (unless the API call is skipped) 3. Run `postProcessingSpecifications` 4. Airnode encodes the response values defined by `reservedParameters` -The processing schema is the same for both -[`preProcessingSpecifications`](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) -and -[`postProcessingSpecifications`](/reference/ois/latest/specification.md#_5-10-postprocessingspecifications). -Snippets for both specifications follow this schema: - -- `environment` - Currently one of `Node` or `Node async`. Both options - interpret the code as JavaScript and execute in Node.js. The async version can - use asynchronous code. The code snippet is expected to call `resolve(output)` - with the output value as an argument. Airnode will use the resolved value as - the input to subsequent snippets (if defined). +The processing schema is the same for both [`preProcessingSpecifications`](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) and [`postProcessingSpecifications`](/reference/ois/latest/specification.md#_5-10-postprocessingspecifications). Snippets for both specifications follow this schema: + +- `environment` - Currently one of `Node` or `Node async`. Both options interpret the code as JavaScript and execute in Node.js. The async version can use asynchronous code. The code snippet is expected to call `resolve(output)` with the output value as an argument. Airnode will use the resolved value as the input to subsequent snippets (if defined). - `value` - The processing code written as a string. -- `timeoutMs` - The maximum duration that this snippet can run. In case the - timeout is exceeded an error is thrown. +- `timeoutMs` - The maximum duration that this snippet can run. In case the timeout is exceeded an error is thrown. -Try the [Post processing](/guides/airnode/post-processing/) guide to further -understand pre/post processing. +Try the [Post processing](/guides/airnode/post-processing/) guide to further understand pre/post processing. #### Input and Output -The processing snippet receives an `input` value which is either the initial -value or the output value from the previous processing snippet. The snippet must -create a variable `output` which will be used for the next processing snippet. -The processing snippet can use most Node.js built-in modules. Refer to the -source code of Airnode to understand how processing works and what modules are -made available to the snippet code. Modules cannot be imported directly in cloud -environments. +The processing snippet receives an `input` value which is either the initial value or the output value from the previous processing snippet. The snippet must create a variable `output` which will be used for the next processing snippet. The processing snippet can use most Node.js built-in modules. Refer to the source code of Airnode to understand how processing works and what modules are made available to the snippet code. Modules cannot be imported directly in cloud environments. #### Accessing endpoint parameters -Endpoint parameters, with the exception of reserved parameters, are accessible -within pre-processing and post-processing via the immutable `endpointParameters` -object. For example, if there was a parameter named `myParameter` defined in the -`endpoints[n].parameters` array, its value could be accessed using -`endpointParameters.myParameter` within pre-processing and post-processing code -snippets. +Endpoint parameters, with the exception of reserved parameters, are accessible within pre-processing and post-processing via the immutable `endpointParameters` object. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing and post-processing code snippets. ::: info Accessing reserved parameters -Note that reserved parameters are inaccessible in both pre-processing and -post-processing. +Note that reserved parameters are inaccessible in both pre-processing and post-processing. ::: ### v2 -The processing snippet receives parameters submitted as part of a template or -on-chain request. +The processing snippet receives parameters submitted as part of a template or on-chain request. -Airnode executes snippets for `preProcessingSpecificationV2` and -`postProcessingSpecificationV2` during its run cycle. The following describes -the work flow Airnode uses: +Airnode executes snippets for `preProcessingSpecificationV2` and `postProcessingSpecificationV2` during its run cycle. The following describes the work flow Airnode uses: 1. Run `preProcessingSpecificationV2` 2. Airnode calls requested OIS endpoint (unless the API call is skipped) 3. Run `postProcessingSpecificationV2` 4. Airnode encodes the response values defined by `reservedParameters` -The processing schema is the same for both -[`preProcessingSpecificationV2`](/reference/ois/latest/specification.md#_5-11-preprocessingspecificationv2) -and -[`postProcessingSpecificationV2`](/reference/ois/latest/specification.md#_5-12-postprocessingspecificationv2). -Snippets for both specifications follow this schema: +The processing schema is the same for both [`preProcessingSpecificationV2`](/reference/ois/latest/specification.md#_5-11-preprocessingspecificationv2) and [`postProcessingSpecificationV2`](/reference/ois/latest/specification.md#_5-12-postprocessingspecificationv2). Snippets for both specifications follow this schema: -- `environment` - Currently only possible value is `Node`. This options - interprets the code as JavaScript and executes it in Node.js. The function can - be also asynchronous (async/await is supported as well). The processing - implementation will wait for the function to resolve. +- `environment` - Currently only possible value is `Node`. This options interprets the code as JavaScript and executes it in Node.js. The function can be also asynchronous (async/await is supported as well). The processing implementation will wait for the function to resolve. - `value` - The processing code written as a string. -- `timeoutMs` - The maximum duration that this snippet can run. In case the - timeout is exceeded an error is thrown. +- `timeoutMs` - The maximum duration that this snippet can run. In case the timeout is exceeded an error is thrown. -Try the [Post processing](/guides/airnode/post-processing/) guide to further -understand pre/post processing. +Try the [Post processing](/guides/airnode/post-processing/) guide to further understand pre/post processing. #### Input and Output -The processing snippet expects a function that takes an object as an argument, -the properties of which are different for pre-processing and post-processing. -The return value of the function is treated as a processing result. Within the -snippet, you can use most Node.js built-in modules. +The processing snippet expects a function that takes an object as an argument, the properties of which are different for pre-processing and post-processing. The return value of the function is treated as a processing result. Within the snippet, you can use most Node.js built-in modules. The pre-processing argument object contains the following property: -- `endpointParameters` - The endpoint parameters with the exception of reserved - parameters. For example, if there was a parameter named `myParameter` defined - in the `endpoints[n].parameters` array, its value could be accessed using - `endpointParameters.myParameter` within pre-processing snippet. +- `endpointParameters` - The endpoint parameters with the exception of reserved parameters. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing snippet. -The output of the pre-processing snippet is an object with the following -property: +The output of the pre-processing snippet is an object with the following property: -- `endpointParameters` - The pre-processed endpoint parameters parameters. These - are used to make the API call. +- `endpointParameters` - The pre-processed endpoint parameters parameters. These are used to make the API call. The post-processing argument object contains the following properties: -- `response` - The response of the underlying data provider API call. In case of - Airnode skipping the API call, the `response` contains the output of - pre-processing snippet. -- `endpointParameters` - The raw (not pre-processed) endpoint parameters with - the exception of reserved parameters. For example, if there was a parameter - named `myParameter` defined in the `endpoints[n].parameters` array, its value - could be accessed using `endpointParameters.myParameter` within pre-processing - snippet. - -The output of the post-processing snippet is an object with the following -properties: - -- `response` - The post-processed API call response (or post-processed result of - pre-processing snippet in case of skipping an API call). This is used to - encode the response values defined by reserved parameters. -- `timestamp` - (Optional) The timestamp of the API call response. Use this if - you want Airnode to use a specific timestamp (instead of a current time at - request processing) when using the - [signed data gateway](/reference/airnode/latest/understand/http-gateways.md#http-signed-data-gateway). - See the example below for more details. +- `response` - The response of the underlying data provider API call. In case of Airnode skipping the API call, the `response` contains the output of pre-processing snippet. +- `endpointParameters` - The raw (not pre-processed) endpoint parameters with the exception of reserved parameters. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing snippet. + +The output of the post-processing snippet is an object with the following properties: + +- `response` - The post-processed API call response (or post-processed result of pre-processing snippet in case of skipping an API call). This is used to encode the response values defined by reserved parameters. +- `timestamp` - (Optional) The timestamp of the API call response. Use this if you want Airnode to use a specific timestamp (instead of a current time at request processing) when using the [signed data gateway](/reference/airnode/latest/understand/http-gateways.md#http-signed-data-gateway). See the example below for more details. #### Timestamp example -One of the possible use cases for post-processing v2 would be to use override -the timestamp used by -[signed data gateway](/reference/airnode/next/understand/http-gateways.md#http-signed-data-gateway). -By default the signed data gateway uses the timestamp of the request processing. -However, sometimes the API itself returns the timestamp. Modifying timestamp is -only supported with the v2 of the processing. +One of the possible use cases for post-processing v2 would be to use override the timestamp used by [signed data gateway](/reference/airnode/next/understand/http-gateways.md#http-signed-data-gateway). By default the signed data gateway uses the timestamp of the request processing. However, sometimes the API itself returns the timestamp. Modifying timestamp is only supported with the v2 of the processing. ```json { @@ -190,13 +122,9 @@ only supported with the v2 of the processing. ## Interpolation -Note, that config.json supports interpolation of secrets via the JavaScript -string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with -the string interpolation inside the processing snippets. In order to use the -interpolation in snippets, you need to escape the interpolation. +Note, that config.json supports interpolation of secrets via the JavaScript string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with the string interpolation inside the processing snippets. In order to use the interpolation in snippets, you need to escape the interpolation. -For example, the following code (using the v1 processing snippet, but the -concept is the same for v2): +For example, the following code (using the v1 processing snippet, but the concept is the same for v2): ```js console.log(`Received input ${input}`); @@ -215,57 +143,25 @@ should be escaped inside the `config.json` like this: ## Error Handling and Security -Processing code is expected to be trustworthy as it is specified by the Airnode -operator. Processing is an advanced feature that carries great security risks. -It is therefore advised that developers using the processing feature familiarize -themselves with the Airnode sources prior to developing any processing code -snippets. +Processing code is expected to be trustworthy as it is specified by the Airnode operator. Processing is an advanced feature that carries great security risks. It is therefore advised that developers using the processing feature familiarize themselves with the Airnode sources prior to developing any processing code snippets. -Processing code executes in a constrained execution environment resembling -Node.js. Some resources may not be available, for example the `require` -statement. Therefore code should be tested thoroughly in the target environment -(e.g. Lambda and/or Docker client). For example, authentication implemented in -pre-processing should always be executed at the end of the respective processing -chain and special care should be taken to avoid leakage of secrets. +Processing code executes in a constrained execution environment resembling Node.js. Some resources may not be available, for example the `require` statement. Therefore code should be tested thoroughly in the target environment (e.g. Lambda and/or Docker client). For example, authentication implemented in pre-processing should always be executed at the end of the respective processing chain and special care should be taken to avoid leakage of secrets. ## Skip the API call -Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on -either (or both) pre-processing or post-processing to acquire a value for the -Airnode to place on-chain. +Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on either (or both) pre-processing or post-processing to acquire a value for the Airnode to place on-chain. -Instead of calling an API, Airnode uses the output of -`preProcessingSpecifications`, `postProcessingSpecifications`, or both. The -field `operation` must be undefined, `fixedOperationParameters` must be an empty -array and some processing specification needs to be defined. This means that one -of `preProcessingSpecifications` or `postProcessingSpecifications` must be -defined and not be an empty array or `preProcessingSpecificationV2` or -`postProcessingSpecificationV2` must be defined. +Instead of calling an API, Airnode uses the output of `preProcessingSpecifications`, `postProcessingSpecifications`, or both. The field `operation` must be undefined, `fixedOperationParameters` must be an empty array and some processing specification needs to be defined. This means that one of `preProcessingSpecifications` or `postProcessingSpecifications` must be defined and not be an empty array or `preProcessingSpecificationV2` or `postProcessingSpecificationV2` must be defined. ### Random number example -An Airnode endpoint that places a random number on-chain. Rather than calling an -API, the Airnode will derive a random number during its execution of a -pre-processing v1 specification. A requester would make a request of this -Airnode endpoint without parameters. The Airnode endpoint simply sets the random -number on-chain in response to the request using a `preProcessingSpecifications` -specification. Example #1 below implements this use case. - -This example creates an Airnode endpoint named `generateRandomNumber` with no -parameters. Because there isn't an -[operation field](/reference/ois/latest/specification.md#_5-2-operation) defined -for this Airnode endpoint, a call to an API will not be made. The Airnode will -instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) -array. - -To implement the use case mentioned above, the -[operation field](/reference/ois/latest/specification.md#_5-2-operation) will be -undefined, `fixedOperationParameters` will be an empty array, and -`preProcessingSpecifications` will be defined with a single specification. - -- A requester makes a request of the Airnode endpoint `generateRandomNumber` - without any parameters. +An Airnode endpoint that places a random number on-chain. Rather than calling an API, the Airnode will derive a random number during its execution of a pre-processing v1 specification. A requester would make a request of this Airnode endpoint without parameters. The Airnode endpoint simply sets the random number on-chain in response to the request using a `preProcessingSpecifications` specification. Example #1 below implements this use case. + +This example creates an Airnode endpoint named `generateRandomNumber` with no parameters. Because there isn't an [operation field](/reference/ois/latest/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) array. + +To implement the use case mentioned above, the [operation field](/reference/ois/latest/specification.md#_5-2-operation) will be undefined, `fixedOperationParameters` will be an empty array, and `preProcessingSpecifications` will be defined with a single specification. + +- A requester makes a request of the Airnode endpoint `generateRandomNumber` without any parameters. - Airnode runs the specification in `preProcessingSpecifications[0]`. - The specification generates a random number. - The reserved parameter named `randomNumber` now holds the random number. @@ -303,14 +199,7 @@ endpoints: [ ### Parameter processing example -The code below is unrelated to the above example. Instead, this example creates -an Airnode endpoint named `endpointThatSumsWith1000` with a parameter named -`numberToSum`. Because there isn't an -[operation field](/reference/ois/latest/specification.md#_5-2-operation) defined -for this Airnode endpoint, a call to an API will not be made. The Airnode will -instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) -array. +The code below is unrelated to the above example. Instead, this example creates an Airnode endpoint named `endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there isn't an [operation field](/reference/ois/latest/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) array. - A requester passes the number `5` in the parameter named `numberToSum`. - Airnode runs the specification in `preProcessingSpecifications[0]`. diff --git a/docs/reference/ois/latest/reserved-parameters.md b/docs/reference/ois/latest/reserved-parameters.md index 99189554..18bd3de8 100644 --- a/docs/reference/ois/latest/reserved-parameters.md +++ b/docs/reference/ois/latest/reserved-parameters.md @@ -19,63 +19,36 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an OIS object as part of the `endpoints` field -(Airnode endpoints) and warrant a more in-depth explanation. They are part of an -Airnode's defined endpoints in an OIS object but do not map to operation -parameters (API parameters). They are used by Airnode for special purposes. - -A requester can pass request parameters either by referencing a -[template](/reference/airnode/latest/concepts/template.md) that contains them, -or as an argument of the request-making methods of -[AirnodeRrpV0.sol](/reference/airnode/latest/concepts/#airnoderrpv0-sol). In -either case, these parameters are encoded using the -[AirnodeRrpV0 ABI](/reference/airnode/latest/specifications/airnode-abi.md). -There are two types of parameters which are part of the OIS object: - -1. [Endpoint parameters](/reference/ois/latest/specification.md#_5-5-parameters) - - Airnode endpoint parameters are mapped to API operation parameters. -2. [Reserved parameters](/reference/ois/latest/specification.md#_5-4-reservedparameters) - - Reserved parameters perform a specific operation related to the request or on - the response before fulfilling the request. Reserved parameter names start - with `_`. Depending on the configuration, they may be overridden by a - parameter supplied by a requester. +Reserved parameters are part of an OIS object as part of the `endpoints` field (Airnode endpoints) and warrant a more in-depth explanation. They are part of an Airnode's defined endpoints in an OIS object but do not map to operation parameters (API parameters). They are used by Airnode for special purposes. + +A requester can pass request parameters either by referencing a [template](/reference/airnode/latest/concepts/template.md) that contains them, or as an argument of the request-making methods of [AirnodeRrpV0.sol](/reference/airnode/latest/concepts/#airnoderrpv0-sol). In either case, these parameters are encoded using the [AirnodeRrpV0 ABI](/reference/airnode/latest/specifications/airnode-abi.md). There are two types of parameters which are part of the OIS object: + +1. [Endpoint parameters](/reference/ois/latest/specification.md#_5-5-parameters) - Airnode endpoint parameters are mapped to API operation parameters. +2. [Reserved parameters](/reference/ois/latest/specification.md#_5-4-reservedparameters) - Reserved parameters perform a specific operation related to the request or on the response before fulfilling the request. Reserved parameter names start with `_`. Depending on the configuration, they may be overridden by a parameter supplied by a requester. ## `_type` -Signifies what Solidity type the API response will be encoded to before -fulfillment. +Signifies what Solidity type the API response will be encoded to before fulfillment. -Support is provided for most common -[Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), -but the following are not supported. +Support is provided for most common [Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), but the following are not supported. - Custom bits integer types - e.g. `uint32` or `uint8` - Fixed point decimal numbers - e.g. `fixed128x18` or `ufixed128x18` - Custom fixed size bytes - e.g. `bytes4` - Tuples - e.g. `(int256, string)` -On top of supported solidity types, there is support for a few "artificial" -types created for special purposes that would otherwise be hard or impossible to -represent. +On top of supported solidity types, there is support for a few "artificial" types created for special purposes that would otherwise be hard or impossible to represent. - [`string32`](/reference/ois/latest/reserved-parameters.md#string32-encoded-to-bytes32-on-chain) - [`timestamp`](/reference/ois/latest/reserved-parameters.md#timestamp-encoded-to-uint256-on-chain) -You can also encode multiple values for one single API call - but this impacts -all of the reserved parameters and is explained in the -[Encoding Multiple Values](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values) -section below. +You can also encode multiple values for one single API call - but this impacts all of the reserved parameters and is explained in the [Encoding Multiple Values](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values) section below. ### Conversion and encoding behavior -Before the API response value is encoded for on chain use, it is parsed and -converted. The conversion behaviors for any given type is explained in depth in -the -[adapter package docs](/reference/airnode/latest/packages/adapter.md#conversion). +Before the API response value is encoded for on chain use, it is parsed and converted. The conversion behaviors for any given type is explained in depth in the [adapter package docs](/reference/airnode/latest/packages/adapter.md#conversion). -The converted value is then encoded internally by -[ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) -using the following +The converted value is then encoded internally by [ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) using the following ```js ethers.utils.defaultAbiCoder.encode([solidityType], [value]); @@ -93,54 +66,35 @@ ethers.utils.defaultAbiCoder.encode([solidityType], [value]); #### string32 (encoded to `bytes32` on chain) -The `string32` is an artificial type that is not supported by solidity. It is -instead encoded to `bytes32` and provides a cheaper alternative to the regular -`string` type for values with less than 32 characters. +The `string32` is an artificial type that is not supported by solidity. It is instead encoded to `bytes32` and provides a cheaper alternative to the regular `string` type for values with less than 32 characters. ::: warning Limitations -While using `string32` is more efficient, decoding the original string from -`bytes32` on chain is both difficult and expensive. Also bear in mind that this -type is able to encode only strings shorter than 32 characters. If the value is -longer, it will be trimmed and only first 31 characters will be encoded. +While using `string32` is more efficient, decoding the original string from `bytes32` on chain is both difficult and expensive. Also bear in mind that this type is able to encode only strings shorter than 32 characters. If the value is longer, it will be trimmed and only first 31 characters will be encoded. ::: #### timestamp (encoded to `uint256` on chain) -The `timestamp` is an artificial type that is not supported by solidity. It is -instead encoded to `uint256` and specifies the UNIX timestamp value at the time -when the transaction was encoded. You can use this value on chain to check the -"freshness" of the Airnode response. This might be useful in certain scenarios, -because Airnode cannot guarantee when a particular transaction will be mined on -chain. +The `timestamp` is an artificial type that is not supported by solidity. It is instead encoded to `uint256` and specifies the UNIX timestamp value at the time when the transaction was encoded. You can use this value on chain to check the "freshness" of the Airnode response. This might be useful in certain scenarios, because Airnode cannot guarantee when a particular transaction will be mined on chain. -When using the `timestamp` type, the corresponding `_path` and `_times` -variables must be empty strings or not provided. +When using the `timestamp` type, the corresponding `_path` and `_times` variables must be empty strings or not provided. #### Arrays -Apart from the primitives defined above as well as all "artificial" types we -created, you are free to use arrays with any of the above. Multidimensional -arrays are supported as well. Solidity allows you to define fixed size arrays, -which are more gas efficient to encode and you can use those as well. +Apart from the primitives defined above as well as all "artificial" types we created, you are free to use arrays with any of the above. Multidimensional arrays are supported as well. Solidity allows you to define fixed size arrays, which are more gas efficient to encode and you can use those as well. For example - `int256[]` - regular integer array - `uint256[8]` - unsigned integer array with 8 elements - `int256[][]` - 2 dimensional integer array -- `string32[]` - is an array of `string32` values, which will be encoded to - `bytes32[]` on chain -- `string[2][][3]` - 3 dimensional string array, where first dimension contains - 3 elements, second unboundedly many and last dimension only 2. Note that this - [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) - compared to C-style languages +- `string32[]` - is an array of `string32` values, which will be encoded to `bytes32[]` on chain +- `string[2][][3]` - 3 dimensional string array, where first dimension contains 3 elements, second unboundedly many and last dimension only 2. Note that this [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) compared to C-style languages ## `_path` -Assuming that the API response will be a JSON object, defines the field to be -used to fulfill the request using dot notation. For example, if the API returns +Assuming that the API response will be a JSON object, defines the field to be used to fulfill the request using dot notation. For example, if the API returns ``` { @@ -159,15 +113,11 @@ used to fulfill the request using dot notation. For example, if the API returns and `_path` is `field1.fieldA.1`, the response will be `valueA2`. -If the response is a literal value (i.e., not a JSON object) and `_path` is not -provided or is an empty string (needed for -[encoding multiple values](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values)), -Airnode will use the API response itself to fulfill the request. +If the response is a literal value (i.e., not a JSON object) and `_path` is not provided or is an empty string (needed for [encoding multiple values](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values)), Airnode will use the API response itself to fulfill the request. ::: warning Beware the separator -Make sure the keys in the path of the API response do not contain `.`, because -it will be incorrectly considered as a separator. +Make sure the keys in the path of the API response do not contain `.`, because it will be incorrectly considered as a separator. ``` { @@ -175,18 +125,13 @@ it will be incorrectly considered as a separator. } ``` -A `_path` defined as `"strange.key"` will not work. As workaround you can -[escape the separator](/reference/ois/latest/reserved-parameters.md#escaping-separators). +A `_path` defined as `"strange.key"` will not work. As workaround you can [escape the separator](/reference/ois/latest/reserved-parameters.md#escaping-separators). ::: ### Escaping Separators -In rare cases, when the `_path` to the API response would contain `,` or `.` -(comma or a dot) things get a bit complicated. Those symbols have a very -specific meaning when parsing the reserved parameters and they need to be -escaped if they are to be considered as literals. If the API provider response -looks like the following: +In rare cases, when the `_path` to the API response would contain `,` or `.` (comma or a dot) things get a bit complicated. Those symbols have a very specific meaning when parsing the reserved parameters and they need to be escaped if they are to be considered as literals. If the API provider response looks like the following: ``` { @@ -198,9 +143,7 @@ Then escape the symbols, in this case `_path="very\\,strange\\.key"`. ## `_times` -If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided -Airnode multiplies the value returned by the API with the `_times` parameter -before fulfilling the request. For example, if the API returns: +If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided Airnode multiplies the value returned by the API with the `_times` parameter before fulfilling the request. For example, if the API returns: ``` { @@ -217,29 +160,15 @@ _path: data _times: "100" ``` -the request will be fulfilled with the value `123`. Note that the number gets -multiplied by `100`, and then gets floored. This is because the result of the -multiplication is [cast](/reference/airnode/latest/packages/adapter.md) to -`int256` afterwards. +the request will be fulfilled with the value `123`. Note that the number gets multiplied by `100`, and then gets floored. This is because the result of the multiplication is [cast](/reference/airnode/latest/packages/adapter.md) to `int256` afterwards. -Make sure to pass the `_times` parameter as string. Airnode will convert this -string to number internally. You can also pass and empty string `""` to `_times` -parameter - this has the same effect as if the `_times` parameter was not -provided. However, this is important when -[encoding multiple values](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values). +Make sure to pass the `_times` parameter as string. Airnode will convert this string to number internally. You can also pass and empty string `""` to `_times` parameter - this has the same effect as if the `_times` parameter was not provided. However, this is important when [encoding multiple values](/reference/ois/latest/reserved-parameters.md#encoding-multiple-values). -The `_times` parameter also works in conjunction with arrays and -multidimensional arrays. All elements of the API response array will be -multiplied before they are encoded. +The `_times` parameter also works in conjunction with arrays and multidimensional arrays. All elements of the API response array will be multiplied before they are encoded. ## `_gasPrice` -The `_gasPrice` reserved parameter enables a requester to override -[Airnode gas price strategies](/reference/airnode/latest/concepts/gas-prices.md) -with a specified gas price when Airnode -[fulfills](/reference/airnode/latest/concepts/request.md#fulfill) the request. -The recommended implementation is to have the `_gasPrice` reserved parameter -without a `default` or `fixed` value as shown in the abbreviated snippet below: +The `_gasPrice` reserved parameter enables a requester to override [Airnode gas price strategies](/reference/airnode/latest/concepts/gas-prices.md) with a specified gas price when Airnode [fulfills](/reference/airnode/latest/concepts/request.md#fulfill) the request. The recommended implementation is to have the `_gasPrice` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -251,10 +180,7 @@ without a `default` or `fixed` value as shown in the abbreviated snippet below: } ``` -This allows requesters to specify the gas price via a parameter in their -request. The value, in `wei`, should be -[encoded](/reference/airnode/latest/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the gas price via a parameter in their request. The value, in `wei`, should be [encoded](/reference/airnode/latest/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; @@ -268,19 +194,11 @@ encode([ ]); ``` -Note that if a requester specifies a `_gasPrice` as a parameter in a request but -the Airnode's configuration does not include the `_gasPrice` reserved parameter, -the requester's gas price will be ignored. +Note that if a requester specifies a `_gasPrice` as a parameter in a request but the Airnode's configuration does not include the `_gasPrice` reserved parameter, the requester's gas price will be ignored. ## `_minConfirmations` -The `_minConfirmations` reserved parameter enables a requester to override the -default minimum number of block confirmations set by the Airnode for that chain -in -[config.json](/reference/airnode/latest/deployment-files/config-json.md#minconfirmations). -The recommended implementation is to have the `_minConfirmations` reserved -parameter without a `default` or `fixed` value as shown in the abbreviated -snippet below: +The `_minConfirmations` reserved parameter enables a requester to override the default minimum number of block confirmations set by the Airnode for that chain in [config.json](/reference/airnode/latest/deployment-files/config-json.md#minconfirmations). The recommended implementation is to have the `_minConfirmations` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -292,29 +210,20 @@ snippet below: } ``` -This allows requesters to specify the minimum number of block confirmations via -a parameter in their request. The value should be -[encoded](/reference/airnode/latest/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the minimum number of block confirmations via a parameter in their request. The value should be [encoded](/reference/airnode/latest/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; encode([{ name: '_minConfirmations', type: 'string32', value: '1' }]); ``` -In order to respond to requests in the same nonce order as they are received -when requests specify different `_minConfirmations` values, the maximum -`_minConfirmations` value of all requests in the queue for a given sponsor is -applied to all requests. +In order to respond to requests in the same nonce order as they are received when requests specify different `_minConfirmations` values, the maximum `_minConfirmations` value of all requests in the queue for a given sponsor is applied to all requests. -Note that if a requester specifies a `_minConfirmations` as a parameter in a -request but the Airnode's configuration does not include the `_minConfirmations` -reserved parameter, the requester's minimum confirmations value will be ignored. +Note that if a requester specifies a `_minConfirmations` as a parameter in a request but the Airnode's configuration does not include the `_minConfirmations` reserved parameter, the requester's minimum confirmations value will be ignored. ## Encoding Multiple Values -Solidity has support for decoding and "destructuring" multiple values. For -example: +Solidity has support for decoding and "destructuring" multiple values. For example: ```solidity function decodeMultipleParameters(bytes calldata data) @@ -326,11 +235,7 @@ function decodeMultipleParameters(bytes calldata data) } ``` -The example above demonstrates the decoding on chain of three values of types -`string`, `uint256` and `address` respectively. You can instruct Airnode to -encode these values using the `_type`, `_path`, and `_times` reserved parameters -by separating the values using `,` (comma). For example using the following -combination of reserved parameters: +The example above demonstrates the decoding on chain of three values of types `string`, `uint256` and `address` respectively. You can instruct Airnode to encode these values using the `_type`, `_path`, and `_times` reserved parameters by separating the values using `,` (comma). For example using the following combination of reserved parameters: ```js { @@ -340,10 +245,7 @@ combination of reserved parameters: } ``` -Airnode will split the reserved parameters by `,` into "split values" and ensure -they all contain the same number of them. It will extract and convert each of -the "split values". Notice, that an `""` (empty string) is used to specify that -a certain reserved parameter should not be used for a certain "split value". +Airnode will split the reserved parameters by `,` into "split values" and ensure they all contain the same number of them. It will extract and convert each of the "split values". Notice, that an `""` (empty string) is used to specify that a certain reserved parameter should not be used for a certain "split value". For example, let's say the API response looks like this: @@ -357,23 +259,15 @@ For example, let's say the API response looks like this: Airnode will extract and convert each of the "split values" separately -1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` - results in `"some string"` -2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` - results in `12345670` -3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` - results in `"0xe021...8a74"` +1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` results in `"some string"` +2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` results in `12345670` +3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` results in `"0xe021...8a74"` -All of these values are then together encoded to single bytes value that can be -sent on chain. You can use -[testing gateway](/reference/airnode/latest/understand/deploying.md#testing-with-http-gateway) -to inspect the raw API response, casting results and the final encoded value. +All of these values are then together encoded to single bytes value that can be sent on chain. You can use [testing gateway](/reference/airnode/latest/understand/deploying.md#testing-with-http-gateway) to inspect the raw API response, casting results and the final encoded value. ::: info Multiple Reserved Parameters Tutorial -The -[weather-multi-value](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates encoding of multiple values of different types. +The [weather-multi-value](/guides/airnode/monorepo-examples.md) monorepo example demonstrates encoding of multiple values of different types. ::: diff --git a/docs/reference/ois/latest/specification.md b/docs/reference/ois/latest/specification.md index 08939c0b..3188e09c 100644 --- a/docs/reference/ois/latest/specification.md +++ b/docs/reference/ois/latest/specification.md @@ -19,34 +19,21 @@ tags: # {{$frontmatter.title}} -The Oracle Integration Specification (OIS) is based on -[Open API specification (OAS)](https://swagger.io/specification/), but there are -some differences, be sure to focus on the following documentation when working -on an OIS file. +The Oracle Integration Specification (OIS) is based on [Open API specification (OAS)](https://swagger.io/specification/), but there are some differences, be sure to focus on the following documentation when working on an OIS file. ::: warning OAS -It is not recommended to refer to OAS for help while creating an OIS object. OIS -only borrows formatting practices from OAS. Everything needed to create an OIS -object is in these docs. +It is not recommended to refer to OAS for help while creating an OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: -For an overview that explains how Airnode maps its endpoints to API provider -operations, see -[API integration](/reference/airnode/latest/understand/api-integration.md). Also -see the medium article -[Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) -for an overview of OIS. +For an overview that explains how Airnode maps its endpoints to API provider operations, see [API integration](/reference/airnode/latest/understand/api-integration.md). Also see the medium article [Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) for an overview of OIS. -- Fields denoted by (\*) are for documentation purposes and not used by an - Airnode. +- Fields denoted by (\*) are for documentation purposes and not used by an Airnode. - The OIS fields should be reviewed and customized by the integrating party. -- All URLs are absolute (i.e., - [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) - are not supported). +- All URLs are absolute (i.e., [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) are not supported). ## OIS Object Summary @@ -58,8 +45,7 @@ An OIS has five root fields (keys). 1. [apiSpecifications](/reference/ois/latest/specification.md#_4-apispecifications) 1. [endpoints](/reference/ois/latest/specification.md#_5-endpoints) -`apiSpecifications` describe the API's operations which are mapped to the -`endpoints` that Airnode exposes on-chain. +`apiSpecifications` describe the API's operations which are mapped to the `endpoints` that Airnode exposes on-chain. ```json { @@ -77,21 +63,17 @@ An OIS has five root fields (keys). ## 1. `oisFormat` -(Required) The OIS format version followed while generating the specifications. -See [Versions](/reference/ois/latest/versions.md) for a list of OIS versions -used by each Airnode version. +(Required) The OIS format version followed while generating the specifications. See [Versions](/reference/ois/latest/versions.md) for a list of OIS versions used by each Airnode version. ## 2. `title` -(Required) The OIS title. Title field is at most 64 characters, can only include -alphanumeric characters, hyphens, underscores and whitespaces. +(Required) The OIS title. Title field is at most 64 characters, can only include alphanumeric characters, hyphens, underscores and whitespaces. ## 3. `version` -(Required) A user defined version for the OIS object. Not to be confused with -the `oisFormat` version which defines an OIS formatting version. +(Required) A user defined version for the OIS object. Not to be confused with the `oisFormat` version which defines an OIS formatting version. ## 4. `apiSpecifications` @@ -139,21 +121,18 @@ the `oisFormat` version which defines an OIS formatting version. ### 4.1. `servers` -(Required) An array of objects containing the base URL of the API. Only one -object (i.e., base URL) is allowed in the array. Applies to all API operations. +(Required) An array of objects containing the base URL of the API. Only one object (i.e., base URL) is allowed in the array. Applies to all API operations. ### 4.2. `paths` -(Required) An object where an API's operations are defined by `{path}.{method}` -(i.e. `paths./myPath.get`) each with a `parameters` array. +(Required) An object where an API's operations are defined by `{path}.{method}` (i.e. `paths./myPath.get`) each with a `parameters` array. #### 4.2.1. `parameters` -(Required) A list of the API operation's parameters, each with the following -fields: +(Required) A list of the API operation's parameters, each with the following fields: - `name` - `in` @@ -177,9 +156,7 @@ the non-nested application/json content-type is supported.

### 4.3. `components` -(Required) An object where -[security schemes](/reference/airnode/latest/understand/api-security.md) can be -found under `securitySchemes.{securitySchemeName}` with the following elements: +(Required) An object where [security schemes](/reference/airnode/latest/understand/api-security.md) can be found under `securitySchemes.{securitySchemeName}` with the following elements: - `type` - `name` @@ -195,8 +172,7 @@ Allowed values: - Used by an API operation to authenticate Airnode. - `apiKey` - `http` -- Allows an API operation to acquire information about the requester and/or the - chain. +- Allows an API operation to acquire information about the requester and/or the chain. - `relayRequesterAddress` - `relaySponsorAddress` - `relaySponsorWalletAddress` @@ -222,9 +198,7 @@ Allowed values: `query`, `header`, `cookie` #### 4.3.4. `scheme` -(Only if `type` is http) The name of the HTTP Authorization scheme to be used in -the -[Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). +(Only if `type` is http) The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). Allowed values: (`basic` and `bearer`). @@ -241,20 +215,9 @@ Allowed values: (`basic` and `bearer`). ### 4.4. `security` -(Required) An object containing all security schemes required by an API call. -Applies to all operations. A security scheme can contain information required by -the API to authenticate Airnode as well as information about the requester -(relay information) the API may also require. Read more about security schemes -in the [API Security](/reference/airnode/latest/understand/api-security.md) -section of the _Build an Airnode_ guide and the -[Airnode Authentication](/reference/airnode/latest/concepts/airnode-auth.md) -section of _Concepts and Definitions_. - -The `security` object maintains the names of all the security schemes used. Each -security scheme in `security` maps to an empty list. The empty list will be used -by future versions of Airnode for individual endpoint authentication. The -`components.securitySchemes.{name}` object defines the security schemes. Unlike -OAS `security` is an object, not an array. +(Required) An object containing all security schemes required by an API call. Applies to all operations. A security scheme can contain information required by the API to authenticate Airnode as well as information about the requester (relay information) the API may also require. Read more about security schemes in the [API Security](/reference/airnode/latest/understand/api-security.md) section of the _Build an Airnode_ guide and the [Airnode Authentication](/reference/airnode/latest/concepts/airnode-auth.md) section of _Concepts and Definitions_. + +The `security` object maintains the names of all the security schemes used. Each security scheme in `security` maps to an empty list. The empty list will be used by future versions of Airnode for individual endpoint authentication. The `components.securitySchemes.{name}` object defines the security schemes. Unlike OAS `security` is an object, not an array. ```json // OIS object @@ -273,8 +236,7 @@ OAS `security` is an object, not an array. } ``` -The `apiCredential` object (which is not part of the OIS object) holds -credentials needed by the security scheme if any. +The `apiCredential` object (which is not part of the OIS object) holds credentials needed by the security scheme if any. ```json // config.json root object. @@ -292,46 +254,32 @@ credentials needed by the security scheme if any. ::: warning Please note: -Currently Airnode reads the security schemes from `component.securitySchemes` -and not `security`. Using the `security` field now (in conjunction with -`component.securitySchemes`) provides for a smooth transition to future releases -of Airnode with regards to security scheme implementation. This will allow -assigning of security schemes to individual API operations. Currently security -schemes are assign to the entire API. +Currently Airnode reads the security schemes from `component.securitySchemes` and not `security`. Using the `security` field now (in conjunction with `component.securitySchemes`) provides for a smooth transition to future releases of Airnode with regards to security scheme implementation. This will allow assigning of security schemes to individual API operations. Currently security schemes are assign to the entire API. ::: ## 5. `endpoints` -(Required) A list of objects, each specifying an Airnode endpoint with the -following fields: +(Required) A list of objects, each specifying an Airnode endpoint with the following fields: ::: info Please Note -Fields denoted by \* are for documentation purposes and not used by Airnode -node. +Fields denoted by \* are for documentation purposes and not used by Airnode node. ::: - 5.1. [name](/reference/ois/latest/specification.md#_5-1-name) - 5.2. [operation](/reference/ois/latest/specification.md#_5-2-operation) -- 5.3. - [fixedOperationParameters](/reference/ois/latest/specification.md#_5-3-fixedoperationparameters) -- 5.4. - [reservedParameters](/reference/ois/latest/specification.md#_5-4-reservedparameters) +- 5.3. [fixedOperationParameters](/reference/ois/latest/specification.md#_5-3-fixedoperationparameters) +- 5.4. [reservedParameters](/reference/ois/latest/specification.md#_5-4-reservedparameters) - 5.5. [parameters](/reference/ois/latest/specification.md#_5-5-parameters) - 5.6. [summary \*](/reference/ois/latest/specification.md#_5-6-summary) - 5.7. [description \*](/reference/ois/latest/specification.md#_5-7-description) -- 5.8. - [externalDocs \*](/reference/ois/latest/specification.md#_5-8-externaldocs) -- 5.9. - [preProcessingSpecifications](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) -- 5.10. - [postProcessingSpecifications](/reference/ois/latest/specification.md#_5-10-postprocessingspecifications) -- 5.11. - [preProcessingSpecificationV2](/reference/ois/latest/specification.md#_5-11-preprocessingspecificationv2) -- 5.12. - [postProcessingSpecificationV2](/reference/ois/latest/specification.md#_5-12-postprocessingspecificationv2) +- 5.8. [externalDocs \*](/reference/ois/latest/specification.md#_5-8-externaldocs) +- 5.9. [preProcessingSpecifications](/reference/ois/latest/specification.md#_5-9-preprocessingspecifications) +- 5.10. [postProcessingSpecifications](/reference/ois/latest/specification.md#_5-10-postprocessingspecifications) +- 5.11. [preProcessingSpecificationV2](/reference/ois/latest/specification.md#_5-11-preprocessingspecificationv2) +- 5.12. [postProcessingSpecificationV2](/reference/ois/latest/specification.md#_5-12-postprocessingspecificationv2) ```json // endpoints @@ -403,18 +351,12 @@ operation.--> ### 5.2. `operation` -(Required: when calling an API) An object that refers to an API operation -defined in `apiSpecifications.paths`. The following elements must be defined: +(Required: when calling an API) An object that refers to an API operation defined in `apiSpecifications.paths`. The following elements must be defined: - `path` - `method` -The `operation` field must be omitted if the intent is _not_ to call an API but -rather return a value from the -[Pre/Post Processing](/reference/ois/latest/processing.md) capabilities of -Airnode. See -[Skip the API provider call](/reference/ois/latest/processing.md#skip-the-api-call) -for more information. +The `operation` field must be omitted if the intent is _not_ to call an API but rather return a value from the [Pre/Post Processing](/reference/ois/latest/processing.md) capabilities of Airnode. See [Skip the API provider call](/reference/ois/latest/processing.md#skip-the-api-call) for more information. #### 5.2.1. `path` @@ -434,18 +376,14 @@ respective API operation.--> ### 5.3. `fixedOperationParameters` -(Required) A list of objects specifying the fixed parameters for an API -operation. While required, the -[fixedOperationParameters](/reference/airnode/latest/understand/api-integration.md#fixedoperationparameters) -array can be left empty. Each object has the following elements: +(Required) A list of objects specifying the fixed parameters for an API operation. While required, the [fixedOperationParameters](/reference/airnode/latest/understand/api-integration.md#fixedoperationparameters) array can be left empty. Each object has the following elements: - `operationParameter` - `value` #### 5.3.1. `operationParameter` -(Required) An object that refers to a parameter of an API operation with the -following elements: +(Required) An object that refers to a parameter of an API operation with the following elements: - `name` - `in` @@ -460,54 +398,35 @@ following elements: #### 5.3.2. `value` -(Required) The value to be used for the respective parameter of an API operation -that cannot be overridden by the requester. This is allowed to be any type, -including an object; for example, the following specifies an array containing -multiple primitives: `["finalized", false]`. +(Required) The value to be used for the respective parameter of an API operation that cannot be overridden by the requester. This is allowed to be any type, including an object; for example, the following specifies an array containing multiple primitives: `["finalized", false]`. ### 5.4. `reservedParameters` -A list of objects that specify reserved Airnode endpoint parameters that do not -map to any API operation parameters, but are used for special purposes by the -Airnode. See the -[Reserved Parameters](/reference/ois/latest/reserved-parameters.md) doc for an -in-depth explanation and -[reservedParameters](/reference/airnode/latest/understand/api-integration.md#reservedparameters). -Each object has the following elements: +A list of objects that specify reserved Airnode endpoint parameters that do not map to any API operation parameters, but are used for special purposes by the Airnode. See the [Reserved Parameters](/reference/ois/latest/reserved-parameters.md) doc for an in-depth explanation and [reservedParameters](/reference/airnode/latest/understand/api-integration.md#reservedparameters). Each object has the following elements: - `name` - `fixed` - `default` -Note that if a reserved parameter object does not include a `fixed` value, a -requester can, or may be expected to, supply this value as a parameter. A value -supplied by a requester overrides a `default`. See the -[\_gasPrice](/reference/ois/latest/reserved-parameters.md#gasprice) reserved -parameter description for an example. +Note that if a reserved parameter object does not include a `fixed` value, a requester can, or may be expected to, supply this value as a parameter. A value supplied by a requester overrides a `default`. See the [\_gasPrice](/reference/ois/latest/reserved-parameters.md#gasprice) reserved parameter description for an example. #### 5.4.1. `name` (Required) The name of the reserved parameter. Always starts with `_`. -Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and -`_minConfirmations`. +Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. #### 5.4.2. `fixed` -(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. -Cannot be used together with `default`. +(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. Cannot be used together with `default`. #### 5.4.3. `default` -(Optional) The default value for the reserved parameter. Used when no value is -provided by a requester. Cannot be used together with `fixed`. +(Optional) The default value for the reserved parameter. Used when no value is provided by a requester. Cannot be used together with `fixed`. ### 5.5. `parameters` -(Optional) A list of objects that specify Airnode endpoint -[parameters](/reference/airnode/latest/understand/api-integration.md#parameters) -that map to an particular API operation's parameters. Each object has the -following elements: +(Optional) A list of objects that specify Airnode endpoint [parameters](/reference/airnode/latest/understand/api-integration.md#parameters) that map to an particular API operation's parameters. Each object has the following elements: - `operationParameter` - `name` @@ -518,9 +437,7 @@ following elements: #### 5.5.1. `operationParameter` -(Optional) An object that refers to a parameter of an API operation and has the -below elements. Note that if omitted, the `parameter` will not be included as -part of the request to the API endpoint. +(Optional) An object that refers to a parameter of an API operation and has the below elements. Note that if omitted, the `parameter` will not be included as part of the request to the API endpoint. - `name` - `in` @@ -535,16 +452,14 @@ part of the request to the API endpoint. #### 5.5.2. `name` -(Required) The name of the Airnode endpoint parameter. Is not allowed to start -with `_`. +(Required) The name of the Airnode endpoint parameter. Is not allowed to start with `_`. #### 5.5.3. `default` -(Optional) The default value for the Airnode endpoint parameter. Used when no -value is provided. +(Optional) The default value for the Airnode endpoint parameter. Used when no value is provided. @@ -592,17 +507,13 @@ corresponding operation parameter.--> ::: warning Deprecation -The `preProcessingSpecifications` field is deprecated. Use -`preProcessingSpecificationV2` instead. +The `preProcessingSpecifications` field is deprecated. Use `preProcessingSpecificationV2` instead. ::: -(Optional) Defines the pre-processing code that can be used to modify the -endpoint parameters before making the API request defined by an Airnode -endpoint. +(Optional) Defines the pre-processing code that can be used to modify the endpoint parameters before making the API request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for additional details. #### Example @@ -631,16 +542,13 @@ additional details. ::: warning Deprecation -The `postProcessingSpecifications` field is deprecated. Use -`postProcessingSpecificationV2` instead. +The `postProcessingSpecifications` field is deprecated. Use `postProcessingSpecificationV2` instead. ::: -(Optional) Defines the post-processing code that can be used to modify the API -response from the request defined by an Airnode endpoint. +(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for additional details. #### Example @@ -659,12 +567,9 @@ additional details. ### 5.11. `preProcessingSpecificationV2` \* -(Optional) Defines the pre-processing code that can be used to modify the -endpoint parameters before making the API request defined by an Airnode -endpoint. +(Optional) Defines the pre-processing code that can be used to modify the endpoint parameters before making the API request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for additional details. #### Example @@ -681,11 +586,9 @@ additional details. ### 5.12. `postProcessingSpecificationV2` \* -(Optional) Defines the post-processing code that can be used to modify the API -response from the request defined by an Airnode endpoint. +(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/latest/processing.md) doc for additional details. #### Example diff --git a/docs/reference/ois/latest/template.md b/docs/reference/ois/latest/template.md index 7f42d2aa..6744e419 100644 --- a/docs/reference/ois/latest/template.md +++ b/docs/reference/ois/latest/template.md @@ -19,19 +19,11 @@ tags: # {{$frontmatter.title}} -An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's -`config.json` file. +An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's `config.json` file. -In the OIS template, there are some fields that contain . This means -that the value you will be replacing this with is independent from the other -fields. On the other hand, if two fields contain the same expression (e.g., -``), you must use the same value in them, -because they are referencing each other. +In the OIS template, there are some fields that contain . This means that the value you will be replacing this with is independent from the other fields. On the other hand, if two fields contain the same expression (e.g., ``), you must use the same value in them, because they are referencing each other. -The file below is a basic template for OIS. Note, that it might look differently -for your particular use case. You can also check out the OISes created for the -examples in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations). +The file below is a basic template for OIS. Note, that it might look differently for your particular use case. You can also check out the OISes created for the examples in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations). ```json { diff --git a/docs/reference/ois/latest/versions.md b/docs/reference/ois/latest/versions.md index 09b600ed..c71ee983 100644 --- a/docs/reference/ois/latest/versions.md +++ b/docs/reference/ois/latest/versions.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Be sure to use the correct OIS version for the Airnode version you are -deploying. +Be sure to use the correct OIS version for the Airnode version you are deploying. | Airnode version | Latest compatible OIS version | | ------------------- | -------------------------------------------- | @@ -35,10 +34,8 @@ deploying. | 0.8.x | [1.1.2](https://old-docs.api3.org/ois/v1.1/) | | 0.2.x through 0.7.x | [1.0.0](https://old-docs.api3.org/ois/v1.0/) | -Documentation for versions `v1.0.0` through `v1.4.0` are available on the -[legacy documentation site](https://old-docs.api3.org). +Documentation for versions `v1.0.0` through `v1.4.0` are available on the [legacy documentation site](https://old-docs.api3.org). -See GitHub [releases](https://github.com/api3dao/ois/releases) for more -information about the changes in each version. +See GitHub [releases](https://github.com/api3dao/ois/releases) for more information about the changes in each version. diff --git a/docs/reference/ois/next/index.md b/docs/reference/ois/next/index.md index 41d292aa..7bb522b7 100644 --- a/docs/reference/ois/next/index.md +++ b/docs/reference/ois/next/index.md @@ -19,10 +19,7 @@ tags: # {{$frontmatter.title}} -OIS (or Oracle Integration Specifications) is a JSON object that describes an -API specification and defines Airnode endpoints linked to API operations (a.k.a. -endpoints). It is one of five root level objects in a `config.json` file that -defines an Airnode. +OIS (or Oracle Integration Specifications) is a JSON object that describes an API specification and defines Airnode endpoints linked to API operations (a.k.a. endpoints). It is one of five root level objects in a `config.json` file that defines an Airnode. - chains - nodeSettings @@ -30,14 +27,9 @@ defines an Airnode. - ois - apiCredentials -For more information about the config.json file see the -[Deployment Files](/reference/airnode/next/deployment-files/config-json.md) -section in the Airnode document set. +For more information about the config.json file see the [Deployment Files](/reference/airnode/next/deployment-files/config-json.md) section in the Airnode document set. -In the diagram below, an Airnode exposes its endpoints to the on-chain -AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to -an API operation. It should be noted that Airnode can have more than one -endpoint that maps to the same API operation. +In the diagram below, an Airnode exposes its endpoints to the on-chain AirnodeRrpV0.sol contract. Airnode uses the OIS object to map its endpoints to an API operation. It should be noted that Airnode can have more than one endpoint that maps to the same API operation. > > @@ -47,18 +39,11 @@ endpoint that maps to the same API operation. ## API Mapping Examples -The following are three possible Airnode to API operation mapping examples. -Mapping details are better documented in the next doc -[Specification](/reference/ois/next/specification.md). +The following are three possible Airnode to API operation mapping examples. Mapping details are better documented in the next doc [Specification](/reference/ois/next/specification.md). ### Simple Airnode Endpoint -An API has a simple operation the returns the current value of an on-chain token -`GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint -will only mimic the API operation. To do so, the Airnode will declare its -endpoint to have one parameter, `id`. Airnode will accept an `id` argument from -an on-chain request and move its value to the API operation's path parameter -named `id`. +An API has a simple operation the returns the current value of an on-chain token `GET /token/{id}` and has `id` as its only parameter. Here the Airnode endpoint will only mimic the API operation. To do so, the Airnode will declare its endpoint to have one parameter, `id`. Airnode will accept an `id` argument from an on-chain request and move its value to the API operation's path parameter named `id`. ```json // ois.apiSpecifications (API operations) @@ -97,25 +82,11 @@ named `id`. ### Fixed Operation Parameters Airnode Endpoint -An API may have an operation that returns a crypto coin in either a summary or -detail form. The API operation has two parameters, `coinId` in the path and -`includeDetails` in the query. The Airnode (by design) will not allow the -details of the coin to be returned, only the summary. Therefore the Airnode will -require a requester to pass a `coinId` but will ignore the `includeDetails` -parameter if passed. The Airnode will always set the `includeDetails` query -parameter to false regardless of what a requester sends when it calls the API -operation. It does so using a `fixedOperationParameters` when calling the API -operation. +An API may have an operation that returns a crypto coin in either a summary or detail form. The API operation has two parameters, `coinId` in the path and `includeDetails` in the query. The Airnode (by design) will not allow the details of the coin to be returned, only the summary. Therefore the Airnode will require a requester to pass a `coinId` but will ignore the `includeDetails` parameter if passed. The Airnode will always set the `includeDetails` query parameter to false regardless of what a requester sends when it calls the API operation. It does so using a `fixedOperationParameters` when calling the API operation. ### Two Airnode Endpoints - One API Operation -An Airnode may wish to create two Airnode endpoints mapped to a single API -operation whereas the requester does not pass any argument. While the API -operation returns any token value based on a path parameter `id`, Airnode will -only allow one particular token per Airnode endpoint. This is done using -`fixedOperationParameters` rather than normal `parameters`. By applying a -`value` to `fixedOperationParameters` for each Airnode endpoint, only the token -in the `value` can be returned to the requester. +An Airnode may wish to create two Airnode endpoints mapped to a single API operation whereas the requester does not pass any argument. While the API operation returns any token value based on a path parameter `id`, Airnode will only allow one particular token per Airnode endpoint. This is done using `fixedOperationParameters` rather than normal `parameters`. By applying a `value` to `fixedOperationParameters` for each Airnode endpoint, only the token in the `value` can be returned to the requester. ```json "endpoints": [ diff --git a/docs/reference/ois/next/processing.md b/docs/reference/ois/next/processing.md index 2660455c..6ab3106c 100644 --- a/docs/reference/ois/next/processing.md +++ b/docs/reference/ois/next/processing.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Processing allows Airnode operators to define custom logic that executes before -or after an API call. This feature is useful for multiple use cases, including: +Processing allows Airnode operators to define custom logic that executes before or after an API call. This feature is useful for multiple use cases, including: - Authentication - Data transformation @@ -30,152 +29,85 @@ or after an API call. This feature is useful for multiple use cases, including: ## Processing versions -OIS specification has two versions of pre/post processing. Both versions serve -the same use cases, but the second version is more flexible and convenient. -Users are encouraged to use the second version. +OIS specification has two versions of pre/post processing. Both versions serve the same use cases, but the second version is more flexible and convenient. Users are encouraged to use the second version. ### v1 -The processing schema accepts an array of processing snippets (user defined -code) which are chained. The first snippet receives parameters submitted as part -of a template or on-chain request. The output of this snippet is passed to the -second snippet and so on. +The processing schema accepts an array of processing snippets (user defined code) which are chained. The first snippet receives parameters submitted as part of a template or on-chain request. The output of this snippet is passed to the second snippet and so on. -Airnode executes snippets for `preProcessingSpecifications` and -`postProcessingSpecifications` during its run cycle. The following describes the -work flow Airnode uses: +Airnode executes snippets for `preProcessingSpecifications` and `postProcessingSpecifications` during its run cycle. The following describes the work flow Airnode uses: 1. Run `preProcessingSpecifications` 2. Airnode calls requested OIS endpoint (unless the API call is skipped) 3. Run `postProcessingSpecifications` 4. Airnode encodes the response values defined by `reservedParameters` -The processing schema is the same for both -[`preProcessingSpecifications`](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) -and -[`postProcessingSpecifications`](/reference/ois/next/specification.md#_5-10-postprocessingspecifications). -Snippets for both specifications follow this schema: - -- `environment` - Currently one of `Node` or `Node async`. Both options - interpret the code as JavaScript and execute in Node.js. The async version can - use asynchronous code. The code snippet is expected to call `resolve(output)` - with the output value as an argument. Airnode will use the resolved value as - the input to subsequent snippets (if defined). +The processing schema is the same for both [`preProcessingSpecifications`](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) and [`postProcessingSpecifications`](/reference/ois/next/specification.md#_5-10-postprocessingspecifications). Snippets for both specifications follow this schema: + +- `environment` - Currently one of `Node` or `Node async`. Both options interpret the code as JavaScript and execute in Node.js. The async version can use asynchronous code. The code snippet is expected to call `resolve(output)` with the output value as an argument. Airnode will use the resolved value as the input to subsequent snippets (if defined). - `value` - The processing code written as a string. -- `timeoutMs` - The maximum duration that this snippet can run. In case the - timeout is exceeded an error is thrown. +- `timeoutMs` - The maximum duration that this snippet can run. In case the timeout is exceeded an error is thrown. -Try the [Post processing](/guides/airnode/post-processing/) guide to further -understand pre/post processing. +Try the [Post processing](/guides/airnode/post-processing/) guide to further understand pre/post processing. #### Input and Output -The processing snippet receives an `input` value which is either the initial -value or the output value from the previous processing snippet. The snippet must -create a variable `output` which will be used for the next processing snippet. -The processing snippet can use most Node.js built-in modules. Refer to the -source code of Airnode to understand how processing works and what modules are -made available to the snippet code. Modules cannot be imported directly in cloud -environments. +The processing snippet receives an `input` value which is either the initial value or the output value from the previous processing snippet. The snippet must create a variable `output` which will be used for the next processing snippet. The processing snippet can use most Node.js built-in modules. Refer to the source code of Airnode to understand how processing works and what modules are made available to the snippet code. Modules cannot be imported directly in cloud environments. #### Accessing endpoint parameters -Endpoint parameters, with the exception of reserved parameters, are accessible -within pre-processing and post-processing via the immutable `endpointParameters` -object. For example, if there was a parameter named `myParameter` defined in the -`endpoints[n].parameters` array, its value could be accessed using -`endpointParameters.myParameter` within pre-processing and post-processing code -snippets. +Endpoint parameters, with the exception of reserved parameters, are accessible within pre-processing and post-processing via the immutable `endpointParameters` object. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing and post-processing code snippets. ::: info Accessing reserved parameters -Note that reserved parameters are inaccessible in both pre-processing and -post-processing. +Note that reserved parameters are inaccessible in both pre-processing and post-processing. ::: ### v2 -The processing snippet receives parameters submitted as part of a template or -on-chain request. +The processing snippet receives parameters submitted as part of a template or on-chain request. -Airnode executes snippets for `preProcessingSpecificationV2` and -`postProcessingSpecificationV2` during its run cycle. The following describes -the work flow Airnode uses: +Airnode executes snippets for `preProcessingSpecificationV2` and `postProcessingSpecificationV2` during its run cycle. The following describes the work flow Airnode uses: 1. Run `preProcessingSpecificationV2` 2. Airnode calls requested OIS endpoint (unless the API call is skipped) 3. Run `postProcessingSpecificationV2` 4. Airnode encodes the response values defined by `reservedParameters` -The processing schema is the same for both -[`preProcessingSpecificationV2`](/reference/ois/next/specification.md#_5-11-preprocessingspecificationv2) -and -[`postProcessingSpecificationV2`](/reference/ois/next/specification.md#_5-12-postprocessingspecificationv2). -Snippets for both specifications follow this schema: +The processing schema is the same for both [`preProcessingSpecificationV2`](/reference/ois/next/specification.md#_5-11-preprocessingspecificationv2) and [`postProcessingSpecificationV2`](/reference/ois/next/specification.md#_5-12-postprocessingspecificationv2). Snippets for both specifications follow this schema: -- `environment` - Currently only possible value is `Node`. This options - interprets the code as JavaScript and executes it in Node.js. The function can - be also asynchronous (async/await is supported as well). The processing - implementation will wait for the function to resolve. +- `environment` - Currently only possible value is `Node`. This options interprets the code as JavaScript and executes it in Node.js. The function can be also asynchronous (async/await is supported as well). The processing implementation will wait for the function to resolve. - `value` - The processing code written as a string. -- `timeoutMs` - The maximum duration that this snippet can run. In case the - timeout is exceeded an error is thrown. +- `timeoutMs` - The maximum duration that this snippet can run. In case the timeout is exceeded an error is thrown. -Try the [Post processing](/guides/airnode/post-processing/) guide to further -understand pre/post processing. +Try the [Post processing](/guides/airnode/post-processing/) guide to further understand pre/post processing. #### Input and Output -The processing snippet expects a function that takes an object as an argument, -the properties of which are different for pre-processing and post-processing. -The return value of the function is treated as a processing result. Within the -snippet, you can use most Node.js built-in modules. +The processing snippet expects a function that takes an object as an argument, the properties of which are different for pre-processing and post-processing. The return value of the function is treated as a processing result. Within the snippet, you can use most Node.js built-in modules. The pre-processing argument object contains the following property: -- `endpointParameters` - The endpoint parameters with the exception of reserved - parameters. For example, if there was a parameter named `myParameter` defined - in the `endpoints[n].parameters` array, its value could be accessed using - `endpointParameters.myParameter` within pre-processing snippet. +- `endpointParameters` - The endpoint parameters with the exception of reserved parameters. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing snippet. -The output of the pre-processing snippet is an object with the following -property: +The output of the pre-processing snippet is an object with the following property: -- `endpointParameters` - The pre-processed endpoint parameters parameters. These - are used to make the API call. +- `endpointParameters` - The pre-processed endpoint parameters parameters. These are used to make the API call. The post-processing argument object contains the following properties: -- `response` - The response of the underlying data provider API call. In case of - Airnode skipping the API call, the `response` contains the output of - pre-processing snippet. -- `endpointParameters` - The raw (not pre-processed) endpoint parameters with - the exception of reserved parameters. For example, if there was a parameter - named `myParameter` defined in the `endpoints[n].parameters` array, its value - could be accessed using `endpointParameters.myParameter` within pre-processing - snippet. - -The output of the post-processing snippet is an object with the following -properties: - -- `response` - The post-processed API call response (or post-processed result of - pre-processing snippet in case of skipping an API call). This is used to - encode the response values defined by reserved parameters. -- `timestamp` - (Optional) The timestamp of the API call response. Use this if - you want Airnode to use a specific timestamp (instead of a current time at - request processing) when using the - [signed data gateway](/reference/airnode/next/understand/http-gateways.md#http-signed-data-gateway). - See the example below for more details. +- `response` - The response of the underlying data provider API call. In case of Airnode skipping the API call, the `response` contains the output of pre-processing snippet. +- `endpointParameters` - The raw (not pre-processed) endpoint parameters with the exception of reserved parameters. For example, if there was a parameter named `myParameter` defined in the `endpoints[n].parameters` array, its value could be accessed using `endpointParameters.myParameter` within pre-processing snippet. + +The output of the post-processing snippet is an object with the following properties: + +- `response` - The post-processed API call response (or post-processed result of pre-processing snippet in case of skipping an API call). This is used to encode the response values defined by reserved parameters. +- `timestamp` - (Optional) The timestamp of the API call response. Use this if you want Airnode to use a specific timestamp (instead of a current time at request processing) when using the [signed data gateway](/reference/airnode/next/understand/http-gateways.md#http-signed-data-gateway). See the example below for more details. #### Timestamp example -One of the possible use cases for post-processing v2 would be to use override -the timestamp used by -[signed data gateway](/reference/airnode/next/understand/http-gateways.md#http-signed-data-gateway). -By default the signed data gateway uses the timestamp of the request processing. -However, sometimes the API itself returns the timestamp. Modifying timestamp is -only supported with the v2 of the processing. +One of the possible use cases for post-processing v2 would be to use override the timestamp used by [signed data gateway](/reference/airnode/next/understand/http-gateways.md#http-signed-data-gateway). By default the signed data gateway uses the timestamp of the request processing. However, sometimes the API itself returns the timestamp. Modifying timestamp is only supported with the v2 of the processing. ```json { @@ -190,13 +122,9 @@ only supported with the v2 of the processing. ## Interpolation -Note, that config.json supports interpolation of secrets via the JavaScript -string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with -the string interpolation inside the processing snippets. In order to use the -interpolation in snippets, you need to escape the interpolation. +Note, that config.json supports interpolation of secrets via the JavaScript string interpolation pattern (e.g `${SECRET_NAME}`). This syntax conflicts with the string interpolation inside the processing snippets. In order to use the interpolation in snippets, you need to escape the interpolation. -For example, the following code (using the v1 processing snippet, but the -concept is the same for v2): +For example, the following code (using the v1 processing snippet, but the concept is the same for v2): ```js console.log(`Received input ${input}`); @@ -215,57 +143,25 @@ should be escaped inside the `config.json` like this: ## Error Handling and Security -Processing code is expected to be trustworthy as it is specified by the Airnode -operator. Processing is an advanced feature that carries great security risks. -It is therefore advised that developers using the processing feature familiarize -themselves with the Airnode sources prior to developing any processing code -snippets. +Processing code is expected to be trustworthy as it is specified by the Airnode operator. Processing is an advanced feature that carries great security risks. It is therefore advised that developers using the processing feature familiarize themselves with the Airnode sources prior to developing any processing code snippets. -Processing code executes in a constrained execution environment resembling -Node.js. Some resources may not be available, for example the `require` -statement. Therefore code should be tested thoroughly in the target environment -(e.g. Lambda and/or Docker client). For example, authentication implemented in -pre-processing should always be executed at the end of the respective processing -chain and special care should be taken to avoid leakage of secrets. +Processing code executes in a constrained execution environment resembling Node.js. Some resources may not be available, for example the `require` statement. Therefore code should be tested thoroughly in the target environment (e.g. Lambda and/or Docker client). For example, authentication implemented in pre-processing should always be executed at the end of the respective processing chain and special care should be taken to avoid leakage of secrets. ## Skip the API call -Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on -either (or both) pre-processing or post-processing to acquire a value for the -Airnode to place on-chain. +Not all Airnode endpoints need to call an API. An Airnode endpoint can rely on either (or both) pre-processing or post-processing to acquire a value for the Airnode to place on-chain. -Instead of calling an API, Airnode uses the output of -`preProcessingSpecifications`, `postProcessingSpecifications`, or both. The -field `operation` must be undefined, `fixedOperationParameters` must be an empty -array and some processing specification needs to be defined. This means that one -of `preProcessingSpecifications` or `postProcessingSpecifications` must be -defined and not be an empty array or `preProcessingSpecificationV2` or -`postProcessingSpecificationV2` must be defined. +Instead of calling an API, Airnode uses the output of `preProcessingSpecifications`, `postProcessingSpecifications`, or both. The field `operation` must be undefined, `fixedOperationParameters` must be an empty array and some processing specification needs to be defined. This means that one of `preProcessingSpecifications` or `postProcessingSpecifications` must be defined and not be an empty array or `preProcessingSpecificationV2` or `postProcessingSpecificationV2` must be defined. ### Random number example -An Airnode endpoint that places a random number on-chain. Rather than calling an -API, the Airnode will derive a random number during its execution of a -pre-processing v1 specification. A requester would make a request of this -Airnode endpoint without parameters. The Airnode endpoint simply sets the random -number on-chain in response to the request using a `preProcessingSpecifications` -specification. Example #1 below implements this use case. - -This example creates an Airnode endpoint named `generateRandomNumber` with no -parameters. Because there isn't an -[operation field](/reference/ois/next/specification.md#_5-2-operation) defined -for this Airnode endpoint, a call to an API will not be made. The Airnode will -instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) -array. - -To implement the use case mentioned above, the -[operation field](/reference/ois/next/specification.md#_5-2-operation) will be -undefined, `fixedOperationParameters` will be an empty array, and -`preProcessingSpecifications` will be defined with a single specification. - -- A requester makes a request of the Airnode endpoint `generateRandomNumber` - without any parameters. +An Airnode endpoint that places a random number on-chain. Rather than calling an API, the Airnode will derive a random number during its execution of a pre-processing v1 specification. A requester would make a request of this Airnode endpoint without parameters. The Airnode endpoint simply sets the random number on-chain in response to the request using a `preProcessingSpecifications` specification. Example #1 below implements this use case. + +This example creates an Airnode endpoint named `generateRandomNumber` with no parameters. Because there isn't an [operation field](/reference/ois/next/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) array. + +To implement the use case mentioned above, the [operation field](/reference/ois/next/specification.md#_5-2-operation) will be undefined, `fixedOperationParameters` will be an empty array, and `preProcessingSpecifications` will be defined with a single specification. + +- A requester makes a request of the Airnode endpoint `generateRandomNumber` without any parameters. - Airnode runs the specification in `preProcessingSpecifications[0]`. - The specification generates a random number. - The reserved parameter named `randomNumber` now holds the random number. @@ -303,14 +199,7 @@ endpoints: [ ### Parameter processing example -The code below is unrelated to the above example. Instead, this example creates -an Airnode endpoint named `endpointThatSumsWith1000` with a parameter named -`numberToSum`. Because there isn't an -[operation field](/reference/ois/next/specification.md#_5-2-operation) defined -for this Airnode endpoint, a call to an API will not be made. The Airnode will -instead execute a single specification defined in the -[preProcessingSpecifications](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) -array. +The code below is unrelated to the above example. Instead, this example creates an Airnode endpoint named `endpointThatSumsWith1000` with a parameter named `numberToSum`. Because there isn't an [operation field](/reference/ois/next/specification.md#_5-2-operation) defined for this Airnode endpoint, a call to an API will not be made. The Airnode will instead execute a single specification defined in the [preProcessingSpecifications](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) array. - A requester passes the number `5` in the parameter named `numberToSum`. - Airnode runs the specification in `preProcessingSpecifications[0]`. diff --git a/docs/reference/ois/next/reserved-parameters.md b/docs/reference/ois/next/reserved-parameters.md index 49a6394a..1ea0fe44 100644 --- a/docs/reference/ois/next/reserved-parameters.md +++ b/docs/reference/ois/next/reserved-parameters.md @@ -19,63 +19,36 @@ tags: # {{$frontmatter.title}} -Reserved parameters are part of an OIS object as part of the `endpoints` field -(Airnode endpoints) and warrant a more in-depth explanation. They are part of an -Airnode's defined endpoints in an OIS object but do not map to operation -parameters (API parameters). They are used by Airnode for special purposes. - -A requester can pass request parameters either by referencing a -[template](/reference/airnode/next/concepts/template.md) that contains them, or -as an argument of the request-making methods of -[AirnodeRrpV0.sol](/reference/airnode/next/concepts/#airnoderrpv0-sol). In -either case, these parameters are encoded using the -[AirnodeRrpV0 ABI](/reference/airnode/next/specifications/airnode-abi.md). There -are two types of parameters which are part of the OIS object: - -1. [Endpoint parameters](/reference/ois/next/specification.md#_5-5-parameters) - - Airnode endpoint parameters are mapped to API operation parameters. -2. [Reserved parameters](/reference/ois/next/specification.md#_5-4-reservedparameters) - - Reserved parameters perform a specific operation related to the request or on - the response before fulfilling the request. Reserved parameter names start - with `_`. Depending on the configuration, they may be overridden by a - parameter supplied by a requester. +Reserved parameters are part of an OIS object as part of the `endpoints` field (Airnode endpoints) and warrant a more in-depth explanation. They are part of an Airnode's defined endpoints in an OIS object but do not map to operation parameters (API parameters). They are used by Airnode for special purposes. + +A requester can pass request parameters either by referencing a [template](/reference/airnode/next/concepts/template.md) that contains them, or as an argument of the request-making methods of [AirnodeRrpV0.sol](/reference/airnode/next/concepts/#airnoderrpv0-sol). In either case, these parameters are encoded using the [AirnodeRrpV0 ABI](/reference/airnode/next/specifications/airnode-abi.md). There are two types of parameters which are part of the OIS object: + +1. [Endpoint parameters](/reference/ois/next/specification.md#_5-5-parameters) - Airnode endpoint parameters are mapped to API operation parameters. +2. [Reserved parameters](/reference/ois/next/specification.md#_5-4-reservedparameters) - Reserved parameters perform a specific operation related to the request or on the response before fulfilling the request. Reserved parameter names start with `_`. Depending on the configuration, they may be overridden by a parameter supplied by a requester. ## `_type` -Signifies what Solidity type the API response will be encoded to before -fulfillment. +Signifies what Solidity type the API response will be encoded to before fulfillment. -Support is provided for most common -[Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), -but the following are not supported. +Support is provided for most common [Solidity types](https://docs.soliditylang.org/en/latest/abi-spec.html#types), but the following are not supported. - Custom bits integer types - e.g. `uint32` or `uint8` - Fixed point decimal numbers - e.g. `fixed128x18` or `ufixed128x18` - Custom fixed size bytes - e.g. `bytes4` - Tuples - e.g. `(int256, string)` -On top of supported solidity types, there is support for a few "artificial" -types created for special purposes that would otherwise be hard or impossible to -represent. +On top of supported solidity types, there is support for a few "artificial" types created for special purposes that would otherwise be hard or impossible to represent. - [`string32`](/reference/ois/next/reserved-parameters.md#string32-encoded-to-bytes32-on-chain) - [`timestamp`](/reference/ois/next/reserved-parameters.md#timestamp-encoded-to-uint256-on-chain) -You can also encode multiple values for one single API call - but this impacts -all of the reserved parameters and is explained in the -[Encoding Multiple Values](/reference/ois/next/reserved-parameters.md#encoding-multiple-values) -section below. +You can also encode multiple values for one single API call - but this impacts all of the reserved parameters and is explained in the [Encoding Multiple Values](/reference/ois/next/reserved-parameters.md#encoding-multiple-values) section below. ### Conversion and encoding behavior -Before the API response value is encoded for on chain use, it is parsed and -converted. The conversion behaviors for any given type is explained in depth in -the -[adapter package docs](/reference/airnode/next/packages/adapter.md#conversion). +Before the API response value is encoded for on chain use, it is parsed and converted. The conversion behaviors for any given type is explained in depth in the [adapter package docs](/reference/airnode/next/packages/adapter.md#conversion). -The converted value is then encoded internally by -[ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) -using the following +The converted value is then encoded internally by [ethers ABI Coder](https://docs.ethers.io/v5/api/utils/abi/coder/#AbiCoder) using the following ```js ethers.utils.defaultAbiCoder.encode([solidityType], [value]); @@ -93,54 +66,35 @@ ethers.utils.defaultAbiCoder.encode([solidityType], [value]); #### string32 (encoded to `bytes32` on chain) -The `string32` is an artificial type that is not supported by solidity. It is -instead encoded to `bytes32` and provides a cheaper alternative to the regular -`string` type for values with less than 32 characters. +The `string32` is an artificial type that is not supported by solidity. It is instead encoded to `bytes32` and provides a cheaper alternative to the regular `string` type for values with less than 32 characters. ::: warning Limitations -While using `string32` is more efficient, decoding the original string from -`bytes32` on chain is both difficult and expensive. Also bear in mind that this -type is able to encode only strings shorter than 32 characters. If the value is -longer, it will be trimmed and only first 31 characters will be encoded. +While using `string32` is more efficient, decoding the original string from `bytes32` on chain is both difficult and expensive. Also bear in mind that this type is able to encode only strings shorter than 32 characters. If the value is longer, it will be trimmed and only first 31 characters will be encoded. ::: #### timestamp (encoded to `uint256` on chain) -The `timestamp` is an artificial type that is not supported by solidity. It is -instead encoded to `uint256` and specifies the UNIX timestamp value at the time -when the transaction was encoded. You can use this value on chain to check the -"freshness" of the Airnode response. This might be useful in certain scenarios, -because Airnode cannot guarantee when a particular transaction will be mined on -chain. +The `timestamp` is an artificial type that is not supported by solidity. It is instead encoded to `uint256` and specifies the UNIX timestamp value at the time when the transaction was encoded. You can use this value on chain to check the "freshness" of the Airnode response. This might be useful in certain scenarios, because Airnode cannot guarantee when a particular transaction will be mined on chain. -When using the `timestamp` type, the corresponding `_path` and `_times` -variables must be empty strings or not provided. +When using the `timestamp` type, the corresponding `_path` and `_times` variables must be empty strings or not provided. #### Arrays -Apart from the primitives defined above as well as all "artificial" types we -created, you are free to use arrays with any of the above. Multidimensional -arrays are supported as well. Solidity allows you to define fixed size arrays, -which are more gas efficient to encode and you can use those as well. +Apart from the primitives defined above as well as all "artificial" types we created, you are free to use arrays with any of the above. Multidimensional arrays are supported as well. Solidity allows you to define fixed size arrays, which are more gas efficient to encode and you can use those as well. For example - `int256[]` - regular integer array - `uint256[8]` - unsigned integer array with 8 elements - `int256[][]` - 2 dimensional integer array -- `string32[]` - is an array of `string32` values, which will be encoded to - `bytes32[]` on chain -- `string[2][][3]` - 3 dimensional string array, where first dimension contains - 3 elements, second unboundedly many and last dimension only 2. Note that this - [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) - compared to C-style languages +- `string32[]` - is an array of `string32` values, which will be encoded to `bytes32[]` on chain +- `string[2][][3]` - 3 dimensional string array, where first dimension contains 3 elements, second unboundedly many and last dimension only 2. Note that this [definition is read backwards](https://ethereum.stackexchange.com/questions/64331/why-is-multidimensional-array-declaration-order-reversed) compared to C-style languages ## `_path` -Assuming that the API response will be a JSON object, defines the field to be -used to fulfill the request using dot notation. For example, if the API returns +Assuming that the API response will be a JSON object, defines the field to be used to fulfill the request using dot notation. For example, if the API returns ``` { @@ -159,15 +113,11 @@ used to fulfill the request using dot notation. For example, if the API returns and `_path` is `field1.fieldA.1`, the response will be `valueA2`. -If the response is a literal value (i.e., not a JSON object) and `_path` is not -provided or is an empty string (needed for -[encoding multiple values](/reference/ois/next/reserved-parameters.md#encoding-multiple-values)), -Airnode will use the API response itself to fulfill the request. +If the response is a literal value (i.e., not a JSON object) and `_path` is not provided or is an empty string (needed for [encoding multiple values](/reference/ois/next/reserved-parameters.md#encoding-multiple-values)), Airnode will use the API response itself to fulfill the request. ::: warning Beware the separator -Make sure the keys in the path of the API response do not contain `.`, because -it will be incorrectly considered as a separator. +Make sure the keys in the path of the API response do not contain `.`, because it will be incorrectly considered as a separator. ``` { @@ -175,18 +125,13 @@ it will be incorrectly considered as a separator. } ``` -A `_path` defined as `"strange.key"` will not work. As workaround you can -[escape the separator](/reference/ois/next/reserved-parameters.md#escaping-separators). +A `_path` defined as `"strange.key"` will not work. As workaround you can [escape the separator](/reference/ois/next/reserved-parameters.md#escaping-separators). ::: ### Escaping Separators -In rare cases, when the `_path` to the API response would contain `,` or `.` -(comma or a dot) things get a bit complicated. Those symbols have a very -specific meaning when parsing the reserved parameters and they need to be -escaped if they are to be considered as literals. If the API provider response -looks like the following: +In rare cases, when the `_path` to the API response would contain `,` or `.` (comma or a dot) things get a bit complicated. Those symbols have a very specific meaning when parsing the reserved parameters and they need to be escaped if they are to be considered as literals. If the API provider response looks like the following: ``` { @@ -198,9 +143,7 @@ Then escape the symbols, in this case `_path="very\\,strange\\.key"`. ## `_times` -If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided -Airnode multiplies the value returned by the API with the `_times` parameter -before fulfilling the request. For example, if the API returns: +If `_type` is `int256` or `uint256` and a valid `_times` parameter is provided Airnode multiplies the value returned by the API with the `_times` parameter before fulfilling the request. For example, if the API returns: ``` { @@ -217,29 +160,15 @@ _path: data _times: "100" ``` -the request will be fulfilled with the value `123`. Note that the number gets -multiplied by `100`, and then gets floored. This is because the result of the -multiplication is [cast](/reference/airnode/next/packages/adapter.md) to -`int256` afterwards. +the request will be fulfilled with the value `123`. Note that the number gets multiplied by `100`, and then gets floored. This is because the result of the multiplication is [cast](/reference/airnode/next/packages/adapter.md) to `int256` afterwards. -Make sure to pass the `_times` parameter as string. Airnode will convert this -string to number internally. You can also pass and empty string `""` to `_times` -parameter - this has the same effect as if the `_times` parameter was not -provided. However, this is important when -[encoding multiple values](/reference/ois/next/reserved-parameters.md#encoding-multiple-values). +Make sure to pass the `_times` parameter as string. Airnode will convert this string to number internally. You can also pass and empty string `""` to `_times` parameter - this has the same effect as if the `_times` parameter was not provided. However, this is important when [encoding multiple values](/reference/ois/next/reserved-parameters.md#encoding-multiple-values). -The `_times` parameter also works in conjunction with arrays and -multidimensional arrays. All elements of the API response array will be -multiplied before they are encoded. +The `_times` parameter also works in conjunction with arrays and multidimensional arrays. All elements of the API response array will be multiplied before they are encoded. ## `_gasPrice` -The `_gasPrice` reserved parameter enables a requester to override -[Airnode gas price strategies](/reference/airnode/next/concepts/gas-prices.md) -with a specified gas price when Airnode -[fulfills](/reference/airnode/next/concepts/request.md#fulfill) the request. The -recommended implementation is to have the `_gasPrice` reserved parameter without -a `default` or `fixed` value as shown in the abbreviated snippet below: +The `_gasPrice` reserved parameter enables a requester to override [Airnode gas price strategies](/reference/airnode/next/concepts/gas-prices.md) with a specified gas price when Airnode [fulfills](/reference/airnode/next/concepts/request.md#fulfill) the request. The recommended implementation is to have the `_gasPrice` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -251,10 +180,7 @@ a `default` or `fixed` value as shown in the abbreviated snippet below: } ``` -This allows requesters to specify the gas price via a parameter in their -request. The value, in `wei`, should be -[encoded](/reference/airnode/next/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the gas price via a parameter in their request. The value, in `wei`, should be [encoded](/reference/airnode/next/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; @@ -268,19 +194,11 @@ encode([ ]); ``` -Note that if a requester specifies a `_gasPrice` as a parameter in a request but -the Airnode's configuration does not include the `_gasPrice` reserved parameter, -the requester's gas price will be ignored. +Note that if a requester specifies a `_gasPrice` as a parameter in a request but the Airnode's configuration does not include the `_gasPrice` reserved parameter, the requester's gas price will be ignored. ## `_minConfirmations` -The `_minConfirmations` reserved parameter enables a requester to override the -default minimum number of block confirmations set by the Airnode for that chain -in -[config.json](/reference/airnode/next/deployment-files/config-json.md#minconfirmations). -The recommended implementation is to have the `_minConfirmations` reserved -parameter without a `default` or `fixed` value as shown in the abbreviated -snippet below: +The `_minConfirmations` reserved parameter enables a requester to override the default minimum number of block confirmations set by the Airnode for that chain in [config.json](/reference/airnode/next/deployment-files/config-json.md#minconfirmations). The recommended implementation is to have the `_minConfirmations` reserved parameter without a `default` or `fixed` value as shown in the abbreviated snippet below: ```json { @@ -292,29 +210,20 @@ snippet below: } ``` -This allows requesters to specify the minimum number of block confirmations via -a parameter in their request. The value should be -[encoded](/reference/airnode/next/packages/airnode-abi.md#encode) as a -`string32` type by the requester, for example: +This allows requesters to specify the minimum number of block confirmations via a parameter in their request. The value should be [encoded](/reference/airnode/next/packages/airnode-abi.md#encode) as a `string32` type by the requester, for example: ```ts import { encode } from '@api3/airnode-abi'; encode([{ name: '_minConfirmations', type: 'string32', value: '1' }]); ``` -In order to respond to requests in the same nonce order as they are received -when requests specify different `_minConfirmations` values, the maximum -`_minConfirmations` value of all requests in the queue for a given sponsor is -applied to all requests. +In order to respond to requests in the same nonce order as they are received when requests specify different `_minConfirmations` values, the maximum `_minConfirmations` value of all requests in the queue for a given sponsor is applied to all requests. -Note that if a requester specifies a `_minConfirmations` as a parameter in a -request but the Airnode's configuration does not include the `_minConfirmations` -reserved parameter, the requester's minimum confirmations value will be ignored. +Note that if a requester specifies a `_minConfirmations` as a parameter in a request but the Airnode's configuration does not include the `_minConfirmations` reserved parameter, the requester's minimum confirmations value will be ignored. ## Encoding Multiple Values -Solidity has support for decoding and "destructuring" multiple values. For -example: +Solidity has support for decoding and "destructuring" multiple values. For example: ```solidity function decodeMultipleParameters(bytes calldata data) @@ -326,11 +235,7 @@ function decodeMultipleParameters(bytes calldata data) } ``` -The example above demonstrates the decoding on chain of three values of types -`string`, `uint256` and `address` respectively. You can instruct Airnode to -encode these values using the `_type`, `_path`, and `_times` reserved parameters -by separating the values using `,` (comma). For example using the following -combination of reserved parameters: +The example above demonstrates the decoding on chain of three values of types `string`, `uint256` and `address` respectively. You can instruct Airnode to encode these values using the `_type`, `_path`, and `_times` reserved parameters by separating the values using `,` (comma). For example using the following combination of reserved parameters: ```js { @@ -340,10 +245,7 @@ combination of reserved parameters: } ``` -Airnode will split the reserved parameters by `,` into "split values" and ensure -they all contain the same number of them. It will extract and convert each of -the "split values". Notice, that an `""` (empty string) is used to specify that -a certain reserved parameter should not be used for a certain "split value". +Airnode will split the reserved parameters by `,` into "split values" and ensure they all contain the same number of them. It will extract and convert each of the "split values". Notice, that an `""` (empty string) is used to specify that a certain reserved parameter should not be used for a certain "split value". For example, let's say the API response looks like this: @@ -357,23 +259,15 @@ For example, let's say the API response looks like this: Airnode will extract and convert each of the "split values" separately -1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` - results in `"some string"` -2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` - results in `12345670` -3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` - results in `"0xe021...8a74"` +1. Combination of `_type="string"`, `_path="pathToString"` and `_times=""` results in `"some string"` +2. Combination of `_type="uint256"`, `_path="pathToFloat"` and `_times="10000"` results in `12345670` +3. Combination of `_type="address"`, `_path="pathToAddress"` and `_times=""` results in `"0xe021...8a74"` -All of these values are then together encoded to single bytes value that can be -sent on chain. You can use -[testing gateway](/reference/airnode/next/understand/deploying.md#testing-with-http-gateway) -to inspect the raw API response, casting results and the final encoded value. +All of these values are then together encoded to single bytes value that can be sent on chain. You can use [testing gateway](/reference/airnode/next/understand/deploying.md#testing-with-http-gateway) to inspect the raw API response, casting results and the final encoded value. ::: info Multiple Reserved Parameters Tutorial -The -[weather-multi-value](/guides/airnode/monorepo-examples.md) -monorepo example demonstrates encoding of multiple values of different types. +The [weather-multi-value](/guides/airnode/monorepo-examples.md) monorepo example demonstrates encoding of multiple values of different types. ::: diff --git a/docs/reference/ois/next/specification.md b/docs/reference/ois/next/specification.md index 0fd2c74e..61c500ac 100644 --- a/docs/reference/ois/next/specification.md +++ b/docs/reference/ois/next/specification.md @@ -19,34 +19,21 @@ tags: # {{$frontmatter.title}} -The Oracle Integration Specification (OIS) is based on -[Open API specification (OAS)](https://swagger.io/specification/), but there are -some differences, be sure to focus on the following documentation when working -on an OIS file. +The Oracle Integration Specification (OIS) is based on [Open API specification (OAS)](https://swagger.io/specification/), but there are some differences, be sure to focus on the following documentation when working on an OIS file. ::: warning OAS -It is not recommended to refer to OAS for help while creating an OIS object. OIS -only borrows formatting practices from OAS. Everything needed to create an OIS -object is in these docs. +It is not recommended to refer to OAS for help while creating an OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs. ::: -For an overview that explains how Airnode maps its endpoints to API provider -operations, see -[API integration](/reference/airnode/next/understand/api-integration.md). Also -see the medium article -[Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) -for an overview of OIS. +For an overview that explains how Airnode maps its endpoints to API provider operations, see [API integration](/reference/airnode/next/understand/api-integration.md). Also see the medium article [Setting Oracle Integration Standards](https://medium.com/api3/setting-oracle-integration-standards-ac9104c38f9e) for an overview of OIS. -- Fields denoted by (\*) are for documentation purposes and not used by an - Airnode. +- Fields denoted by (\*) are for documentation purposes and not used by an Airnode. - The OIS fields should be reviewed and customized by the integrating party. -- All URLs are absolute (i.e., - [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) - are not supported). +- All URLs are absolute (i.e., [relative URLs](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#relative-references-in-urls) are not supported). ## OIS Object Summary @@ -58,8 +45,7 @@ An OIS has five root fields (keys). 1. [apiSpecifications](/reference/ois/next/specification.md#_4-apispecifications) 1. [endpoints](/reference/ois/next/specification.md#_5-endpoints) -`apiSpecifications` describe the API's operations which are mapped to the -`endpoints` that Airnode exposes on-chain. +`apiSpecifications` describe the API's operations which are mapped to the `endpoints` that Airnode exposes on-chain. ```json { @@ -77,21 +63,17 @@ An OIS has five root fields (keys). ## 1. `oisFormat` -(Required) The OIS format version followed while generating the specifications. -See [Versions](/reference/ois/next/versions.md) for a list of OIS versions used -by each Airnode version. +(Required) The OIS format version followed while generating the specifications. See [Versions](/reference/ois/next/versions.md) for a list of OIS versions used by each Airnode version. ## 2. `title` -(Required) The OIS title. Title field is at most 64 characters, can only include -alphanumeric characters, hyphens, underscores and whitespaces. +(Required) The OIS title. Title field is at most 64 characters, can only include alphanumeric characters, hyphens, underscores and whitespaces. ## 3. `version` -(Required) A user defined version for the OIS object. Not to be confused with -the `oisFormat` version which defines an OIS formatting version. +(Required) A user defined version for the OIS object. Not to be confused with the `oisFormat` version which defines an OIS formatting version. ## 4. `apiSpecifications` @@ -139,21 +121,18 @@ the `oisFormat` version which defines an OIS formatting version. ### 4.1. `servers` -(Required) An array of objects containing the base URL of the API. Only one -object (i.e., base URL) is allowed in the array. Applies to all API operations. +(Required) An array of objects containing the base URL of the API. Only one object (i.e., base URL) is allowed in the array. Applies to all API operations. ### 4.2. `paths` -(Required) An object where an API's operations are defined by `{path}.{method}` -(i.e. `paths./myPath.get`) each with a `parameters` array. +(Required) An object where an API's operations are defined by `{path}.{method}` (i.e. `paths./myPath.get`) each with a `parameters` array. #### 4.2.1. `parameters` -(Required) A list of the API operation's parameters, each with the following -fields: +(Required) A list of the API operation's parameters, each with the following fields: - `name` - `in` @@ -177,9 +156,7 @@ the non-nested application/json content-type is supported.

### 4.3. `components` -(Required) An object where -[security schemes](/reference/airnode/next/understand/api-security.md) can be -found under `securitySchemes.{securitySchemeName}` with the following elements: +(Required) An object where [security schemes](/reference/airnode/next/understand/api-security.md) can be found under `securitySchemes.{securitySchemeName}` with the following elements: - `type` - `name` @@ -195,8 +172,7 @@ Allowed values: - Used by an API operation to authenticate Airnode. - `apiKey` - `http` -- Allows an API operation to acquire information about the requester and/or the - chain. +- Allows an API operation to acquire information about the requester and/or the chain. - `relayRequesterAddress` - `relaySponsorAddress` - `relaySponsorWalletAddress` @@ -222,9 +198,7 @@ Allowed values: `query`, `header`, `cookie` #### 4.3.4. `scheme` -(Only if `type` is http) The name of the HTTP Authorization scheme to be used in -the -[Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). +(Only if `type` is http) The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). Allowed values: (`basic` and `bearer`). @@ -241,20 +215,9 @@ Allowed values: (`basic` and `bearer`). ### 4.4. `security` -(Required) An object containing all security schemes required by an API call. -Applies to all operations. A security scheme can contain information required by -the API to authenticate Airnode as well as information about the requester -(relay information) the API may also require. Read more about security schemes -in the [API Security](/reference/airnode/next/understand/api-security.md) -section of the _Build an Airnode_ guide and the -[Airnode Authentication](/reference/airnode/next/concepts/airnode-auth.md) -section of _Concepts and Definitions_. - -The `security` object maintains the names of all the security schemes used. Each -security scheme in `security` maps to an empty list. The empty list will be used -by future versions of Airnode for individual endpoint authentication. The -`components.securitySchemes.{name}` object defines the security schemes. Unlike -OAS `security` is an object, not an array. +(Required) An object containing all security schemes required by an API call. Applies to all operations. A security scheme can contain information required by the API to authenticate Airnode as well as information about the requester (relay information) the API may also require. Read more about security schemes in the [API Security](/reference/airnode/next/understand/api-security.md) section of the _Build an Airnode_ guide and the [Airnode Authentication](/reference/airnode/next/concepts/airnode-auth.md) section of _Concepts and Definitions_. + +The `security` object maintains the names of all the security schemes used. Each security scheme in `security` maps to an empty list. The empty list will be used by future versions of Airnode for individual endpoint authentication. The `components.securitySchemes.{name}` object defines the security schemes. Unlike OAS `security` is an object, not an array. ```json // OIS object @@ -273,8 +236,7 @@ OAS `security` is an object, not an array. } ``` -The `apiCredential` object (which is not part of the OIS object) holds -credentials needed by the security scheme if any. +The `apiCredential` object (which is not part of the OIS object) holds credentials needed by the security scheme if any. ```json // config.json root object. @@ -292,45 +254,32 @@ credentials needed by the security scheme if any. ::: warning Please note: -Currently Airnode reads the security schemes from `component.securitySchemes` -and not `security`. Using the `security` field now (in conjunction with -`component.securitySchemes`) provides for a smooth transition to future releases -of Airnode with regards to security scheme implementation. This will allow -assigning of security schemes to individual API operations. Currently security -schemes are assign to the entire API. +Currently Airnode reads the security schemes from `component.securitySchemes` and not `security`. Using the `security` field now (in conjunction with `component.securitySchemes`) provides for a smooth transition to future releases of Airnode with regards to security scheme implementation. This will allow assigning of security schemes to individual API operations. Currently security schemes are assign to the entire API. ::: ## 5. `endpoints` -(Required) A list of objects, each specifying an Airnode endpoint with the -following fields: +(Required) A list of objects, each specifying an Airnode endpoint with the following fields: ::: info Please Note -Fields denoted by \* are for documentation purposes and not used by Airnode -node. +Fields denoted by \* are for documentation purposes and not used by Airnode node. ::: - 5.1. [name](/reference/ois/next/specification.md#_5-1-name) - 5.2. [operation](/reference/ois/next/specification.md#_5-2-operation) -- 5.3. - [fixedOperationParameters](/reference/ois/next/specification.md#_5-3-fixedoperationparameters) -- 5.4. - [reservedParameters](/reference/ois/next/specification.md#_5-4-reservedparameters) +- 5.3. [fixedOperationParameters](/reference/ois/next/specification.md#_5-3-fixedoperationparameters) +- 5.4. [reservedParameters](/reference/ois/next/specification.md#_5-4-reservedparameters) - 5.5. [parameters](/reference/ois/next/specification.md#_5-5-parameters) - 5.6. [summary \*](/reference/ois/next/specification.md#_5-6-summary) - 5.7. [description \*](/reference/ois/next/specification.md#_5-7-description) - 5.8. [externalDocs \*](/reference/ois/next/specification.md#_5-8-externaldocs) -- 5.9. - [preProcessingSpecifications](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) -- 5.10. - [postProcessingSpecifications](/reference/ois/next/specification.md#_5-10-postprocessingspecifications) -- 5.11. - [preProcessingSpecificationV2](/reference/ois/next/specification.md#_5-11-preprocessingspecificationv2) -- 5.12. - [postProcessingSpecificationV2](/reference/ois/next/specification.md#_5-12-postprocessingspecificationv2) +- 5.9. [preProcessingSpecifications](/reference/ois/next/specification.md#_5-9-preprocessingspecifications) +- 5.10. [postProcessingSpecifications](/reference/ois/next/specification.md#_5-10-postprocessingspecifications) +- 5.11. [preProcessingSpecificationV2](/reference/ois/next/specification.md#_5-11-preprocessingspecificationv2) +- 5.12. [postProcessingSpecificationV2](/reference/ois/next/specification.md#_5-12-postprocessingspecificationv2) ```json // endpoints @@ -402,18 +351,12 @@ operation.--> ### 5.2. `operation` -(Required: when calling an API) An object that refers to an API operation -defined in `apiSpecifications.paths`. The following elements must be defined: +(Required: when calling an API) An object that refers to an API operation defined in `apiSpecifications.paths`. The following elements must be defined: - `path` - `method` -The `operation` field must be omitted if the intent is _not_ to call an API but -rather return a value from the -[Pre/Post Processing](/reference/ois/next/processing.md) capabilities of -Airnode. See -[Skip the API provider call](/reference/ois/next/processing.md#skip-the-api-call) -for more information. +The `operation` field must be omitted if the intent is _not_ to call an API but rather return a value from the [Pre/Post Processing](/reference/ois/next/processing.md) capabilities of Airnode. See [Skip the API provider call](/reference/ois/next/processing.md#skip-the-api-call) for more information. #### 5.2.1. `path` @@ -433,18 +376,14 @@ respective API operation.--> ### 5.3. `fixedOperationParameters` -(Required) A list of objects specifying the fixed parameters for an API -operation. While required, the -[fixedOperationParameters](/reference/airnode/next/understand/api-integration.md#fixedoperationparameters) -array can be left empty. Each object has the following elements: +(Required) A list of objects specifying the fixed parameters for an API operation. While required, the [fixedOperationParameters](/reference/airnode/next/understand/api-integration.md#fixedoperationparameters) array can be left empty. Each object has the following elements: - `operationParameter` - `value` #### 5.3.1. `operationParameter` -(Required) An object that refers to a parameter of an API operation with the -following elements: +(Required) An object that refers to a parameter of an API operation with the following elements: - `name` - `in` @@ -459,54 +398,35 @@ following elements: #### 5.3.2. `value` -(Required) The value to be used for the respective parameter of an API operation -that cannot be overridden by the requester. This is allowed to be any type, -including an object; for example, the following specifies an array containing -multiple primitives: `["finalized", false]`. +(Required) The value to be used for the respective parameter of an API operation that cannot be overridden by the requester. This is allowed to be any type, including an object; for example, the following specifies an array containing multiple primitives: `["finalized", false]`. ### 5.4. `reservedParameters` -A list of objects that specify reserved Airnode endpoint parameters that do not -map to any API operation parameters, but are used for special purposes by the -Airnode. See the -[Reserved Parameters](/reference/ois/next/reserved-parameters.md) doc for an -in-depth explanation and -[reservedParameters](/reference/airnode/next/understand/api-integration.md#reservedparameters). -Each object has the following elements: +A list of objects that specify reserved Airnode endpoint parameters that do not map to any API operation parameters, but are used for special purposes by the Airnode. See the [Reserved Parameters](/reference/ois/next/reserved-parameters.md) doc for an in-depth explanation and [reservedParameters](/reference/airnode/next/understand/api-integration.md#reservedparameters). Each object has the following elements: - `name` - `fixed` - `default` -Note that if a reserved parameter object does not include a `fixed` value, a -requester can, or may be expected to, supply this value as a parameter. A value -supplied by a requester overrides a `default`. See the -[\_gasPrice](/reference/ois/next/reserved-parameters.md#gasprice) reserved -parameter description for an example. +Note that if a reserved parameter object does not include a `fixed` value, a requester can, or may be expected to, supply this value as a parameter. A value supplied by a requester overrides a `default`. See the [\_gasPrice](/reference/ois/next/reserved-parameters.md#gasprice) reserved parameter description for an example. #### 5.4.1. `name` (Required) The name of the reserved parameter. Always starts with `_`. -Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and -`_minConfirmations`. +Allowed values: `_type`, `_path`, `_times`, `_gasPrice`, and `_minConfirmations`. #### 5.4.2. `fixed` -(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. -Cannot be used together with `default`. +(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. Cannot be used together with `default`. #### 5.4.3. `default` -(Optional) The default value for the reserved parameter. Used when no value is -provided by a requester. Cannot be used together with `fixed`. +(Optional) The default value for the reserved parameter. Used when no value is provided by a requester. Cannot be used together with `fixed`. ### 5.5. `parameters` -(Optional) A list of objects that specify Airnode endpoint -[parameters](/reference/airnode/next/understand/api-integration.md#parameters) -that map to an particular API operation's parameters. Each object has the -following elements: +(Optional) A list of objects that specify Airnode endpoint [parameters](/reference/airnode/next/understand/api-integration.md#parameters) that map to an particular API operation's parameters. Each object has the following elements: - `operationParameter` - `name` @@ -517,9 +437,7 @@ following elements: #### 5.5.1. `operationParameter` -(Optional) An object that refers to a parameter of an API operation and has the -below elements. Note that if omitted, the `parameter` will not be included as -part of the request to the API endpoint. +(Optional) An object that refers to a parameter of an API operation and has the below elements. Note that if omitted, the `parameter` will not be included as part of the request to the API endpoint. - `name` - `in` @@ -534,16 +452,14 @@ part of the request to the API endpoint. #### 5.5.2. `name` -(Required) The name of the Airnode endpoint parameter. Is not allowed to start -with `_`. +(Required) The name of the Airnode endpoint parameter. Is not allowed to start with `_`. #### 5.5.3. `default` -(Optional) The default value for the Airnode endpoint parameter. Used when no -value is provided. +(Optional) The default value for the Airnode endpoint parameter. Used when no value is provided. @@ -591,17 +507,13 @@ corresponding operation parameter.--> ::: warning Deprecation -The `preProcessingSpecifications` field is deprecated. Use -`preProcessingSpecificationV2` instead. +The `preProcessingSpecifications` field is deprecated. Use `preProcessingSpecificationV2` instead. ::: -(Optional) Defines the pre-processing code that can be used to modify the -endpoint parameters before making the API request defined by an Airnode -endpoint. +(Optional) Defines the pre-processing code that can be used to modify the endpoint parameters before making the API request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for additional details. #### Example @@ -630,16 +542,13 @@ additional details. ::: warning Deprecation -The `postProcessingSpecifications` field is deprecated. Use -`postProcessingSpecificationV2` instead. +The `postProcessingSpecifications` field is deprecated. Use `postProcessingSpecificationV2` instead. ::: -(Optional) Defines the post-processing code that can be used to modify the API -response from the request defined by an Airnode endpoint. +(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for additional details. #### Example @@ -658,12 +567,9 @@ additional details. ### 5.11. `preProcessingSpecificationV2` \* -(Optional) Defines the pre-processing code that can be used to modify the -endpoint parameters before making the API request defined by an Airnode -endpoint. +(Optional) Defines the pre-processing code that can be used to modify the endpoint parameters before making the API request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for additional details. #### Example @@ -680,11 +586,9 @@ additional details. ### 5.12. `postProcessingSpecificationV2` \* -(Optional) Defines the post-processing code that can be used to modify the API -response from the request defined by an Airnode endpoint. +(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint. -See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for -additional details. +See the [Pre/Post Processing](/reference/ois/next/processing.md) doc for additional details. #### Example diff --git a/docs/reference/ois/next/template.md b/docs/reference/ois/next/template.md index 1b7f7527..4153662f 100644 --- a/docs/reference/ois/next/template.md +++ b/docs/reference/ois/next/template.md @@ -19,19 +19,11 @@ tags: # {{$frontmatter.title}} -An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's -`config.json` file. +An OIS (Oracle Integration Specifications) JSON object is part of an Airnode's `config.json` file. -In the OIS template, there are some fields that contain . This means -that the value you will be replacing this with is independent from the other -fields. On the other hand, if two fields contain the same expression (e.g., -``), you must use the same value in them, -because they are referencing each other. +In the OIS template, there are some fields that contain . This means that the value you will be replacing this with is independent from the other fields. On the other hand, if two fields contain the same expression (e.g., ``), you must use the same value in them, because they are referencing each other. -The file below is a basic template for OIS. Note, that it might look differently -for your particular use case. You can also check out the OISes created for the -examples in the -[Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations). +The file below is a basic template for OIS. Note, that it might look differently for your particular use case. You can also check out the OISes created for the examples in the [Airnode repository](https://github.com/api3dao/airnode/tree/v0.13/packages/airnode-examples/integrations). ```json { diff --git a/docs/reference/ois/next/versions.md b/docs/reference/ois/next/versions.md index d85d6601..52ce1a95 100644 --- a/docs/reference/ois/next/versions.md +++ b/docs/reference/ois/next/versions.md @@ -19,8 +19,7 @@ tags: # {{$frontmatter.title}} -Be sure to use the correct OIS version for the Airnode version you are -deploying. +Be sure to use the correct OIS version for the Airnode version you are deploying. | Airnode version | Latest compatible OIS version | | ------------------- | -------------------------------------------- | @@ -35,10 +34,8 @@ deploying. | 0.8.x | [1.1.2](https://old-docs.api3.org/ois/v1.1/) | | 0.2.x through 0.7.x | [1.0.0](https://old-docs.api3.org/ois/v1.0/) | -Documentation for versions `v1.0.0` through `v1.4.0` are available on the -[legacy documentation site](https://old-docs.api3.org). +Documentation for versions `v1.0.0` through `v1.4.0` are available on the [legacy documentation site](https://old-docs.api3.org). -See GitHub [releases](https://github.com/api3dao/ois/releases) for more -information about the changes in each version. +See GitHub [releases](https://github.com/api3dao/ois/releases) for more information about the changes in each version.