Documentation
A newer release of the API3 Technical documentation is available.
📂 Reference > Deployment Files

# config.json

Table of Contents

The config.json defines a single Airnode deployment. The file contents are a single JSON object. Each config object can be thought of as the static NoSQL database of an Airnode deployment. It contains five fields as show below.

{
  "chains": [],
  "nodeSettings": {},
  "triggers": {},
  "ois": [],
  "apiCredentials": []
}
1
2
3
4
5
6
7
  • chains: Blockchains the Airnode deployment will serve on and configuration details
  • nodeSettings: General deployment parameters such as node version and deployment configuration.
  • triggers: Which on-chain endpoints will be usable by which an available protocol (currently only RRP) and under what endpoint ID.
  • ois: API specifications and the corresponding on-chain endpoints, kept as OIS objects.
  • apiCredentials: Which API credentials will be usable by which OIS and security scheme.

# chains

Lists the blockchains the Airnode deployment will serve on and specifies respective parameters.

// chains
[
  {
    "maxConcurrency": 100,
    "authorizers": ["0xeabb...C123", "0xCE5e...1abc"],
    "contracts": {
      "AirnodeRrp": "0x12B4...0C1a"
    },
    "id": "1",
    "providers": {
      "selfHostedMainnet": {
        "url": "${CP_SELF_HOSTED_MAINNET_URL}"
      },
      "infuraMainnet": {
        "url": "${CP_INFURA_MAINNET_URL}"
      }
    },
    "type": "evm",
    "options": {
      "txType": "eip1559",
      "priorityFee": {
        "value": 3.12,
        "unit": "gwei"
      },
      "baseFeeMultiplier": 2
    },
    "blockHistoryLimit": 300,
    "minConfirmations": 0
  },
  {
    "maxConcurrency": 100,
    "authorizers": [],
    "contracts": {
      "AirnodeRrp": "0xf1d4...0bd1"
    },
    "id": "3",
    "providers": {
      "infuraRopsten": {
        "url": "${CP_INFURA_ROPSTEN_URL}"
      }
    },
    "type": "evm",
    "options": {
      "txType": "eip1559",
      "priorityFee": {
        "value": 3.12,
        "unit": "gwei"
      },
      "baseFeeMultiplier": 2
    }
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

# maxConcurrency

info (required) - The maximum concurrency specifies the maximum number of concurrent handler calls per single Airnode invocation.

# authorizers

info (required) - The list of authorizer contract addresses specifying the authorization patterns that the Airnode should use. An empty array would allow-all.

# contracts

info (required) - An object that keeps the addresses of the protocol contracts deployed on the respective chain. It must include the AirnodeRrp contract address.

# id

info (required) - The corresponding chain (or network) ID. If this is an Ethereum-based chain, id should be the chain ID as described in EIP-155 (opens new window). Refer to the documentations of the chain you will be using to find its chain ID.

# providers

info (required) - List of chain providers that will be used. Note that multiple of them can be used simultaneously. The Airnode deployment will expect to find the URLs of each of these chain providers in their respective url fields.

# type

info (required) - The type of chain. Currently only evm is supported.

# options

info (required) - An object that configures chain-related options.

# options.txType

(required) - The transaction type to use:

# options.priorityFee

(optional) - An object that configures the EIP-1559 Priority Fee. Defaults: {"value": 3.12, "unit": "gwei"}.

# options.priorityFee.value

(required) - A number specifying the EIP-1559 priority fee value.

# options.priorityFee.unit

(required) - The unit of the priority fee value. It can be one of the following:

  • wei
  • kwei
  • mwei
  • gwei
  • szabo
  • finney
  • ether

# options.baseFeeMultiplier

(optional) - Configures the EIP-1559 Base Fee to Maximum Fee Multiplier (defaults to 2)

The resulting Maximum Fee will equal (Base Fee * baseFeeMultiplier) + priorityFee

# blockHistoryLimit

info (optional) - The number of blocks in the past that the Airnode deployment should search for requests. Defaults to 300 (roughly 1 hour for Ethereum).

# minConfirmations

info (optional) - The number of confirmations required for a request to be considered valid. Minimum confirmations refers to the number of blocks that have elapsed since the current confirmed block. Defaults to 0.

# nodeSettings

An object containing general deployment parameters of an Airnode.

// nodeSettings
{
  "nodeVersion": "0.5.2",
  "cloudProvider": {
    "type": "gcp",
    "region": "us-east1",
    "disableConcurrencyReservations": false,
    "projectId": "${GCP_PROJECT_ID}"
  },
  "stage": "testnet",
  "airnodeWalletMnemonic": "${AIRNODE_WALLET_MNEMONIC}",
  "heartbeat": {
    "enabled": true,
    "url": "${HEARTBEAT_URL}",
    "apiKey": "${HEARTBEAT_API_KEY}",
    "id": "${HEARTBEAT_ID}"
  },
  "httpGateway": {
    "enabled": true,
    "apiKey": "${HTTP_GATEWAY_API_KEY}",
    "maxConcurrency": 20
  },
  "httpSignedDataGateway": {
    "enabled": true,
    "apiKey": "${HTTP_SIGNED_DATA_GATEWAY_API_KEY}",
    "maxConcurrency": 20
  },
  "logFormat": "json",
  "logLevel": "INFO"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# cloudProvider

info (required) - The cloud provider that the node will be deployed at and its configuration.

# cloudProvider.type

(required) - Currently aws and gcp are supported for serverless (deployer-image). Use local if you want to run Airnode as a docker container locally (client-image).

# cloudProvider.region

(required for AWS and GCP) - The cloud provider region that the node will be deployed at. See the cloud provider's documentation for possible values. When using GCP, make sure to choose a region and not a zone.

# cloudProvider.disableConcurrencyReservations

(required for AWS and GCP) - Disables concurency reservations for spawned cloud functions. For more information refer to the maxConcurrency section.

# cloudProvider.projectId

(required for GCP) - Project ID of the GCP project the Airnode will be deployed under.

# airnodeWalletMnemonic

info (required) - The wallet mnemonic that will be used by the Airnode.

# heartbeat

info (required) - The Airnode's "call home" functionality. Airnode can periodically make a request to the specified URL signaling that it's active. There are plans in the future to allow the sending of a payload with information for reporting purposes.

# heartbeat.enabled

(required) - Enable/disable, using true/false, Airnode's heartbeat.

# heartbeat.apiKey

(only if enabled) - The API key to authenticate against the heartbeat URL.

# heartbeat.id

(only if enabled) - The Airnode heartbeat ID for accounting purposes.

# heartbeat.url

(only if enabled) - The URL to make the heartbeat request to.

# httpGateway

info (required) - The Airnode's HTTP gateway can request endpoints without using the blockchain.

# httpGateway.enabled

(required) - Enable/disable, using true/false, Airnode's access to the HTTP gateway.

# httpGateway.apiKey

(only if enabled) - The API key to authenticate against the gateway.

# httpGateway.maxConcurrency

(only if enabled, optional) - A number higher than zero representing the maximum number of serverless functions serving HTTP gateway requests running at the same time. When omitted, there is no maximum concurrency set.

# httpSignedDataGateway

info (required) - The Airnode's HTTP gateway can request endpoints without using the blockchain.

# httpSignedDataGateway.enabled

(required) - Enable/disable, using true/false, Airnode's access to the HTTP gateway.

# httpSignedDataGateway.apiKey

(only if enabled) - The API key to authenticate against the gateway.

# httpSignedDataGateway.maxConcurrency

(only if enabled, optional) - A number higher than zero representing the maximum number of serverless functions serving HTTP gateway requests running at the same time. When omitted, there is no maximum concurrency set.

# logFormat

info (required) - The format that will be used to output logs. Either json or plain.

# logLevel

info (required) - The highest verbosity level of the logs that will be outputted. DEBUG, INFO, WARN or ERROR.

# nodeVersion

info (required) - The version of the node (Airnode) that will be deployed with this config object.

# stage

info (required) - The label used to distinguish between multiple deployments of the same Airnode on a cloud provider. For example, the same Airnode may have multiple deployments with stage set to a different value (dev, public, prod). stage cannot be longer than 16 characters and can only include lowercase alphanumeric characters (a–z, 0–9) and hyphens (-).

# skipValidation

info (optional) - Whether the config.json validation should be skipped. Defaults to false.

# triggers

An array that maps external triggers such as a request made through RRP (or a subscription made through PSP, which is not implemented yet) to an endpoint defined in an OIS.

// triggers
{
  "rrp": [
    {
      "endpointId": "0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838",
      "oisTitle": "myOisTitle",
      "endpointName": "myEndpointName"
    }
  ],
  "http": [
    {
      "endpointId": "0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838",
      "oisTitle": "myOisTitle",
      "endpointName": "myEndpointName"
    }
  ],
  "httpSignedData": [
    {
      "endpointId": "0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838",
      "oisTitle": "myOisTitle",
      "endpointName": "myEndpointName"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

In the example above, the Airnode deployment has an OIS with the title myOisTitle. This OIS has an endpoint with the name myEndpointName. When the Airnode deployment detects a request that references its airnodeAddress and 0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838 as the endpointId, it will call the specified endpoint (myOisTitle-myEndpointName) with the parameters provided in the request to fulfill it. See the endpoint id documentation for the default convention for deriving the endpointId.

# rrp

info (required) - An array of endpoints from OIS that the Airnode will respond to for the RRP protocol.

# rrp[n].endpointId

(required) - A identifier derived for an oisTitle/endpointName pair, see derive-endpoint-id.

# rrp[n].oisTitle

(required) - The title of an OIS object.

# rrp[n].endpointName

(required) - The endpoint name of an OIS endpoint.

# http

info (required) - An array of endpoints from OIS that the Airnode will respond to.

# http[n].endpointId

(required) - A identifier derived for an oisTitle/endpointName pair, see derive-endpoint-id.

# http[n].oisTitle

(required) - The title of an OIS object.

# http[n].endpointName

(required) - The endpoint name of an OIS endpoint.

# httpSignedData

info (required) - An array of endpoints from OIS that the Airnode will respond to.

# httpSignedData[n].endpointId

(required) - A identifier derived for an oisTitle/endpointName pair, see derive-endpoint-id.

# httpSignedData[n].oisTitle

(required) - The title of an OIS object.

# httpSignedData[n].endpointName

(required) - The endpoint name of an OIS endpoint.

# ois

A list of OIS objects. Since each OIS specifies the integration of an API to an oracle, a single Airnode deployment can serve multiple APIs. To avoid duplication of content, see the Oracle Integration Specifications (OIS) for a complete example and the explanation of its fields.

# apiCredentials

Each entry in apiCredentials maps to a security scheme defined in an OIS (ois[n].components.securitySchemes.{securitySchemeName}), 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) which would be in secrets.env in the example below.

The security field in the OIS object must be included and hold the names of all security schemes the API operation

Use of apiCredentials is not required, leave its array empty.

// apiCredentials
[
  {
    "oisTitle": "myOisTitle",
    "securitySchemeName": "mySecurityScheme",
    "securitySchemeValue": "${SS_MY_API_KEY}"
  }
]
// components and security field in OIS object
{
"title": "myOisTitle",
...,
"components": {
  "securitySchemes": {
    "mySecurityScheme": {
      "in": "header",
      "type": "apiKey",
      "name": "X-api-key"
    }
  }
},
"security": {
  "mySecurityScheme" []
}
...
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# oisTitle

info (required) - The ois.title of the OIS where the securitySchemeName can be found.

# securitySchemeName

info (required) - The name of a security scheme from ois[n].components.securitySchemes.{securitySchemeName}.

# securitySchemeValue

info (required) - The value of the security scheme used (as defined by ois[n].components.securitySchemes.{securitySchemeName} for the authentication. Usually stored in secrets.env.

Last Updated: 8/9/2022, 2:28:25 PM

← secrets.env →