At its core, the Infernet Node operates according to a set of runtime configurations. Parameterized in config.json, these configurations enable node operators to flexibily configure the functionality of a node.

While some configurations have sane defaults and do not need modification, it is useful to understand the implications of each option to configure your node to your unique application and use case.

Initializing config.json

Out-of-the-box, we provide a default config.sample.json (opens in a new tab) as an example starting point that you can copy and modify:

# Copy and modify sample config
cp config.sample.json config.json
vim config.json

Required parameters

chain (object)

Configuration parameters specific to on-chain event processing.

enabled (boolean)

Whether listening and responding to on-chain events is enabled for this node. If set to false, only the REST API will be active and the ChainProcessor will not run.

trail_head_blocks (integer)

Some Ethereum-compatible chains finalize (opens in a new tab) or are significantly less likely to have a chain reorganization (opens in a new tab) after a number of blocks. By configuring trail_head_blocks, node operators can add a global delay to chain syncing, preventing failed transactions and unnecessary compute operations due to volatile state by trailing the head block, at the expense of increased latency.

rpc_url (string)

HTTP(s) JSON-RPC url with support for the eth_newFilter (opens in a new tab) method.

registry_address (string)

Infernet SDK Registry address to read all other Infernet contracts from.

wallet (object)

Configuration parameters specific to on-chain Ethereum wallets used by the node to send transactions.

max_gas_limit (integer)

Global maximum gas limit to use for each independent transaction sent from the node wallet.

private_key (string)

0x-prefixed node wallet private key.

payment_address (string, optional)

Public address of the node's escrow wallet. This is an instance of Infernet's Wallet contract. If not provided, the node will skip subscriptions that provide payment.

allowed_sim_errors (array[string], optional)

Allowed error messages to ignore when simulating transactions. Checks for inclusion in error message. Case-insensitive. i.e. ["out of gas"] matches "Contract reverted: Out of gas". Defaults to [].

snapshot_sync (object, optional)

Snapshot sync configurations, to control rate-limitation from the RPC.

sleep (float, optional)

Number of seconds to sleep between snapshot syncs. Defaults to 1.0.

batch_size (int, optional)

Number of subscription to sync per batch. Defaults to 200.

docker (object, optional)

Optional Docker Hub (opens in a new tab) credentials to access private containers.

username (string)

Docker Hub username.

password (string)

Docker Hub Personal Access Token (PAT) (opens in a new tab).

containers (array[container_spec])

Array of supported workflow container specifications.

container_spec (object)

Workflow container specification object.

id (string)

Must be unique; user-configured ID of supported workflow service.

image (string)

Docker Hub image of container workflow. Must be local, public, or accessible with the provided Docker Hub credentials in the docker configuration parameter.

command (string)

The command and flags to run the container with.

env (object)

Key-value pairs of environment variables to expose to the container.

external (boolean)

Whether this container can be the first container in a JobRequest (opens in a new tab). If set to false, using this container as the entrypoint of a request will fail (container must be non-first, intermediary).

port (integer)

Local port to expose this container on.

rate_limit (object, optional)

REST server rate-limiting configurations. If not provided, defaults are used.

num_requests (integer, optional)

Maximum number of requests per period. Defaults to 60.

period (float, optional)

Time period in seconds for allowing num_requests. Defaults to 60.0.

description (string, optional)

Description of service provided by this workflow container.

allowed_ips (array[string])

Container-level firewall. Only specified IPs and/or CIDR blocks (opens in a new tab) allowed to request execution of this container. Leave empty for no restrictions.

allowed_addresses (array[string])

Container-level firewall. Only specified addresses are allowed to request execution of this container, with request originating from an on-chain contract. Leave empty for no restrictions.


Note: with contracts that consume Delegate Subscriptions with off-chain data, it may be useful to set "allowed_addresses": [""], restricting a container from being executed from on-chain. This prevents race conditions where nodes process the creation of on-chain subscriptions before receiving off-chain data via a Delegate Subscription.

allowed_delegate_addresses (array[string])

Container-level firewall. Only specified addresses allowed to request execution of this container, with request originating from on-chain contract but via off-chain Delegate Subscription (with this array corresponding to the delegate subscription owner address). Leave empty for no restrictions.

gpu (boolean)

Whether this should be a GPU-enabled container. The host must also be GPU-enabled.

volumes (array[string], optional)

The volume mounts for this container.

accepted_payments (dict[string, string], optional)

Payment configurations for this container. This is a dictionary of accepted token addresses (zero address for native token i.e. ETH) and their corresponding minimum payment amount. If not provided, no payments will be received. If provided, subscriptions that don't meet these requirements will be skipped.

generates_proofs (boolean)

Whether this container generates proofs. Defaults to false. If false, the node will skip subscriptions that require proofs from this container.


Note: Only set this parameter to true if you know what you're doing! Wrong proofs can lead to slashing of your node's wallet. If using this, be sure to permission the node using allowed_addresses and allowed_delegate_addresses to only allow trusted contracts to request proofs.

Sane default parameters

log_path (string)

The local file path for logging. Infernet Nodes use structlog (opens in a new tab) for JSON logging. Defaults to infernet_node.log.

manage_containers (boolean, optional)

Whether containers should be managed by the node. If true, the node will pull images, start containers at boot, and stop containers at shutdown.

If false, the node operator is responsible for setting up, running, and tearing down the containers. This option is useful for more complex or specialized container deployments; for critical containers where node failures should not result in a container shutdown; and for development.

Defaults to true.

startup_wait (float, optional)

Some Docker containers may have a startup lifecycle that takes a few moments. By configuring startup_wait, you can optionally choose to pause any Infernet Node execution for a fixed duration of time, while you wait for all Docker containers to finish their startup lifecycles. Defaults to 60.

server (object)

HTTP web server configuration parameters.

port (integer)

Port to run web server on. Defaults to 4000.

redis (object)

Redis DB configuration parameters.

host (string)

Redis host to connect to. Defaults to "redis", assuming the node is running using Docker Compose.

port (integer)

Redis host port to connect to. Defaults to 6379.

forward_stats (boolean)

Whether to send diagnostic system statistics to Ritual. Defaults to true.