Skip to content

Osmosis Epoch and Rewards Indexing

Jump to bottom
pharr117 edited this page May 29, 2023 · 1 revision

We want to index and store information on Osmosis Epochs. This will allow us to support Osmosis-specific indexing requirements such as:

  1. Rewards distribution that takes place at fixed intervals
  2. Establishing a precedent for indexing the concept of "Epochs" in case the same principle can be applied to other blockchains that use similar logic for fixed-time execution of code

Osmosis Epochs

Definition

Epochs are on-chain timers that allow execution of code at fixed time intervals - source.

Epochs in Osmosis are defined primarily by an identifier and a duration. The identifier uniquely names the Epoch, while the duration specified how long an Epoch lasts.

As of the time of writing, Osmosis has 2 Epochs defined, the "day" and "week" epochs:

>> osmosisd query epochs epoch-infos --node https://osmosisarchive-rpc.quickapi.com:443 --output json | jq .       
{
  "epochs": [
    {
      "identifier": "day",
      "start_time": "2021-06-18T17:00:00Z",
      "duration": "86400s",
      "current_epoch": "709",
      "current_epoch_start_time": "2023-05-28T17:16:09.898160996Z",
      "epoch_counting_started": true,
      "current_epoch_start_height": "9835327"
    },
    {
      "identifier": "week",
      "start_time": "2021-06-18T17:00:00Z",
      "duration": "604800s",
      "current_epoch": "101",
      "current_epoch_start_time": "2023-05-26T17:02:07.229632445Z",
      "epoch_counting_started": true,
      "current_epoch_start_height": "9805295"
    }
  ]
}

Uses

The Osmosis codebase uses Epochs to execute code at particular times. Other Osmosis modules can hook into the Epoch module and setup code to be run on one of the identified Epochs.

For example:

  1. The Incentives module distributes staking rewards on an Epoch basis - source
  2. The Protorev module distributes MEV profits back to the community on an Epoch basis - source

Indexing Requirements

Why?

Indexing Osmosis Epochs will allow the application to do the following:

  1. Store and return indexed information for Epochs as a distinct data point
  2. Allow querying Blockchain data for events that occurred on specific Epochs such as:
    • Incentives module rewards distribution
    • Protorev module profit distribution

2-Phase Plan

Phase 1 - Index Epochs into their own table

Summary

We will index Osmosis Epochs into their own distinct table. The table model should be generalized enough to fit the needs of Blockchains that have a similar concept as Epochs (if any exist at all).

The Model should look like this at a rough glance:

Chain ID Start Height Identifier Epoch Number
1 7 day 7
1 1 week 1

Where:

  • Chain ID is the foreign key into the Chain table
  • Start Height is the Epoch's start height
  • Identifier is the unique ID of the Epoch
  • Epoch number is the data returned by the chain indicating which Epoch this is

This data can be gathered through the RPC query epoch epoch-infos provided by the Osmosis Epoch module.

You can query the Epoch module for Epochs at a given height using the --height <num> option:

>> osmosisd query epochs epoch-infos --height 9805294 --node https://osmosisarchive-rpc.quickapi.com:443 --output json | jq .
{
  "epochs": [
    {
      "identifier": "day",
      "start_time": "2021-06-18T17:00:00Z",
      "duration": "86400s",
      "current_epoch": "706",
      "current_epoch_start_time": "2023-05-25T17:16:09.898160996Z",
      "epoch_counting_started": true,
      "current_epoch_start_height": "9790555"
    },
    {
      "identifier": "week",
      "start_time": "2021-06-18T17:00:00Z",
      "duration": "604800s",
      "current_epoch": "100",
      "current_epoch_start_time": "2023-05-19T17:02:07.229632445Z",
      "epoch_counting_started": true,
      "current_epoch_start_height": "9700652"
    }
  ]
}

This information presents the following general guidance for indexing Epochs:

  1. We can index all Epochs with (as of time of writing) 709 queries.
  2. With no Epochs in the table, we get the current Epoch and index it.
  3. We then take that Epoch's current_epoch_start_height and subtract 1 from it.
  4. We use this new height as the query param to epochs epoch-infos --height <num> to get the previous Epoch info
  5. We repeat until we have indexed all Epochs

We could do this in a number of ways:

  1. Index all Epochs in one process - we would need to use the Epoch with the smallest "duration" value as the baseline, which will find all Epochs with larger durations.
  2. Index each Epoch Identifier in a separate process - For Osmosis, this means "day" and "week" Epochs will be handled using the same code but just do different calculations.

Development Requirements

The development requirements will be as follows:

  1. Design an Epoch RPC querying mechanism in Lens/Probe using Osmosis Epoch Querying endpoints
  2. Design the Models
  3. Design the application command to run the backwards indexing.

Phase 2 - Use Epochs in Osmosis Rewards Indexing

The current method of indexing rewards is purely sequential, going block by block and looking for Incentives module distribution events. This means rewards distribution currently requires ~9,000,000 RPC queries to index all rewards.

We can knock this down to (for Incentives module) N queries where N is the number of Epochs. We will gather the Epoch blocks from the indexed Epochs table, and query BlockResults on those particular heights to get that Epoch's rewards.

Clone this wiki locally