@lombard.finance/sdk 2.5.2 → 3.2.0

package/README.md

@@ -1,554 +1,641 @@
 # @lombard.finance/sdk
 
-The SDK package provides a set of tools to interact with the Lombard Protocol.
+The Lombard's SDK package provides a set of functions that allow interacting with the Lombard protocol and its features.
 
-It includes API-based and Web3-based methods with which to interact.
+Read more about Lombard's mission: https://www.lombard.finance
 
-Web3 methods require a Web3 provider to be set up.
+# Table of Contents
 
-## Installation
+[Installation](#installation)
 
-```bash
-npm i @lombard.finance/sdk
-```
+  1. [Dependencies installation](#1-dependencies-installation)
 
-Install Dependencies
+  2. [SDK installation](#2-sdk-installation)
 
-```bash
-npm i web3@^4 axios@^1 bignumber.js@^9 @bitcoin-js/tiny-secp256k1-asmjs@2.2.3 bitcoinjs-lib@6.1.5
-```
+[Usage](#usage)
 
-## Usage
+  1. [Depositing BTC in order to get LBTC (aka staking)](#1-depositing-btc-in-order-to-get-lbtc-aka-staking)
 
-All methods are documented with JSDoc comments. You can use your IDE's autocomplete feature to see the available methods and their parameters.
+     1.1. [Get the current minting fee](#11-get-the-current-minting-fee)
 
-### Importing
+     1.2. [Sign the network fee signature](#12-sign-the-network-fee-signature)
 
-If you are using a module bundler like Vite, Webpack or Rollup, you can import the package like this:
+     1.3. [Store the signature to the Lombard's systems](#13-store-the-signature-to-the-lombards-systems)
 
-```typescript
-import { getDepositBtcAddress } from '@lombard.finance/sdk';
-```
+     1.4. [Get or generate the BTC deposit address](#14-get-or-generate-the-btc-deposit-address)
 
-If you are using a commonjs module system, you can import the package like this:
+     1.5. [Deposit BTC to the address](#15-deposit-btc-to-the-address)
 
-```javascript
-const { getDepositBtcAddress } = require('@lombard.finance/sdk');
-```
-
-### API Methods
-
-- API based
-  - [getDepositBtcAddress](#getDepositBtcAddress)
-  - [getDepositBtcAddresses](#getDepositBtcAddresses)
-  - [generateDepositBtcAddress](#generateDepositBtcAddress)
-  - [getDepositsByAddress](#getDepositsByAddress)
-  - [getLBTCExchangeRate](#getLBTCExchangeRate)
-  - [storeStakeAndBakeSignature](#storeStakeAndBakeSignature)
-  - [getUserStakeAndBakeSignature](#getUserStakeAndBakeSignature)
-  - [storeNetworkFeeSignature](#storeNetworkFeeSignature)
-  - [getNetworkFeeSignature](#getNetworkFeeSignature)
-- Web3 based
-  - [signLbtcDestionationAddr](#signLbtcDestionationAddr)
-  - [claimLBTC](#claimLBTC)
-  - [unstakeLBTC](#unstakeLBTC)
-  - [getBasculeDepositStatus](#getBasculeDepositStatus)
-  - [getLBTCTotalSupply](#getLBTCTotalSupply)
-  - [signStakeAndBake](#signStakeAndBake)
-  - [getStakeAndBakeFee](#getStakeAndBakeFee)
-  - [signNetworkFee](#signNetworkFee)
-
-#### getDepositBtcAddress
-
-`@returns Promise<string>`
-
-Returns the address for depositing BTC.
-
-Parameters:
-| name | type | description |
-|-----------|----------|--------------------------------------------------------------|
-| `address` | `string` | The destination EVM user address where LBTC will be claimed. |
-| `chainId` | `TChainId` | The destination chain ID where LBTC will be claimed. |
-| `env` | `Env` | Environment (optional, default: 'prod') |
-| `partnerId` | `string` | Partner ID (optional) |
-
-Usage
+     1.6. [Check the status of your deposit](#16-check-the-status-of-your-deposit)
 
-```typescript
-import { getDepositBtcAddress } from '@lombard.finance/sdk';
-...
-const depositBtcAddress = await getDepositBtcAddress({
-  address: '0x...',
-  chainId: 1,
-  partnerId: 'YOUR_PARTNER_ID',
-}); // bc1q...
-```
+  2. [Manually claiming LBTC](#2-manually-claiming-lbtc)
 
-#### getDepositBtcAddresses
+  3. [Depositing BTC and automatically staking LBTC into the DeFi vault (aka stake and bake)](#3-depositing-btc-and-automatically-staking-lbtc-into-the-defi-vault-aka-stake-and-bake)
 
-`@returns Promise<IDepositAddress[]>`
+     3.1. [See what's the current stake and bake fee](#31-see-whats-the-current-stake-and-bake-fee)
 
-Returns the addresses for depositing BTC.
+     3.2. [Sign the stake and bake signature](#32-sign-the-stake-and-bake-signature)
 
-Parameters are the same as for `getDepositBtcAddress`.
+     3.3. [Store the signature to the Lombard's systems](#33-store-the-signature-to-the-lombards-systems)
 
-Probably you will not need this method. You can just use `getDepositBtcAddress`.
+     3.4. [Get or generate the BTC deposit address](#34-get-or-generate-the-btc-deposit-address)
 
-#### generateDepositBtcAddress
+     3.5. [Deposit BTC to the address](#35-deposit-btc-to-the-address)
 
-`@returns {Promise<string>}`
+     3.6. [Check the status of your deposit](#36-check-the-status-of-your-deposit)
 
-Generates a BTC deposit address.
-If the provided EVM address is sanctioned, the function will return the `SANCTIONED_ADDRESS` variable.
+     3.7. [Check the amount of shares acquired](#37-check-the-amount-of-shares-acquired)
 
-Parameters:
-| name | type | description |
-|----------------|------------|---------------------------------------------------------------------------------------------------|
-| `address` | `string` | The destination EVM user address where LBTC will be claimed. |
-| `chainId` | `TChainId` | The destination chain ID where LBTC will be claimed. |
-| `signature` | `string` | The signature of the address. The signature is generated by signing the address using EVM wallet. |
-| `referrerCode` | `string` | The referrer code. |
-| `env` | `Env` | Environment (optional, default: 'prod') |
-| `captchaToken` | `string` | The captcha token (optional) |
-| `partnerId` | `string` | The partner ID (optional) |
+  4. [Unstaking LBTC and getting BTC back](#4-unstaking-lbtc-and-getting-btc-back)
 
-Usage
+     4.1. [Unstake LBTC](#41-unstake-lbtc)
 
-```typescript
-import { generateDepositBtcAddress } from '@lombard.finance/sdk';
-...
-const depositBtcAddress = await generateDepositBtcAddress({
-  address: '0x...',
-  chainId: 1,
-  signature: 'SIGNATURE',
-  partnerId: 'YOUR_PARTNER_ID',
-  referrerCode: 'YOUR_REFERRER_CODE',
-}); // bc1q...
-```
+     4.2. [Check the status of your unstakes](#42-check-the-status-of-your-unstakes)
 
-#### getDepositsByAddress
+  5. [Depositing LBTC to the DeFi vault](#5-depositing-lbtc-to-the-defi-vault)
 
-`@returns Promise<IDeposit[]>`
-Returns all deposits for a given address.
+     5.1. [Making a deposit to the DeFi vault](#51-making-a-deposit-to-the-defi-vault)
 
-Parameters:
+     5.2. [Checking the deposit history](#52-checking-the-deposit-history)
 
-| name      | type    | description                             |
-| --------- | ------- | --------------------------------------- |
-| `address` | `string` | The EVM address to get deposits for     |
-| `env`     | `Env`   | Environment (optional, default: 'prod') |
+     5.3. [Checking the user's DeFi vault balance](#53-checking-the-users-defi-vault-balance)
 
-Usage
+  6. [Withdrawing LBTC from the DeFi vault](#6-withdrawing-lbtc-from-the-defi-vault)
 
-```typescript
-import { getDepositsByAddress } from '@lombard.finance/sdk';
-...
-const deposits = await getDepositsByAddress({
-  address: '0x...',
-}); // [{...}]
-```
+     6.1. [Requesting a withdrawal from the DeFi vault](#61-requesting-a-withdrawal-from-the-defi-vault)
 
-#### getLBTCExchangeRate
+     6.2. [Checking the withdrawal history (tracking the withdrawal request)](#62-checking-the-withdrawal-history-tracking-the-withdrawal-request)
 
-`@returns Promise<number>`
+     6.3. [Cancelling the withdrawal](#63-cancelling-the-withdrawal)
 
-Returns the exchange rate for LBTC.
+  7. [Getting the points earned by an address](#7-getting-the-points-earned-by-an-address)
 
-Parameters:
+  8. [Getting the DeFi vault points earned by an address](#8-getting-the-defi-vault-points-earned-by-an-address)
 
-| name      | type      | description                                            |
-| --------- | --------- | ------------------------------------------------------ |
-| `chainId` | `TChainId` | The chain id of the asset to get the exchange rate for |
-| `amount`  | `number`  | The amount of the asset to get the exchange rate for   |
-| `env`     | `Env`     | Environment (optional, default: 'prod')                |
+  9. [Claiming rewards](#9-claiming-rewards)  
 
-Usage
+     9.1. [Checking reward balances](#91-checking-reward-balances)  
 
-```typescript
-import { getLBTCExchangeRate } from '@lombard.finance/sdk';
-...
-const exchangeRate = await getLBTCExchangeRate({
-  chainId: 1,
-  amount: 3,
-}); // 3
-```
+     9.2. [Claiming rewards](#92-claiming-rewards)  
 
-#### signLbtcDestionationAddr
+     9.3. [Checking the reward withdrawal fee](#93-checking-the-reward-withdrawal-fee)  
 
-`@returns Promise<string>` - The signature of the message.
+     9.4. [Getting the withdrawal history (checking withdrawal status)](#94-getting-the-withdrawal-history-checking-withdrawal-status)
 
-Signs the destination address for the LBTC in active chain in the current account.
-Signing is necessary for the generation of the deposit address.
+  10. [Metrics](#10-metrics)
 
-Parameters:
+      10.1. [Getting the vault's TVL](#101-getting-the-vaults-tvl)
 
-| name       | type               | description                    |
-| ---------- | ------------------ | ------------------------------ |
-| `provider` | `IEIP1193Provider` | The EIP-1193 provider instance |
-| `account`  | `string`           | Current account address        |
-| `chainId`  | `TChainId`         | Current chain ID               |
+      10.2. [Getting the vault's performance data](#102-getting-the-vaults-performance-data)
+      
+      10.3. [Getting the LBTC statistics](#103-getting-the-lbtc-statistics)
 
-Usage
 
-```typescript
-import { signLbtcDestinationAddr } from '@lombard.finance/sdk';
 
-...
-// do connect to the wallet using web3.js or ethers.js or any other library
-// and get the provider, account and chainId
-const destinationAddr = await signLbtcDestinationAddr({
-  provider: window.ethereum,
-  account: '0x...',
-  chainId: 1,
-}); // '0x...'
-```
+## Installation
 
-#### claimLBTC
+### 1. Dependencies installation
 
-`@returns Promise<IWeb3SendResult>` transaction promise
+The SDK depends on the following packages:
+* axios
+* viem@2.23
+* bignumber.js@9
+* bitcoinjs-lib@6.1.5
+* @bitcoin-js/tiny-secp256k1-asmjs@2.2.3
+* @layerzerolabs/lz-v2-utilities@3.0.17
 
-Claims LBTC.
+You may install them by running the following command:
 
-Parameters:
+```bash
+npm i --save viem@^2.23.15 axios@^1 bignumber.js@^9 @bitcoin-js/tiny-secp256k1-asmjs@2.2.3 bitcoinjs-lib@6.1.5 @layerzerolabs/lz-v2-utilities@3.0.17
+```
 
-| name             | type              | description                                                                            |
-| ---------------- | ----------------- | -------------------------------------------------------------------------------------- |
-| `data`           | `string`          | Raw payload from deposit notarization. Can be obtained from the `getDepositsByAddress` |
-| `proofSignature` | `string`          | Signature from deposit notarization. Can be obtained from the `getDepositsByAddress`   |
-| `provider`       | `IEIP1193Provider` | The EIP-1193 provider instance                                                         |
-| `account`        | `string`          | Current account address                                                                |
-| `chainId`        | `TChainId`        | Current chain ID                                                                       |
-| `env`            | `Env`             | Environment (optional, default: 'prod')                                                |
+### 2. SDK installation
 
-Usage
+To install the SDK package, please run:
 
-```typescript
-import { claimLBTC } from '@lombard.finance/sdk';
-...
-// do connect to the wallet using web3.js or ethers.js or any other library
-// and get the provider, account and chainId
-const { receiptPromise, transactionHash } = await claimLBTC({
-  data: 'PAYLOAD',
-  proofSignature: 'SIGNATURE',
-  provider: window.ethereum,
-  account: '0x...',
-  chainId: 1,
-});
-console.log(transactionHash); // '0x...'
-const receipt = await receiptPromise; // {...}
+```bash
+npm i --save @lombard.finance/sdk
 ```
 
-#### unstakeLBTC
+## Usage
 
-`@returns Promise<IWeb3SendResult>` transaction promise
+All functions are documented with JSDoc comments. You can use your IDE's autocomplete feature to see the available methods and their parameters.
 
-Unstakes LBTC to the specified BTC address.
+### 1. Depositing BTC in order to get LBTC (aka staking).
 
-Parameters:
+You can read more about LBTC here: https://docs.lombard.finance/lbtc-liquid-bitcoin/introduction-to-lbtc
 
-| name         | type              | description                                 |
-| ------------ | ----------------- | ------------------------------------------- |
-| `btcAddress` | `string`          | The BTC address to send the unstaked BTC to |
-| `amount`     | `string`          | The amount of LBTC to unstake               |
-| `provider`   | `IEIP1193Provider` | The EIP-1193 provider instance              |
-| `account`    | `string`          | Current account address                     |
-| `chainId`    | `TChainId`        | Current chain ID                            |
-| `env`        | `Env`             | Environment (optional, default: 'prod')     |
+If you'd wish to stake your BTC and get LBTC follow the below steps:
 
-Usage
+#### 1.1 Get the current minting fee.
 
-```typescript
-import { unstakeLBTC } from '@lombard.finance/sdk';
-...
-// do connect to the wallet using web3.js or ethers.js or any other library
-// and get the provider, account and chainId
-const { receiptPromise, transactionHash } = await unstakeLBTC({
-  btcAddress: 'bs...',
-  amount: 1,
-  provider: window.ethereum,
-  account: '0x...',
-  chainId: 1,
+```javascript
+const fee = await getLBTCMintingFee({ chainId: ChainId.ethereum }); // The fee represented in satoshis (BigNumber)
+```
+
+#### 1.2. Sign the network fee signature.
+
+```javascript
+const expiry = Math.round((Date.now() + 24 * 60 * 60 * 1000) / 1000);
+const { signature, typedData } = await signNetworkFee({
+  fee, // The fee from step 1
+  expiry, // The optional expiration unix timestamp. This parameter can be omitted, it default to 24h from now. We recommend to set this to at least 8h from now.
+  account, // The destination account address from the connected wallet.
+  chainId: ChainId.ethereum // The destination chain id.
+  provider, // The EIP-1193 provider, e.g. the injected provider: window.ethereum
 });
-console.log(transactionHash); // '0x...'
-const receipt = await receiptPromise; // {...}
 ```
 
-#### getBasculeDepositStatus
+#### 1.3. Store the signature to the Lombard's systems.
 
-`@returns Promise<BasculeDepositStatus>` transaction promise
+```javascript
+await storeNetworkFeeSignature({ signature, typedData, address }); // Pass the signature and typed data from step 2.
+```
 
-Check Deposit Status by hash id through Bascule
+It is recommended to verify that the signature has been stored. Please use `getNetworkFeeSignature`.
 
-Parameters:
+```javascript
+const { expirationData, hasSignature, isDelayed } = await getNetworkFeeSignature({ address, chainId });
+```
 
-| name       | type              | description                                                                        |
-| ---------- | ----------------- | ---------------------------------------------------------------------------------- |
-| `txId`     | `string`          | Payload from deposit notarization. Can be obtained from the `getDepositsByAddress` |
-| `provider` | `IEIP1193Provider` | The EIP-1193 provider instance                                                     |
-| `account`  | `string`          | Current account address                                                            |
-| `chainId`  | `TChainId`        | Current chain ID                                                                   |
-| `env`      | `Env`             | Environment (optional, default: 'prod')                                            |
+`isDelayed` is a flag determining whether the execution of auto-claimer using the stored signature is delayed due to the higher gas costs.
 
-Usage
+#### 1.4. Get or generate the BTC deposit address.
 
-```typescript
-import { getBasculeDepositStatus } from '@lombard.finance/sdk';
-...
-// do connect to the wallet using web3.js or ethers.js or any other library
-// and get the provider, account and chainId
-const status = await getBasculeDepositStatus({
-  txId: 'PAYLOAD',
-  provider: window.ethereum,
-  chainId: 1,
-});
-console.log(status); // '0, 1, 2'
+```javascript
+let depositBtcAddress = await getDepositBtcAddress({ address, chainId });
+if (!depositBtcAddress) {
+  depositBtcAddress = await generateDepositBtcAddress({ 
+    address,
+    chainId,
+    signature, // Pass here the signature from step 2.
+    eip712Data: typedData // Pass here the typed data from step 2.
+  });
+}
 ```
 
-#### getLBTCTotalSupply
+#### 1.5. Deposit BTC to the address.
+
+Now you can deposit your BTC to the generated in the previous step BTC address.
+The funds will be claimed automatically by Lombard's claimer and transferred to
+the account (`address`).
 
-`@returns Promise<string>` Supply promise
+#### 1.6. Check the status of your deposit.
 
-Get LBTC total supply
+If you'd like to check the status of your deposit use `getDepositsByAddress` function.
 
-Parameters:
+```javascript
+const deposits = await getDepositsByAddress({ address });
+```
+
+Every entry in the result of the above function may consist of the following properties:
+* `txid` - the BTC transaction id,
+* `index` - the index of the actual deposit transaction,
+* `blockHeight`
+* `blockTime`
+* `value` - the amount of BTC deposited,
+* `address` - the destination address,
+* `chainId` - the destination chain id,
+* `isClaimer` - a flag determining whether the deposit has been already claimed,
+* `claimedTxId` - the corresponding claim transaction that transfer funds to the destination address,
+* `rawPayload` - the payload of the transaction (can be use to claim the funds manually),
+* `signature` - the signature used (can be used to claim the funds manually),
+* `isRestricted` - a flag determining whether the transaction has been marked as suspicious/restricted,
+* `payload` - the payload (corresponding to the Bascule drawbridge security),
+* `sessionId`
+* `notarizationStatus` - the notarization status of the deposit (pending, submitted, approved or failed),
+* `sessionState` - the state of the session (pending, completed, expired)
+
+### 2. Manually claiming LBTC.
+
+In case when a user deposited BTC to the BTC deposit address but the transaction has not been claimed automatically (due to expired signature or any other issue), you may want to claim LBTC manually as in the example below:
+
+```javascript
+const txHash = await claimLBTC({
+  data: rawPayload, // Pass the raw payload from the deposit data as presented in the previous step.
+  proofSignature: signature, // Pass the signature from the deposit data.
+  account, // The connected account address
+  chainId, // The chain id
+  provider, // The EIP-1193 provider,
+  rpcUrl, // The optional RPC url.
+})
+```
 
-| name      | type      | description                             |
-| --------- | --------- | --------------------------------------- |
-| `rpcUrl`  | `string`  | Rpc url for the chain                   |
-| `chainId` | `TChainId` | Current chain ID                        |
-| `env`     | `Env`     | Environment (optional, default: 'prod') |
+The successful execution of the above will result with the transaction id.
 
-Usage
+### 3. Depositing BTC and automatically staking LBTC into the DeFi vault (aka stake and bake)
 
-```typescript
-import { getLBTCTotalSupply } from '@lombard.finance/sdk';
+You can read more about the DeFi vaults here: https://docs.lombard.finance/lbtc-liquid-bitcoin/defi-vaults/lombard-defi-vault
+
+If you'd wish to stake and bake your BTC follow the steps below.
 
-const totalSupply = await getLBTCTotalSupply({
-  rpcUrl: 'yourRpcUrl',
-  chainId: 1,
+#### 3.1. See what's the current stake and bake fee.
+
+To check the current stake and bake fee you may use the following function:
+
+```javascript
+const fee = await getStakeAndBakeFee({
+  vaultKey: Vault.Veda, // The vault identifier, currently only "veda" is accepted.
+  chainId, // The chain id.
+  rpcUrl, // The options RPC url.
 });
-console.log(totalSupply); // '2000000'
+const expectedLBTCAmount = BigNumber(amountToBeDeposited).minus(fee);
 ```
+The fee amount will be deducted from the claimed LBTC automatically.
 
-#### signStakeAndBake
+#### 3.2. Sign the stake and bake signature.
 
-`@returns Promise<ISignStakeAndBakeResult>` Sign authorization promise
+```javascript
+const { signature, typedData } = await signStakeAndBake({
+  account, // The connected account address,
+  expiry, // The optional expiration unix timestamp. This parameter can be omitted, it default to 24h from now. We recommend to set this to at least 8h from now.
+  value, // The amount of BTC (in satoshis)
+  vaultKey: Vault.Veda, // The vault identifier, currently only "veda" is accepted.
+  chainId, // The chain id.
+  provider, // The EIP-1193 provider.
+  rpcUrl, // The optional RPC url.
+})
+```
 
-Sign Stake And Bake
+#### 3.3. Store the signature to the Lombard's systems.
 
-## Parameters
+```javascript
+await storeStakeAndBakeSignature({
+  signature, // Pass here the signature form the previous step.
+  typedData, // Pass here the typed data from the previous step.
+})
+```
 
-| name       | type                | description                                       |
-| ---------- | ------------------- | ------------------------------------------------- |
-| `provider` | `IProvider`         | Provider instance to interact with the blockchain |
-| `address`  | `string`            | The address to sign with (owner)                  |
-| `chainId`  | `TChainId`          | Chain ID for the signature                        |
-| `value`    | `string`            | The value to approve                              |
-| `expiry`   | `number`            | Expiry date as a unix timestamp                   |
-| `rpcUrl`   | `string` (optional) | Optional RPC URL for the network                  |
-| `vaultKey` | `string`            | The key of the vault to authorize                 |
+It is recommended to verify if the signature has been stored.
 
-Usage
+```javascript
+const data = await getUserStakeAndBakeSignature({
+  userDestinationAddress: address,
+  chainId,
+})
+```
 
-```typescript
-import { signStakeAndBake } from '@lombard.finance/sdk';
+#### 3.4. Get or generate the BTC deposit address.
 
-const { signature, signatureData } = await signStakeAndBake({
-  provider: window.ethereum,
-  address: '0x...',
-  chainId,
-  value: toSatoshi(approvalValue.toString()).toString(),
-  expiry: permitExpiryTime,
-  vaultKey: selectedVault.key,
-});
+```javascript
+let depositBtcAddress = await getDepositBtcAddress({ address, chainId });
+if (!depositBtcAddress) {
+  depositBtcAddress = await generateDepositBtcAddress({ 
+    address,
+    chainId,
+    signature, // Pass here the signature from step 2.
+    signatureData: typedData // Pass here the typed data from step 2.
+  });
+}
 ```
 
-#### storeStakeAndBakeSignature
+#### 3.5. Deposit BTC to the address. 
+
+Now you can deposit your BTC to the BTC deposit address from above. The funds will be automatically claimed and deposited to the DeFi vault.
 
-`@returns Promise<IStoreStakeAndBakeSignatureStatus>` Store Stake And Bake Signature Status promise
+#### 3.6. Check the status of you deposit
 
-Store stake and bake signature
+```javascript
+const deposits = await getDepositsByAddress({ address });
+```
+
+#### 3.7. Check the amount of shares acquired.
+
+```javascript
+const { balance, exchangeRate, balanceLbtc } = await getSharesByAddress({
+  vaultKey: Vault.Veda, // The vault identifier.
+  address, // The account address.
+  chainId, // The chain id.
+  rpcUrl, // The optional RPC url
+});
+```
 
-## Parameters
+The above code results with:
+* `balance` - The amount of LBTCv shares owned by the account,
+* `exchangeRate` - The current LBTCv to LBTC exchange rate,
+* `balanceLbtc` - The value of the owned shares is LBTC.
 
-| name        | type     | description                             |
-| ----------- | -------- | --------------------------------------- |
-| `env`       | `TEnv`   | Environment (e.g., 'prod', 'stage', etc.) |
-| `signature` | `string` | The generated signature                 |
-| `typedData` | `string` | JSON typed data used for the signature  |
+### 4. Unstaking LBTC and getting BTC back.
 
-Usage
+Every LBTC is redeemable back to BTC, you can do that programmatically by following the steps:
 
-```typescript
-import { storeStakeAndBakeSignature } from '@lombard.finance/sdk';
+#### 4.1. Unstake LBTC.
 
-const status = await storeStakeAndBakeSignature({
-  signature,
-  signatureData,
-  env: 'prod',
+```javascript
+const txaHash = await unstakeLBTC({
+  btcAddress, // The address to which the funds will be redeemed.
+  amount, // The amount of LBTC to unstake.
+  account, // The account address.
+  chainId, // The chain id.
+  provider, // The EIP-1193 provider.
+  rpcUrl, // The optional RPC url.
 });
 ```
 
-#### getUserStakeAndBakeSignature
+#### 4.2. Check the status of your unstakes.
 
-`@returns Promise<IGetUserStakeAndBakeSignatureResponse>` Promise that resolves to the signature response
+If you'd like to get the list of all unstaked made by an address, use this:
 
-Get user's stake and bake signature from the API
+```javascript
+const unstakes = await getUnstakesByAddress({ address });
+```
 
-## Parameters
+Every entry in the result of the above may consist of:
+* `txHash` - The unstake transaction hash,
+* `chainId`,
+* `blockHeight`,
+* `unstakeDate`,
+* `fromAddress` - The EVM source address,
+* `toAddress` - The BTC destination address of the funds,
+* `amount` - The amount unstaked,
+* `payoutTxHash` - The BTC transaction hash,
+* `payoutTxIndex` - The index of the actual payout transfer,
+* `sanctioned` - A flag indicating whether the unstake transaction has been sanctioned and flagged as suspicious.
 
-| name                     | type    | description                             |
-| ------------------------ | ------- | --------------------------------------- |
-| `userDestinationAddress` | `string` | The user's destination address          |
-| `chainId`                | `string` | The chain ID                            |
-| `env`                    | `TEnv`   | Environment (e.g., 'prod', 'stage', etc.) |
+### 5. Depositing LBTC to the DeFi vault.
 
-Usage
+If a user already has LBTC depositing to the DeFi vault can be done via the `deposit` function.
 
-```typescript
-import { getUserStakeAndBakeSignature } from '@lombard.finance/sdk';
+#### 5.1. Making a deposit to the DeFi vault.
 
-const response = await getUserStakeAndBakeSignature({
-  userDestinationAddress: address,
-  chainId,
-  env: 'prod',
+```javascript
+const txHash = await deposit({
+  amount, // The deposit amount, e.g. 1.23 (LBTC)
+  approve = true, // The optional flag determining whether approval should be done within deposit execution.
+  token = 'LBTC', // The optional deposit token.
+  vaultKey = Vault.Veda, // The optional vault identifier.
+  account, // The account address.
+  chainId, // The chain id.
+  provider, // The EIP-1193 provider
+  rpcUrl, // The optional RPC url
+})
+```
+
+#### 5.2. Checking the deposit history.
+
+```javascript
+const deposits = await getVaultDeposits({
+  account, // The account address.
+  chainId, // The chain id.
+  vaultKey = Vault.Veda // The optional vault identifier.
 });
-console.log(response);
 ```
 
-#### storeNetworkFeeSignature
+The above function returns an array of deposit data made by the specified user.
+Each entry contains:
+* `txHash` -  the transaction hash,
+* `blockNumber` -    the transaction's block number,
+* `chainId` -    the chain id,
+* `amount` -    the deposited amount,
+* `shareAmount` -    the amount of shares received,
+* `token` - the deposit token.
 
-`@returns Promise<IStoreNetworkFeeSignatureResponse>` Response promise with statuses
+#### 5.3. Checking the user's DeFi vault balance.
 
-Store authorize network fee
+In order to check the user's balance of the vault tokens, use this:
 
-## Parameters
+```javascript
+const { balance, exchangeRate, balanceLbtc } = await getSharesByAddress({
+  vaultKey: Vault.Veda, // The vault identifier.
+  address, // The account address.
+  chainId, // The chain id.
+  rpcUrl, // The optional RPC url
+});
+```
 
-| name                     | type     | description                             |
-| ------------------------ | -------- | --------------------------------------- |
-| `signature`              | `string` | The signature of signNetworkFee method  |
-| `typedData`              | `string` | JSON typed data used for the signature  |
-| `address`                | `string` | Destination address                     |
-| `env`                    | `TEnv`   | Environment (e.g., 'prod', 'stage', etc.) |
+The above function returns the:
+* `balance` - balance of LBTCv,
+* `exchangeRate` - the current exchange rate between LBTCv and LBTC,
+* `balanceLbtc` - the value of LBTCv represented in LBTC.
 
-Usage
+### 6. Withdrawing LBTC from the DeFi vault.
 
-```typescript
-import { storeNetworkFeeSignature } from '@lombard.finance/sdk';
+#### 6.1. Requesting a withdrawal from the DeFi vault
 
-const status = await storeNetworkFeeSignature({
-  signature: '',
-  typedData: '',
-  address: '0x...',
-  env: 'prod',
-});
-console.log(status); // success
+Requesting a withdrawal from the DeFi vault can be done via:
+```javascript
+const txHash = await withdraw({
+  amount, // The amount of shares.
+  approve = true, // The optional flag determining if approve action should be done within this execution.
+  token = 'LBTC', // The optional withdraw token.
+  vaultKey = Vault.Veda, // The optional vault identifier.
+  account, // The account address.
+  chainId, // The chain id.
+  provider, // The EIP-1192 provider.
+  rpcUrl, // The optional RPC url
+})
 ```
 
-#### getNetworkFeeSignature
+#### 6.2. Checking the withdrawal history (tracking the withdrawal request)
 
-`@returns Promise<IStoreNetworkFeeSignatureResponse>` Response promise with statuses
+In order to check the whole history or to track the particular withdrawal please use the following function:
 
-Store authorize network fee
+```javascript
+const withdrawals = await getVaultWithdrawals({
+  account, // The account address.
+  chainId, // The chain id.
+  vaultKey = Vault.Veda, // The optional vault identifier.
+  rpcUrl, // The optional RPC url
+})
+```
 
-## Parameters
+The result of the above is an object with broken down withdrawals by their state:
+```javascript
+{
+  cancelled: [...], // The cancelled requests.
+  expired: [...], // The requests that expired.
+  fulfilled: [...], // The fulfilled requests (funds were transferred).
+  open: [...], // The open withdrawal requests (still to be processed).
+}
+```
 
-| name                     | type     | description                             |
-| ------------------------ | -------- | --------------------------------------- |
-| `chainId`                | `number` | The chain ID                            |
-| `address`                | `string` | Destination address                     |
-| `env`                    | `TEnv`   | Environment (e.g., 'prod', 'stage', etc.) |
+Each of the arrays from above consist of:
+* `token` - the withdrawal token (LBTC),
+* `shareAmount` - the amount of shares withdrawn,
+* `amount` - the amount of funds withdrawn,
+* `minPrice` - the min price of a share,
+* `deadline` - the expiration timestamp,
+* `timestamp` - the request timestamp,
+* `txHash` - the withdraw request transaction hash,
+* `blockNumber` - the request block number,
+* `fulfilledTimestamp` - the fulfilment timestamp,
+* `fulfilledTxHash` - the funds transfer transaction hash,
+* `fulfilledBlockNumber` - the fulfilment block number.
 
-Usage
+#### 6.3. Cancelling the withdrawal
 
-```typescript
-import { getNetworkFeeSignature } from '@lombard.finance/sdk';
+If you wish to cancel you open withdrawal request use this:
 
-const signatureResponse = await getNetworkFeeSignature({
-  chainId: 1,
-  address: '0x...',
-  env: 'prod',
+```javascript
+const txHash = await cancelWithdraw({
+  token = 'LBTC', // The optional withdrawal asset.
+  vaultKey = Vault.Veda, // The optional vault identifier.
+  account, // The account address.
+  chainId, // The chain id.
+  provider, // The EIP-1193 provider.
+  rpcUrl, // The optional RPC url.
 });
-console.log(signatureResponse);
 ```
 
-#### getStakeAndBakeVaults
+### 7. Getting the points earned by an address.
+
+If you'd like to check the amount of LUX points earned by an address then simply run the following function:
 
-`@returns IStakeAndBakeVault[]` A list of available vaults
+```javascript
+const points = await getPointsByAddress({ address: "0x...YOUR_ADDRESS" })
+```
 
-## Parameters
+The function returns the object of shape:
+```typescript
+  {
+    /**
+     * The number of points earned by holding LBTC.
+     */
+    holdingPoints: number;
+    /**
+     * The number of points earned by taking positions in DeFi vaults.
+     */
+    protocolPoints: number;
+    /**
+     * The number of points earned by your referrals.
+     */
+    referralPoints: number;
+    /**
+     * The number of points earned in the OKX campaign.
+     */
+    okxPoints: number;
+    /**
+     * The number of points earned by participating in the flash events.
+     */
+    flashEventPoints: number;
+    /**
+     * The total number of points.
+     */
+    totalPoints: number;
+    /**
+     * The breakdown of points earned from each protocol.
+     */
+    protocolPointsBreakdown: IProtocolPointsBreakdown;
+  }
+```
 
-| name      | type     | description  |
-| --------- | -------- | ------------ |
-| `chainId` | `string` | The chain ID |
+### 8. Getting the DeFi vault points earned by an address.
 
-Usage
+```javascript
+const { 
+  totalPoints, // The total points earned in the DeFi vault.
+  pointsBreakdown // The points breakdown by network (chain).
+} = await getVaultPoints({
+  account, // The account address.
+  vaultKey // The optional vault identifier.
+})
+```
 
-```typescript
-import { getStakeAndBakeVaults } from '@lombard.finance/sdk';
+### 9. Claiming rewards.
 
-const vaults = getStakeAndBakeVaults(1);
+#### 9.1. Checking reward balances.
 
-console.log(vaults);
+```javascript
+const rewards = await getRewardBalances({
+  address,
+  rewardToken: RewardToken.BABY
+});
 ```
 
-#### getStakeAndBakeFee
+The data returned by the above function contains:
 
-`@returns Promise<string>` Promise that resolves stakeAndBake fee in satoshis
+* `address` - the address of the reward earner (claimer),
+* `availableBalance` - the available balance of the reward token (ready to be withdrawn),
+* `lockedBalance` - the locked balance (in processing),
+* `pendingBalance` - the pending balance to be credited,
+* `rewardToken` - the reward token,
+* `timestamp` - the timestamp.
 
-Get Stake and bake fee in satoshis
+#### 9.2. Claiming rewards.
 
-## Parameters
+```javascript
+const withdrawal = await claimReward({
+  account, // The account address.
+  rewardToken, // The reward token, e.g. RewardToken.BABY
+  amount, // The amount to be claimed (withdrawn)
+  to, // The destination address, e.g. BABYLON chain address.
+  chainId, // The chain id
+  provider, // The EIP-1193 provider.
+});
+```
 
-| name           | type     | description           |
-| -------------- | -------- | --------------------- |
-| `vaultAddress` | `string` | The vault address     |
-| `chainId`      | `string` | The chain ID          |
-| `rpcUrl`       | `string` | Rpc url for the chain |
+The function will ask a user to sign a message that consists of the amount, destination address and also a withdrawal fee and after obtaining this signature it will request a reward withdrawal from the pool to the provided destination address.
 
-Usage
+The function returns the `RewardWithdrawal` object.
 
-```typescript
-import { getStakeAndBakeFee } from '@lombard.finance/sdk';
+#### 9.3. Checking the reward withdrawal fee.
 
-const response = await getStakeAndBakeFee({
-  chainId: OChainId.binanceSmartChain,
-  rpcUrl: 'https://rpc.ankr.com/bsc',
-  vaultAddress: '0xC8bbF6153D7Ba105f1399D992ebd32B0541996ef',
-});
-console.log(response);
+```javascript
+const withdrawalFee = await getRewardWithdrawalFee({ address, rewardToken });
+```
+
+#### 9.4. Getting the withdrawal history (checking withdrawal status).
+
+```javascript
+const withdrawals = await getRewardWithdrawals({ address })
 ```
 
-#### signNetworkFee
+The function returns an array of:
+
+* `amount` - the withdrawn (claimed) amount of rewards token,
+* `rewardToken` - the reward token,
+* `fee` - the applied withdrawal fee,
+* `to` - the destination address,
+* `signature` - the signature used,
+* `status` - the withdrawal status,
+* `estimatedTimeSent` - the estimated time when the funds are sent,
+* `timestamp` - the timestamp.
 
-`@returns Promise<ISignNetworkFeeResponse>` A promise that resolves to the signature and typed data
+### 10. Metrics
 
-Signs the network fee transaction in the current account.
-Signing is necessary for the auto-mint.
+#### 10.1. Getting the vault's TVL
 
-## Parameters
+The vault's TVL can be obtained by calling the `getVaultTVL` function.
 
-| name       | type        | description                                       |
-| ---------- | ----------- | ------------------------------------------------- |
-| `address`  | `string`    | The user address                                  |
-| `fee`      | `string`    | The Authorization fee                             |
-| `expiry`   | `number`    | Expiration time                                   |
-| `chainId`  | `string`    | The chain ID                                      |
-| `env`      | `TEnv`      | Environment (e.g., 'prod', 'stage', etc.)           |
-| `provider` | `IProvider` | Provider instance to interact with the blockchain |
+```javascript
+const data = await getVaultTVL({ vaultKey: Vault.Veda });
+```
 
-Usage
+The above returns:
+* `btcBalance` - the amount of BTC locked into the vault,
+* `btcPrice` - the current price of BTC,
+* `tvl` - the amount of USD locked into the vault.
 
-```typescript
-import { signNetworkFee } from '@lombard.finance/sdk';
-
-const response = await signNetworkFee({
-  chainId: OChainId.binanceSmartChain,
-  address: '0x...',
-  provider: window.ethereum,
-  fee: toSatoshi('0.0001'),
-  expiry: Math.floor(Date.now() / 1000) + NETWORK_FEE_EXPIRATION_TIME_SECONDS,
-  env: 'prod',
+#### 10.2. Getting the vault's performance data.
+
+The performance of the vault can be checked via the `getVaultApy` function.
+As in the example below:
+
+```javascript
+const APYs = await getVaultApy({
+  aggregationPeriod: 7, // The aggregation period in days, only 7, 14, and 30 are allowed.
+  chainId: ChainId.ethereum, // The vault's chain - can be omitted, defaults to `Ethereum`.
+  vaultKey: Vault.Veda // The vault identifier - can be omitted, default to `Vault.Veda`
 });
-console.log(response);
 ```
+
+The above returns an array of APY entries sorted in descending order (newest first).
+Each entry contains:
+
+* `apy` - the APY value,
+* `allocations` - the record of general allocations in protocols used by the vault,
+* `breakdown` - the detailed record of allocations and APY values broken down by chain and protocol,
+* `timestamp` - the timestamp of the entry.
+
+#### 10.3. Getting the LBTC statistics.
+
+The simple set of LBTC statistics is accessible via `getLBTCStats` function.
+
+The stats contain:
+
+* `historicalHolders` - the number of all-time LBTC holders,
+* `holders` - the number of current LBTC holders,
+* `price` - the current BTC price,
+* `supply` - the number of LBTC minted,
+* `tvl` - the Lombard's TVL in USD.