Run Autonity Oracle Server
How to run Autonity Oracle Server in your own environment on Linux Ubuntu OS
- 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. Editplugins-conf.yml
to specify thename
andkey
for each plugins you are using. For how to do this see the Set up plugins config file section on this page.NoteA 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 theplugins-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.NoteA 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:
2025/03/24 14:39:22 Running autonity oracle server v0.2.3 with plugin directory: ./plugins by connecting to L1 node: ws://127.0.0.1:8546 on oracle contract address: 0x47e9Fbef8C83A1714F1951F142132E6e90F5fa5D
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.
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 thename
andkey
for each plugins you are using.touch plugins-conf.yml
NoteA 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
NoteA 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 fileplugins-conf.yml
. E.g../plugins-conf.yml
.<ORACLE_SERVER_CONF_FILE>
is the path to the oracle server configuration fileoracle-server.config
. E.g../oracle-server.config
.<ORACLE_CONTAINER_NAME>
is the name you are specifying for the container, i.e.oracle-server-bakerloo
ororacle-server-piccadilly
<DOCKER_IMAGE>
is the Docker image name, i.e.ghcr.io/autonity/autonity-oracle
.
See the Autonity Oracle Server command-line reference for the full set of available flags.
NoteAOS 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>
NoteThe 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:
2025/03/25 11:44:45 Running autonity oracle server v0.2.3 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 theplugins-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:
Option | Description |
---|---|
tip |
Sets a gas priority fee cap for your oracle server data report transactions. The gas priority fee cap is reimbursed by the Autonity network. Specify in ton . |
key.file |
Path to the oracle server key file. e.g. ../aut/keystore/oracle.key |
key.password |
The password to the oracle server key file. |
log.level |
Sets logging verbosity. Available logging levels: 0 : No logging, 1 : Trace, 2 : Debug, 3 : Info, 4 : Warn, 5 : Error |
ws |
The WS-RPC server listening interface and port of the connected Autonity Go Client node (see install Autonity, networks. E.g.: "ws://127.0.0.1:8546" |
plugin.dir |
The path to the directory containing the built data plugins. For example "./plugins" |
plugin.conf |
The path to the plugins configuration file. For example "./plugins-conf.yml" |
confidence.strategy |
The confidence rule. Available strategies are: 0 : linear, 1 : fixed. |
profile.dir |
The profiling report directory, where the profiling report (i.e. runtime state) will be saved to. For example "." |
Oracle prices are submitted with a confidence score in the range \((0, 100]\) expressing the oracle’s level of trust in the provided price (For detail on confidence score, see the concept description Oracle Accountability Fault Detection (OAFD).
confidenceStrategy
provides two out-the-box options to compute the confidence score for a symbol:
0
: linear, dynamic. The oracle server will use the number of price samples it retrieved during the voting round for a symbol to compute the confidence score. The higher the number of samples, the higher the confidence score. The confidence score computed is capped at the maximum trust level of \(100\).1
: fixed, set to \(100\) the maximum trust level.
oracle-server.config
to your configuration before running oracle server
The oracle-server.config
file is preset to a testing configuration using test key credentials.
If you run the server without setting your own configuration, then the test configuration will de facto be picked up and used as a default configuration. Without editing the key options (key.file
, key.password
) at minimum, the server will error with an unable to load key message:
$ ./autoracle oracle-server.config
2025/03/20 11:52:09 cannot read key from oracle key file: ./UTC--2023-02-27T09-10-19.592765887Z--b749d3d83376276ab4ddef2d9300fb5ce70ebafe, open ./UTC--2023-02-27T09-10-19.592765887Z--b749d3d83376276ab4ddef2d9300fb5ce70ebafe: no such file or directory
could not load key from key store: ./UTC--2023-02-27T09-10-19.592765887Z--b749d3d83376276ab4ddef2d9300fb5ce70ebafe with password, err: open ./UTC--2023-02-27T09-10-19.592765887Z--b749d3d83376276ab4ddef2d9300fb5ce70ebafe: no such file or directory
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
confidence.strategy 0
profile.dir .
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
confidence.strategy 0
profile.dir .
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" \
--confidence.strategy="0" \
--profile.dir="."
;
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" \
-confidence.strategy="<CONFIDENCE_STRATEGY>" \
-profile.dir="<PROFILE_DIR>"
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 fileplugins-conf.yml
. E.g../plugins-conf.yml
.<ORACLE_CONTAINER_NAME>
is the name you are specifying for the container, e.g.oracle-server-v0.2.3
<DOCKER_IMAGE>
is the Docker image name, i.e.ghcr.io/autonity/autonity-oracle
<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).<CONFIDENCE_STRATEGY>
sets a confidence score strategy for your oracle server data report transactions, e.g.0
.<PROFILE_DIR>
is the path to the directory where your profile report data is saved to, e.g..
.
- 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 for ASM ACU basket currency prices. See the
forex_
prefixed adaptors in/plugins
. Five forex plugins are currently provided. - Crypto plugins: for connecting to public CEX and DEX data sources for USD stablecoin and ATN, NTN prices. ATN NTN price data is used for the ASM Stabilisation CDP mechanism. See the
crypto_
prefixed adaptors in/plugins
. Four crypto plugins are currently provided. - Simulator plugin: for simulated protocol asset (ATN, NTN, NTN-ATN) data. Used for testnet or local development purposes to provide ATN, NTN price data. See the
simulator_plugin
adaptor in/plugins
.
Plugins are configured by default or by explicit configuration. The crypto_
plugins have a default configuration set in the plugin source golang code as a defaultConfig
. The forex_
and simulator_
plugin configuration is specified explicitly in the plugins-conf.yml
file by addding a config entry for each plugin configured.
The full set of plugin configuration fields are:
Name | Datatype | Mandatory? | Description |
---|---|---|---|
name |
string | ✔ | the name of the plugin binary; use the name of the sub-directory in the plugins directory |
key |
string | ✔ | the API key granted by your data provider to access their data API |
scheme |
string | the data service http scheme: http, https, ws or wss. Default value is https. | |
endpoint |
string | the data service endpoint url of the data provider | |
timeout |
int | the duration of the timeout period for an API request in seconds. Default value is 10. | |
refresh |
int | the data update interval in seconds. Used for a rate limited provider’s plugin to limit the request rate. Default value is 30. | |
ntnTokenAddress |
string | (crypto_uniswap_usdcx plugin only) |
The NTN ERC20 token address on the target blockchain. This is the Autonity Protocol Contract Address. |
atnTokenAddress |
string | (crypto_uniswap_usdcx plugin only) |
The Wrapped ATN erc20 token address on the target blockchain. |
usdcTokenAddress |
string | (crypto_uniswap_usdcx plugin only) |
USDC ERC20 token address on the target blockchian. For Piccadilly Testnet this is the USDCx ERC20 token address. |
swapAddress |
string | (crypto_uniswap_usdcx plugin only) |
UniSwap factory contract address or AirSwap SwapERC20 contract address on the target blockchain. For Piccadilly Testnet this is the Uniswap V2 AMM clone factory contract address. |
disabled |
boolean | The flag to disable a plugin. False by default. |
The configuration fields used depends on the type of plugin. Set optional fields as needed to fit the service level agreed with your rate provider and your own operational practice.
Setup forex plugin config
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 five 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 FX 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) for the listed FX endpoint. 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.
Plugin 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, https, ws or wss. 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. |
disabled |
boolean | optional | The flag to disable a plugin. False by default. |
An example minimal entry could be:
- name: forex_currencyfreaks
key: 5490e15565e741129788f6100e022ec5
The optional fields should be set as needed to fit the service level agreed with your rate provider and your own operational practice.
Remember that the oracle server auto-detects changes to the plugin configuration. If you want to temporarily switch off a plugin you can edit the config to set disabled
to true
and toggle it back to false
to switch it back on again without re-starting the oracle server.
Setup crypto plugin config
The crypto_
plugins have default configuration and run by default when oracle server is initialised. There are four plugins:
- 1 DEX:
crypto_uniswap
. Connector to retrieve ATN, NTN USDC price data from an on-chain Uniswap V2 AMM on Piccadilly Testnet. - 3 CEX:
crypto_kraken
,crypto_coingecko
,crypto_coinbase
. Connectors to retrieve USDC-USD price data.
Configure the crypto_uniswap
plugin to set the RPC endpoint of a Piccadilly Testnet Full Node (i.e. your own node or a public rpc endpoint). Un-comment and edit the crypto_uniswap
entry in plugins-conf.yml
. Edit the configuration fields:
Name | Datatype | Mandatory? | Description |
---|---|---|---|
scheme |
string | required | edit to the scheme used for connecting to your full node: http , https , ws or wss |
endpoint |
string | required | edit to the rpc endpoint address of your connected full node |
No editing of default configuration is required for the 3 CEX connectors used to retrieve USDC-USD price data.
The oracle server uses the USDC-USD pricing to convert the ATN, NTN USDC market prices from the Testnet Uniswap V2 AMM to ATN,NTN USD prices. The price report for ATN, NTN is then submitted on-chain with USD as the quote pair by the oracle server’s connected validator node.
On-chain, the oracle protocol is pricing in USD and not USDC.
ATN and NTN data simulator plugin
If a simulator has been deployed and is available to provide simulated data for testnet use, this can be connected to by adding a config entry for the simulated source to your plugins-conf.yml
file.
- Edit your
plugins-conf.yml
config file to point to the deployed ATN and NTN data simulator. Just add asimulator_plugin
entry for the simulator data source, specifyingendpoint
andscheme
at minimum.
An example config could be:
- name: simulator_plugin
endpoint: simfeed.bakerloo.autonity.org
scheme: https
When running make
on oracle server the simulator plugin is built to a test directory. So you can get the plugin by just copying the file to your plugins directory:
cp e2e_test/plugins/simulator_plugins/simulator_plugin build/bin/plugins/simulator_plugin
The data source simulator can also be built independently by running the make simulator
command as described in the README.
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!