diff --git a/docs/developer-reference/sdk/API.md b/docs/developer-reference/sdk/API.md index ce2a4db3..754ebc29 100644 --- a/docs/developer-reference/sdk/API.md +++ b/docs/developer-reference/sdk/API.md @@ -253,7 +253,7 @@ This class provides functionality to: ### Example -See the [swap guide](../../integration-guides/swapping/swaps-with-sor-sdk.md) and [swap examples](https://github.com/MattPereira/v3-pool-operation-examples/tree/main/scripts/hardhat/swap). +See the [swap guide](../../integration-guides/swapping/swaps-with-sor-sdk.md) and [swap examples](https://github.com/balancer/balancer-v3-sdk-examples/tree/main/scripts/swap). ### Constructor diff --git a/docs/developer-reference/sdk/README.md b/docs/developer-reference/sdk/README.md index fef2afa2..13c75253 100644 --- a/docs/developer-reference/sdk/README.md +++ b/docs/developer-reference/sdk/README.md @@ -40,4 +40,4 @@ npm install @balancer/sdk For detailed guides explaining how to use the SDK for common actions please see [Developer Guides](../../integration-guides/). -There are also detailed examples that run against a local fork in the [pool operation examples repo](https://github.com/MattPereira/v3-pool-operation-examples). \ No newline at end of file +There are also detailed examples that run against a local fork in the [SDK examples repo](https://github.com/balancer/balancer-v3-sdk-examples/tree/main/scripts/swap). \ No newline at end of file diff --git a/docs/integration-guides/add-liquidity/overview.md b/docs/integration-guides/add-liquidity/overview.md index 35424d57..5a1e5c88 100644 --- a/docs/integration-guides/add-liquidity/overview.md +++ b/docs/integration-guides/add-liquidity/overview.md @@ -33,21 +33,23 @@ The core concepts of adding liquidity are the same for any programming language ## Example Scripts -Run any of the scripts listed below against a local fork of Ethereum mainnet using the [v3 pool operation examples repo](https://github.com/MattPereira/v3-pool-operation-examples/tree/main?tab=readme-ov-file#balancer-v3-pool-operation-examples) +:::tip +Run example scripts against a local fork using our [typescript SDK](https://github.com/balancer/balancer-v3-sdk-examples/tree/main) and [foundry starter](https://github.com/balancer/pool-operation-examples-v3) repos +::: #### TypeScript SDK -- [addLiquidityUnbalanced.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/add-liquidity/addLiquidityUnbalanced.ts) -- [addLiquidityProportional.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/add-liquidity/addLiquidityProportional.ts) -- [addLiquidityUnbalancedToERC4626.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/add-liquidity/addLiquidityUnbalancedToERC4626Pool.ts) -- [addLiquidityProportionalToERC4626.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/add-liquidity/addLiquidityProportionalToERC4626Pool.ts) +- [addLiquidityUnbalanced.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/add-liquidity/addLiquidityUnbalanced.ts) +- [addLiquidityProportional.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/add-liquidity/addLiquidityProportional.ts) +- [addLiquidityUnbalancedToERC4626.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/add-liquidity/addLiquidityUnbalancedToERC4626Pool.ts) +- [addLiquidityProportionalToERC4626.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/add-liquidity/addLiquidityProportionalToERC4626Pool.ts) #### Solidity -- [AddLiquidityUnbalanced.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/add-liquidity/AddLiquidityUnbalanced.s.sol) -- [AddLiquidityProportional.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/add-liquidity/AddLiquidityProportional.s.sol) -- [AddLiquidityUnbalancedToERC4626.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/add-liquidity/AddLiquidityUnbalancedToERC4626Pool.s.sol) -- [AddLiquidityProportionalToERC4626.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/add-liquidity/AddLiquidityProportionalToERC4626Pool.s.sol) +- [AddLiquidityUnbalanced.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/add-liquidity/AddLiquidityUnbalanced.s.sol) +- [AddLiquidityProportional.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/add-liquidity/AddLiquidityProportional.s.sol) +- [AddLiquidityUnbalancedToERC4626.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/add-liquidity/AddLiquidityUnbalancedToERC4626Pool.s.sol) +- [AddLiquidityProportionalToERC4626.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/add-liquidity/AddLiquidityProportionalToERC4626Pool.s.sol) ## Beginner Tutorials diff --git a/docs/integration-guides/add-liquidity/sdk-tutorial.md b/docs/integration-guides/add-liquidity/sdk-tutorial.md index 0ac81f68..35a2214a 100644 --- a/docs/integration-guides/add-liquidity/sdk-tutorial.md +++ b/docs/integration-guides/add-liquidity/sdk-tutorial.md @@ -36,9 +36,9 @@ npm install @balancer/sdk ### Example Script -Run this example script on a local fork of Ethereum mainnet using our [v3 pool operation examples repo](https://github.com/MattPereira/v3-pool-operation-examples/tree/main?tab=readme-ov-file#balancer-v3-pool-operation-examples) +Run this example script on a local fork of Ethereum mainnet using our [SDK examples repo](https://github.com/balancer/balancer-v3-sdk-examples/tree/main) - + The four main helper classes we use from the SDK are: diff --git a/docs/integration-guides/add-liquidity/solidity-tutorial.md b/docs/integration-guides/add-liquidity/solidity-tutorial.md index c6462fe5..547ee15a 100644 --- a/docs/integration-guides/add-liquidity/solidity-tutorial.md +++ b/docs/integration-guides/add-liquidity/solidity-tutorial.md @@ -13,4 +13,4 @@ The following code snippet shows how to add liquidity from a smart contract. ::: warning Queries should not be used onchain to set minAmountOut due to possible manipulation via frontrunning. ::: - + diff --git a/docs/integration-guides/remove-liquidity/overview.md b/docs/integration-guides/remove-liquidity/overview.md index d61e0fec..ec96952b 100644 --- a/docs/integration-guides/remove-liquidity/overview.md +++ b/docs/integration-guides/remove-liquidity/overview.md @@ -33,21 +33,23 @@ The core concepts of removing liquidity are the same for any programming languag ## Example Scripts -Run example scripts against a local fork of Ethereum mainnet using the [v3 pool operation examples repo](https://github.com/MattPereira/v3-pool-operation-examples/tree/main?tab=readme-ov-file#balancer-v3-pool-operation-examples) +:::tip +Run example scripts against a local fork using our [typescript SDK](https://github.com/balancer/balancer-v3-sdk-examples/tree/main) and [foundry starter](https://github.com/balancer/pool-operation-examples-v3) repos +::: #### TypeScript SDK -- [removeLiquidityProportional.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/remove-liquidity/removeLiquidityProportional.ts) -- [removeLiquidityProportionalFromERC4626Pool.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/remove-liquidity/removeLiquidityProportionalFromERC4626Pool.ts) -- [removeLiquiditySingleTokenExactIn.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/remove-liquidity/removeLiquiditySingleTokenExactIn.ts) -- [removeLiquiditySingleTokenExactOut.ts](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/hardhat/remove-liquidity/removeLiquiditySingleTokenExactOut.ts) +- [removeLiquidityProportional.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/remove-liquidity/removeLiquidityProportional.ts) +- [removeLiquidityProportionalFromERC4626Pool.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/remove-liquidity/removeLiquidityProportionalFromERC4626Pool.ts) +- [removeLiquiditySingleTokenExactIn.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/remove-liquidity/removeLiquiditySingleTokenExactIn.ts) +- [removeLiquiditySingleTokenExactOut.ts](https://github.com/balancer/balancer-v3-sdk-examples/blob/main/scripts/remove-liquidity/removeLiquiditySingleTokenExactOut.ts) #### Solidity -- [RemoveLiquidityProportional.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/remove-liquidity/RemoveLiquidityProportional.s.sol) -- [RemoveLiquidityProportionalFromERC4626Pool.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/remove-liquidity/RemoveLiquidityProportionalFromERC4626Pool.s.sol) -- [RemoveLiquiditySingleTokenExactIn.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/remove-liquidity/RemoveLiquiditySingleTokenExactIn.s.sol) -- [RemoveLiquiditySingleTokenExactOut.s.sol](https://github.com/MattPereira/v3-pool-operation-examples/blob/main/scripts/foundry/remove-liquidity/RemoveLiquiditySingleTokenExactOut.s.sol) +- [RemoveLiquidityProportional.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/remove-liquidity/RemoveLiquidityProportional.s.sol) +- [RemoveLiquidityProportionalFromERC4626Pool.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/remove-liquidity/RemoveLiquidityProportionalFromERC4626Pool.s.sol) +- [RemoveLiquiditySingleTokenExactIn.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/remove-liquidity/RemoveLiquiditySingleTokenExactIn.s.sol) +- [RemoveLiquiditySingleTokenExactOut.s.sol](https://github.com/balancer/pool-operation-examples-v3/blob/main/scripts/foundry/remove-liquidity/RemoveLiquiditySingleTokenExactOut.s.sol) ## Beginner Tutorials diff --git a/docs/integration-guides/remove-liquidity/sdk-tutorial.md b/docs/integration-guides/remove-liquidity/sdk-tutorial.md index e0a6c4b0..29a5475b 100644 --- a/docs/integration-guides/remove-liquidity/sdk-tutorial.md +++ b/docs/integration-guides/remove-liquidity/sdk-tutorial.md @@ -36,9 +36,9 @@ npm install @balancer/sdk ### Example Script -Run this example script on a local fork of Ethereum mainnet using our [v3 pool operation examples repo](https://github.com/MattPereira/v3-pool-operation-examples/tree/main?tab=readme-ov-file#balancer-v3-pool-operation-examples) +Run this example script on a local fork of Ethereum mainnet using our [SDK examples repo](https://github.com/balancer/balancer-v3-sdk-examples/tree/main) - + The four main helper classes we use from the SDK are: diff --git a/docs/integration-guides/remove-liquidity/solidity-tutorial.md b/docs/integration-guides/remove-liquidity/solidity-tutorial.md index 49c98d30..2ae43a76 100644 --- a/docs/integration-guides/remove-liquidity/solidity-tutorial.md +++ b/docs/integration-guides/remove-liquidity/solidity-tutorial.md @@ -13,4 +13,4 @@ The following code snippet shows how to remove liquidity from a smart contract. ::: warning Queries should not be used onchain to set minAmountOut due to possible manipulation via frontrunning. ::: - + diff --git a/docs/integration-guides/swapping/swapping-custom-paths-with-router.md b/docs/integration-guides/swapping/swapping-custom-paths-with-router.md index 7884ab2a..37ff8d4e 100644 --- a/docs/integration-guides/swapping/swapping-custom-paths-with-router.md +++ b/docs/integration-guides/swapping/swapping-custom-paths-with-router.md @@ -30,67 +30,7 @@ The following sections provide specific implementation details for Javascript (w The SDK `Swap` object provides functionality to easily fetch updated swap quotes and create swap transactions with user defined slippage protection. -```typescript -import { - ChainId, - Slippage, - SwapKind, - Swap, - SwapBuildOutputExactIn, - ExactInQueryOutput -} from "@balancer/sdk"; -import { Address } from "viem"; - -// User defined -const swapInput = { - chainId: ChainId.SEPOLIA, - swapKind: SwapKind.GivenIn, - paths: [ - { - pools: ["0x1e5b830439fce7aa6b430ca31a9d4dd775294378" as Address], - tokens: [ - { - address: "0xb19382073c7a0addbb56ac6af1808fa49e377b75" as Address, - decimals: 18, - }, // tokenIn - { - address: "0xf04378a3ff97b3f979a46f91f9b2d5a1d2394773" as Address, - decimals: 18, - }, // tokenOut - ], - vaultVersion: 3 as const, - inputAmountRaw: 1000000000000000000n, - outputAmountRaw: 990000000000000000n, - }, - ], -}; - -// Swap object provides useful helpers for re-querying, building call, etc -const swap = new Swap(swapInput); - -console.log( - `Input token: ${swap.inputAmount.token.address}, Amount: ${swap.inputAmount.amount}` -); -console.log( - `Output token: ${swap.outputAmount.token.address}, Amount: ${swap.outputAmount.amount}` -); - -// Get up to date swap result by querying onchain -const updatedOutputAmount = await swap.query(RPC_URL) as ExactInQueryOutput; -console.log(`Updated amount: ${updatedOutputAmount.expectedAmountOut}`); - -// Build call data using user defined slippage -const callData = swap.buildCall({ - slippage: Slippage.fromPercentage("0.1"), // 0.1%, - deadline: 999999999999999999n, // Deadline for the swap, in this case infinite - queryOutput: updatedOutputAmount, - wethIsEth: false - }) as SwapBuildOutputExactIn; - -console.log( - `Min Amount Out: ${callData.minAmountOut.amount}\n\nTx Data:\nTo: ${callData.to}\nCallData: ${callData.callData}\nValue: ${callData.value}` -); -``` + ### Install the Balancer SDK @@ -149,28 +89,22 @@ type Path = { Using the input given above as an illustrative example: ```typescript -const swapInput = { - chainId: ChainId.SEPOLIA, - swapKind: SwapKind.GivenIn, - paths: [ - { - pools: ["0x1e5b830439fce7aa6b430ca31a9d4dd775294378" as Address], - tokens: [ - { - address: "0xb19382073c7a0addbb56ac6af1808fa49e377b75" as Address, - decimals: 18, - }, // tokenIn - { - address: "0xf04378a3ff97b3f979a46f91f9b2d5a1d2394773" as Address, - decimals: 18, - }, // tokenOut - ], - vaultVersion: 3 as const, - inputAmountRaw: 1000000000000000000n, - outputAmountRaw: 990000000000000000n, - }, - ], -}; + const swapInput = { + chainId: ChainId.SEPOLIA, + swapKind: SwapKind.GivenIn, + paths: [ + { + pools: [aaveLidowETHwstETHPool], + tokens: [ + { address: waEthLidowETH, decimals: 18 }, // tokenIn + { address: waEthLidowstETH, decimals: 18 }, // tokenOut + ], + inputAmountRaw: parseUnits('1', 18), + outputAmountRaw: parseUnits('1', 18), + protocolVersion: 3 as const, + }, + ], + }; ``` We can infer: * The swap is of the GivenIn type and is valid for Balancer v3 on Sepolia diff --git a/docs/integration-guides/swapping/swaps-with-sor-sdk.md b/docs/integration-guides/swapping/swaps-with-sor-sdk.md index f1b3524b..025dcade 100644 --- a/docs/integration-guides/swapping/swaps-with-sor-sdk.md +++ b/docs/integration-guides/swapping/swaps-with-sor-sdk.md @@ -9,97 +9,7 @@ This guide showcases the capabilities of the Balancer Smart Order Router (SOR) a _This guide uses the Balancer API SOR which will find the best result using v2 and v3 liquidity. The SDK supports both._ -```typescript -import { - BalancerApi, - ChainId, - Slippage, - SwapKind, - Token, - TokenAmount, - Swap, - SwapBuildOutputExactIn, - SwapBuildCallInput, - ExactInQueryOutput -} from "@balancer/sdk"; - -// User defined -const chainId = ChainId.MAINNET; -const swapKind = SwapKind.GivenIn; -const tokenIn = new Token( - chainId, - "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", - 18, - "WETH" -); -const tokenOut = new Token( - chainId, - "0xba100000625a3754423978a60c9317c58a424e3D", - 18, - "BAL" -); -const wethIsEth = false; // If true, incoming ETH will be wrapped to WETH, otherwise the Vault will pull WETH tokens -const deadline = 999999999999999999n; // Deadline for the swap, in this case infinite -const slippage = Slippage.fromPercentage("0.1"); // 0.1% -const swapAmount = TokenAmount.fromHumanAmount(tokenIn, "1.2345678910"); - -// API is used to fetch best swap paths from available liquidity across v2 and v3 -const balancerApi = new BalancerApi( - "https://api-v3.balancer.fi/", - chainId -); - -const sorPaths = await balancerApi.sorSwapPaths.fetchSorSwapPaths({ - chainId, - tokenIn: tokenIn.address, - tokenOut: tokenOut.address, - swapKind, - swapAmount, -}); - -// Swap object provides useful helpers for re-querying, building call, etc -const swap = new Swap({ - chainId, - paths: sorPaths, - swapKind, -}); - -console.log( - `Input token: ${swap.inputAmount.token.address}, Amount: ${swap.inputAmount.amount}` -); -console.log( - `Output token: ${swap.outputAmount.token.address}, Amount: ${swap.outputAmount.amount}` -); - -// Get up to date swap result by querying onchain -const updated = await swap.query(RPC_URL) as ExactInQueryOutput; -console.log(`Updated amount: ${updated.expectedAmountOut.amount}`); - -let buildInput: SwapBuildCallInput; -// In v2 the sender/recipient can be set, in v3 it is always the msg.sender -if (swap.protocolVersion === 2) { - buildInput = { - slippage, - deadline, - queryOutput: updated, - wethIsEth, - sender: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", - recipient: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", - }; -} else { - buildInput = { - slippage, - deadline, - queryOutput: updated, - wethIsEth, - }; -} -const callData = swap.buildCall(buildInput) as SwapBuildOutputExactIn; - -console.log( - `Min Amount Out: ${callData.minAmountOut.amount}\n\nTx Data:\nTo: ${callData.to}\nCallData: ${callData.callData}\nValue: ${callData.value}` -); -``` + ### Install the Balancer SDK @@ -133,11 +43,8 @@ The three main helper classes we use from the SDK are: In this example we use the BalancerApi `fetchSorSwapPaths` function to fetch the optimized swap paths for a token pair and swap amount. ```typescript -const balancerApi = new BalancerApi( - 'https://api-v3.balancer.fi/', - chainId, -); -const sorPaths = await balancerApi.sorSwapPaths.fetchSorSwapPaths({ +const balancerApi = new BalancerApi('https://api-v3.balancer.fi/', chainId); +const paths = await balancerApi.sorSwapPaths.fetchSorSwapPaths({ chainId, tokenIn: tokenIn.address, tokenOut: tokenOut.address, @@ -156,13 +63,13 @@ By default the API will return the swap that gives the best result from either v [Router queries](../../concepts/router/queries.md) allow for simulation of operations without execution. In this example, when the `query` function is called: ```typescript -const updated = await swap.query(RPC_URL) as ExactInQueryOutput; +const queryOutput = await swap.query(rpcUrl, await client.getBlockNumber()); ``` An onchain call is used to find an updated result for the swap paths, `expectedAmountOut`. In the next step `buildCall` uses the `amount` and the user defined `slippage` to calculate the `minAmountOut`: ```typescript -const callData = swap.buildCall(buildInput) as SwapBuildOutputExactIn; +const call = swap.buildCallWithPermit2({ queryOutput, slippage }, permit2); ``` In the full example above, we defined our slippage as `Slippage.fromPercentage('1')`, meaning that we if we do not receive at least 99% of our expected `amount`, the transaction should revert.