Merge pull request #167 from lidofinance/develop

v3.5.0

.github/workflows/checks.yml

@@ -40,4 +40,6 @@ jobs:
           TEST_PRIVATE_KEY: ${{ secrets.TEST_PRIVATE_KEY }}
           TEST_CHAIN_ID: ${{ vars.TEST_CHAIN_ID }}
           TEST_RPC_URL: ${{ secrets.TEST_RPC_URL }}
+          TEST_L2_CHAIN_ID: ${{ vars.TEST_L2_CHAIN_ID }}
+          TEST_L2_RPC_URL: ${{ secrets.TEST_L2_RPC_URL }}
           TEST_SUBGRAPH_URL: ${{ secrets.TEST_SUBGRAPH_URL }}

.github/workflows/publish-dry-run.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   publish-dry-run:
     runs-on: ubuntu-latest
-    environment: development
+    environment: pre-publish
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
@@ -31,14 +31,16 @@ jobs:
         run: yarn build:packages
 
       - name: Dry run Publish
-        run: yarn multi-semantic-release --dry-run --silent | grep -E '#|###|\*'  > dry_run_output.txt
+        run: |
+          yarn multi-semantic-release --dry-run --silent > /tmp/multi-semantic-release-output
+          grep -E '#|###|\*' /tmp/multi-semantic-release-output > dry_run_output.txt || [ $? -eq 1 ]
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Write results to summary
         run: |
-          if [ -s dry_run_output.txt ]; then 
+          if [ -s dry_run_output.txt ]; then
             echo "# Packages to be published:" >> $GITHUB_STEP_SUMMARY
             cat dry_run_output.txt >> $GITHUB_STEP_SUMMARY
           else

docs/examples/rewards/intro.md

