Skip to content

Commit 87ec66c

Browse files
JedayJeday
authored
Merge pull request #142 from lidofinance/develop
Develop
2 parents a20dedb + bea4366 commit 87ec66c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+12536
-1235
lines changed

‎.github/workflows/checks.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ jobs:
1616
cache: 'yarn'
1717

1818
- name: Install dependencies
19-
run: yarn --frozen-lockfile
19+
run: yarn --immutable
2020

2121
- name: Check Lint
2222
run: yarn lint

‎.github/workflows/deploy-pages.yml

+6-4
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,9 @@ jobs:
4545
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
4646
# If source files changed but packages didn't, rebuild from a prior cache.
4747
restore-keys: |
48-
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
48+
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}--${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
4949
- name: Install dependencies
50-
run: yarn --frozen-lockfile
50+
run: yarn --immutable
5151

5252
- name: Build
5353
run: yarn build
@@ -59,15 +59,17 @@ jobs:
5959
WALLETCONNECT_PROJECT_ID: ${{ vars.WALLETCONNECT_PROJECT_ID }}
6060
SUPPORTED_CHAINS: ${{ vars.SUPPORTED_CHAINS }}
6161
DEFAULT_CHAIN: ${{ vars.DEFAULT_CHAIN }}
62-
BASE_PATH: ${{ steps.config_pages.outputs.base_path }}
62+
BASE_PATH: ${{ steps.config_pages.outputs.base_path }}/playground
6363
- name: Export
6464
run: yarn build:export
6565
env:
6666
NODE_NO_BUILD_DYNAMICS: true
67+
- name: Move artifacts
68+
run: mkdir -p ./apps && mkdir -p ./apps/playground && mv ./playground/out/* ./apps/playground && mv ./docs/build/* ./apps
6769
- name: Upload artifact
6870
uses: actions/upload-pages-artifact@v3
6971
with:
70-
path: ./playground/out
72+
path: ./apps
7173

7274
# Deployment job
7375
deploy:

‎.github/workflows/publish-alpha.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ jobs:
2727
cache: 'yarn'
2828

2929
- name: Install dependencies
30-
run: yarn --frozen-lockfile
30+
run: yarn --immutable
3131

3232
- name: Build
3333
run: yarn build:packages

‎.github/workflows/publish.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ jobs:
2727
cache: 'yarn'
2828

2929
- name: Install dependencies
30-
run: yarn --frozen-lockfile
30+
run: yarn --immutable
3131

3232
- name: Build
3333
run: yarn build:packages

‎README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ For changes between versions see [CHANGELOG.MD](packages/sdk/CHANGELOG.md)
3131

3232
You can install the Lido Ethereum SDK using npm or yarn:
3333

34-
[Docs SDK package](packages/sdk/README.md)
34+
[Docs SDK package](https://lidofinance.github.io/lido-ethereum-sdk/)
3535

3636
```bash
3737
// SDK (stakes, wrap, withdrawals)
@@ -88,7 +88,7 @@ Replace "https://eth-goerli.alchemyapi.io/v2/{ALCHEMY_API_KEY}" with the address
8888

8989
## Examples
9090

91-
All examples and usage instructions can be found in the [Docs SDK package](packages/sdk/README.md).
91+
All examples and usage instructions can be found in the [Docs SDK package](https://lidofinance.github.io/lido-ethereum-sdk/).
9292

9393
```ts
9494
const lidoSDK = new LidoSDK({
@@ -120,8 +120,8 @@ For breaking changes between versions see [MIGRATION.md](packages/sdk/MIGRATION.
120120

121121
## Documentation
122122

123-
For additional information about available methods and functionality, refer to the [the documentation for the Lido Ethereum SDK](packages/sdk/README.md).
123+
For additional information about available methods and functionality, refer to the [the documentation for the Lido Ethereum SDK](https://lidofinance.github.io/lido-ethereum-sdk/).
124124

125125
## Playground
126126

127-
To check out SDK in action visit [playground](https://lidofinance.github.io/lido-ethereum-sdk/). Or tinker locally by cloning this repo and following [Playground instructions](playground/README.md).
127+
To check out SDK in action visit [playground](https://lidofinance.github.io/lido-ethereum-sdk/playground). Or tinker locally by cloning this repo and following [Playground instructions](playground/README.md).

‎docs/.gitignore

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎docs/babel.config.js

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎docs/docusaurus.config.ts

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
import { themes as prismThemes } from 'prism-react-renderer';
2+
import type { Config } from '@docusaurus/types';
3+
import type * as Preset from '@docusaurus/preset-classic';
4+
5+
const config: Config = {
6+
title: 'Lido Ethereum SDK',
7+
tagline:
8+
'Lido Ethereum SDK is a package that provides convenient tools for interacting with Lido contracts on the Ethereum network through a software development kit (SDK). This SDK simplifies working with Lido contracts and accessing their functionality',
9+
favicon: 'img/favicon.png',
10+
11+
// Set the production url of your site here
12+
url: 'https://lidofinance.github.io/',
13+
14+
baseUrl: '/lido-ethereum-sdk/',
15+
organizationName: 'lidofinance',
16+
projectName: 'lido-ethereum-sdk',
17+
18+
onBrokenLinks: 'throw',
19+
onBrokenMarkdownLinks: 'throw',
20+
21+
i18n: {
22+
defaultLocale: 'en',
23+
locales: ['en'],
24+
},
25+
plugins: [
26+
[
27+
'@docusaurus/plugin-content-docs',
28+
{
29+
id: 'examples',
30+
path: 'examples',
31+
routeBasePath: 'examples',
32+
sidebarPath: './sidebarsExamples.ts',
33+
},
34+
],
35+
],
36+
presets: [
37+
[
38+
'classic',
39+
{
40+
docs: {
41+
sidebarPath: './sidebarsSdk.ts',
42+
path: 'sdk',
43+
// Remove this to remove the "edit this page" links.
44+
editUrl: 'https://github.com/lidofinance/lido-ethereum-sdk',
45+
routeBasePath: '/',
46+
},
47+
blog: {
48+
showReadingTime: true,
49+
// Please change this to your repo.
50+
// Remove this to remove the "edit this page" links.
51+
editUrl: 'https://github.com/lidofinance/lido-ethereum-sdk',
52+
},
53+
} satisfies Preset.Options,
54+
],
55+
],
56+
57+
markdown: {
58+
mermaid: true,
59+
},
60+
themes: ['@docusaurus/theme-mermaid'],
61+
themeConfig: {
62+
image: 'img/package_logo.png',
63+
navbar: {
64+
title: 'Lido Ethereum SDK Docs',
65+
logo: {
66+
alt: 'Lido Ethereum SDK Logo',
67+
src: 'img/favicon.png',
68+
},
69+
items: [
70+
{
71+
type: 'docSidebar',
72+
sidebarId: 'sdkSidebar',
73+
position: 'left',
74+
label: 'Docs',
75+
},
76+
{ to: '/examples/intro', label: 'Examples', position: 'left' },
77+
{
78+
href: '/playground',
79+
label: 'Playground',
80+
position: 'left',
81+
target: '_blank',
82+
},
83+
{
84+
href: 'https://github.com/lidofinance/lido-ethereum-sdk',
85+
label: 'GitHub',
86+
position: 'right',
87+
},
88+
],
89+
},
90+
} satisfies Preset.ThemeConfig,
91+
};
92+
93+
export default config;

‎docs/examples/intro.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
sidebar_position: 1
3+
title: Introduction
4+
---
5+
6+
SDK usage examples for various practical cases.
7+
8+
## stETH rewards accounting
9+
10+
The provided examples are useful to establish robust accounting for the stETH rebaseable token, learn more about [stETH rebases](https://docs.lido.fi/contracts/lido/#rebase). For some complicated scenarios of using collective accounts for multiples users (might be applicable for CEXes and custodian services), see the suggested [reward attribution](https://hackmd.io/@lido/rewards-attribution) approaches.
11+
12+
### Basic rebase tracking
13+
14+
- [Example 1. Subscribe on the stETH token rebase events to track rewards updates](rewards/subscribe-on-events)
15+
- [Example 2. Get rewards accrued with the latest stETH token rebase for the chosen account](rewards/get-rewards.md)
16+
17+
### Reward history
18+
19+
- [Example 3. Retrieve reward history for the chosen account using the event logs (recommended)](rewards/retrieve-rewards-onchain.md)
20+
- [Example 4. Retrieve reward history for the chosen account using the Subgraph indexer (alternative way)](rewards/retrieve-rewards-subgraph.md)
21+
- [Example 5. Calculate the effective APR for the chosen account concerning the given period](rewards/calculate-effective-apr.md)
22+
- [Example 6. Keep track of rewards accrued for the set of accounts](rewards/keep-track-rewards.md)

‎docs/examples/rewards/_category_.json

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"label": "Rewards",
3+
"position": 2,
4+
"link": {
5+
"type": "generated-index"
6+
}
7+
}

‎docs/examples/rewards/calculate-effective-apr.md

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
sidebar_position: 6
3+
---
4+
5+
# Calculate the effective APR for the chosen account concerning the given period
6+
7+
## On-chain
8+
9+
[Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/averageAPRbyOnChain.ts)
10+
11+
### Requirements
12+
13+
- RPC provider (full node)
14+
15+
To calculate the effective APR for the address concerning the given period, you need:
16+
17+
- Calculate user's rewards for the period
18+
- Sum APR for each rebase event
19+
- Calculate the average APR for the period
20+
21+
Simplified code example:
22+
23+
```ts
24+
const rewardsQuery = await lidoSDK.rewards.getRewardsFromChain({
25+
address: mockAddress,
26+
stepBlock: 10000, // max blocks in 1 query - depend on the RPC capabilities and pricing plans
27+
back: {
28+
days: 1n,
29+
},
30+
includeOnlyRebases: true,
31+
});
32+
const totalAPR = rewardsQuery.rewards.reduce(
33+
(acc: number, reward: any) => acc + reward.apr,
34+
0,
35+
);
36+
37+
return totalAPR / rewards.length;
38+
```
39+
40+
## Subgraph
41+
42+
### Requirements
43+
44+
- The Graph API key
45+
46+
> **_NOTE:_** The subgraph deployed on The Graph Decentralized Network. The subgraph data is indexed and served by independent indexers on the network. Therefore, the performance of the subgraph may depend on the indexer selected at the time of the request.
47+
> Also, due to distributed indexers, the data in the subgraph may lag slightly behind the data in the on-chain network.
48+
49+
[Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/averageAPRbySubgraph.ts)
50+
51+
To calculate the effective APR for the address concerning the given period, you need:
52+
53+
- Calculate user's rewards for the period
54+
- Sum APR for each rebase event
55+
- Calculate the average APR for the period
56+
57+
Simplified code example:
58+
59+
```ts
60+
const rewardsQuery = await lidoSDK.rewards.getRewardsFromSubgraph({
61+
address: rewardsAddress,
62+
blocksBack: 10000,
63+
stepEntities: 500, // defaults to 1000, max entities per one request to endpoint
64+
includeOnlyRebases: true,
65+
getSubgraphUrl(graphId, chainId) {
66+
return `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/${id}`;
67+
},
68+
});
69+
const totalAPR = rewardsQuery.rewards.reduce(
70+
(acc: number, reward: any) => acc + reward.apr,
71+
0,
72+
);
73+
74+
return totalAPR / rewards.length;
75+
```

‎docs/examples/rewards/get-rewards.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Get rewards accrued with the latest stETH token rebase for the chosen account
6+
7+
## Requirements
8+
9+
- RPC provider
10+
11+
[Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/lastEvent.ts)
12+
13+
For the convenience of calculating user balances, it is proposed to use [`Shares`](https://docs.lido.fi/guides/lido-tokens-integration-guide#steth-internals-share-mechanics).
14+
15+
This case can be used to calculate rewards without having to subscribe to a Rebase event.
16+
The first thing you need to do is get the latest `TokenRebased` event to receive information about the token rebase. As soon as the event is received, it is necessary to calculate the change in the user’s balance. To do this you need to use the following formula:
17+
18+
```ts
19+
(balanceInShares * totalEther) / totalShares;
20+
```
21+
22+
Next, you need to calculate the user’s balance in stETH before the event (if unknown) and calculate the user’s balance in stETH after the event. The difference between these values will be the user’s reward for the rebase.
23+
24+
Simplified code example:
25+
26+
```ts
27+
// Get the last Rebase event
28+
const lastRebaseEvent = await sdk.events.stethEvents.getLastRebaseEvent();
29+
// Event arguments
30+
const { preTotalShares, preTotalEther, postTotalShares, postTotalEther } =
31+
lastRebaseEvent?.args;
32+
33+
// User's balance in shares before the event
34+
const balanceInShares = await lidoSDK.shares.balance(address); // for example, the value can be taken from the database
35+
// Calculation of the user's balance in stETH before the event
36+
const preBalanceStETH = (balanceInShares * preTotalEther) / preTotalShares;
37+
// Calculation of the user's balance in stETH after the event
38+
const postBalanceStETH = (balanceInShares * postTotalEther) / postTotalShares;
39+
40+
// Calculate user's balance change per Rebase event
41+
const rewardsInStETH = postBalanceStETH - preBalanceStETH;
42+
```

0 commit comments

Comments
 (0)