From cf8ea8bfe8b2a81368df36920eb92f6f7125adb4 Mon Sep 17 00:00:00 2001 From: MikeDiam Date: Tue, 11 Aug 2026 11:46:48 +0300 Subject: [PATCH] Sync SDK documentation [11.08.2026] --- .../01-transactions/burnAndWithdraw.md | 45 ++++ .../API/01-vault/01-transactions/deposit.md | 11 +- .../01-transactions/depositAndMint.md | 50 ++++ docs/sdk/API/01-vault/getMaxWithdrawAmount.md | 13 +- docs/sdk/API/01-vault/getUserRewards.md | 26 ++- docs/sdk/API/02-boost/01-transactions/lock.md | 23 +- .../API/02-boost/01-transactions/unlock.md | 12 +- docs/sdk/API/03-osToken/getMaxMintAmount.md | 11 + .../helpers/getBurnAmountForUnstake.md | 13 +- .../helpers/getUnstakeAmountForBurn.md | 37 +++ .../sdk/API/06-utils/checkTxBatchSupported.md | 28 +++ docs/sdk/ai-assistance.md | 29 +++ docs/sdk/fundamentals/batch-transactions.md | 215 ++++++++++++++++++ 13 files changed, 470 insertions(+), 43 deletions(-) create mode 100644 docs/sdk/API/01-vault/01-transactions/burnAndWithdraw.md create mode 100644 docs/sdk/API/01-vault/01-transactions/depositAndMint.md create mode 100644 docs/sdk/API/03-osToken/helpers/getUnstakeAmountForBurn.md create mode 100644 docs/sdk/API/06-utils/checkTxBatchSupported.md create mode 100644 docs/sdk/ai-assistance.md create mode 100644 docs/sdk/fundamentals/batch-transactions.md diff --git a/docs/sdk/API/01-vault/01-transactions/burnAndWithdraw.md b/docs/sdk/API/01-vault/01-transactions/burnAndWithdraw.md new file mode 100644 index 00000000..d6a521ad --- /dev/null +++ b/docs/sdk/API/01-vault/01-transactions/burnAndWithdraw.md @@ -0,0 +1,45 @@ +--- +id: burnAndWithdraw +slug: /sdk/api/vault/transactions/burnandwithdraw +description: Use the StakeWise SDK burnAndWithdraw method to burn osToken and unstake funds from a vault in a single transaction. +--- + +#### Description: + +Burn the osToken required to unstake and withdraw funds from a vault in a single transaction. + +Pass `assets` for the default withdraw-driven mode: unstake that amount, burning the minimum osToken it requires. +Pass `shares` instead for the burn-driven mode: burn exactly that many osToken shares and unstake all the collateral that burning frees. + +Provide one of `assets` or `shares`. + +#### Arguments: + +| Name | Type | Required | Description | +|--------------|----------|----------|-------------------------------------------------------------------| +| assets | `bigint` | No | Unstake amount (withdraw-driven mode) | +| shares | `bigint` | No | osToken shares to burn; unstakes all the collateral it frees | +| userAddress | `string` | **Yes** | The user address | +| vaultAddress | `string` | **Yes** | The address of the vault | + +#### Example: + +```ts +const params = { + vaultAddress: '0x...', + userAddress: '0x...', + assets: 200n, // withdraw-driven; or pass shares: 200n to burn exactly that and unstake the equivalent +} + +// Send transaction +const hash = await sdk.vault.burnAndWithdraw(params) + +// Wait for the transaction to be confirmed and indexed +await sdk.provider.waitForTransaction(hash) +await sdk.utils.waitForSubgraph({ hash }) + +// When you sign transactions on the backend (for custodians) +const { data, to } = await sdk.vault.burnAndWithdraw.encode(params) +// Get an approximate gas per transaction +const gas = await sdk.vault.burnAndWithdraw.estimateGas(params) +``` diff --git a/docs/sdk/API/01-vault/01-transactions/deposit.md b/docs/sdk/API/01-vault/01-transactions/deposit.md index d48c6aaf..50c1c956 100644 --- a/docs/sdk/API/01-vault/01-transactions/deposit.md +++ b/docs/sdk/API/01-vault/01-transactions/deposit.md @@ -10,11 +10,12 @@ Deposit (stake) in a vault #### Arguments: -| Name | Type | Required | Description | -|--------------|----------|----------|---------------------------| -| assets | `bigint` | **Yes** | Deposit amount | -| userAddress | `string` | **Yes** | The user address | -| vaultAddress | `string` | **Yes** | The address of the vault | +| Name | Type | Required | Description | +|-----------------|----------|----------|------------------------------| +| assets | `bigint` | **Yes** | Deposit amount | +| userAddress | `string` | **Yes** | The user address | +| vaultAddress | `string` | **Yes** | The address of the vault | +| referrerAddress | `string` | **No** | The address of the referrer | #### Example: diff --git a/docs/sdk/API/01-vault/01-transactions/depositAndMint.md b/docs/sdk/API/01-vault/01-transactions/depositAndMint.md new file mode 100644 index 00000000..450a7391 --- /dev/null +++ b/docs/sdk/API/01-vault/01-transactions/depositAndMint.md @@ -0,0 +1,50 @@ +--- +id: depositAndMint +slug: /sdk/api/vault/transactions/depositandmint +description: Use the StakeWise SDK vault depositAndMint method to stake assets and mint osToken in one transaction. +--- + +#### Description: + +Deposit (stake) and mint osToken in one transaction. + +#### Arguments: + +| Name | Type | Required | Description | +|-----------------|----------|----------|-------------------------------| +| assets | `bigint` | **Yes** | Deposit amount | +| receiveShares | `bigint` | **Yes** | The amount of osToken to mint | +| userAddress | `string` | **Yes** | The user address | +| vaultAddress | `string` | **Yes** | The address of the vault | +| referrerAddress | `string` | **No** | The address of the referrer | + +#### Example: + +```ts +const assets = parseEther('1') + +const receiveShares = await sdk.osToken.getMaxMintAmount({ + vaultAddress: '0x...', + userAddress: '0x...', + additionalStakedAssets: assets, +}) + +const params = { + vaultAddress: '0x...', + userAddress: '0x...', + assets, + receiveShares, +} + +// Send transaction +const hash = await sdk.vault.depositAndMint(params) + +// Wait for the transaction to be confirmed and indexed +await sdk.provider.waitForTransaction(hash) +await sdk.utils.waitForSubgraph({ hash }) + +// When you sign transactions on the backend (for custodians) +const { data, to, value } = await sdk.vault.depositAndMint.encode(params) +// Get an approximate gas per transaction +const gas = await sdk.vault.depositAndMint.estimateGas(params) +``` diff --git a/docs/sdk/API/01-vault/getMaxWithdrawAmount.md b/docs/sdk/API/01-vault/getMaxWithdrawAmount.md index 36be73a5..e8ecae52 100644 --- a/docs/sdk/API/01-vault/getMaxWithdrawAmount.md +++ b/docs/sdk/API/01-vault/getMaxWithdrawAmount.md @@ -1,19 +1,20 @@ --- id: getMaxWithdrawAmount slug: /sdk/api/vault/requests/getmaxwithdrawamount -description: Use the StakeWise SDK getMaxWithdrawAmount method to calculate the maximum amount a user can withdraw from a vault. +description: Use the StakeWise SDK getMaxWithdrawAmount method to calculate the maximum amount a user can withdraw from a vault, optionally including the assets freed by burning their osToken. --- #### Description: -How much a user can withdraw. Use this method if the user has mintedAssets, if minted balance is null then maxWithdraw will be equal to stakedAssests. +How much a user can withdraw. The result accounts for the user's minted osToken; if there is no minted balance, it equals their staked assets. Pass `withBurn: true` to also include the assets that would be freed by burning the user's osToken, capped by the balance held in their wallet. #### Arguments: -| Name | Type | Required | Info | -|--------------|----------|----------|--------------------------------------------------------------| -| vaultAddress | `string` | **Yes** | The address of the vault | -| userAddress | `string` | **Yes** | The address of the user | +| Name | Type | Required | Info | +|--------------|-----------|----------|------------------------------------------------------------------| +| vaultAddress | `string` | **Yes** | The address of the vault | +| userAddress | `string` | **Yes** | The address of the user | +| withBurn | `boolean` | No | Include assets freed by burning osToken (capped by the wallet) | #### Returns: diff --git a/docs/sdk/API/01-vault/getUserRewards.md b/docs/sdk/API/01-vault/getUserRewards.md index 9ea235cb..6b0af09b 100644 --- a/docs/sdk/API/01-vault/getUserRewards.md +++ b/docs/sdk/API/01-vault/getUserRewards.md @@ -30,20 +30,24 @@ type Output = { dailyRewardsJpy: number dailyRewardsKrw: number dailyRewardsAud: number + dailyStakeRewards: number + dailyBoostRewards: number } ``` -| Name | Description | -|-------------------|---------------------------| -| `date` | Сurrent rate date | -| `dailyRewards` | Daily reward asset in ETH | -| `dailyRewardsUsd` | Daily reward asset in USD | -| `dailyRewardsEur` | Daily reward asset in EUR | -| `dailyRewardsGbp` | Daily reward asset in GBP | -| `dailyRewardsCny` | Daily reward asset in CNY | -| `dailyRewardsJpy` | Daily reward asset in JPY | -| `dailyRewardsKrw` | Daily reward asset in KRW | -| `dailyRewardsAud` | Daily reward asset in AUD | +| Name | Description | +|---------------------|---------------------------------| +| `date` | Сurrent rate date | +| `dailyRewards` | Daily reward asset in ETH | +| `dailyRewardsUsd` | Daily reward asset in USD | +| `dailyRewardsEur` | Daily reward asset in EUR | +| `dailyRewardsGbp` | Daily reward asset in GBP | +| `dailyRewardsCny` | Daily reward asset in CNY | +| `dailyRewardsJpy` | Daily reward asset in JPY | +| `dailyRewardsKrw` | Daily reward asset in KRW | +| `dailyRewardsAud` | Daily reward asset in AUD | +| `dailyStakeRewards` | Daily stake reward asset in ETH | +| `dailyBoostRewards` | Daily boost reward asset in ETH | #### Example: diff --git a/docs/sdk/API/02-boost/01-transactions/lock.md b/docs/sdk/API/02-boost/01-transactions/lock.md index 7f598059..6c21e59e 100644 --- a/docs/sdk/API/02-boost/01-transactions/lock.md +++ b/docs/sdk/API/02-boost/01-transactions/lock.md @@ -10,20 +10,21 @@ Boost your osToken apy using leverage staking #### Arguments: -| Name | Type | Required | Description | -|-----------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| amount | `bigint` | **Yes** | Boost amount | -| userAddress | `string` | **Yes** | The user address | -| vaultAddress | `string` | **Yes** | The address of the vault that will mint osTokens for leverage staking | -| boostAddress | `string` | **Yes** | The address of the strategy proxy using the [sdk.boost.getLeverageStrategyProxy](/sdk/api/boost/requests/getleveragestrategyproxy) method | -| referrerAddress | `string` | **No** | The address of the referrer | -| permitParams | `PermitParams` | **No** | The permit signature is required if there isn’t enough osToken allowance for the strategy proxy contract.