@@ -26,7 +26,7 @@ The proposed approach involves maintaining an accounting model based on stETH [s
 ## 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.
+You can also use [SDK methods](/modules/shares) to work with users’ shares directly.
 
 ## Usage
 
@@ -40,13 +40,13 @@ By adopting this approach and leveraging the capabilities of the SDK, developers
 
 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
+- [estimating APR](/modules/lido-statistics#getlastapr) for the latest token rebase.
+- [calculating average APR](/modules/lido-statistics#getsmaapr) over a selected period.
+- [last rebase event](/modules/lido-events#getlastrebaseevent) (contains share rate)
+- [first rebase event](/modules/lido-events#getfirstrebaseevent) starting from the reference point in the past
+- [get last N](/modules/lido-events#getlastrebaseevents) rebase events
+- [get all rebase events](/modules/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
+  - [On-chain](/modules/rewards#get-rewards-from-chain)
+  - [Subgraph](/modules/rewards#get-rewards-from-subgraph)
+- work with [user balances](/modules/shares) based on stETH shares

docs/examples/rewards/retrieve-rewards-onchain.md

@@ -11,7 +11,7 @@ sidebar_position: 4
 [Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/rewardsOnChain.ts)
 
 Information about the user’s rewards can be calculating from on-chain using SDK without the need to calculate using a formula.
-To do this, you need to use the `getRewardsFromChain` method ([Docs](/methods/rewards))
+To do this, you need to use the `getRewardsFromChain` method ([Docs](/modules/rewards))
 The method allows you to request rewards for a certain period of time (days, seconds, blocks)
 
 Simplified code example:

docs/examples/rewards/retrieve-rewards-subgraph.md

@@ -14,7 +14,7 @@ sidebar_position: 5
 [Implementation example](https://github.com/lidofinance/lido-ethereum-sdk/blob/main/examples/rewards/src/rewardsSubgraph.ts)
 
 Information about the user’s rewards can be obtained from off-chain using SDK without the need for calculation using a formula.
-To do this, you need to use the `getRewardsFromSubgraph` method [[Docs](/methods/rewards)]. You will also need a key to access `The Graph`. ([Docs](https://docs.lido.fi/integrations/subgraph/))
+To do this, you need to use the `getRewardsFromSubgraph` method [[Docs](/modules/rewards)]. You will also need a key to access `The Graph`. ([Docs](https://docs.lido.fi/integrations/subgraph/))
 
 Simplified code example:
 

docs/examples/rewards/subscribe-on-events.md

@@ -20,7 +20,7 @@ The first thing you need to do is subscribe to the `TokenRebased` event to recei
 
 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 rewards for the rebase.
 
-Docs: [Shares](/methods/shares)
+Docs: [Shares](/modules/shares)
 Simplified code example:
 
 ```ts

docs/lidoPulse/get-started/usage.md

@@ -15,7 +15,7 @@ To form a JSON-RPC request, you need to specify:
 - `params`: The parameters required by the method.
 - `id`: A unique identifier for the request.
 
-The method names and their required parameters can be found in the [Lido SDK documentation](/category/methods).
+The method names and their required parameters can be found in the [Lido SDK documentation](/category/modules).
 
 ## Example JSON-RPC Request
 

docs/sdk/intro.md

@@ -18,11 +18,11 @@ For changes between versions see [CHANGELOG.MD](https://github.com/lidofinance/l
 
 ## Installation
 
-You can install the Lido Ethereum SDK using npm or yarn:
+You can install the Lido Ethereum SDK using npm or yarn. `viem` is required as a peer dep:
 
 ```bash
 // SDK (stakes, wrap, withdrawals)
-yarn add @lidofinance/lido-ethereum-sdk
+yarn add viem @lidofinance/lido-ethereum-sdk
 ```
 
 ## Usage
@@ -107,7 +107,7 @@ For breaking changes between versions see [MIGRATION.md](https://github.com/lido
 
 ## Documentation
 
-For additional information about available methods and functionality, refer to the [the documentation for the Lido Ethereum SDK](/category/methods).
+For additional information about available methods and functionality, refer to the [the documentation for the Lido Ethereum SDK](/category/modules).
 
 ## Playground
 

docs/sdk/methods/_category_.json → docs/sdk/modules/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Methods",
+  "label": "Modules",
   "position": 3,
   "link": {
     "type": "generated-index"

docs/sdk/modules/l2.md

@@ -0,0 +1,131 @@
+---
+sidebar_position: 14
+---
+
+# L2
+
+Modules exposes Lido MultiChain deployments. [See full info here](https://lido.fi/lido-multichain).
+
+## LidoSDKL2
+
+This is core module for all L2 functionality. It will throw error if used on with chains that are not currently supported.
+
+| **Chain**        | **wsETH** | **stETH+(un)Wrap** |
+| ---------------- | --------- | ------------------ |
+| Optimism Sepolia | ✅        | ✅                 |
+| Optmism          | ✅        | ✅                 |
+| 🔜               |           |                    |
+
+Use this helper to understand which contracts are supported on chain:
+
+```ts
+import {
+  LidoSDKL2,
+  LIDO_L2_CONTRACT_NAMES,
+  CHAINS,
+} from '@lidofinance/lido-ethereum-sdk';
+
+LidoSDKL2.isContractAvailableOn(
+  LIDO_L2_CONTRACT_NAMES.wsteth,
+  CHAINS.OptimismSepolia,
+); // true
+// Example
+LidoSDKL2.isContractAvailableOn(LIDO_L2_CONTRACT_NAMES.steth, CHAINS.Arbitrum); // false
+```
+
+### Fields
+
+- `wsteth`: see [LidoSDKL2Wsteth](#lidosdkl2wsteth)
+- `steth`: see [LidoSDKL2Steth](#lidosdkl2steth)
+
+### Methods
+
+On L2 with stETH deployments bridged wstETH is wrapped to stETH. And stETH is unwrapped to wstETH. Those semantics are upkept in SDK with more explicit naming. See [LIP-22](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-22.md#rebasable-token-steth-on-l2) for more details.
+
+#### Wrap bridged wstETH to stETH
+
+To wrap stETH you first need to approve stETH to wrap contract:
+
+```ts
+import { LidoSDK } from '@lidofinance/lido-ethereum-sdk';
+
+const lidoSDK = new LidoSDK({
+  rpcUrls: ['https://rpc-url'],
+  chainId: 11155420, // OP sepolia
+  web3Provider: LidoSDKCore.createWeb3Provider(11155420, window.ethereum),
+});
+
+// get existing allowance
+const allowance = await lidoSDK.l2.getWstethForWrapAllowance();
+
+// if value is more than allowance perform approve
+if (allowance < value) {
+  const approveResult = await lidoSDK.wrap.approveWstethForWrap({
+    value,
+    callback,
+  });
+}
+
+// wrap wstETH
+const wrapTx = await lidoSDK.wrap.wrapWstethToSteth({ value, callback });
+
+const { stethReceived, wstethWrapped } = wrapTx.results;
+```
+
+#### Unwrap stETH to wstETH
+
+```ts
+// unwrap stETH to receive wstETH
+const unwrapTx = await lidoSDK.l2.unwrapStethToWsteth({
+  value: unwrapAmount,
+  callback,
+});
+
+console.log(unwrapTx.result.stethUnwrapped, unwrapTx.result.wstethReceived);
+```
+
+### Wrap utilities
+
+For all transaction methods helper methods are available similar to `stake` module:
+
+- `...populateTX`: returns ready to sign transaction object with all data encoded
+- `...simulateTX`: performs dry-ran of the transaction to see if it will execute on the network
+
+## LidoSDKL2Wsteth
+
+This submodule is built on top of existing ERC20 modules and has extra functionality. See docs for all [ERC20 related methods](./w-steth.md).
+For original L2 ABI functionality use `.getL2Contract()` and get raw Viem contract instance.
+
+## LidoSDKL2Steth
+
+This submodule is built on top of existing ERC20 modules but has extra L2 stETH related features. See docs for all [ERC20 related methods](./w-steth.md).
+For original L2 ABI functionality use `.getL2Contract()` and get raw Viem contract instance.
+
+```ts
+import { LidoSDK } from '@lidofinance/lido-ethereum-sdk';
+
+const lidoSDK = new LidoSDK({
+  rpcUrls: ['https://rpc-url'],
+  chainId: 11155420, // OP sepolia
+  web3Provider: LidoSDKCore.createWeb3Provider(11155420, window.ethereum),
+});
+
+// balance of stETH for account in shares
+const balanceShares = await lidoSDK.l2.steth.balanceShares(address);
+
+// transferring shares is equivalent to transferring corresponding amount of stETH
+const transferTx = await lidoSDK.l2.steth.transferShares({
+  account,
+  amount,
+  to,
+});
+
+// converting stETH amount to shares trough on-chain call based on actual share rate
+// This also can be used to convert stETH to wstETH as 1 wstETH = 1 share
+const shares = await lidoSDK.l2.steth.convertToShares(1000n);
+// reverse
+const steth = await lidoSDK.l2.steth.convertToSteth(1000n);
+
+// total supply of shares and ether in protocol
+const totalShares = await lidoSDK.totalShares();
+```

docs/sdk/methods/rewards.md → docs/sdk/modules/rewards.md

@@ -10,11 +10,11 @@ y
 ## Common Options
 
 - **address** - (Type: Address) address of an account you want to query rewards for
-- **to** (Type: [`blockType`](/methods/lido-events#getrebaseevents)) defaults to `{block: "latest"}`, upper bound for query
+- **to** (Type: [`blockType`](/modules/lido-events#getrebaseevents)) defaults to `{block: "latest"}`, upper bound for query
 
-- **from** (Type: [`blockType`](/methods/lido-events#getrebaseevents)) lower bound for query
+- **from** (Type: [`blockType`](/modules/lido-events#getrebaseevents)) lower bound for query
   or
-- **back** (Type: [`backType`](/methods/lido-events#getrebaseevents)) alternative way to define lower bound relative to `to`
+- **back** (Type: [`backType`](/modules/lido-events#getrebaseevents)) 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

examples/erlang-bridge/package.json

@@ -9,6 +9,6 @@
   },
   "dependencies": {
     "@lidofinance/lido-ethereum-sdk": "workspace:*",
-    "viem": "^2.0.6"
+    "viem": "^2.21.9"
   }
 }

examples/rewards/package.json

@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@lidofinance/lido-ethereum-sdk": "workspace:*",
-    "viem": "^2.0.6"
+    "viem": "^2.21.9"
   },
   "devDependencies": {
     "rimraf": "^5.0.5",

packages/lido-pulse/package.json

@@ -53,7 +53,7 @@
     "fastify": "^4.28.1",
     "fastify-plugin": "^4.5.1",
     "reflect-metadata": "^0.2.2",
-    "viem": "^2.0.6"
+    "viem": "^2.21.9"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",

packages/sdk/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 3.5.0
+
+## Breaking change
+
+- `viem` is no longer an internal dependency and is listed as peer dependency
+
+## SDK
+
+### Added
+
+- `LidoSDKL2` module is added to support Lido on L2 networks functionality
+- `Optimism` and `Optimism-sepolia` chains are added as separate L2 chains
+- `core.getL2ContractAddress` and `LIDO_L2_CONTRACT_NAMES enum` are added to support l2 contracts
+- ABIs are exported from corresponding modules to support custom functionality and direct viem access
+
+### Fixed
+
+- `multicall` is used only if supported by client
+
+## Playground
+
+- L2 and updated reef-knot support
+
 # 3.4.0
 
 ## SDK

packages/sdk/MIGRATION.md

@@ -1,3 +1,7 @@
+# Migrating from V3 -> V4
+
+- `viem` is now a peer dependency and you will need to install it separately.
+
 # Migrating from V2 -> V3
 
 ## Common

packages/sdk/package.json

@@ -71,6 +71,11 @@
       "default": "./dist/cjs/shares/index.js",
       "types": "./dist/types/shares/index.d.ts"
     },
+    "./l2": {
+      "import": "./dist/esm/l2/index.js",
+      "default": "./dist/cjs/l2/index.js",
+      "types": "./dist/types/l2/index.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -104,6 +109,9 @@
       ],
       "shares": [
         "./dist/types/shares/index.d.ts"
+      ],
+      "l2": [
+        "./dist/types/l2/index.d.ts"
       ]
     }
   },
@@ -145,8 +153,10 @@
   "dependencies": {
     "@ethersproject/bytes": "^5.7.0",
     "graphql": "^16.8.1",
-    "graphql-request": "^6.1.0",
-    "viem": "^2.0.6"
+    "graphql-request": "^6.1.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.21"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",