Run Autonity Oracle Server

How to run Autonity Oracle Server in your own environment on Linux Ubuntu OS

Prerequisites

Ensure that the host machine meets the minimum requirements
A running instance of an Autonity Go Client running on your host machine, with networking configured to allow incoming traffic on its WebSocket port. This will be registered as a validator node and oracle server will be configured to connect to it.
A configured instance of aut.
Auton (ATN) to seed-fund your oracle server account.

To run Autonity Oracle Server you will need to generate a keyfile for your oracle server account and seed-fund it, configure plugin(s) for external data sources, set the oracle server configuration, and connect to your Autonity Go Client node. Autonity Oracle Server will initialise, connect to the data sources and node, and then begin to submit price reports to your connected node.

Create oracle server account

Begin by creating an account that will be used as the cryptographic identity of the oracle server. Note that the account’s:

private key is used as the oracle server key to sign price report transactions submitted to the Oracle Contract on-chain
address is used as the oracle identifier, the unique identifier of the oracle server.

Transaction costs for submitting price report data on-chain are refunded but the account needs to be pre-funded to prevent an out of gas error on the first transaction submitted by the server.

Generate a key file for the oracle server. Use aut to create an account for the oracle. Make a note of your oracle account address as this will be required when registering your validator.
Pre-fund the oracle server account. See Fund account.

Run Autonity Oracle Server (binary or source code install)

Ensure that the Autonity Oracle Server has been installed from a pre-compiled binary or from source code

Enter your working directory for the oracle server.
Configure the data plugins. Edit your oracle server data plugins config file plugins-conf.yml to specify the plugins configuration. The file can be found in the /autonity-oracle/config sub-directory. Edit plugins-conf.yml to specify the name and key for each plugins you are using. For how to do this see the Set up plugins config file section on this page.

Note

A sample plugins-conf.yml config file can be downloaded from the Autonity Oracle Server GitHub.
(Optional) Add your own data source plugin(s). If you have developed your own FX plugins, (a) add sub-directory(ies) containing the plugin source code to the plugins sub-directory of your installation; (b) add config entry(ies) to the plugins-conf.yml file.
Configure the oracle server. Edit your oracle server config file oracle-server.config to specify the oracle server configuration. The file can be found in the /autonity-oracle/config sub-directory. For how to do this see the Set up oracle server config file section on this page.

Note

A sample oracle-server.config file can be downloaded from the Autonity Oracle Server GitHub.

Start oracle server:

./autoracle --config="./oracle-server.config"

Oracle server will connect to external data sources using the providers set in the plugins configuration and begin submitting price reports to the connected node.

On running oracle server you should see something like:

2024/06/05 11:22:48 

   Running autonity oracle server v0.1.9
   with plugin directory: ./build/bin/plugins
   by connecting to L1 node: ws://127.0.0.1:8546
   on oracle contract address: 0x47e9Fbef8C83A1714F1951F142132E6e90F5fa5D

Note

The oracle server configuration can also be set as system environment variables or directly in the terminal as console flags. For how to do this see the page section Setup using command line flags or system env variables.

Note

New or updated plugins are configured by simply adding the binary code to the configured plugins directory (plugin.dir). See Installing data source plugins for more detail.

If plugins for external data sources or the symbols for which oracle server provides price data are changed while oracle server is running, changes are auto-detected and applied. Oracle server does not need to be re-started.

Run Autonity Oracle Server as Docker image

Ensure that the Autonity Oracle Server Docker image has been installed.

Enter your working directory for autonity oracle server.
Configure the data plugins. Create and edit your oracle server data plugins config file plugins-conf.yml to specify the name and key for each plugins you are using.
```
touch plugins-conf.yml
```
Note

A sample plugins-conf.yml config file can be downloaded from the Autonity Oracle Server GitHub.

Edit plugins-conf.yml to configure plugins for data sources. See Set up plugins config file for how to do this.
Configure the oracle server. Create and edit your oracle server config file oracle-server.config to specify the oracle server configuration.
```
touch oracle-server.config
```
Note

A sample oracle-server.config file can be downloaded from the Autonity Oracle Server GitHub.

Edit oracle-server.config to specify the oracle server configuration. See Set up oracle server config file for how to do this.
Set the Docker configuration and the arguments for running Autonity Oracle Server and connecting to the Autonity Go Client it is serving.
```
docker run \
     -t -i \
     --volume ./<ORACLE_KEYFILE>:/autoracle/oracle.key \
     --volume ./<PLUGINS_CONF_FILE>:/autoracle/plugins-conf.yml \
     --volume ./<ORACLE_SERVER_CONF_FILE>:/autoracle/oracle-server.config \
     --name <ORACLE_CONTAINER_NAME> \
     --rm <DOCKER_IMAGE>:latest \
     --config="/autoracle/oracle-server.config" \
     ;
```
where:
- <ORACLE_KEYFILE> specifies the path to your oracle server key file. E.g. ../aut/keystore/oracle.key
- <PLUGINS_CONF_FILE> is the path to the data plugins configuration file plugins-conf.yml. E.g. ./plugins-conf.yml.
- <ORACLE_SERVER_CONF_FILE> is the path to the oracle server configuration file oracle-server.config. E.g. ./oracle-server.config.
- <ORACLE_CONTAINER_NAME> is the name you are specifying for the container, i.e. oracle-server-bakerloo or oracle-server-piccadilly
- <DOCKER_IMAGE> is the Docker image name, i.e. ghcr.io/autonity/autonity-oracle-bakerloo or ghcr.io/autonity/autonity-oracle-piccadilly.
See the Autonity Oracle Server command-line reference for the full set of available flags.