**For MultiSig**
The permit signature is not necessary for Multi Sig (e.g. Safe Wallet), as it should use `sdk.contracts.tokens.mintToken.approve(boostAddress, MaxUint256)` instead of a permit call to set up osToken allowance. This will be called in the action if needed.

**For other wallets**
The permit signature is optional since it will be obtained automatically using the [utils.getPermitSignature](/sdk/api/utils/getpermitsignature) method. | +| Name | Type | Required | Description | +|----------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| amount | `bigint` | **Yes** | Boost amount | +| userAddress | `string` | **Yes** | The user address | +| vaultAddress | `string` | **Yes** | The address of the vault that will mint osTokens for leverage staking | +| boostAddress | `string` | **Yes** | The address of the strategy proxy using the [sdk.boost.getLeverageStrategyProxy](/sdk/api/boost/requests/getleveragestrategyproxy) method | +| referrerAddress | `string` | **No** | The address of the referrer | +| permitParams | `PermitParams` | **No** | The permit signature is required if there isn’t enough osToken allowance for the strategy proxy contract.

**For MultiSig**
The permit signature is not necessary for Multi Sig (e.g. Safe Wallet), as it should use `sdk.contracts.tokens.mintToken.approve(boostAddress, MaxUint256)` instead of a permit call to set up osToken allowance. This will be called in the action if needed.

