StakeWise Oracle

Oracles are responsible for submitting off-chain data of StakeWise pool validators from ETH2 beacon chain to the Oracles smart contract.

Installation

Prerequisites

• Python 3.8+
• pip3
• Geth v1.9.25+
• Prysm v1.0.5+

Option 1. Build oracle with native Python

pip3 install -r requirements/prod.txt

Option 2. Build oracle with virtualenv

For the virtualenv users, you can create a new venv:

python3 -m venv venv
source venv/bin/activate

and install the dependencies:

pip install -r requirements/prod.txt

Option 3. Build the docker image (see below to use the existing one)

Run the following command locally to build the docker image:

docker build --pull -t oracle .

Usage

Option 1. Use the existing docker image

Run the following command locally to start the oracle:

docker run --env-file ./settings.txt stakewiselabs/oracle:latest

where settings.txt is an environment file with Settings.

Option 2. Run with Python

Run the following command locally to start the oracle:

source ./settings.txt
python main.py

where settings.txt is an environment file with Settings.

Settings

Variable	Description	Required	Default
LOG_LEVEL	The log level of the program.	No	DEBUG
WEB3_WS_ENDPOINT	The WS endpoint to the ETH1 client. Must be specified if WEB3_HTTP_ENDPOINT endpoint is not provided.	No	-
WEB3_HTTP_ENDPOINT	The HTTP endpoint to the ETH1 client. Must be specified if WEB3_WS_ENDPOINT endpoint is not provided.	No	-
BEACON_CHAIN_RPC_ENDPOINT	The Beacon Chain RPC HTTP endpoint.	Yes	-
INJECT_POA_MIDDLEWARE	Whether to inject POA middleware into Web3 client (see POA middleware).	No	False
INJECT_STALE_CHECK_MIDDLEWARE	Whether to check for stale ETH1 blocks in Web3 client (see Stale check middleware).	No	False
STALE_CHECK_MIDDLEWARE_ALLOWABLE_DELAY	The time specified in seconds after which the block is considered stale in INJECT_STALE_CHECK_MIDDLEWARE middleware. Must be specified if INJECT_STALE_CHECK_MIDDLEWARE is set to True.	No	-
INJECT_RETRY_REQUEST_MIDDLEWARE	Whether to retry failed transactions (see Retry middleware).	No	False
INJECT_LOCAL_FILTER_MIDDLEWARE	Whether to store log event filters locally instead of storing on the ETH1 node (see Local middleware).	No	False
BALANCE_WARNING_THRESHOLD	The telegram notification will be sent when the oracle's balance will drop below such amount of ether.	Yes	-
BALANCE_ERROR_THRESHOLD	The program will exit with an error when the oracle's balance will drop below such amount of ether.	Yes	-
APPLY_GAS_PRICE_STRATEGY	Defines whether the gas strategy should be applied.	No	False
MAX_TX_WAIT_SECONDS	The preferred number of seconds the oracle is willing to wait for the transaction to mine. Will be applied only if APPLY_GAS_PRICE_STRATEGY is set to True.	No	120
TRANSACTION_TIMEOUT	The maximum number of seconds the oracle is willing to wait for the transaction to mine. After that it will throw time out error.	Yes	-
POOL_CONTRACT_ADDRESS	The address of the Pool Contract.	Yes	-
ORACLES_CONTRACT_ADDRESS	The address of the Oracle Contract.	Yes	-
REWARD_ETH_CONTRACT_ADDRESS	The address of the Reward ETH Token Contract.	Yes	-
STAKED_ETH_CONTRACT_ADDRESS	The address of the Staked ETH Token Contract.	Yes	-
ORACLE_PRIVATE_KEY	The ETH1 private key of the operator (see Generating Private Key below).	Yes	-
NOTIFIERS_TELEGRAM_TOKEN	Telegram chat token where notifications about low balance or errors will be sent.	Yes	-
NOTIFIERS_TELEGRAM_CHAT_ID	Telegram chat ID where notifications about low balance or errors will be sent.	Yes	-
PROCESS_INTERVAL	How long to wait before processing again.	Yes	-

Example settings

cat >./settings.txt <<EOL
WEB3_WS_ENDPOINT=ws://localhost:8546
BEACON_CHAIN_RPC_ENDPOINT=http://localhost:4000
INJECT_STALE_CHECK_MIDDLEWARE=False
STALE_CHECK_MIDDLEWARE_ALLOWABLE_DELAY=120
INJECT_RETRY_REQUEST_MIDDLEWARE=True
BALANCE_WARNING_THRESHOLD=0.05
BALANCE_ERROR_THRESHOLD=0.008
APPLY_GAS_PRICE_STRATEGY=True
MAX_TX_WAIT_SECONDS=180
TRANSACTION_TIMEOUT=3600
PROCESS_INTERVAL=30
ORACLES_CONTRACT_ADDRESS=0x2f1C5E86B13a74f5A6E7B4b35DD77fe29Aa47514
POOL_CONTRACT_ADDRESS=0xC874b064f465bdD6411D45734b56fac750Cda29A
REWARD_ETH_CONTRACT_ADDRESS=0x20BC832ca081b91433ff6c17f85701B6e92486c5
STAKED_ETH_CONTRACT_ADDRESS=0xFe2e637202056d30016725477c5da089Ab0A043A
ORACLE_PRIVATE_KEY=0x<private_key>
NOTIFIERS_TELEGRAM_TOKEN=12345token
NOTIFIERS_TELEGRAM_CHAT_ID=123456
EOL

Generating Private Key

source venv/bin/activate
python -c "from web3 import Web3; w3 = Web3(); acc = w3.eth.account.create(); print(f'private key={w3.toHex(acc.privateKey)}, account={acc.address}')"