Note

AOS requires an accessible ws/wss AGC endpoint. If you are also running AGC in docker and facing issues in connecting AOS to it, please execute the following command to correctly identify the IP address required for the <WS_ADDRESS>: docker inspect -f '{{.NetworkSettings.IPAddress}}' <container_id_or_name>
Note
- The command above creates a temporary container, which is deleted (via the --rm flag) when the node is shut down.
- The --volume flags are needed to mount the key and config files. The plugins are pre-built and included in the Docker container at the path /usr/local/bin/plugins/.
Naturally, the above command line can be tailored to suit a specific deployment. See the docker documentation for the complete list of Docker options.
Start oracle server. On running the Docker you should see something like:
```
 2024/06/05 11:44:45

 Running autonity oracle server v0.1.9
 with plugin directory: /usr/local/bin/plugins/
 by connecting to L1 node: ws://127.0.0.1:8546
 on oracle contract address: 0x47e9Fbef8C83A1714F1951F142132E6e90F5fa5D
```
Oracle server will discover plugins in the plugins configuration, set them up, connect to external data sources using the providers set in the plugins-conf.yml configuration properties, and begin submitting price reports to the connected node.

Configure oracle server

The runtime configuration of oracle server can be specified using a configuration file, command line flags, or system environment variables. Using the configuration file oracle-server.config is the preferred default path.

Set up oracle server config file

The oracle server config file oracle-server.config can be found in the /autonity-oracle/config sub-directory. Edit the file to set the config values where:

