feat: add docusaurus docs, add deploy

.github/workflows/deploy-pages.yml

@@ -45,7 +45,7 @@ jobs:
           key: ${{ runner.os }}-nextjs-${{ hashFiles('**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
           # If source files changed but packages didn't, rebuild from a prior cache.
           restore-keys: |
-            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
+            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}--${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
       - name: Install dependencies
         run: yarn --frozen-lockfile
 
@@ -64,10 +64,12 @@ jobs:
         run: yarn build:export
         env:
           NODE_NO_BUILD_DYNAMICS: true
+      - name: Move artifacts
+        run: mkdir -p ./apps && mkdir -p ./apps/playground && mv ./playground/out/* ./apps/playground && mv ./docs/build/* ./apps
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./playground/out
+          path: ./apps
 
   # Deployment job
   deploy:

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+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

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

docs/docusaurus.config.ts

@@ -0,0 +1,93 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'Lido Ethereum SDK',
+  tagline:
+    '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',
+  favicon: 'img/favicon.png',
+
+  // Set the production url of your site here
+  url: 'https://lidofinance.github.io/',
+
+  baseUrl: '/',
+  organizationName: 'lidofinance',
+  projectName: 'lido-ethereum-sdk',
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'throw',
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+  plugins: [
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'examples',
+        path: 'examples',
+        routeBasePath: 'examples',
+        sidebarPath: './sidebarsExamples.ts',
+      },
+    ],
+  ],
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebarsSdk.ts',
+          path: 'sdk',
+          // Remove this to remove the "edit this page" links.
+          editUrl: 'https://github.com/lidofinance/lido-ethereum-sdk',
+          routeBasePath: '/',
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl: 'https://github.com/lidofinance/lido-ethereum-sdk',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  markdown: {
+    mermaid: true,
+  },
+  themes: ['@docusaurus/theme-mermaid'],
+  themeConfig: {
+    image: 'img/package_logo.png',
+    navbar: {
+      title: 'Lido Ethereum SDK Docs',
+      logo: {
+        alt: 'Lido Ethereum SDK Logo',
+        src: 'img/favicon.png',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'sdkSidebar',
+          position: 'left',
+          label: 'Docs',
+        },
+        { to: '/examples/intro', label: 'Examples', position: 'left' },
+        {
+          to: '/playground',
+          label: 'Playground',
+          position: 'left',
+          target: '_blank',
+        },
+        {
+          href: 'https://github.com/lidofinance/lido-ethereum-sdk',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

docs/examples/intro.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 1
+title: Introduction
+---
+
+SDK usage examples for various practical cases.
+
+## stETH rewards accounting
+
+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.
+
+### Basic rebase tracking
+
+- [Example 1. Subscribe on the stETH token rebase events to track rewards updates](rewards/subscribe-on-events)
+- [Example 2. Get rewards accrued with the latest stETH token rebase for the chosen account](rewards/get-rewards.md)
+
+### Reward history
+
+- [Example 3. Retrieve reward history for the chosen account using the event logs (recommended)](rewards/retrieve-rewards-onchain.md)
+- [Example 4. Retrieve reward history for the chosen account using the Subgraph indexer (alternative way)](rewards/retrieve-rewards-subgraph.md)
+- [Example 5. Calculate the effective APR for the chosen account concerning the given period](rewards/calculate-effective-apr.md)
+- [Example 6. Keep track of rewards accrued for the set of accounts](rewards/keep-track-rewards.md)

docs/examples/rewards/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Rewards",
+  "position": 2,
+  "link": {
+    "type": "generated-index"
+  }
+}

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

@@ -0,0 +1,75 @@
+---
+sidebar_position: 6
+---
+
+# Calculate the effective APR for the chosen account concerning the given period
+
+## On-chain
+
+[Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/averageAPRbyOnChain.ts)
+
+### Requirements
+
+- RPC provider (full node)
+
+To calculate the effective APR for the address concerning the given period, you need:
+
+- Calculate user's rewards for the period
+- Sum APR for each rebase event
+- Calculate the average APR for the period
+
+Simplified code example:
+
+```ts
+const rewardsQuery = await lidoSDK.rewards.getRewardsFromChain({
+  address: mockAddress,
+  stepBlock: 10000, // max blocks in 1 query - depend on the RPC capabilities and pricing plans
+  back: {
+    days: 1n,
+  },
+  includeOnlyRebases: true,
+});
+const totalAPR = rewardsQuery.rewards.reduce(
+  (acc: number, reward: any) => acc + reward.apr,
+  0,
+);
+
+return totalAPR / rewards.length;
+```
+
+## Subgraph
+
+### Requirements
+
+- The Graph API key
+
+> **_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.
+> Also, due to distributed indexers, the data in the subgraph may lag slightly behind the data in the on-chain network.
+
+[Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/averageAPRbySubgraph.ts)
+
+To calculate the effective APR for the address concerning the given period, you need:
+
+- Calculate user's rewards for the period
+- Sum APR for each rebase event
+- Calculate the average APR for the period
+
+Simplified code example:
+
+```ts
+const rewardsQuery = await lidoSDK.rewards.getRewardsFromSubgraph({
+  address: rewardsAddress,
+  blocksBack: 10000,
+  stepEntities: 500, // defaults to 1000, max entities per one request to endpoint
+  includeOnlyRebases: true,
+  getSubgraphUrl(graphId, chainId) {
+    return `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/${id}`;
+  },
+});
+const totalAPR = rewardsQuery.rewards.reduce(
+  (acc: number, reward: any) => acc + reward.apr,
+  0,
+);
+
+return totalAPR / rewards.length;
+```

docs/examples/rewards/get-rewards.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 3
+---
+
+# Get rewards accrued with the latest stETH token rebase for the chosen account
+
+## Requirements
+
+- RPC provider
+
+[Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/lastEvent.ts)
+
+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).
+
+This case can be used to calculate rewards without having to subscribe to a Rebase event.
+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:
+
+```ts
+(balanceInShares * totalEther) / totalShares;
+```
+
+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.
+
+Simplified code example:
+
+```ts
+// Get the last Rebase event
+const lastRebaseEvent = await sdk.events.stethEvents.getLastRebaseEvent();
+// Event arguments
+const { preTotalShares, preTotalEther, postTotalShares, postTotalEther } =
+  lastRebaseEvent?.args;
+
+// User's balance in shares before the event
+const balanceInShares = await lidoSDK.shares.balance(address); // for example, the value can be taken from the database
+// Calculation of the user's balance in stETH before the event
+const preBalanceStETH = (balanceInShares * preTotalEther) / preTotalShares;
+// Calculation of the user's balance in stETH after the event
+const postBalanceStETH = (balanceInShares * postTotalEther) / postTotalShares;
+
+// Calculate user's balance change per Rebase event
+const rewardsInStETH = postBalanceStETH - preBalanceStETH;
+```

docs/examples/rewards/intro.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+title: Introduction
+---
+
+# Case study: stETH rewards accounting with SDK
+
+## Introduction
+
+stETH is a [rebaseable ERC-20 token](https://docs.lido.fi/guides/lido-tokens-integration-guide/#what-is-steth) that represents ether staked with Lido.
+
+The integration of stETH into decentralized applications (dApps), protocols, CEXes, and custodian services, have additional requirements and considerations due to its rebasing mechanism.
+
+While stETH is designed to have the best UX for users (e.g., representing their staked ether amount at the moment with the balance), incorporating it into various platforms requires careful consideration of the reward attribution approaches.
+
+## Approach
+
+The SDK offers several methods for retrieving reward information.
+
+This is particularly useful in scenarios where recalculating user balances directly through the stETH token mechanism is not feasible.
+
+## Accounting model
+
+The proposed approach involves maintaining an accounting model based on stETH [shares](https://docs.lido.fi/guides/lido-tokens-integration-guide#bookkeeping-shares) rather than stETH balances. This model relies on tracking the individual account balance in shares. The same accounting model of shares is applicable for collective accounts (used for CEXes and custodian services), allowing participants to join and leave with precise share amounts, thus ensuring accurate reward attribution.
+
+## Implementation notes
+
+Token shares are managed at the contract level, with dedicated methods for handling share-related operations. Detailed documentation on these methods can be found in the [shares-related methods](https://docs.lido.fi/contracts/lido/#shares-related-methods) section.
+You can also use [SDK methods](/methods/shares) to work with users’ shares directly.
+
+## Usage
+
+For developers looking to integrate stETH rewards management into their applications, the Lido Ethereum SDK offers comprehensive interfaces and methods for shares and rewards estimation. Detailed examples and usage guidelines are provided in the [Lido Ethereum SDK documentation](/).
+
+By adopting this approach and leveraging the capabilities of the SDK, developers can effectively manage stETH rewards within their applications, ensuring a seamless user experience despite the complexities of the underlying rebasing mechanism.
+
+---
+
+> **_NOTE:_** Due to possibility of rounding errors on shares -> stETH conversion, events-based approach described below is intended for display purposes mostly, bookkeeping should be based on the stETH token shares. See also [1](https://docs.lido.fi/guides/lido-tokens-integration-guide/#1-2-wei-corner-case), [2](https://github.com/lidofinance/lido-dao/issues/442).
+
+The [Lido Ethereum SDK](/) has the full set of features in this regard:
+
+- [estimating APR](/methods/lido-statistics#getlastapr) for the latest token rebase.
+- [calculating average APR](/methods/lido-statistics#getsmaapr) over a selected period.
+- [last rebase event](/methods/lido-events#getlastrebaseevent) (contains share rate)
+- [first rebase event](/methods/lido-events#getfirstrebaseevent) starting from the reference point in the past
+- [get last N](/methods/lido-events#getlastrebaseevents) rebase events
+- [get all rebase events](/methods/lido-events#getrebaseevents) for the last N days
+- assessing specific rewards accrued over a chosen period by an address
+  - [On-chain](/methods/rewards#get-rewards-from-chain)
+  - [Subgraph](/methods/rewards#get-rewards-from-subgraph)
+- work with [user balances](/methods/shares) based on stETH shares