{"id":27801171,"url":"https://github.com/ergoplatform/oracle-core","last_synced_at":"2026-01-12T09:27:40.489Z","repository":{"id":37101263,"uuid":"271548503","full_name":"ergoplatform/oracle-core","owner":"ergoplatform","description":"Core off-chain component of Oracle Pools","archived":false,"fork":false,"pushed_at":"2025-09-27T20:31:54.000Z","size":27938,"stargazers_count":65,"open_issues_count":21,"forks_count":38,"subscribers_count":13,"default_branch":"develop","last_synced_at":"2025-10-09T00:57:04.588Z","etag":null,"topics":["blockchain","defi","ergo","oracles","smart-contracts","utxo"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ergoplatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-06-11T13:07:06.000Z","updated_at":"2025-09-27T20:13:55.000Z","dependencies_parsed_at":"2023-11-19T23:24:40.106Z","dependency_job_id":"2384d66b-b7ca-4dd1-9d0e-bc9d0a0e39eb","html_url":"https://github.com/ergoplatform/oracle-core","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/ergoplatform/oracle-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergoplatform%2Foracle-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergoplatform%2Foracle-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergoplatform%2Foracle-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergoplatform%2Foracle-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ergoplatform","download_url":"https://codeload.github.com/ergoplatform/oracle-core/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergoplatform%2Foracle-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","defi","ergo","oracles","smart-contracts","utxo"],"created_at":"2025-05-01T05:00:53.850Z","updated_at":"2026-01-12T09:27:40.483Z","avatar_url":"https://github.com/ergoplatform.png","language":"Rust","funding_links":[],"categories":["🏗️ Core Infrastructure \u003ca id=\"core-infrastructure\"\u003e\u003c/a\u003e"],"sub_categories":["🔮 Oracles \u003ca id=\"oracles\"\u003e\u003c/a\u003e"],"readme":"# Oracle Core v2.0\n\nThe oracle core requires that the user has access to a public node with activated extra option to create txs. 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).\n\nThe current oracle core is built to run the protocol specified in the [EIP-0023 PR](https://github.com/ergoplatform/eips/pull/41).\n\n## Getting started\n\n### Docker Image\n\nAMD64 and ARM64 images are available from [Docker Hub Repo](https://hub.docker.com/r/ergoplatform/oracle-core)\n\nIF running in Ubuntu read section below\n\nThe 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 ).\n\nAn example docker run command:\n\n``` console\ndocker run -d \\\n -v /path/on/host:/data \\\n -p 9010:9010 \\\n -p 9011:9011 \\\n -e ORACLE_WALLET_MNEMONIC=CHANGE_ME \\\n ergoplatform/oracle-core:latest\n```\n\nTo enter container shell for debugging or pool modifications:\n\n``` console\ndocker exec -it -u oracle-core \u003ccontainer id\u003e /bin/sh\n```\n\n### Download\n\nGet the latest release binary from [Releases](https://github.com/ergoplatform/oracle-core/releases)\nOr install it from the source code with:\n\n``` console\ncargo install --path core\n```\n\nIf you want to run it as systemd daemon check out [this](https://github.com/ergoplatform/oracle-core#how-to-run-as-systemd-daemon) section.\nRun it with `oracle-core --help` or `oracle-core \u003cSUBCOMMAND\u003e --help` to see the available commands and their options.\n\n## Setup\n\nGenerate an oracle config file from the default template with:\n\n```console\noracle-core generate-oracle-config\n```\n\nand set the required parameters:\n\n- `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;\n- `node_url` node URL;\n\nSet the environment variable `ORACLE_WALLET_MNEMONIC` to the oracle's mnemonic. 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.\n\n## Bootstrapping a new oracle pool\n\nTo bootstrap a new oracle pool:\n\n- Run\n\n``` console\noracle-core bootstrap --generate-config-template bootstrap.yaml\n```\n\nto generate an example of the bootstrap config file.\n\n- Edit `bootstrap.yaml` (see the parameters list below);\n- Make sure node's wallet is unlocked;\n- Run\n\n``` console\noracle-core bootstrap bootstrap.yaml\n```\n\nto 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;\n\n- Run an oracle with\n\n``` console\noracle-core run\n```\n\nBootstrap parameters available to edit:\n\n- `[token]:name`, `description` - token names and descriptions that will be used to mint tokens;\n- `[token]:quantity` - number of tokens to mint;\n- `data_point_source` - can be one of the following: NanoErgUsd, NanoErgXau, NanoErgAda;\n- `min_data_points` - minimal number of posted datapoint boxes needed to update the pool box (consensus);\n- `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);\n- `epoch_length` - minimal number of blocks between refresh(pool box) actions;\n- `min_votes` - minimal number of posted ballot boxes voting for a change to the pool box contracts;\n- `min_storage_rent` - box value in nanoERG used in oracle and ballot boxes;\n\nCheck out [How I bootstrapped an ERG/XAU pool on testnet](docs/how_to_bootstrap.md) report for an example.\n\n## Invite new oracle to the running pool\n\nTo 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.\nUse [scripts/send_new_oracle.sh](scripts/send_new_oracle.sh) to send one oracle, reward and ballot token.\nBesides the tokens the pool config file that you are running now should be sent as well. Send `pool_config.yaml` to the new oracle.\n\n## Joining a running pool\n\nTo 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.\n\nTo run the oracle:\n\n- Make sure node's wallet is unlocked;\n- Run an oracle with\n\n``` console\noracle-core run\n```\n\n## Extract reward tokens\n\nSince 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:\n\n``` console\noracle-core extract-reward-tokens \u003cADDRESS\u003e\n```\n\nTo show the amount of accumulated reward tokens in the oracle box run\n\n``` console\noracle-core print-reward-tokens\n```\n\n## Transfer the oracle token to a new operator\n\nBe 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.\nRun\n\n``` console\noracle-core transfer-oracle-token \u003cADDRESS\u003e\n```\n\nEnsure the new address has enough coins for tx fees to run in a pool.\nAs 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.\n\n## Updating the contracts/tokens\n\nChanges to the contract(parameters)/tokens can be done in three steps:\n\n- `prepare-update` command submits a new refresh box with the updated refresh contract;\n- `vote-update-pool` command submits oracle's ballot box voting for the changes;\n- `update-pool` command submits the update transaction, which produces a new pool box;\nEach of the step is described below. See also a detailed instruction on [Updating the epoch length](docs/update_epoch_length.md)\n\n### Create a new refresh box with `prepare-update` command\n\nCreate a YAML file describing what contract parameters should be updated.\nSee also an example of such YAML file at [Updating the epoch length](docs/update_epoch_length.md)\nRun:\n\n```console\noracle-core prepare-update \u003cYAML file\u003e\n```\n\nThis will generate `pool_config_updated.yaml` config file which should be used in `update-pool` command.\nThe 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.\n\n### Vote for contract update with `vote-update-pool` command\n\nRun\n\n```console\noracle-core vote-update-pool \u003cNEW_POOL_BOX_ADDRESS_HASH_STR\u003e \u003cUPDATE_BOX_CREATION_HEIGHT\u003e\n```\n\nWhere:\n\n- \u003cNEW_POOL_BOX_ADDRESS_HASH_STR\u003e - base16-encoded blake2b hash of the serialized pool box contract for the new pool box\n- \u003cUPDATE_BOX_CREATION_HEIGHT\u003e - The creation height of the existing update box.\n\nare required parameters, with optinal (in case of minting a new reward token):\n\n- \u003cREWARD_TOKEN_ID_STR\u003e - base16-encoded reward token id in the new pool box (use existing if unchanged)\n- \u003cREWARD_TOKEN_AMOUNT\u003e - reward token amount in the pool box at the time of update transaction is committed\n\nThey are printed in the output of the `prepare-update` command.\n\n### Update the pool box contract with `update-pool` command\n\nMake sure the `pool_config_updated.yaml` config file generated during the `prepare-update` command is in the same folder as the oracle-core binary.\nRun\n\n```console\noracle-core update-pool\n```\n\nWith optional(only if minted) parameters:\n  \u003cREWARD_TOKEN_ID_STR\u003e - base16-encoded reward token id in the new pool box (only if minted)\n  \u003cREWARD_TOKEN_AMOUNT\u003e - reward token amount in the pool box at the time of update transaction is committed (only if minted)\n\nThis will submit an update tx.\nAfter the update tx is confirmed and use `pool_config_updated.yaml` to run the oracle (i.e., rename it to `pool_config.yaml` and restart the oracle).\nDistribute the `pool_config.yaml` file to all the oracles.\n\n### Import update pool config with `import-pool-update` command\n\nMake sure the `pool_config_updated.yaml` config file generated during the `prepare-update` command is at hand.\nRun\n\n```console\noracle-core import-update-pool pool_config_updated.yaml\n```\n\nThis will update the pool_config.yaml. Restart the oracle afterwards.\n\n## How to run as systemd daemon\n\nTo run oracle-core as a systemd unit, the unit file in [systemd/oracle-core.service](systemd/oracle-core.service) should be installed.\nThe default configuration file path is ~/.config/oracle-core/oracle_config.yaml. This can be changed inside the .service file\n\n``` console\ncp systemd/oracle-core.service ~/.config/systemd/user/oracle-core.service\nsystemctl --user enable oracle-core.service\n```\n\n## Verifying contracts against EIP-23\n\nIt is recommended to check that the contracts used are indeed coming from EIP-23. Run the following command to get encoded hashes of each contract:\n\n```console\n./oracle-core print-contract-hashes\n```\n\nor if running from source files:\n\n```console\ncargo test check_contract_hashes -- --nocapture\n```\n\nCheck these values against those described in EIP-23.\n\n## Metrics\n\nPrometheus metrics are disabled by default and can be enabled by setting `metrics_port` parameter in the oracle config file.\nThe dashboard for Grafana is available in the `scripts` folder.\n\n## Ubuntu Install Instructions\n\nInstalling Ergo Oracle Core on Ubuntu 24.04 requires setting up a Rust environment and then building the off-chain component.\n\n### Install Prerequisites\nErgo Oracle Core is written in Rust. You must install the Rust toolchain and necessary system libraries:\n- System Dependencies:\n  ```bash\n     sudo apt update\n     sudo apt install build-essential libssl-dev pkg-config git\n  ```\n- Rust Toolchain: Install via rustup.rs:\n  ```bash\n     curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n     \"$HOME/.cargo/env\"\n- Check Rust installed:\n  ```bash\n     rustc --version\n  \n### Clone \u0026 Build Oracle core\n- Clone the Repository:\n  ``` bash\n      ~git clone https://github.com/ergoplatform/oracle-core\n      cd oracle-core\n- Build the binary:\n  ``` bash\n      cargo build --release\n  ```\n- The compiled binary will be located at ./target/release/oracle-core.\n\n### Setup Oracle Core\n1) Generate an oracle config file from the default template with:\n```bash\n   console\n   oracle-core generate-oracle-config\n```\n2) Edit the `oracle_config.yaml` and set the required parameters:\n- `change_address` - a node's address that will be used by this oracle-core instance(pay tx fees, keep tokens, etc.). Make sure it has the oracle tokens \u0026 enough ERG;\n- `node_url`: The URL of your Ergo node (e.g. ;\n- `oracle_network`: mainnet\n- `node_api_key`: YOUR_NODE_API_KEY  *note this isn't in the config file, you'll have to add this line*\n- `metrics port`: 9090 IF you plan on installing graphana to view the prebuilt oracle status dashboards\n- `oracle_secret`: null\n- `oracle_mnemonic`: null  *by setting this \"null\", you ensure that the application does **not** look for a mnemonic inside that file. Instead, it will search for the environment variable you are about to set\n\n3) How to use the `.secrets` file (the README method)\nTo avoid storing your mnemonic key in your terminal command nor shell history, follow this specific recommendation:\n- Create the hidden secrets file:\n  ```bash\n     nano .secrets\n- Add your mnemonic as an export command:\n  Inside the file, type:\n  ```bash\n     export ORACLE_WALLET_MNEMONIC=\"your tweleve or fifteen or however many word mnemonci phrase here\"\n     ```\n     **Save an exit (Ctrl+X)\n- Load the secrets into your environment:\n  ```bash\n     source .secrets\n  ```\n  *Note, you will need to run this command each new terminal or reboot of computer*\n\n4) Obtain a Pool Configuration - *if joining an existing pool* contact the pool operator to get their `pool_config.yaml` and place that in `/oracle-core/` folder\n5) Start the Oracle - *load your source secrets* from above; cd to folder and run command `oracle-core run`. IF everything is correct, you will see logs indicating the oracle is scanning for the pool box and waiting for the next epoch.\n   - on the second or third line you'll see \"Oracle Address derived from secret: 9xxxxxx\" \u003c\u003c\u003c ensure this matches your node wallet (otherwise you didn't input your mnemonic properly).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fergoplatform%2Foracle-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fergoplatform%2Foracle-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fergoplatform%2Foracle-core/lists"}