tip: sets a gas priority fee cap for your oracle server data report transactions.
key.file: is the path to your oracle server key file, e.g. ../aut/keystore/oracle.key
key.password: is the password to your oracle server key file
log.level: sets the logging level. Values are: 0: No logging, 1: Trace, 2:Debug, 3: Info, 4: Warn, 5: Error.
ws: is the WebSocket IP Address of your connected Autonity Go Client node (see install Autonity, networks
plugin.dir is the path to the directory containing the built data plugins.
plugin.conf is the path to the plugins YAML configuration file plugins-conf.yml (defaults to ./plugins-conf.yml).

An example configuration for an oracle server binary could be:

tip 1
key.file ./UTC--2023-02-27T09-10-19.592765887Z--b749d3d83376276ab4ddef2d9300fb5>
key.password 123%&%^$
log.level 3
ws ws://127.0.0.1:8546
plugin.dir ./build/bin/plugins
plugin.conf ./config/plugins-conf.yml

An example configuration for an oracle server Docker image could be per beneath. Note the mounted path is used for key.file and plugin.conf files. A mounted path is not used for the plugin.dir config which takes the Docker image plugins directory path /usr/local/bin/plugins/:

tip 1
key.file /autoracle/UTC--2023-02-27T09-10-19.592765887Z--b749d3d83376276ab4ddef2d9300fb5>
key.password 123%&%^$
log.level 3
ws ws://127.0.0.1:8546
plugin.dir /usr/local/bin/plugins/
plugin.conf /autoracle/plugins-conf.yml

Setup using command line flags or system env variables

The oracle server configuration can also be set directly in the terminal as console flags or as system environment variables.

For example, to start oracle server specifying command line flags when running the binary, simply specify the config as flags:

./autoracle \
     --tip="1" \
     --key.file="../../test_data/keystore/UTC--2023-02-27T09-10-19.592765887Z--b749d3d83376276ab4ddef2d9300fb5ce70ebafe" \
     --key.password="123" \
     --ws="ws://127.0.0.1:8546" \
     --plugin.dir="./plugins" \
     --plugin.conf="./plugins-conf.yml" \
     ;

For example, to start oracle server specifying command line flags when running the Docker image, specify the Docker configuration and oracle server config as flags:

docker run \
     -t -i \
     --volume ./<ORACLE_KEYFILE>:/autoracle/oracle.key \
     --volume ./<PLUGINS_CONF_FILE>:/autoracle/plugins-conf.yml \
     --name <ORACLE_CONTAINER_NAME> \
     --rm \
     <DOCKER_IMAGE>:latest \
     -tip="<TIP>" \
     -key.file="/autoracle/oracle.key" \
     -key.password="<PWD>" \
     -ws="<WS_ADDRESS>" \
     -plugin.dir="/usr/local/bin/plugins/" \
     -plugin.conf="/autoracle/plugins-conf.yml"

where:

<ORACLE_KEYFILE> specifies the path to your oracle server key file. E.g. ../aut/keystore/oracle.key
<PLUGINS_CONF_FILE> is the path to the data plugins configuration file plugins-conf.yml. E.g. ./plugins-conf.yml.
<ORACLE_CONTAINER_NAME> is the name you are specifying for the container, i.e. oracle-server-bakerloo or oracle-server-piccadilly
<DOCKER_IMAGE> is the Docker image name, i.e. ghcr.io/autonity/autonity-oracle-bakerloo or ghcr.io/autonity/autonity-oracle-piccadilly
<TIP> sets a gas priority fee cap for your oracle server data report transactions, e.g. 1.
<PWD> is the password to your oracle server key file
<WS_ADDRESS> is the WebSocket IP Address of your connected Autonity Go Client node, e.g. “ws://172.17.0.2:8546”, see install Autonity, networks).

Note

Note that all flags after the image name are passed to the Autonity Oracle Server in the container, and thus follow the same pattern as for running a binary or source install
The command above creates a temporary container, which is deleted (via the --rm flag) when the node is shut down.
The --volume flags are needed to mount the key and config files. The plugins are pre-built and included in the Docker container at the path /usr/local/bin/plugins/.

See the Autonity Oracle Server command-line reference or the oracle server’s GitHub repo README, Configuration of oracle server section CLI flags for the full set of available flags.

For how to set the flags as system environment variables see the README section System Environment Variables.

Configure data source plugins

The oracle server will need to provide FX, ATN and NTN currency pairs utilised in the Auton Stabilization Mechanism.

A basic set of data adaptor plugins for sourcing this data is provided out the box with oracle server for testnet pre-Mainnet in the autonity-oracle GitHub repo /plugins directory:

Forex plugins: for connecting to public FX data sources. See the forex_ prefixed adaptors. Four forex plugins are currently provided.
Simulator plugin: for simulated ATN/NTN data. See the sim_plugin adaptor.

Set up plugins config file

To configure FX data source plugins edit the plugins_conf.yml file to add a config entry for each plugin. The oracle server release contains out-the-box plugins for four publicly accessible FX endpoints with free and paid subscriptions tiers. You will need to create an account and get an API Key to connect. One or more plugin source must be configured.

Navigate to the public GitHub repo autonity-oracle README.md Configuration section to view the supported FX endpoint providers.

For each FX endpoint configured:

Get FX plugin API Key(s). Navigate to one of the listed FX endpoint websites and create an account. Make a note of the API Key.
Add configuration entry to plugins-conf.yml. Edit the file to add an entry for each plugin you are configuring.

Configuration fields:

Name	Datatype	Mandatory?	Description
`name`	string	required	the name of the plugin binary; use the name of the sub-directory in the `plugins` directory
`key`	string	required	the API key granted by your data provider to access their data API
`scheme`	string	optional	the data service http scheme, http or https. Default value is https.
`endpoint`	string	optional	the data service endpoint url of the data provider
`timeout`	int	optional	the duration of the timeout period for an API request in seconds. Default value is 10.
`refresh`	int	optional	the data update interval in seconds. Used for a rate limited provider’s plugin to limit the request rate. Default value is 30.

An example minimal entry could be:

- name: forex_currencyfreaks
  key: 5490e15565e741129788f6100e022ec5

Note

The optional fields should be set as needed to fit the service level agreed with your rate provider.

ATN and NTN data simulator plugin

If you are connecting to Bakerloo testnet an ATN and NTN Simulator is deployed and available to provide simulated data for testnet use.

To connect to this simulator as a data source, you need to edit your plugins-conf.yml config file to point to the Bakerloo ATN and NTN data simulator. Just add an entry for the Bakerloo simulator data source:

- name: sim_plugin
  endpoint: simfeed.bakerloo.autonity.org
  scheme: https

Note

The sim_plugin is built and added to the plugins directory when building from source running the make autoracle-bakerloo command.

When running make on oracle server the simulator plugin is also built to a test directory. So if you didn’t run the Bakerloo-specific make command you can still get the plugin by just copying the file to the plugins directory:

cp e2e_test/plugins/simulator_plugins/sim_plugin build/bin/plugins/sim_plugin

The simulator can also be built independently by running the make simulator command.

Develop plugins

Additional data adaptors for any external data source can be developed using the oracle server’s plugin template. See:

Adaptor code template template_plugin in /plugins.
Guide for how To write a new plugin using the template in /plugins/README.

Stopping the Autonity Oracle Server

To shutdown the oracle server, press CTRL-C and wait for it to exit.

If you need help, you can chat to us on Autonity Discord Server!