From f9eb30060632b389c2ece75a5681cc2443c7bbdd Mon Sep 17 00:00:00 2001 From: Coach Chuck Date: Wed, 15 May 2024 14:41:50 -0500 Subject: [PATCH] added readme --- keepers/validator-keeper/README.md | 51 ++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 keepers/validator-keeper/README.md diff --git a/keepers/validator-keeper/README.md b/keepers/validator-keeper/README.md new file mode 100644 index 00000000..2c79d9c8 --- /dev/null +++ b/keepers/validator-keeper/README.md @@ -0,0 +1,51 @@ +## Keeper State +The `KeeperState` keeps track of: +- current epoch data +- running tally of all operations successes and failures for the given epoch +- all accounts fetched from the RPC that are needed downstream + +Note: All maps are key'd by the `vote_account` + +## Program + +### Initialize +Gather all needed arguments, and initialize the global `KeeperState`. + +### Loop +The forever loop consists of two parts: **Fetch** and **Fire**. There is only ever one **Fetch** section, and there can be several **Fire** sections. + +The **Fire** sections can run on independent cadences - say we want the Validator History functions to run every 300sec and we want to emit metrics every 60sec. + +The **Fetch** section is run _before_ and **Fire** section. + +#### Fetch +The **Fetch** section is in charge of three operations: +- Keeping track of the current epoch and resetting the runs and error counts for each operation +- Creating any missing accounts needed for the downstream **Fires** to run +- Fetching and updating all of the needed accounts needed downstream + +This is accomplished is by running three functions within the **Fetch** section +- `pre_create_update` - Updates epoch, and fetches all needed accounts that are not dependant on any missing accounts. +- `create_missing_accounts` - Creates the missing accounts, which can be determined by the accounts fetched in the previous step +- `post_create_update` - Fetches any last accounts that needed the missing accounts + +Since this is run before every **FIRE** section, some accounts will be fetched that are not needed. This may seem wasteful but the simplicity of having a synchronized global is worth the cost. + +Notes: +- The **Fetch** section is the only section that will mutate the `KeeperState`. +- If anything in the **Fetch** section fails, no **Fires** will run + +#### Fire +There are several **Fire** sections running at their own cadence. Before any **Fire** section is run, the **Fetch** section will be called. + +Each **Fire** is a call to `operations::operation_name::fire_and_emit` which will fire off the operation, emit the data points and return the new count of runs and errors for that operation to be saved in the `KeeperState` + +Notes: +- Each **Fire** is self contained, one should not be dependant on another. +- No **Fire* will fetch any accounts, if there are needs for them, they should be added to the `KeeperState` + + + + + +