Oracle service for LiDo liquid staking. Collects staking parameters from relay chain and reports to the parachain liquid staking module.
- Upon the start daemon determines the reportable era and retrieves the list of stash accounts to report for.
- If no stash accounts were found, waits for the beginning of the next era. Otherwise, daemon starts collections staking parameters for each stash account separately, signs and sends transaction to the oracle contract.
- After a report has been sent for all stash accounts, it moves on to waiting for the next era.
- Running relay chain node, from which the staking parameters are read.
- Running parachain node with contracts deployed.
- ABI for the OracleMaster contract (see above).
- Python 3.7+
- The application functions as a linux service under systemd or as a docker container.
python -m pip install --upgrade pip
pip install -r requirements.txtBy default, the assets directory contains oracle ABI and the service tries to get it from the assets/oracle.json file, but you can change it as follows:
- Clone
lido-dot-ksmrepository. - Run the
brownie compilecommand. - Copy the contents of the
build/contracts/OracleMaster.jsonwith the 'abi' key toassets/oracle.jsonor change theABI_PATHenvironment variable (see below).
The service receives its configuration parameters from environment variables. Export required parameters from this list and start the service:
./oracleservice/start.pyTo stop the service, send a SIGINT or SIGTERM signal to the process.
WS_URL_RELAY- WS URL of relay chain node. Required.WS_URL_PARA- WS URL of parachain node. Required.CONTRACT_ADDRESS- OracleMaster contract address. Required. Example:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84.ORACLE_PRIVATE_KEY_PATH- The path to the oracle private key file. Required if theORACLE_PRIVATE_KEYparameter is not specified.ORACLE_PRIVATE_KEY- Oracle private key, 0x prefixed. Used if there is no file with the key. Required if theORACLE_PRIVATE_KEY_PATHis not specified.ABI_PATH- Path to ABI file. The default value isassets/oracle.json.GAS_LIMIT- The predefined gas limit for composed transaction. The default value is10000000.MAX_PRIORITY_FEE_PER_GAS- The maxPriorityFeePerGas transaction parameter. The default value is0.FREQUENCY_OF_REQUESTS- The frequency of sending requests to receive the active era in seconds. The default value is180.MAX_NUMBER_OF_FAILURE_REQUESTS- If the number of failure requests exceeds this value, the node (relay chain or parachain) is blacklisted for TIMEOUT seconds during recovery mode. The default value is 10.TIMEOUT- The time in seconds the failure node stays in the black list in recovery mode. The default value is60.ERA_DURATION_IN_SECONDS- The duration of era in seconds. Needed for setting the SIGALRM timer. The default value is180. Required.ERA_DURATION_IN_BLOCKS- The duration of era in blocks. The default value is30. Required.SS58_FORMAT- The default value is42. Required.TYPE_REGISTRY_PRESET- The default value iskusama. Required.REST_API_SERVER_IP_ADDRESS- REST API server IP address. The default value is0.0.0.0.REST_API_SERVER_PORT- REST API server port. The default value is800.LOG_LEVEL_STDOUT- Logging level of the logging module:DEBUG,INFO,WARNING,ERRORorCRITICAL. The default level isINFO.ORACLE_MODE- If the value isDEBUG, the oracle will not send transactions, but only prepare a report.ERA_UPDATE_DELAY- The maximum delay in seconds with which an era can be updated before the service stops working. The default value is360.ERA_DELAY_TIME- The maximum delay in seconds with which an era can be updated comparing to the OracleMaster before the service stops working. The default value is600.WAITING_TIME_BEFORE_SHUTDOWN- Waiting time in seconds before shutdown the service. The default value is600.
The Prometheus exporter provides the following metrics.
| name | description | frequency |
|---|---|---|
| agent Info |
The address of the connected relay chain node | Each reconnection |
| is_recovery_mode_active Gauge |
Is oracle-service in recovery mode or not: 1, if the recovery mode, otherwise - the default mode | Starting and ending recovery mode |
| active_era_id Gauge |
Active era index | Every change of era |
| last_era_reported Gauge |
The last era that the Oracle has reported | After completing a sending of reports for an era |
| last_failed_era Gauge |
The last era for which sending the report ended with a revert | During sending a report for an era |
| previous_era_change_block_number Gauge |
Block number of the previous era change | Every change of era, if at least one stash account was found |
| time_elapsed_until_last_era_report Gauge |
The time elapsed until the last report from the UNIX epoch in seconds | After each successful sending of a report |
| total_stashes_free_balance Gauge |
Total free balance of all stash accounts for the era | Every time a new report is generated |
| oracle_balance Gauge |
Oracle balance | Every change of era |
| tx_revert Histogram |
Number of failed transactions | Every unsuccessful sending of a report |
| tx_success Histogram |
Number of successful transactions | Every successful sending of a report |
| para_exceptions_count Counter |
Parachain exceptions count | Every exception in the parachain |
| relay_exceptions_count Counter |
Relay chain exceptions count | Every exception in relay chain |
Prometheus metrics are provided by URL '/metrics'.
The status of the oracle is provided by URL '/healthcheck'. The following states are possible:
- not working - the service is in parameter preparation mode;
- starting - the service is starting but has not yet started monitoring the event;
- monitoring - the service is monitoring the event;
- processing - the service is preparing data for a report or sending a transaction;
- recovering - the service is in recovery mode.