The oracle core requires that the user has access to a full node wallet in order to create txs & perform UTXO-set scanning. Furthermore, each oracle core is designed to work with only a single oracle pool. If an operator runs several oracles in several oracle pools then a single full node can be used, but several instances of oracle cores must be run (and set with different API ports).
The current oracle core is built to run the protocol specified in the EIP-0023 PR.
AMD64 and ARM64 images are available from Docker Hub Repo
The container runs under oracle-core user (9010 uid), if using bind mount for container's /data folder (where config files and other data lives), set the container's uid for the host's folder ownership ( ex: chown -R 9010:9010 oracle_data ).
An example docker run command:
docker run -d \
-v /path/on/host:/data \
-p 9010:9010 \
-p 9011:9011 \
-e ORACLE_NODE_API_KEY=CHANGE_ME_KEY \
ergoplatform/oracle-core:latest
To enter container shell for debugging or pool modifications:
docker exec -it -u oracle-core <container id> /bin/sh
Get the latest release binary from Releases Or install it from the source code with:
cargo install --path core
If you want to run it as systemd daemon check out this section.
Run it with oracle-core --help
or oracle-core <SUBCOMMAND> --help
to see the available commands and their options.
Generate an oracle config file from the default template with:
oracle-core generate-oracle-config
and set the required parameters:
oracle_address
- a node's address that will be used by this oracle-core instance(pay tx fees, keep tokens, etc.). Make sure it has coins;node_url
node URL;Set the environment variable ORACLE_NODE_API_KEY
to the node's API key. You can put it in the .secrets
file and then run source .secrets
to load it into the environment. This way, the key does not get stored in the shell history.
To bootstrap a new oracle pool:
oracle-core bootstrap --generate-config-template bootstrap.yaml
to generate an example of the bootstrap config file.
bootstrap.yaml
(see the parameters list below);oracle-core bootstrap bootstrap.yaml
to mint tokens and create pool, refresh, update boxes. The pool_config.yaml
file will be generated. It contains the configuration needed to run this pool;
oracle-core run
Bootstrap parameters available to edit:
[token]:name
, description
- token names and descriptions that will be used to mint tokens;[token]:quantity
- number of tokens to mint;data_point_source
- can be one of the following: NanoErgUsd, NanoErgXau, NanoErgAda;min_data_points
- minimal number of posted datapoint boxes needed to update the pool box (consensus);max_deviation_percent
- a cut off for the lowest and highest posted datapoints(i.e. datapoints deviated more than this will be filtered out and not take part in the refresh of the pool box);epoch_length
- minimal number of blocks between refresh(pool box) actions;min_votes
- minimal number of posted ballot boxes voting for a change to the pool box contracts;min_storage_rent
- box value in nanoERG used in oracle and ballot boxes;Check out How I bootstrapped an ERG/XAU pool on testnet report for an example.
To invite a new oracle the person that bootstrapped the pool need to send one oracle token and one reward token. On bootstrap X oracle and reward tokens are sent to the oracle_address
, where X is the total oracle token quantity minted on bootstrap.
Use scripts/send_new_oracle.sh to send one oracle, reward and ballot token.
Besides the tokens the pool config file that you are running now should be sent as well. Send pool_config.yaml
to the new oracle.
To join the existing pool one oracle and one reward token must be received to the address which will be used as oracle_address
in the config file of the oracle. The received pool_config.yaml
config file must placed accordingly.
To run the oracle:
oracle-core run
Since the earned reward tokens are accumulating in the oracle box there is a command to send all accumulated reward tokensminus 1 (needed for the contract) to the specified address:
oracle-core extract-reward-tokens <ADDRESS>
To show the amount of accumulated reward tokens in the oracle box run
oracle-core print-reward-tokens
Be aware that reward tokens currently accumulated in the oracle box should be extracted with extract-reward-tokens
command firstbefore transferring the oracle token to the new address.
Run
oracle-core transfer-oracle-token <ADDRESS>
Ensure the new address has enough coins for tx fees to run in a pool.
As with inviting a new oracle, the pool config file that you are running now should be sent as well. Send pool_config.yaml
to the new operator.
Changes to the contract(parameters)/tokens can be done in three steps:
prepare-update
command submits a new refresh box with the updated refresh contract;vote-update-pool
command submits oracle's ballot box voting for the changes;update-pool
command submits the update transaction, which produces a new pool box;
Each of the step is described below. See also a detailed instruction on Updating the epoch lengthprepare-update
commandCreate a YAML file describing what contract parameters should be updated. See also an example of such YAML file at Updating the epoch length Run:
oracle-core prepare-update <YAML file>
This will generate pool_config_updated.yaml
config file which should be used in update-pool
command.
The output shows the new pool box contract hash and reward tokens amounts for the subsequent dozen epochs. To be used in the vote-update-pool
command run by the oracles on the next step.
vote-update-pool
commandRun
oracle-core vote-update-pool <NEW_POOL_BOX_ADDRESS_HASH_STR> <UPDATE_BOX_CREATION_HEIGHT>
Where:
are required parameters, with optinal (in case of minting a new reward token):
They are printed in the output of the prepare-update
command.
update-pool
commandMake sure the pool_config_updated.yaml
config file generated during the prepare-update
command is in the same folder as the oracle-core binary.
Run
oracle-core update-pool
With optional(only if minted) parameters: