balancer · MattPereira · Mar 13, 2025
diff --git 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
@@ -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).
+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).
diff --git 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
@@ -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)
 
-<GithubCode url="https://raw.githubusercontent.com/MattPereira/v3-pool-operation-examples/refs/heads/main/scripts/hardhat/add-liquidity/addLiquidityUnbalanced.ts" clipEndLines=8 clipStartLines=4 />
+<GithubCode url="https://raw.githubusercontent.com/balancer/balancer-v3-sdk-examples/refs/heads/main/scripts/add-liquidity/addLiquidityUnbalanced.ts" clipEndLines=8 clipStartLines=11 />
 
 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
@@ -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.
 :::
 
-<GithubCode url="https://raw.githubusercontent.com/MattPereira/v3-pool-operation-examples/refs/heads/main/scripts/foundry/add-liquidity/AddLiquidityUnbalanced.s.sol" />
+<GithubCode url="https://raw.githubusercontent.com/balancer/pool-operation-examples-v3/refs/heads/main/scripts/foundry/add-liquidity/AddLiquidityUnbalanced.s.sol" />
diff --git 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
@@ -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)
 
-<GithubCode url="https://raw.githubusercontent.com/MattPereira/v3-pool-operation-examples/refs/heads/main/scripts/hardhat/remove-liquidity/removeLiquidityProportional.ts" clipEndLines=8 clipStartLines=4 />
+<GithubCode url="https://raw.githubusercontent.com/balancer/balancer-v3-sdk-examples/refs/heads/main/scripts/remove-liquidity/removeLiquidityProportional.ts" clipEndLines=8 clipStartLines=4 />
 
 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
@@ -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.
 :::
 
-<GithubCode url="https://raw.githubusercontent.com/MattPereira/v3-pool-operation-examples/refs/heads/main/scripts/foundry/remove-liquidity/RemoveLiquidityProportional.s.sol"  />
+<GithubCode url="https://raw.githubusercontent.com/balancer/pool-operation-examples-v3/refs/heads/main/scripts/foundry/remove-liquidity/RemoveLiquidityProportional.s.sol"  />
diff --git 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}`
-);
-```
+<GithubCode url="https://raw.githubusercontent.com/balancer/balancer-v3-sdk-examples/refs/heads/main/scripts/swap/swapCustomPath.ts" clipStartLines=9 clipEndLines=8 />
 
 ### 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
@@ -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}`
-);
-```
+<GithubCode url="https://raw.githubusercontent.com/balancer/balancer-v3-sdk-examples/refs/heads/main/scripts/swap/swapSmartPath.ts" clipStartLines=4 clipEndLines=8 />
 
 ### 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.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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).
		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).