Rewards

This module allows you to query historical rewards data for given address via chain events or subgraph. y

Common Options

• address - (Type: Address) address of an account you want to query rewards for

• to (Type: blockType) defaults to {block: "latest"}, upper bound for query

• from (Type: blockType) lower bound for query or

• back (Type: backType) alternative way to define lower bound relative to to

• includeZeroRebases [default: false ] - include rebase events when users had no rewards(because of empty balance)

• includeOnlyRewards [default: false ] - include only rebase events

Common Return

type RewardsResult = {
  // pre query states
  baseBalance: bigint;
  baseBalanceShares: bigint;
  baseShareRate: number;
  // commutative rewards in stETH
  totalRewards: bigint;
  // computed block numbers
  fromBlock: bigint;
  toBlock: bigint;
  // query result in block/logIndex ascending order
  rewards: {
    type: 'submit' | 'withdrawal' | 'rebase' | 'transfer_in' | 'transfer_out';
    change: bigint; // negative or positive change in stETH
    changeShares: bigint; // same in shares
    balance: bigint; // post event balance in stETH
    balanceShares: bigint; // same in shares
    shareRate: number; // apx share rate at a time of event
    apr?: number; // apr for rebase events
    originalEvent: RewardsChainEvents | RewardsSubgraphEvents ; // original event from chain/subgraph, contains extra info
  }[]
};

Get Rewards from chain

This method heavily utilizes RPC fetching chain event logs. It's better suited for smaller,recent queries. Beware that this might cause rate limit issues on free RPC endpoints.

import { LidoSDK } from '@lidofinance/lido-ethereum-sdk';
import { http, createPublicClient, hoodi } from 'viem';

const lidoSDK = new LidoSDK({
  publicClient: createPublicClient({
    chain: hoodi,
    transport: http('<RPC_URL>'),
  }),
});

const rewardsQuery = await lidoSDK.rewards.getRewardsFromChain({
  address: rewardsAddress,
  stepBlock: 10000, // defaults to 50000, max block range per 1 query
  back: {
    days: 10n,
  },
});

console.log(rewardsQuery.rewards);

Get Rewards from subgraph

This method requires you to provide API URL to send subgraph requests to. It's better suited for larger, more historical queries.

Important notes

• to is capped by last indexed block in subgraph. Block number is available in result object by lastIndexedBlock.
• getSubgraphUrl can also return object of type {url:string,requestHeaders?: Record<string,string> } that is passed to graphql-request for extra configurability

import { LidoSDK } from '@lidofinance/lido-ethereum-sdk';
import { http, createPublicClient } from 'viem';

const lidoSDK = new LidoSDK({
  publicClient: createPublicClient({
    chain: hoodi,
    transport: http('<RPC_URL>'),
  }),
});

const rewardsQuery = await lidoSDK.rewards.getRewardsFromSubgraph({
  address: rewardsAddress,
  blocksBack: 10000,
  stepEntities: 500, // defaults to 1000,  max entities per one request to endpoint
  getSubgraphUrl(graphId, chainId) {
    return `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/${id}`;
  },
});

console.log(rewardsQuery.rewards);