**For other wallets**
The permit signature is optional since it will be obtained automatically using the [utils.getPermitSignature](/sdk/api/utils/getpermitsignature) method. | +| approveParams | `ApproveParams` | **No** | Force an on-chain `approve` instead of an off-chain permit, so the approval can be one of the bundled calls in an EIP-5792 transaction batch. When provided, `lock.encode` returns `approveTxData` for EOAs too (not only MultiSig) and `lockTxData` omits the permit. `amount` is the approval amount, must be greater than 0 — pass `MaxUint256` for unlimited allowance. | | leverageStrategyData | `LeverageStrategyData` | **No** | Leverage strategy data from [sdk.boost.getLeverageStrategyData](/sdk/api/boost/requests/getleveragestrategydata). If not provided, it will be fetched automatically during the transaction | ```ts type LeverageStrategyData = { version: number - isRequired: boolean + isUpgradeRequired: boolean } type PermitParams = { @@ -34,6 +35,10 @@ type PermitParams = { r: string s: string } + +type ApproveParams = { + amount: bigint +} ``` #### Example: diff --git a/docs/sdk/API/02-boost/01-transactions/unlock.md b/docs/sdk/API/02-boost/01-transactions/unlock.md index c5be4155..fe528c97 100644 --- a/docs/sdk/API/02-boost/01-transactions/unlock.md +++ b/docs/sdk/API/02-boost/01-transactions/unlock.md @@ -10,17 +10,17 @@ Unboost your boosted osToken #### Arguments: -| Name | Type | Required | Description | -|----------------------|------------|----------|-----------------------------------------------------| +| Name | Type | Required | Description | +|----------------------|------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | percent | `number` | **Yes** | The percent of the boosted position to unboost. Must be in the range `(0, 100]` - strictly greater than 0 and at most 100. The SDK throws before sending the transaction if `percent` is `0` or below, or above `100`. | -| userAddress | `string` | **Yes** | The user address | -| vaultAddress | `string` | **Yes** | The address of the vault where the osTokens boosted | -| leverageStrategyData | `LeverageStrategyData` | **No** | Leverage strategy data from [sdk.boost.getLeverageStrategyData](/sdk/api/boost/requests/getleveragestrategydata). If not provided, it will be fetched automatically during the transaction | +| userAddress | `string` | **Yes** | The user address | +| vaultAddress | `string` | **Yes** | The address of the vault where the osTokens boosted | +| leverageStrategyData | `LeverageStrategyData` | **No** | Leverage strategy data from [sdk.boost.getLeverageStrategyData](/sdk/api/boost/requests/getleveragestrategydata). If not provided, it will be fetched automatically during the transaction | ```ts type LeverageStrategyData = { version: number - isRequired: boolean + isUpgradeRequired: boolean } ``` diff --git a/docs/sdk/API/03-osToken/getMaxMintAmount.md b/docs/sdk/API/03-osToken/getMaxMintAmount.md index f19bc303..d29e9de7 100644 --- a/docs/sdk/API/03-osToken/getMaxMintAmount.md +++ b/docs/sdk/API/03-osToken/getMaxMintAmount.md @@ -13,6 +13,7 @@ Maximum number of **shares** for minting |------------------|----------|----------|--------------------------------------------------------------| | userAddress | `string` | **Yes** | The user address | | vaultAddress | `string` | **Yes** | The address of the vault | +| additionalStakedAssets | `bigint` | **No** | Extra staked assets to fold into the position before computing the max — e.g. a deposit being staked in the same transaction. See [sdk.vault.depositAndMint](/sdk/api/vault/transactions/depositandmint), whose `receiveShares` you size with this | #### Returns: @@ -27,3 +28,13 @@ await sdk.osToken.getMaxMintAmount({ vaultAddress: '0x...', }) ``` + +When staking and minting in the same transaction, pass the not-yet-confirmed deposit as `additionalStakedAssets` so the max accounts for it — this is how you size `receiveShares` for [sdk.vault.depositAndMint](/sdk/api/vault/transactions/depositandmint): + +```ts +await sdk.osToken.getMaxMintAmount({ + userAddress: '0x...', + vaultAddress: '0x...', + additionalStakedAssets: parseEther('1'), // assets being staked in the same batch +}) +``` diff --git a/docs/sdk/API/03-osToken/helpers/getBurnAmountForUnstake.md b/docs/sdk/API/03-osToken/helpers/getBurnAmountForUnstake.md index e2af85c1..517ebbbf 100644 --- a/docs/sdk/API/03-osToken/helpers/getBurnAmountForUnstake.md +++ b/docs/sdk/API/03-osToken/helpers/getBurnAmountForUnstake.md @@ -1,18 +1,19 @@ --- id: getBurnAmountForUnstake slug: /sdk/api/osToken/helpers/getburnamountforunstake -description: Use the StakeWise SDK getBurnAmountForUnstake helper to calculate osTokens that must be burned to enable full unstaking. +description: Use the StakeWise SDK getBurnAmountForUnstake helper to calculate the osToken that must be burned to unstake, in full or up to a target amount. --- #### Description: -This method returns the amount of osToken that must be burned to enable unstaking of all underlying tokens. +Returns the amount of osToken that must be burned to unstake. Omit `assets` for a full exit (all underlying tokens); pass a target `assets` to burn only what that withdrawal needs — it returns `0n` when the amount is already within the max withdraw. #### Arguments: -| Name | Type | Required | Description | -|-----------------|----------|----------|--------------------------------------------------------------| -| vaultAddress | `string` | **Yes** | The address of the vault | -| userAddress | `string` | **Yes** | The user address | +| Name | Type | Required | Description | +|--------------|----------|----------|------------------------------------------------| +| vaultAddress | `string` | **Yes** | The address of the vault | +| userAddress | `string` | **Yes** | The user address | +| assets | `bigint` | **No** | Target withdrawal amount, omit for a full exit | #### Returns: diff --git a/docs/sdk/API/03-osToken/helpers/getUnstakeAmountForBurn.md b/docs/sdk/API/03-osToken/helpers/getUnstakeAmountForBurn.md new file mode 100644 index 00000000..71990f9a --- /dev/null +++ b/docs/sdk/API/03-osToken/helpers/getUnstakeAmountForBurn.md @@ -0,0 +1,37 @@ +--- +id: getUnstakeAmountForBurn +slug: /sdk/api/osToken/helpers/getunstakeamountforburn +description: Use the StakeWise SDK getUnstakeAmountForBurn helper to find how much can be unstaked by burning a given amount of osToken. +--- + +#### Description: + +Returns how much can be unstaked if you burn `shares` of osToken. You get the vault shares to send to the exit queue and their value in underlying tokens. + +The result never breaks the vault's LTV limit, so the burn and the exit can go in one transaction. If the position is already above the limit, the result is lowered to fit. + +#### Arguments: +| Name | Type | Required | Description | +|--------------|----------|----------|-----------------------------------| +| vaultAddress | `string` | **Yes** | The address of the vault | +| userAddress | `string` | **Yes** | The user address | +| shares | `bigint` | **Yes** | The amount of osToken to burn | + +#### Returns: + +```ts +type Output = { + receivedAssets: bigint + exitQueueShares: bigint +} +``` + +#### Example: + +```ts +const { exitQueueShares, receivedAssets } = await sdk.osToken.getUnstakeAmountForBurn({ + userAddress: '0x...', + vaultAddress: '0x...', + shares: 1000000000000000000n, +}) +``` diff --git a/docs/sdk/API/06-utils/checkTxBatchSupported.md b/docs/sdk/API/06-utils/checkTxBatchSupported.md new file mode 100644 index 00000000..7b9e9295 --- /dev/null +++ b/docs/sdk/API/06-utils/checkTxBatchSupported.md @@ -0,0 +1,28 @@ +--- +id: checkTxBatchSupported +slug: /sdk/api/utils/checktxbatchsupported +description: Use the StakeWise SDK checkTxBatchSupported utility to detect whether the connected wallet supports atomic EIP-5792 transaction batching. +--- + +#### Description: + +Checks whether the connected wallet supports atomic EIP-5792 transaction batching (`wallet_sendCalls`) on the current network. Returns `false` when the wallet does not implement EIP-5792 or the provider is read-only. + +#### Arguments: +| Name | Type | Required | Description | +|-------------|----------|----------|------------------| +| userAddress | `string` | **Yes** | The user address | + +#### Returns: + +```ts +type Output = boolean +``` + +#### Example: + +```ts +const isTxBatchSupported = await sdk.utils.checkTxBatchSupported({ + userAddress: '0x...', +}) +``` diff --git a/docs/sdk/ai-assistance.md b/docs/sdk/ai-assistance.md new file mode 100644 index 00000000..64639dd0 --- /dev/null +++ b/docs/sdk/ai-assistance.md @@ -0,0 +1,29 @@ +--- +id: ai-assistance +title: AI-Assisted Development +sidebar_position: 6 +description: Use Context7 to give your AI coding assistant accurate, version-correct StakeWise V3 SDK documentation and avoid hallucinated APIs. +--- + +# AI-Assisted Development + +AI coding assistants (Claude Code, Cursor, Copilot, …) often invent SDK method names or miss invariants like the post-write subgraph wait — their training data is stale. This SDK publishes its docs to **Context7** so your assistant works from the current API instead. + +## Context7 + +[Context7](https://context7.com/stakewise/v3-sdk) (library ID `/stakewise/v3-sdk`) serves LLMs the latest SDK docs and typed snippets on demand. It auto-syncs from this repo's `documentation/` and `src/services/`, so it tracks every release. + +## Using it + +Add the Context7 MCP server to your assistant (per-editor setup at [context7.com](https://context7.com)), then append `use context7` to an SDK prompt: + +``` +Read-only SDK setup that fetches a user's stake balance and osToken +position for a Mainnet vault. use context7 +``` + +Pin the library explicitly with `use library /stakewise/v3-sdk`. No MCP support? Open the library page and paste the snippets you need. + +## What it covers + +The same ground as these docs — init, the [`waitForSubgraph`](./fundamentals/subgraph-indexing.md) rule, [network immutability](./fundamentals/network-switching.md), the three transaction forms, V3 token naming, and every `sdk.vault.* / osToken.* / boost.* / utils.*` signature. Tell the assistant to prefer it over its own memory for any SDK API; if a method isn't in the results, treat it as hallucinated and check the [SDK Reference](./reference.md). diff --git a/docs/sdk/fundamentals/batch-transactions.md b/docs/sdk/fundamentals/batch-transactions.md new file mode 100644 index 00000000..0f0fb83f --- /dev/null +++ b/docs/sdk/fundamentals/batch-transactions.md @@ -0,0 +1,215 @@ +--- +id: batch-transactions +title: Batch transactions +sidebar_position: 2 +description: Bundle several StakeWise SDK operations into one atomic EIP-5792 transaction. Encode each step, collect the calls, and submit them together with wallet_sendCalls. Covers deposit, deposit + boost, boost, and unboost. +--- + +# Batch transactions + +Modern wallets can run several contract calls as a single atomic transaction ([EIP-5792](https://eips.ethereum.org/EIPS/eip-5792)) - the user signs once and either all calls succeed or none do. + +The recipe is always the same three steps: + +1. **Encode** each operation with its `.encode()` form. Instead of sending, it returns transaction data `{ to, data, value? }`. +2. **Collect** those into a `calls` array, in order. +3. **Submit** the array to the wallet with `wallet_sendCalls`. + +Every write method already has an `.encode()` form, so batching is just combining them. + +## Check wallet support + +Not every wallet can batch. Ask first with `sdk.utils.checkTxBatchSupported` and fall back to sending the calls one by one when it returns `false`. + +```ts +const isTxBatchSupported = await sdk.utils.checkTxBatchSupported({ userAddress }) + +if (isTxBatchSupported) { + // collect encoded calls and send batch +} +else { + // send transactions one by one +} +``` + +## Send a batch + +A `call` is `{ to: string, data: string, value?: bigint }`. This helper forwards an array of calls to the wallet with `wallet_sendCalls`, then polls `wallet_getCallsStatus` until the batch is mined and returns the final transaction hash. + +```ts +import { StakeWiseSDK, Network } from '@stakewise/v3-sdk' + + +type Call = { + to: string + data: string + value?: bigint +} + +type SendBatchInput = { + sdk: StakeWiseSDK + calls: Call[] + userAddress: string +} + +const sendBatch = async ({ sdk, calls, userAddress }: SendBatchInput) => { + const chainId = `0x${Network.Mainnet.toString(16)}` + + const sendResult = await sdk.provider.send('wallet_sendCalls', [ + { + chainId, + version: '2.0.0', + from: userAddress, + atomicRequired: true, + calls: calls.map(({ to, data, value }) => ( + typeof value === 'bigint' + ? { to, data, value: `0x${value.toString(16)}` } + : { to, data } + )), + }, + ]) + + const id = typeof sendResult === 'string' ? sendResult : sendResult.id + + let result = await sdk.provider.send('wallet_getCallsStatus', [ id ]) + + while (result.status < 200) { + await new Promise((resolve) => setTimeout(resolve, 2000)) + + result = await sdk.provider.send('wallet_getCallsStatus', [ id ]) + } + + const receipts = result.receipts || [] + + // status 200 means "included", not "succeeded" - an inner call can still revert, so check each receipt + const isReverted = receipts.some(({ status }) => status === '0x0') + + if (isReverted) { + throw new Error('Batch reverted') + } + + return receipts[receipts.length - 1]?.transactionHash +} +``` + +> On Gnosis the deposit token (GNO) is an ERC-20, so any flow that deposits needs an `approve` call before the deposit. On a network with a native deposit token (ETH on Mainnet/Hoodi) the deposit carries its own `value` and no approve is required. The examples show the native-token case; on Gnosis prepend an ERC-20 `approve` of the deposit token for the vault. + +## Deposit (stake) + +On a network with a native deposit token (ETH on Mainnet/Hoodi) a deposit is a single call - no batch needed. On Gnosis the deposit token is an ERC-20, so a stake becomes a two-call batch whenever the vault's allowance can't cover it: approve, then deposit. + +```ts +const assets = parseEther('1') + +const depositToken = sdk.contracts.helpers.createErc20(sdk.config.addresses.tokens.depositToken) + +// Prepend an approve only when the current allowance is short - otherwise it stays a single deposit call +const allowance = await depositToken.allowance(userAddress, vaultAddress) + +const approve = allowance < assets + ? await depositToken.approve.populateTransaction(vaultAddress, assets) + : null + +const deposit = await sdk.vault.deposit.encode({ + assets, + userAddress, + vaultAddress, +}) + +const calls = [ approve, deposit ].filter(Boolean) as Call[] + +const hash = await sendBatch({ sdk, userAddress, calls }) +``` + +Stake-and-mint batches the same way: swap `sdk.vault.deposit` for [`sdk.vault.depositAndMint`](/sdk/api/vault/transactions/depositandmint) (size the minted osToken with `getMaxMintAmount`) and prepend the same approve on Gnosis. + +## Deposit and boost + +Stake, mint osToken, and lock it into the Boost leverage strategy. Combine `depositAndMint` with `sdk.boost.lock.encode`, which returns the boost sub-calls - the leverage-strategy upgrade (only when required), the osToken `approve` for the strategy proxy, and the lock itself. Pass `approveParams` so the approval is emitted as a call inside the batch. Drop the empty ones with `filter(Boolean)`. + +```ts +const assets = parseEther('1') + +const boostShares = await sdk.osToken.getMaxMintAmount({ + userAddress, + vaultAddress, + additionalStakedAssets: assets, +}) + +const depositAndMint = await sdk.vault.depositAndMint.encode({ + assets, + userAddress, + vaultAddress, + receiveShares: boostShares, +}) + +const { lockTxData, approveTxData, upgradeLeverageStrategyTxData } = await sdk.boost.lock.encode({ + amount: boostShares, + userAddress, + vaultAddress, + approveParams: { amount: boostShares }, +}) + +const calls = [ + upgradeLeverageStrategyTxData, + depositAndMint, + approveTxData, + lockTxData, +].filter(Boolean) as Call[] + +const hash = await sendBatch({ sdk, calls, userAddress }) +``` + +## Boost (lock) + +Boost an osToken position you already hold. `sdk.boost.lock.encode` gives you the upgrade, approve, and lock calls; keep the ones that are present. + +```ts +const boost = await sdk.boost.lock.encode({ + amount: parseEther('1'), + userAddress, + vaultAddress, +}) + +const { lockTxData, approveTxData, upgradeLeverageStrategyTxData } = boost + +const calls = [ + upgradeLeverageStrategyTxData, + approveTxData, + lockTxData, +].filter(Boolean) as Call[] + +const hash = await sendBatch({ sdk, calls, userAddress }) +``` + +## Unboost (unlock) + +Exit part or all of a boost position. `percent` is how much of the boosted position to unlock, in `(0, 100]`. `sdk.boost.unlock.encode` returns the unlock call plus an optional strategy upgrade. + +```ts +const unboost = await sdk.boost.unlock.encode({ + percent: 100, + userAddress, + vaultAddress, +}) + +const { unlockTxData, upgradeLeverageStrategyTxData } = unboost + +const calls = [ + upgradeLeverageStrategyTxData, + unlockTxData, +].filter(Boolean) as Call[] + +const hash = await sendBatch({ sdk, calls, userAddress }) +``` + +## Fallback without batching + +When `checkTxBatchSupported` returns `false`, send the same steps as separate transactions with the regular methods: + +- **Deposit and mint** - [sdk.vault.deposit](/sdk/api/vault/transactions/deposit) then [sdk.osToken.mint](/sdk/api/osToken/transactions/mint). +- **Deposit and boost** - [sdk.vault.deposit](/sdk/api/vault/transactions/deposit), [sdk.osToken.mint](/sdk/api/osToken/transactions/mint), then [sdk.boost.lock](/sdk/api/boost/transactions/lock). +- **Boost** - [sdk.boost.lock](/sdk/api/boost/transactions/lock). +- **Unboost** - [sdk.boost.unlock](/sdk/api/boost/transactions/unlock). + +Each one waits for its own transaction (`sdk.provider.waitForTransaction`) and subgraph sync (`sdk.utils.waitForSubgraph`) before the next.