Merge pull request #164 from lidofinance/feature/si-1524-steth-on-opt…

…imism-in-sdk

Docs and optimism

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

@@ -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

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/src/common/constants.ts

@@ -24,12 +24,12 @@ export const SUPPORTED_CHAINS: CHAINS[] = [
   CHAINS.Mainnet,
   CHAINS.Holesky,
   CHAINS.Sepolia,
+  CHAINS.Optimism,
   CHAINS.OptimismSepolia,
 ];
 
 export const SUBMIT_EXTRA_GAS_TRANSACTION_RATIO = 1.05;
 export const GAS_TRANSACTION_RATIO_PRECISION = 10 ** 7;
-export const ESTIMATE_ACCOUNT = '0x87c0e047F4e4D3e289A56a36570D4CB957A37Ef1';
 
 export const LIDO_LOCATOR_BY_CHAIN: {
   [key in CHAINS]?: Address;
@@ -95,6 +95,7 @@ export const LIDO_L2_CONTRACT_ADDRESSES: {
   },
   [CHAINS.Optimism]: {
     wsteth: '0x1F32b1c2345538c0c6f582fCB022739c4A194Ebb',
+    steth: '0x76A50b8c7349cCDDb7578c6627e79b5d99D24138',
   },
 };
 

packages/sdk/src/l2/__test__/l2.test.ts

@@ -177,7 +177,7 @@ describe('LidoSDKL2 wrap', () => {
     const stethAddress = l2.core.getL2ContractAddress(
       LIDO_L2_CONTRACT_NAMES.steth,
     );
-    const tx = await l2.unwrapPopulateTx({ value });
+    const tx = await l2.unwrapStethPopulateTx({ value });
     expectAddress(tx.to, stethAddress);
     expectAddress(tx.from, account.address);
     expectPopulatedTx(tx, undefined);
@@ -188,7 +188,7 @@ describe('LidoSDKL2 wrap', () => {
     const stethAddress = l2.core.getL2ContractAddress(
       LIDO_L2_CONTRACT_NAMES.steth,
     );
-    const tx = await l2.unwrapSimulateTx({ value });
+    const tx = await l2.unwrapStethSimulateTx({ value });
     expectAddress(tx.address, stethAddress);
   });
 
@@ -197,7 +197,10 @@ describe('LidoSDKL2 wrap', () => {
     const stethBalanceBefore = await l2.steth.balance(account.address);
     const wstethBalanceBefore = await l2.wsteth.balance(account.address);
     const mock = jest.fn();
-    const tx = await l2.unwrap({ value: stethValue, callback: mock });
+    const tx = await l2.unwrapStethToWsteth({
+      value: stethValue,
+      callback: mock,
+    });
     expectTxCallback(mock, tx);
     const stethBalanceAfter = await l2.steth.balance(account.address);
     const wstethBalanceAfter = await l2.wsteth.balance(account.address);

packages/sdk/src/l2/l2.ts

@@ -199,7 +199,7 @@ export class LidoSDKL2 extends LidoSDKModule {
 
   @Logger('Call:')
   @ErrorHandler()
-  public async unwrap(
+  public async unwrapStethToWsteth(
     props: WrapProps,
   ): Promise<TransactionResult<UnwrapResults>> {
     this.core.useWeb3Provider();
@@ -219,7 +219,7 @@ export class LidoSDKL2 extends LidoSDKModule {
 
   @Logger('Utils:')
   @ErrorHandler()
-  public async unwrapPopulateTx(
+  public async unwrapStethPopulateTx(
     props: Omit<WrapProps, 'callback'>,
   ): Promise<PopulatedTransaction> {
     const { value, account } = await this.parseProps(props);
@@ -238,7 +238,7 @@ export class LidoSDKL2 extends LidoSDKModule {
 
   @Logger('Call:')
   @ErrorHandler()
-  public async unwrapSimulateTx(
+  public async unwrapStethSimulateTx(
     props: Omit<WrapProps, 'callback'>,
   ): Promise<WriteContractParameters> {
     const { value, account } = await this.parseProps(props);

playground/demo/l2/wrap-l2.tsx

@@ -87,7 +87,7 @@ export const WrapL2Demo = () => {
         walletAction
         title="Unwrap stETH to wstETH"
         action={() =>
-          l2.unwrap({
+          l2.unwrapStethToWsteth({
             value: stethValue ?? ZERO,
 
             callback: transactionToast,
@@ -105,7 +105,7 @@ export const WrapL2Demo = () => {
         title="Populate unwrap"
         walletAction
         action={() =>
-          l2.unwrapPopulateTx({
+          l2.unwrapStethPopulateTx({
             value: stethValue ?? ZERO,
           })
         }
@@ -114,7 +114,7 @@ export const WrapL2Demo = () => {
         title="Simulate unwrap"
         walletAction
         action={() =>
-          l2.unwrapSimulateTx({
+          l2.unwrapStethSimulateTx({
             value: stethValue ?? ZERO,
           })
         }