Unlocking the Power of Balancer V3: Hook Development Made Simple

Using Balancer V3 peripheral contracts to simplify the development and testing of custom Hooks

In my previous post, I discussed the basics of Balancer Hooks and demonstrated how simple it is to create a custom hook with a decaying exit fee. The ease of development on Balancer V3 is greatly aided by the peripheral smart contracts crafted by the Ballerinas (the team behind Balancer’s smart contracts). These contracts serve as helpful tools, simplifying the testing workflow and enhancing the safety and efficiency of projects. In this article, we will explore these in greater detail, showing how they can make developers lives easier.

The Hook That Holds: Enabling Peg Stability through Fee-Based Solutions

In Balancer’s stable pools, maintaining a healthy peg is crucial for yield-bearing assets like stable coins and staking derivatives. However, as market dynamics take over, one token may become significantly overweight, leading to inefficiencies in trading. The mighty ZenDragon has proposed a possible hook design that defends the peg while allowing passive liquidity providers to benefit from this de-pegging behavior (details to be covered in an upcoming post). One possible implementation of this can be seen in this StableSurge hook example which also serves as a good showcase for the simplified development process.

Peripheral Power

The main hook contract inherits three useful building blocks and uses the custom FixedPoint maths library:

contract StableSurgeHookExample is BaseHooks, VaultGuard, Ownable {...
using FixedPoint for uint256;

BaseHooks

BaseHooks.sol is provided as an abstract contract, with a minimal implementation of a hooks contract. At a high level this contract includes:

  • Base implementation: A complete implementation of the IHooks.sol interface, with each implemented function returning false.
  • Configuration: A virtual function getHookFlags that must be implemented by your hooks contract, defining which hooks your contract supports.

By inheriting this contract a hooks developer can concentrate on implementing the subset of callbacks they are interested in and remain confident the rest of the interface requirement is covered. In the StableSurgeHookExample we override three functions:

getHookFlags

function getHookFlags() public pure override returns (HookFlags memory hookFlags){
  hookFlags.shouldCallComputeDynamicSwapFee = true;
}

This is the only mandatory hook and can effectively be thought of as defining the hook config. When a pool is registered, the Vault calls this function to store the configuration. In this example, the shouldCallComputeDynamicSwapFee flag is set to true, indicating that the contract is configured to calculate the dynamic swap fee.

onRegister

function onRegister(address factory, address pool, TokenConfig[] memory, LiquidityManagement calldata) public override onlyVault returns (bool) {
  return factory == _allowedFactory && IBasePoolFactory(factory).isPoolFromFactory(pool);
}

The onRegister function enables developers to implement custom validation logic to ensure the registration is valid. When a new pool is registered, a hook address can be provided to “link” the pool and the hook. At this stage, the onRegister function is invoked by the Vault, and it must return true for the registration to be successful. If the validation fails, the function should return false, preventing the registration from being completed.

In this example we validate that the factory param forwarded from the Vault matches the _allowedFactory set during the hook deployment, and that the pool was deployed by that factory.

onComputeDynamicSwapFeePercentage

The Vault calls onComputeDynamiceSwapFeePercentageto retrieve the swap fee value. This is where the big brain logic for the hook is implemented. The actual code is fairly long but the pseudo-code looks like:

function onComputeDynamicSwapFeePercentage(
    PoolSwapParams calldata params,
    address pool,
    uint256 staticSwapFeePercentage
) public view override onlyVault returns (bool, uint256) {

  uint256 amountCalculatedScaled18 = StableMath.computeSwapResult(...swapParams);
  uint256 weightAfterSwap = getWeightAfterSwap(balancesAfter);
  if (weightAfterSwap > thresholdBoundary) {
    return (true, getSurgeFee(weightAfterSwap, thresholdBoundary, staticSwapFeePercentage, _surgeCoefficient));
  } else {
    return (true, staticSwapFeePercentage);
  }
}

Essentially the virtual weights of the tokens in the pool after the swap are calculated. If these are above a user defined threshold boundary a fee that is proportional to the weights distance from the threshold is returned. If not the normal static swap fee is used. The reader is encouraged to read the full code and theory to appreciate the implementation 🤓.

VaultGuard

The VaultGuard is a simple contract that shares the modifier onlyVault. This ensures a function can only be called when the sender is the vault.

modifier onlyVault() {
  _ensureOnlyVault();
  _;
}

function _ensureOnlyVault() private view {
  if (msg.sender != address(_vault)) {
  revert IVaultErrors.SenderIsNotVault(msg.sender);
  }
}

While it might seem overly cautious, especially for stateless hooks, it serves a crucial purpose. This restriction maintains predictable behavior and simplifies the reasoning about your contract’s state. It’s like having a bouncer at an exclusive club — sure, letting a few extra people in might not hurt, but it’s easier to manage when you stick to the guest list. This approach aligns with the standard lifecycle of Balancer pools, keeping the contract’s behavior consistent and secure. Of course, if the hook has state, permissioned functions, or any functions other than hook overrides, a more relaxed access policy can be appropriate.

Ownable

Ownable is actually an OpenZeppelin contract which “provides a basic access control mechanism, where there is an account (an owner) that can be granted exclusive access to specific functions.”

Here we are leveraging the onlyOwner to restrict the use of the setThresholdand setSurgeCoefficient functions to the owner of the contract. Ownership is set in the constructor to be the contract deployer:

constructor(
  IVault vault,
  address allowedFactory,
  uint256 threshold,
  uint256 surgeCoefficient
) VaultGuard(vault) Ownable(msg.sender)

function setThreshold(uint64 newThreshold) external onlyOwner {
  _threshold = newThreshold;
}

function setSurgeCoefficient(uint64 newSurgeCoefficient) external onlyOwner {
  _surgeCoefficient = newSurgeCoefficient;
}

FixedPoint

FixedPoint is a very useful library that supports 18-decimal fixed point arithmetic. All Vault calculations use this for high and uniform precision. In this example we use it to calculate the swap fee. Some of the commonly used functions are:

Testing

Testing in production is tempting but risky! The Balancer V3 mono-repo contains extensive tests and exposes a particularly useful BaseVaultTest contract that external teams are already leveraging during their own development. A few of the high level benefits include:

  • A default setup (that is also customizable) that handles all V3 related deployments including Vault, Router, Authorizer, etc and all associated approvals
  • Deployment of test tokens and initial seeding of balances for test accounts (test tokens take decimals as an argument, so you can construct them with different decimals if needed)
  • Easily handle deployment of your custom pools and hooks along with initial pool seeding and LP interactions (including all required approvals for common actions)
  • Helpers to get account balances (including pool balances), vault balances and hook balances

The detail of BaseVaultTest could probably be a post in itself so instead we will look at some specific examples of how I leveraged some of the functionality in my tests for the hook, StableSurgeExample.t.sol.

Test Pool And Hook Setup

As mentioned previously the StableSurge hook is configured to only work with a user configured pool factory. In this test, because the hook is expected to be used with Balancer StablePools, I want to make sure we use the StablePoolFactory. To achieve this we can override the createHook function which is called during the initial BaseVault setup:

function createHook() internal override returns (address) {
  stablePoolFactory = new StablePoolFactory(IVault(address(vault)), 365 days,    "Factory v1", "Pool v1");
  // LP will be the owner of the hook.
  vm.prank(lp);
  address stableSurgeHook = address(
  new StableSurgeHookExample(IVault(address(vault)), address(stablePoolFactory),   THRESHOLD, SURGE_COEFFICIENT)
);
  vm.label(stableSurgeHook, "Stable Surge Hook");
  return stableSurgeHook;
}

Fairly simple to follow, it deploys the StablePoolFactory and uses that address as part of the constructor input when deploying the StableSurgeHookExample. The address of the stableSurgeHook is returned at the end of the function and the BaseVaultTest exposes this via the poolsHookContract variable so it can be used later. Also interesting to note here is the hook is deployed by the lp account which will become the hook owner.

Next to override is the _createPool function which handles the actual pool deployment:

function _createPool(address[] memory tokens, string memory label) internal override returns (address) {
  PoolRoleAccounts memory roleAccounts;

  address newPool = address(
    stablePoolFactory.create(
    "Stable Pool Test",
    "STABLE-TEST",
    vault.buildTokenConfig(tokens.asIERC20()),
    AMP_FACTOR,
    roleAccounts,
    MIN_SWAP_FEE,
    poolHooksContract,
    false, // Does not allow donations
    false, // Do not disable unbalanced add/remove liquidity
    ZERO_BYTES32
  )
  );
  vm.label(newPool, label);  authorizer.grantRole(vault.getActionId(IVaultAdmin.setStaticSwapFeePercentage.selector), admin);
  vm.prank(admin);
  vault.setStaticSwapFeePercentage(newPool, SWAP_FEE_PERCENTAGE);

  return newPool;
}

The StableSurge hook is expected to be used with Balancer Stable Pools so unlike some other hook tests I need to make sure I’m not testing with the default MockPool. I use the stablePoolFactory to create a new pool that is configured to use our previously deployed hook, poolHooksContract. The last part of this process is to use the authorizer to set the pool static swap fee. This will be the expected fee when the pool is not “surging”.

And thats it! Now whenever we run our test (using: $ forge test --match-path test/foundary/StableSurgeExample.t.sol) the setUp function will be called and everything is deployed, seeded and ready for tests.

Testing Balances

The final helper we’ll check out is getBalances which can be found here. This function extracts and returns a collection of essential balances, encompassing test user pool and token balances, hook balances, and vault balances. It’s an invaluable tool for validating correct balance adjustments following operations, streamlining the testing process considerably:

function testSwapBelowThreshold() public {
  BaseVaultTest.Balances memory balancesBefore = getBalances(lp);

  // Calculate the expected amount out (amount out without fees)
  uint256 poolInvariant = StableMath.computeInvariant(
    AMP_FACTOR * StableMath.AMP_PRECISION,
    balancesBefore.poolTokens
  );
  uint256 expectedAmountOut = StableMath.computeOutGivenExactIn(
  AMP_FACTOR * StableMath.AMP_PRECISION,
  balancesBefore.poolTokens,
  daiIdx,
  usdcIdx,
  amountInBelowThreshold,
  poolInvariant
  );

  // Swap with amount that should keep within threshold
  vm.prank(bob);
  router.swapSingleTokenExactIn(pool, dai, usdc, amountInBelowThreshold, 0,   MAX_UINT256, false, bytes(""));

  BaseVaultTest.Balances memory balancesAfter = getBalances(lp);

  // Check Bob's balances (Bob deposited DAI to receive USDC)
  assertEq(
  balancesBefore.bobTokens[daiIdx] - balancesAfter.bobTokens[daiIdx],
  amountInBelowThreshold,
  "Bob DAI balance is wrong"
);

...

There is also an alternative implementation that allows balances to be tracked across user defined tokens/pools.

Conclusion

Hopefully this has given a helpful intro to some of the options available to improve the experience and efficiency while developing on top of Balancer V3. It really is easy and quick to get going so take some time and hack around and please reach out anytime if you have any questions or suggestions!

Unlocking the Power of Balancer V3: Exploring Hooks and Custom Routers

Intro

Balancers latest V3 design offers lots of exciting features such as transient accounting, native support for yield bearing tokens and boosted pools (see intro and docs for more details). Lately I’ve been diving into one of the other new features, hooks, which provide a way for developers to easily extend existing pool types at various key points throughout the pool’s lifecycle.

Hooks are standalone contracts with their own logic and state that can be linked to a pool during registration. Depending on the hook configuration, custom logic can be implemented at specific stages like before/after swapping, adding or removing liquidity (see Hook docs for details).

To explore hooks in more detail, I created a hook that charges a decaying fee for LPs removing liquidity. This is a particularly interesting example as it requires implementing a custom router (which doubles as the hook). This setup enables using NFTs to track both liquidity positions and associated metadata. When users add liquidity, they receive an NFT tied to the LP position’s start time and size. As the owner of this NFT, they can exit their LP position at any time, incurring a fee that diminishes over time since the start.

Are You A Hook Or Are You A Router?

A router is a primary entry point for a user to interact with the Vault and they can contain custom logic. Balancer has developed and deployed official routers that would normally be used for add and remove operations. In this example we need custom logic for adds and removes.

Because a hook is just a standalone contract that must implement the IHooks interface by adding the custom logic to handle adding and removing liquidity we get a single contract that can be both a hook and a router.

Note – in both the official Balancer routers and this implementation Permit2 is used to permission approvals and transfer tokens directly and safely from the user.

Show Me Some Code

For the full code see here. Lets take a look at some of the highlights.

Adding Liquidity

Normally when a user adds liquidity via the Balancer router the BPT minted by the Vault is sent to the msg.sender. In this example the BPT is minted to the router instead. The router mints the msg.sender an NFT with a particular `tokenId`. This tokenId is also used to keep track of the pool address, the BPT amount and the time the liquidity is added which are all used when removing liquidity.

We can see the router `addLiquidityProportional` function a user would call:

function addLiquidityProportional(
    address pool,
    uint256[] memory maxAmountsIn,
    uint256 exactBptAmountOut,
    bool wethIsEth,
    bytes memory userData
) external payable saveSender returns (uint256[] memory amountsIn) {
    // Do addLiquidity operation - BPT is minted to this contract.
    amountsIn = _addLiquidityProportional(
        pool,
        msg.sender,
        address(this),
        maxAmountsIn,
        exactBptAmountOut,
        wethIsEth,
        userData
    );

    uint256 tokenId = _nextTokenId++;
    // Store the initial liquidity amount associated with the NFT.
    bptAmount[tokenId] = exactBptAmountOut;
    // Store the initial start time associated with the NFT.
    startTime[tokenId] = block.timestamp;
    // Store the pool/bpt address associated with the NFT.
    nftPool[tokenId] = pool;
    // Mint the associated NFT to sender.
    _safeMint(msg.sender, tokenId);

    emit LiquidityPositionNftMinted(msg.sender, pool, tokenId);
}

The first step is to call _addLiquidityProportional which is inherited from MinimalRouter. This code is very similar to the official Balancer Router with the subtle change that allows it to specify a receiver of the BPT instead of automatically setting it to the sender. In this example its set to the router itself, address(this) The Router will call the Vault addLiquidity function:

(amountsIn, , ) = abi.decode(
    _vault.unlock(
        abi.encodeWithSelector(
            MinimalRouter.addLiquidityHook.selector,
            ExtendedAddLiquidityHookParams({
                sender: sender,
                receiver: receiver, ------ Note receiver can be set unlike Balancer Router
                pool: pool,
                maxAmountsIn: maxAmountsIn,
                minBptAmountOut: exactBptAmountOut,
                kind: AddLiquidityKind.PROPORTIONAL,
                wethIsEth: wethIsEth,
                userData: userData
            })
        )
    ),
    (uint256[], uint256, bytes)
);

During an addLiquidity operation the Vault checks if the associated hook has set “shouldCallBeforeAddLiquidity` and if true the `onBeforeAddLiquidity` hook function is called:

function onBeforeAddLiquidity(
        address router,
        address,
        AddLiquidityKind,
        uint256[] memory,
        uint256,
        uint256[] memory,
        bytes memory
    ) public view override onlySelfRouter(router) returns (bool) {
        // We only allow addLiquidity via the Router/Hook itself (as it must custody BPT).
        return true;
    }

In this example it has the simple job of making sure that liquidity can only be added via the router itself. If a user tries to add via another router `onlySelfRouter` will fail and block the operation. This is done to ensure the decaying exit fee is always taken into account for any pool using the hook.

The final part of the addLiquidity code is where the NFT and meta data magic happen:

uint256 tokenId = _nextTokenId++;
// Store the initial liquidity amount associated with the NFT.
bptAmount[tokenId] = exactBptAmountOut;
// Store the initial start time associated with the NFT.
startTime[tokenId] = block.timestamp;
// Store the pool/bpt address associated with the NFT.
nftPool[tokenId] = pool;
// Mint the associated NFT to sender.
_safeMint(msg.sender, tokenId);

A new `tokenId` is associated with this particular liquidity position. This is then used to store the particular, pool, BPT amount and time associated with the position and finally a new NFT with the tokenId is minted to the user.

Removing Liquidity

To remove liquidity a user must own an NFT linked to a liquidity position. `removeLiquidityProportional` is called using the `tokenId` of the NFT. During the remove operation the fee to applied is calculated using the previously stored time. Once the operation is complete the NFT is burned and the exit tokens are sent to the user.

We can see `removeLiquidityProportional` called by the user looks like:

function removeLiquidityProportional(
    uint256 tokenId,
    uint256[] memory minAmountsOut,
    bool wethIsEth
) external payable saveSender returns (uint256[] memory amountsOut) {
    // Ensure the user owns the NFT.
    address nftOwner = ownerOf(tokenId);

    if (nftOwner != msg.sender) {
        revert WithdrawalByNonOwner(msg.sender, nftOwner, tokenId);
    }

    address pool = nftPool[tokenId];

    // Do removeLiquidity operation - tokens sent to msg.sender.
    amountsOut = _removeLiquidityProportional(
        pool,
        address(this),
        msg.sender,
        bptAmount[tokenId],
        minAmountsOut,
        wethIsEth,
        abi.encode(tokenId) // tokenId is passed to index fee data in hook
    );

    // Set all associated NFT data to 0.
    bptAmount[tokenId] = 0;
    startTime[tokenId] = 0;
    nftPool[tokenId] = address(0);
    // Burn the NFT
    _burn(tokenId);

    emit LiquidityPositionNftBurned(msg.sender, pool, tokenId);
}

NFT ownership is checked and if the `msg.sender` is not the owner of the NFT with `tokenId` the transaction will revert:

address nftOwner = ownerOf(tokenId);

if (nftOwner != msg.sender) {
    revert WithdrawalByNonOwner(msg.sender, nftOwner, tokenId);
}

The pool address associated with the NFT liquidity position is retrieved from the mapping:

address pool = nftPool[tokenId];

which is then used in the `_removeLiquidityProportional`. Similar to the add operation, this is a slightly changed version of the Balancer Router function that allows us set the sender as the router (address(this)) and the receiver as the user (msg.sender). Its also interesting to note here that we pass the encoded tokenId as `userData`. This eventually gets forwarded to the after hook and is used to retrieve the mapped data required to calculate the fee.

During the removeLiquidity operation the Vault checks if the associated hook has set `shouldCallAfterRemoveLiquidity` and if true the `onAfterRemoveLiquidity` hook function is called:

function onAfterRemoveLiquidity(
    address router,
    address pool,
    RemoveLiquidityKind,
    uint256,
    uint256[] memory,
    uint256[] memory amountsOutRaw,
    uint256[] memory,
    bytes memory userData
) public override onlySelfRouter(router) returns (bool, uint256[] memory hookAdjustedAmountsOutRaw) {
    // We only allow removeLiquidity via the Router/Hook itself so that fee is applied correctly.
    uint256 tokenId = abi.decode(userData, (uint256));
    hookAdjustedAmountsOutRaw = amountsOutRaw;
    uint256 currentFee = getCurrentFeePercentage(tokenId);
    if (currentFee > 0) {
        hookAdjustedAmountsOutRaw = _takeFee(IRouterCommon(router).getSender(), pool, amountsOutRaw, currentFee);
    }
    return (true, hookAdjustedAmountsOutRaw);
}

This is the main meat of our hook. It first checks `onlySelfRouter(router)` which ensures that remove can only be done via the router itself (for the same reason given above for add). It then retrieves the `tokenId` passed via the userData. This is used to retrieve the fee using `getCurrentFeePercentage`:

function getCurrentFeePercentage(uint256 tokenId) public view returns (uint256 feePercentage) {
    // Calculate the number of days that have passed since startTime
    uint256 daysPassed = (block.timestamp - startTime[tokenId]) / 1 days;
    if (daysPassed < DECAY_PERIOD_DAYS) {
        // decreasing fee by 1% per day
        feePercentage = INITIAL_FEE_PERCENTAGE - ONE_PERCENT * daysPassed;
    }
}

which we can see uses the stored start time to calculate the fee at the current time. The fee is then taken by `_takeFee`:

function _takeFee(
    address nftHolder,
    address pool,
    uint256[] memory amountsOutRaw,
    uint256 currentFee
) private returns (uint256[] memory hookAdjustedAmountsOutRaw) {
    hookAdjustedAmountsOutRaw = amountsOutRaw;
    IERC20[] memory tokens = _vault.getPoolTokens(pool);
    uint256[] memory accruedFees = new uint256[](tokens.length);
    // Charge fees proportional to the `amountOut` of each token.
    for (uint256 i = 0; i < amountsOutRaw.length; i++) {
        uint256 exitFee = amountsOutRaw[i].mulDown(currentFee);
        accruedFees[i] = exitFee;
        hookAdjustedAmountsOutRaw[i] -= exitFee;
        // Fees don't need to be transferred to the hook, because donation will redeposit them in the vault.
        // In effect, we will transfer a reduced amount of tokensOut to the caller, and leave the remainder
        // in the pool balance.

        emit ExitFeeCharged(nftHolder, pool, tokens[i], exitFee);
    }

    // Donates accrued fees back to LPs.
    _vault.addLiquidity(
        AddLiquidityParams({
            pool: pool,
            to: msg.sender, // It would mint BPTs to router, but it's a donation so no BPT is minted
            maxAmountsIn: accruedFees, // Donate all accrued fees back to the pool (i.e. to the LPs)
            minBptAmountOut: 0, // Donation does not return BPTs, any number above 0 will revert
            kind: AddLiquidityKind.DONATION,
            userData: bytes("") // User data is not used by donation, so we can set it to an empty string
        })
    );
}

This function uses the computed fee to deduct an exitFee from each output token. This is donated back to pool using the special `DONATION` AddLiquidity kind. The updated amounts out are returned to the Vault via the returned `hookAdjustedAmountsOutRaw` which ensures all the Vault accounting passes.

Conclusion

This is a fairly involved example but it covers a lot including some interesting functionality:

  • How a custom router can be used to apply custom logic to pool operations
  • Enforcing pool operations to a specific router
  • Using an NFT to represent a liquidity position which can also be used to track associated meta data

This really shows the flexibility and power that hooks and custom routers can have. Combining these functionalities opens a really wide design space to explore!

Axiom – Testing With Custom Foundry Cheat Codes

Intro

Axiom is a really exciting new protocol that harnesses ZK technology to allow smart contracts to trustlessly compute over the history of Ethereum. I believe its a novel new primitive for others to build with. The docs provide a lot of info about the protocol itself and has a helpful tutorial that can be followed to build an Autonomous Airdrop. An SDK is provided to improve the integration experience for developers and includes a CLI, React client and Typescript and Smart Contract libraries.

One of the SC libraries provides an extension to the standard Foundry test library and has a pretty interesting setup and implementations of custom cheat codes. I thought it would be interesting to investigate this a bit further using the test from the Autonomous Airdrop example as a reference example, specifically looking at AxiomTest in some more detail.

System Overview

To appreciate why the cheat codes are beneficial its useful to have a high level overview of the Axiom system. Following the flow of the Airdrop example:

  1. Query Initialisation
  • A query is sent to the AxiomV2Query contract sendQuery function. In the Airdrop example this is sent by the user from the UI
  • The query format spec can be found here
  • Will use the compute proof from an Axiom client Circuit
  • The query arguments can be created in a number of ways using the SDKs, e.g. CLINodeJSReact
  • Here the AxiomV2Callback is specified. This is what runs after query fulfillment
  1. Query Verification
  • Offchain Axiom indexes the query
  • Computes the result, and generate a ZK proof of validity
  1. Query Fulfillment
  • Axiom calls fulfillQuery on the AxiomV2Query contract.
  • Onchain: verify zk proof onchain, check hashes, confirm mathes original query
  • Calls the callback specified by the AxiomV2Callback in step 1
  1. Callback runs
  • This allows a custom contract to make use of the results of the query and run custom logic
  • In the Airdrop example the AutonomousAirdrop.sol contract validates the relevant airdrop requirements and issues the token if met

When testing locally the QueryFulfillment in step 3 will not be possible which would block testing of the custom logic implemented in the callback used in step 4. That’s where the AxiomTest library can be used.

Step By Step Testing

Following AutonomousAirdrop.t.sol can show us step by step how to use AxiomTest and allows us to investigate what is going on.

Importing

AxiomTest follows the same convention as a usual Foundry Test but instead we import AxiomTest.sol and inherit from AxiomTest in the test contract:

import { AxiomTest, AxiomVm } from "@axiom-crypto/v2-periphery/test/AxiomTest.sol";

contract AutonomousAirdropTest is AxiomTest { ...

Setup

setUp() is also the same as Foundry, an optional function invoked before each test case is run. Here there’s a bit more going on:

function setUp() public {
    _createSelectForkAndSetupAxiom("sepolia", 5_103_100);
    
    inputPath = "app/axiom/data/inputs.json";
    querySchema = axiomVm.compile("app/axiom/swapEvent.circuit.ts", inputPath);

    autonomousAirdrop = new AutonomousAirdrop(axiomV2QueryAddress, uint64(block.chainid), querySchema);
    uselessToken = new UselessToken(address(autonomousAirdrop));
    autonomousAirdrop.updateAirdropToken(address(uselessToken));
}

_createSelectForkAndSetupAxiom is found in the AxiomTest.sol contract. It basically initialises everything Axiom related on a local fork so the tests can be run locally.

  1. Setup and run a new local fork using vm.createSelectFork(urlOrAlias, forkBlock) docs;
  2. Using provided chainId find the addresses for axiomV2Core and axiomV2Query from local AxiomV2Addresses. These are actual deployments and currently only exist on mainnet/sepolia.
  3. Initialise core and query contracts using the addresses and interfaces:
axiomV2Core = IAxiomV2Core(axiomV2CoreAddress);
axiomV2Query = IAxiomV2Query(axiomV2QueryAddress);
  1. Initialise axiomVm
axiomVm = new AxiomVm(axiomV2QueryAddress, urlOrAlias, true);

AxiomVm.sol implements the cheatcode functionality as well as providing utility functions for compiling, proving, parsing args, etc.

Following initialisation of the fork, the axiomVm compile function is used to compile the local circuit and retrieve the querySchema associated to the circuit. The querySchema provides a unique identifier for a callback function to distinguish the type of compute query used to generate the query results passed to the callback and this is used as a constructor argument when creating a new AutonomousAirdrop contract.

Behind the scenes compile is using Foundry FFI to run the Axiom CLI compile command:

npx axiom circuit compile _circuitPath --provider vm.rpcUrl(urlOrAlias) --inputs inputPath --outputs COMPILED_PATH --function circuit --mock

This outputs a JSON file which contains the querySchema. This value is parsed from the file and returned.

Testing SendQuery

The test test_axiomSendQuery covers step 1 in the System Overview above.

function test_axiomSendQuery() public {
    AxiomVm.AxiomSendQueryArgs memory args =
        axiomVm.sendQueryArgs(inputPath, address(autonomousAirdrop), callbackExtraData, feeData);

    axiomV2Query.sendQuery{ value: args.value }(
        args.sourceChainId,
        args.dataQueryHash,
        args.computeQuery,
        args.callback,
        args.feeData,
        args.userSalt,
        args.refundee,
        args.dataQuery
    );
}

Looking at AxiomVm sendQueryArgs we see it is again using Axiom CLI. This time via the functions _prove and _queryParams.

_prove runs the prove command:

npx axiom circuit prove circuitPath --mock --sourceChainId vm.toString(block.chainid) --compiled COMPILED_PATH --provider vm.rpcUrl(urlOrAlias) --inputs inputPath --outputs OUTPUT_PATH --function circuit

This will prove the previously compiled circuit and generate an JSON output file with the interface:

{
    sourceChainId: string,
    computeResults: string[], // bytes32[]
    computeQuery: AxiomV2ComputeQuery,
    dataQuery: DataSubquery[],
}

_queryParams then runs the query-params command:

npx axiom circuit query-params vm.toString(callbackTarget) --sourceChainId vm.toString(block.chainid) --refundAddress vm.toString(msg.sender) --callbackExtraData vm.toString(callbackExtraData) --maxFeePerGas vm.toString(feeData.maxFeePerGas) --callbackGasLimit vm.toString(feeData.callbackGasLimit) --provider vm.rpcUrl(urlOrAlias) --proven OUTPUT_PATH --outputs QUERY_PATH --args-map

This uses the output generate by the prove step (at OUTPUT_PATH) and generates the sendQuery arguments to a JSON file in the format:

{
    value: bigint,
    queryId: bigint,
    calldata: string,
    args,
}

This file is read and the args are returned as a string which are parsed in _parseSendQueryArgs and returned as a AxiomSendQueryArgs struct.

Finally sendQuery itself is called on the axiomV2Query contract initialised during setup using the parsed args.

Testing Callback

The test test_axiomCallback mocks step 3 in the System Overview and allows the callback to be tested.

function test_axiomCallback() public {
    AxiomVm.AxiomFulfillCallbackArgs memory args =
        axiomVm.fulfillCallbackArgs(inputPath, address(autonomousAirdrop), callbackExtraData, feeData, SWAP_SENDER_ADDR);
    
    axiomVm.prankCallback(args);
}

Similar to the previous test fulfillCallbackArgs uses the Axiom CLI to prove and queryParams to generate the required args for AxiomFulfillCallbackArgs. These are used in prankCallback to call the axiomV2Callback function on the AutonomousAirdrop contract (args.callbackTarget is the address) with the relevant spoofed Axiom results:

IAxiomV2Client(args.callbackTarget).axiomV2Callback{gas: args.gasLimit}(
    args.sourceChainId,
    args.caller,
    args.querySchema,
    args.queryId,
    args.axiomResults,
    args.callbackExtraData
);

The axiomV2Callback function is inhertied from the AxiomV2Client and this function in turn calls _validateAxiomV2Call and _axiomV2Callback.

Conclusion

Following through these tests and libraries really helps to understand the moving parts in the Axiom system and hopefully the post helps others. Its exciting to see what gets built with Axiom as it becomes another core primitive!

Photo by David Travis on Unsplash

Building an SDK v1.0.1-beta.13 – Typechain

Intro

The TypeChain project provides developers a tool to generate TypeScript typings for smart contracts they are interacting with. This gives all the usual benefits of Typing for example – flagging an error if you try to call a function on the smart contract that doesn’t exist.

In the SDK we were using the @balancer-labs/typechain package which aims to provide TypeChain bindings for the most commonly used Balancer contracts but we decided it would be better to remove this dependency and generate the bindings as needed. This enables us to remain up to date with new contracts (e.g. Relayers) without waiting for the package support.

Making The Changes

TypeChain is really pretty easy to use but we had to add a few additonal changes to the SDK.

ABIs
To generate the typed wrapper TypeChain uses the Smart Contract ABIs. These were added in src/lib/abi. These can be found in the balancer-v2-monorepo or even from etherscan if the contract is already deployed/verified.

Targets
TypeChain will generate appropriate code for a given web3 library. In the SDK we use ethers.js so we need to make sure the @typechain/ethers-v5 package is added to our dev dependencies. (See the other available targets here)

CLI Command
To actually generate the files we need to run the typechain command and specifify the correct target, path to ABIs, and out path. For example:

typechain --target ethers-v5 --out-dir src/contracts './src/lib/abi/Vault.json'

Will target ethers and use the Vault ABI to generate the bindings in the src/contracts dir. You can see the full CLI docs here.

Its recommended that the generated file are not commited to the codebase so we add src/contracts/ to .gitignore. And in package.json a helper is added to scripts:

"typechain:generate": "npx typechain --target ethers-v5 --out-dir src/contracts './src/lib/abi/Vault.json' './src/lib/abi/WeightedPoolFactory.json' './src/lib/abi/BalancerHelpers.json' './src/lib/abi/LidoRelayer.json' './src/lib/abi/WeightedPool.json'"

and the CI is updated to call this command post install.

Updating the code
The last change to make was removing the old package and replacing any references to it. This is almost a direct replacement and just requires updating to use the path from the new contracts path. E.g.:

// Old
import { BalancerHelpers__factory } from "@balancer-labs/typechain";
// New
import { BalancerHelpers__factory } from '@/contracts/factories/BalancerHelpers__factory';

// Example of use
this.balancerHelpers = BalancerHelpers__factory.connect(
      this.contractAddresses.balancerHelpers,
      provider
    );

Example Of The Benefits

During the updates one of the benefits was highlighted. A previous example was incorrectly calling the queryExit function on the BalancerHelpers contract. This is a function that although it is used like a view it is actually a special case that requires it to be used with an eth_call (see here for more info). This led to a Type warning when trying to access the response. After correctly updating to use a callStatic the response typing matched the expected.

// Incorrect version
const response = await contracts.balancerHelpers.queryExit(...);
expect(response.amountsIn)....
// Shows: Property 'amountsIn' does not exist on type 'ContractTransaction'.

// Correct version
const response = await contracts.balancerHelpers.callStatic.queryExit
expect(response.amountsIn)....
/*
Shows:
const response: [BigNumber, BigNumber[]] & {
    bptOut: BigNumber;
    amountsIn: BigNumber[];
}
*/

Photo by Kristian Strand on Unsplash

Building an SDK v0.1.30 – Swaps With Pool Joins & Exits

In the Balancer Smart Order Router (SOR) we try to find the best “path” to trade from one token to another. Until recently we only considered paths that consisted of swaps but the Relayer allows us to combine swaps with other actions like pool joins and exits and this opens up new paths to consider.

Pools, Actions and BPTs

Lets take a look at the humble 80/20 BAL/WETH weighted balancer pool and see some of the associated actions.

A token holder can join a Balancer pool by depositing tokens into it using the joinPool function on the vault. In return they receive a Balancer Pool Token (BPT) that represents their share in this pool. A user can join with a single token or a combination of tokens, as long as the tokens used already exist in the pool.

A BPT holder can exit the pool at anytime by providing the BPT back to the Vault using the exitPool function. And they can exit to one or a combination of the pool tokens.

In the Balancer veSystem users lock the BPT of the 80/20 BAL/WETH weighted balancer pool. This is cool because it ensures that even if a large portion of BAL tokens are locked, there is deep liquidity that can be used for swaps.

A swap against the 80/20 pool with a “normal” token swap would usually just involve swapping tokens that exist in the pool. e.g. swapping BAL to WETH. This can be achieved by calling the `Swap` function on the Balancer Vault.

We also have multihop swaps that chain together swaps across different pools, which in Balancers case is super efficient because of the Vault architeture. This can be achieved by calling the `batchSwap` function on the Vault.

BPT tokens are actually an ERC20 compatible token which means they have the same approve, transfer, balance functionality as any other ERC20. This means it can itself also be a token within another Balancer pool. This opens up a whole world of interesting use cases, like Boosted Pools. Another example is the auraBal stable pool.

Aura

There’s lots of detailed info in the veBal and Aura docs but as a quick summary:

veBAL (vote-escrow BAL) is a vesting and yield system based based on Curves veCRV system. Users lock the 80/20 BPT and gain voting power and protocol rewards.

Aura Finance is a protocol built on top of the Balancer system to provide maximum incentives to Balancer liquidity providers and BAL stakers.

auraBAL is tokenised veBAL and the stable pool consists of auraBal and the 80/20BPT. Now if a user wants to trade auraBal to Weth they can do a multihop swap like:

For larger trades this requires deep liquidity in the BPT/WETH pool, which in the Aura case hasn’t always been available. But there is another potential path, using a pool exit, that can make use of the deep liquidity locked in the 80/20 pool:

With the similar join path also being available:

Updating The Code

So we can see that adding support for these additional paths is definitely useful but it requires some changes to the existing code.

SOR Path Discovery

First we need to adapt the SOR so it considers join/exits as part of a viable path. An elegant and relatively easy to implement solution was suggested by Fernando. Some pools have pre-minted (or phantom) BPT which basically means the pool contains it’s own BPT in its tokens list. This means a swap can be used to trade to or from a pool token to join or exit, respectively. We can make the SOR consider non preminted pools in the same way by artificially adding the BPT to the pool token list.

        if (useBpts) {
            for (const pool of pools) {
                if (
                    pool.poolType === 'Weighted' ||
                    pool.poolType === 'Investment'
                ) {
                    const BptAsToken: SubgraphToken = {
                        address: pool.address,
                        balance: pool.totalShares,
                        decimals: 18,
                        priceRate: '1',
                        weight: '0',
                    };
                    pool.tokens.push(BptAsToken);
                    pool.tokensList.push(pool.address);
                }
            }
        }

We also have to make sure that each pool also has the relevant maths for BPT<>token swaps. Once these are added the SOR can create the relevant paths and will use the existing algorithm to determine the best price.

Call Construction

Paths containing only swaps can be submitted directly to the Vault batchSwap function. A combination of swaps with joins/exits can not – they have to be submitted via the Relayer multicall function. We wanted to try and keep the SOR focused on path finding so we added some helper functions to the SDK.

The first function `someJoinExit checks whether the paths returned from the SOR need to be submitted via the Vault (e.g. swaps only) or the Relayer (swaps and joins/exits). We can do this by checking if any of the hops involve a weighted pool with one of the tokens being the pool bpt. This works on the assumption that the weighted pools are not preminted.

// Use SOR to get swap information
const swapInfo = await sor.getSwaps(tokenIn, tokenOut, ...);
// Checks if path contains join/exit action
const useRelayer = someJoinExit(pools, swapInfo.swaps, swapInfo.tokenAddresses)

The second, buildRelayerCalls, formats the path data into a set of calls that can be submitted to the Relayer multicall function.

First it creates an action for each part of the path – swap, join or exit using getActions:

  // For each 'swap' create a swap/join/exit action
  const actions = getActions(
    swapInfo.tokenIn,
    swapInfo.tokenOut,
    swapInfo.swaps,
    swapInfo.tokenAddresses,
    slippage,
    pools,
    user,
    relayerAddress
  );

which use the isJoin and isExit functions:

// Finds if a swap returned by SOR is a join by checking if tokenOut === poolAddress
export function isJoin(swap: SwapV2, assets: string[]): boolean {  
  // token[join]bpt
  const tokenOut = assets[swap.assetOutIndex];
  const poolAddress = getPoolAddress(swap.poolId);
  return tokenOut.toLowerCase() === poolAddress.toLowerCase();
}

// Finds if a swap returned by SOR is an exit by checking if tokenIn === poolAddress
export function isExit(swap: SwapV2, assets: string[]): boolean {
  // bpt[exit]token
  const tokenIn = assets[swap.assetInIndex];
  const poolAddress = getPoolAddress(swap.poolId);
  return tokenIn.toLowerCase() === poolAddress.toLowerCase();
}

Then these actions are ordered and grouped. The first step is to categorize actions into a Join, Middle or Exit as this determines the order the actions can be done:

export function categorizeActions(actions: Actions[]): Actions[] {
  const enterActions: Actions[] = [];
  const exitActions: Actions[] = [];
  const middleActions: Actions[] = [];
  for (const a of actions) {
    if (a.type === ActionType.Exit || a.type === ActionType.Join) {
      // joins/exits with tokenIn can always be done first
      if (a.hasTokenIn) enterActions.push(a);
      // joins/exits with tokenOut (and not tokenIn) can always be done last
      else if (a.hasTokenOut) exitActions.push(a);
      else middleActions.push(a);
    }
    // All other actions will be chained inbetween
    else middleActions.push(a);
  }
  const allActions: Actions[] = [
    ...enterActions,
    ...middleActions,
    ...exitActions,
  ];
  return allActions;
}

The second step is to batch all sequential swaps together. This should minimise gas cost by making use of the batchSwap function. We use the batchSwapActions function to do this:

const orderedActions = batchSwapActions(categorizedActions, assets);

and it is essentially checking if subsequent swaps have the same source/destination – if they do then they can be batched together and the relevant assets and limits arrays are updated.

Each of the ordered actions are encoded to their relevant call data. And finally the Relayer multicall is encoded.

  const callData = balancerRelayerInterface.encodeFunctionData('multicall', [
    calls,
  ]);

And here’s a full example showing how the new functions can be used:

/**
* Example showing how to find a swap for a pair using SOR directly
* - Path only uses swaps: use queryBatchSwap on Vault to see result
* - Path use join/exit: Use SDK functions to build calls to submit tx via Relayer
*/
import dotenv from 'dotenv';
import { BigNumber, parseFixed } from '@ethersproject/bignumber';
import { Wallet } from '@ethersproject/wallet';
import { AddressZero } from '@ethersproject/constants';
import {
BalancerSDK,
Network,
SwapTypes,
someJoinExit,
buildRelayerCalls,
canUseJoinExit,
} from '../src/index';
import { ADDRESSES } from '../src/test/lib/constants';
dotenv.config();
async function getAndProcessSwaps(
balancer: BalancerSDK,
tokenIn: string,
tokenOut: string,
swapType: SwapTypes,
amount: BigNumber,
useJoinExitPaths: boolean
) {
const swapInfo = await balancer.swaps.sor.getSwaps(
tokenIn,
tokenOut,
swapType,
amount,
undefined,
useJoinExitPaths
);
if (swapInfo.returnAmount.isZero()) {
console.log('No Swap');
return;
}
// console.log(swapInfo.swaps);
// console.log(swapInfo.tokenAddresses);
console.log(`Return amount: `, swapInfo.returnAmount.toString());
const pools = balancer.swaps.sor.getPools();
// someJoinExit will check if swaps use joinExit paths which needs additional formatting
if (
useJoinExitPaths &&
someJoinExit(pools, swapInfo.swaps, swapInfo.tokenAddresses)
) {
console.log(`Swaps with join/exit paths. Must submit via Relayer.`);
const key: any = process.env.TRADER_KEY;
const wallet = new Wallet(key, balancer.sor.provider);
const slippage = '50'; // 50 bsp = 0.5%
try {
const relayerCallData = buildRelayerCalls(
swapInfo,
pools,
wallet.address,
balancer.contracts.relayerV3!.address,
balancer.networkConfig.addresses.tokens.wrappedNativeAsset,
slippage,
undefined
);
// Static calling Relayer doesn't return any useful values but will allow confirmation tx is ok
// relayerCallData.data can be used to simulate tx on Tenderly to see token balance change, etc
// console.log(wallet.address);
// console.log(await balancer.sor.provider.getBlockNumber());
// console.log(relayerCallData.data);
const result = await balancer.contracts.relayerV3
?.connect(wallet)
.callStatic.multicall(relayerCallData.rawCalls);
console.log(result);
} catch (err: any) {
// If error we can reprocess without join/exit paths
console.log(`Error Using Join/Exit Paths`, err.reason);
await getAndProcessSwaps(
balancer,
tokenIn!,
tokenOut!,
swapType,
amount,
false
);
}
} else {
console.log(`Swaps via Vault.`);
const userAddress = AddressZero;
const deadline = BigNumber.from(`${Math.ceil(Date.now() / 1000) + 60}`); // 60 seconds from now
const maxSlippage = 50; // 50 bsp = 0.5%
const transactionAttributes = balancer.swaps.buildSwap({
userAddress,
swapInfo,
kind: 0,
deadline,
maxSlippage,
});
const { attributes } = transactionAttributes;
try {
// Simulates a call to `batchSwap`, returning an array of Vault asset deltas.
const deltas = await balancer.contracts.vault.callStatic.queryBatchSwap(
swapType,
swapInfo.swaps,
swapInfo.tokenAddresses,
attributes.funds
);
console.log(deltas.toString());
} catch (err) {
console.log(err);
}
}
}
async function swapExample() {
const network = Network.MAINNET;
const rpcUrl = `https://mainnet.infura.io/v3/${process.env.INFURA}`;
const tokenIn = ADDRESSES[network].WETH.address;
const tokenOut = ADDRESSES[network].auraBal?.address;
const swapType = SwapTypes.SwapExactIn;
const amount = parseFixed('18', 18);
// Currently Relayer only suitable for ExactIn and non-eth swaps
const canUseJoinExitPaths = canUseJoinExit(swapType, tokenIn!, tokenOut!);
const balancer = new BalancerSDK({
network,
rpcUrl,
});
await balancer.swaps.sor.fetchPools();
await getAndProcessSwaps(
balancer,
tokenIn!,
tokenOut!,
swapType,
amount,
canUseJoinExitPaths
);
}
// yarn examples:run ./examples/swapSor.ts
swapExample();
view raw SwapExample.ts hosted with ❤ by GitHub

Photo by Jakob Owens on Unsplash

Building an SDK v0.1.24 – Balancer Relayers and Pool Migrations

What Is A Relayer?

A relayer is a contract that is authorized by the protocol and users to make calls to the Vault on behalf of the users. It can use the sender’s ERC20 vault allowance, internal balance and BPTs on their behalf. Multiple actions (such as exit/join pools, swaps, etc) can be chained together which improves the UX.

For security reasons a Relayer has to be authorised by the Balancer DAO before it can be used (see previous votes for V1 and V2) and even after authorisation each user would still be required to opt into the relayer by submitting an approval transaction or signing a message.

How It Works

Contracts

The Balancer Relayers are composed of two contracts, BalancerRelayer, which is the single point of entry via the multicall function and a library contract, such as the V3 VaultActions, which defines the allowed behaviour of the relayer, for example – VaultActions, LidoWrapping, GaugeActions.

Having the multicall single point of entry prevents reentrancy. The library contract cannot be called directly but the multicall can repeatedly delegatecall into the library code to perform a chain of actions.

Some psuedo code demonstrating how an authorisation, exitPool and swap can be chained and called via the multicall function:

const approval = buildApproval(signature); // setRelayerApproval call
const exitPoolCallData = buildExitPool(poolId, bptAmt); // exitPool call
const swapCallData = buildSwap(); // batchSwap call

const tx = await relayer.multicall([approval, exitPoolCallData, swapCallData]);

Approval

A user has to approve each Relayer before they can use it. To check if a Relayer is approved we can use hasApprovedRelayer on the Vault:

const isApprove = await vault.hasApprovedRelayer(userAddress, relayerAddress)

And we can grant (or revoke) approval for a given relayer by using setRelayerApproval:

const approvalTx = await vault.setRelayerApproval(userAddress, relayerAddress, isApprove);

A Relayer can also be approved by using the setRelayerApproval function from the BaseRelayerLibrary contract. Here a signed authorisation message from the user is passed as an input parameter. This allows an approval to be included at the start of a chain of actions so the user only needs to submit a single transaction creating a better UX.

Chained References

Output References allow the Relayer to store output values from once action which can then be read and used in another action. This allows us to chain together actions. For example we could exit a pool, save the exit amounts of each token to a reference and then do a batchSwap using the references as input amounts for each swap:

An OutputReference consists of an index and a key:

struct OutputReference {
  uint256 index;
  uint256 key;
}

Where the key is the slot the value will be stored at. Index indicates which output amount should be stored. For example if exitPool exits to 3 tokens, DAI (index 0), USDC (1), USDT (2), we would want to use index 0 to store DAI, 1 for USDC, etc.

Example Use Case – Pool Migration

Intro

Balancer aims for the best capital efficiency for LPs so it made sense to offer the option to migrate from the old “staBal3” pool consisting of DAI, USDC and USDT to a new “boosted” stable pool which is more capital efficient because it uses yield bearing assets.

To migrate between these pools would take multiple steps:

  1. unstake from staBal3 gauge → staBalBpt
  2. exitPool from staBal, staBalBpt → DAI, USDC, USDT
  3. join the bb-a-usd2 pool by using batchSwaps
    1. DAI → bbausd2Bpt
    2. USDC → bbausd2Bpt
    3. USDT → bbausd2Bpt
  4. stake bbausd2Bpt in gauge

This would be quite an ordeal for a user to do manually but the Relayer can be used to combine all these actions into a single transaction for the user.

Details

As this is a well defined one off action we decided to add this function to the SDK as a “Zap” under a Migrations module. The user can call the staBal3 function to get all the call data required to call the tx:

{ to, data } = migrations.stabal3(
  userAddress,
  staBal3Amount,
  minBbausd2Out,
  isStaked,
  authorisationSignature
);

Behind the scenes all the call data for each step is crafted and the encoded multicall data is returned:

calls = [
        this.buildSetRelayerApproval(authorisation),
        this.buildWithdraw(userAddress, staBal3Amount),
        this.buildExit(relayer, staBal3Amount),
        this.buildSwap(minBbausd2Out, relayer),
        this.buildDeposit(userAddress),
      ];

const callData = balancerRelayerInterface.encodeFunctionData('multicall', [
      calls,
    ]);

buildSetRelayerApproval allows the user to pass the approval signature if this is their first time using the relayer. This allows us to approve and execute the migration all in a single transaction.

buildWithdraw and buildDeposit handle the gauge actions. The initial call is to withdraw from the staBal gauge and the final call deposits the bbausd2 bpt into the new gauge. We withdraw directly to the Relayer address rather than the users. The gauges return the tokens to the caller, so sending them to the user costs more as we need to manually transfer them:

gauge.withdraw(amount);
// Gauge does not support withdrawing BPT to another address atomically.
// If intended recipient is not the relayer then forward the withdrawn BPT on to the recipient.
if (recipient != address(this)) {
    IERC20 bptToken = gauge.lp_token();
    bptToken.transfer(recipient, amount);
}

Skipping this has two benefits. Firstly it saves gas by avoiding an extra transfer. It also avoids approval issues as now the Relayer is just using its own funds. The final deposit uses the userAddress to send the staked tokens from the Relayer back to the user.

buildExit creates the exitPool call:

// Ask to store exit outputs for batchSwap of exit is used as input to swaps
    const outputReferences = [
      { index: assetOrder.indexOf('DAI'), key: EXIT_DAI },
      { index: assetOrder.indexOf('USDC'), key: EXIT_USDC },
      { index: assetOrder.indexOf('USDT'), key: EXIT_USDT },
    ];

    const callData = Relayer.constructExitCall({
      assets,
      minAmountsOut: ['0', '0', '0'],
      userData,
      toInternalBalance: true,
      poolId: this.addresses.staBal3.id,
      poolKind: 0, // This will always be 0 to match supported Relayer types
      sender,
      recipient: this.addresses.relayer,
      outputReferences,
      exitPoolRequest: {} as ExitPoolRequest,
    });

Output references are used to store the final amounts of each stable token received from the pool. We have precomputed the keys by using the Relayer.toChainedReference helper, like:

const EXIT_DAI = Relayer.toChainedReference('21');
const EXIT_USDC = Relayer.toChainedReference('22');
const EXIT_USDT = Relayer.toChainedReference('23');

These will be used later as inputs to the swaps.

Also of interest is the fact we set toInternalBalance to true. The Balancer V2 vault can accrue ERC20 token balances and keep track of them internally in order to allow extremely gas-efficient transfers and swaps. Exiting to internal balances before the swaps allows us to keep gas costs down.

Because we have previously exited into internal balances we also don’t have to worry about the users having previously approved the Relayer for the tokens:

if (fromInternalBalance) {
// We take as many tokens from Internal Balance as possible: any remaining amounts will be transferred.
uint256 deductedBalance = _decreaseInternalBalance(sender, token, amount, true);
// Because deductedBalance will be always the lesser of the current internal balance
// and the amount to decrease, it is safe to perform unchecked arithmetic.
amount -= deductedBalance;
}

if (amount > 0) {
token.safeTransferFrom(sender, address(this), amount);
}

so the amount will be 0 and the safeTransferFrom call will not be executed.

buildSwap – We can join bbausd2 using a swap thanks to the PhantomBpt concept so here we create a batchSwap call that swaps each stable token to the bbausdBpt and we use the output references from the exitPool call as the input amounts to the swap (which is great as we don’t need to precompute these).

const swaps: BatchSwapStep[] = [
    {
      poolId: this.addresses.linearDai2.id,
      assetInIndex: 1,    // DAI
      assetOutIndex: 2,   // bDAI
      amount: EXIT_DAI.toString(),
      userData: '0x',
    },
    {
      poolId: this.addresses.bbausd2.id,
      assetInIndex: 2,  // bDAI
      assetOutIndex: 0,  // bbausd2
      amount: '0',
      userData: '0x',
    }
    ...
    {
      poolId: this.addresses.linearUsdc2.id,
      assetInIndex: 3,  // USDC
      assetOutIndex: 4, // bUSDC
      amount: EXIT_USDC.toString(),
      userData: '0x',
    },
    ...

In the Relayer VaultActions contract we can see how the swap amounts are set to the value stored in the reference:

for (uint256 i = 0; i < swaps.length; ++i) {
	uint256 amount = swaps[i].amount;
  if (_isChainedReference(amount)) {
	  swaps[i].amount = _getChainedReferenceValue(amount); //e.g. EXIT_DAI
  }
}

And finally (😅) we use another output reference to store the total amount out of bbausd2:

const outputReferences = [{ index: 0, key: SWAP_RESULT_BBAUSD }];

This is used as an input to the final gauge deposit to make sure we stake all the BPT that we have received and that should conclude the migration! You can see this in action on a local fork (yay no real funds required!) by running the integration test here.

Conclusion

The Balancer Relayer is probably not that well known so hopefully this has given a good overview of some of its functionality and flexibility. There’s a lot of room for experimentation and improvement of UX for complex operations so its worth investigating!

Photo by Austrian National Library on Unsplash

Building an SDK 0.1.14 – Adding a Contracts module

Intro

The idea of adding this was to make accessing Balancer contracts easier for users. Normally you need to find and import ABIs and deal with deployment addresses, if we want to make it easy we should just remove that complexity.

Also we are trying to make the main SDK functions return the contract name and functions as part of the attributes returned. This means the user could then just call using something like:

const { contractName, functionName, attributes } = transactionAttributes;

sdk.contracts[contractName][functionName](attributes)

Typechain

Typechain is a package that provides TypeScript bindings for Ethereum contracts. This means functions are statically typed and there is also IDE support which makes things safer and easier to develop against.

Balancer has its own @balancer-labs/typechain package that exposes instances of the commononly used contracts. Adding this to the SDK means we can remove the need to import ABI jsons and we can now create instances of contracts by doing:

import {
    Vault__factory
} from '@balancer-labs/typechain';

Vault__factory.connect(
            this.networkConfig.addresses.contracts.vault,
            provider
        );

which will return a typed Vault contract.

Module

  • Uses BALANCER_NETWORK_CONFIG and config.network to find vault/lidoRelayer/multicall addresses.
  • Added contracts getter to SDK module:
constructor(
        public config: BalancerSdkConfig,
        public sor = new Sor(config),
        public subgraph = new Subgraph(config),
        public pools = new Pools(config),
        public balancerContracts = new Contracts(config, sor.provider)
    ) { ... }

get contracts(): ContractInstances {
        return this.balancerContracts.contracts;
    }

This can then be called like:

const vaultContract = balancer.contracts['vault'];

or:

const vaultContract = balancer.contracts.vault

which will provide typed function refs.

Tradeoffs

One interesting discussion is the trade off of using the Contracts module within other modules. As of now only the Swaps and Multicaller modules using contracts. Using the Contracts module means we either have to pass Contracts in constructor, which adds an extra step if someone want to use modules independently:

const contracts = new Contracts(config)
const swaps = new Swaps(config, contracts)

or we instantiate Contracts within the module – which ends up happening twice if we use the high level SDK function as it is also instantiated there. For now we have decided to use the Typechain factories to instantiate the contracts within the module and will revisit in future if needed.

Photo by Pablo Arroyo on Unsplash

Node Performance Measurement

I was working on optimising a javascript maths function and wanted to compare the performance of different versions of the code. Initially I had some difficulty because I was approaching it incorrectly so I wanted to make a note for future reference.

First mistake – only using a small number of runs. I was comparing the two different functions with a very small iteration amount. This was leading to weird results where each iteration would get faster even though it was actually the same code running. I think this was related to some compiler optimisation or something. Anyway, after reading JavaScript Compiler Optimization Techniques, I changed to a very large number of runs. This made the results much more consistent.

Second mistake – using perf_hooks incorrectly. From the same blog I also found out the nice way to use perf_hooks to measure the performance:`

import { performance, PerformanceObserver } from 'perf_hooks';

let iterations = 1_000_000;

performance.mark('start');
while (iterations--) {
    StableMath._calcOutGivenIn(
        poolPairDataBigInt.amp,
        poolPairDataBigInt.balances,
        poolPairDataBigInt.tokenIndexIn,
        poolPairDataBigInt.tokenIndexOut,
        amt,
        poolPairDataBigInt.fee
    );
}
performance.mark('end');

iterations = 1_000_000;

performance.mark('startSecond');
const invariant = StableMath._calculateInvariant(
    poolPairDataBigInt.amp,
    poolPairDataBigInt.balances,
    true
);
while (iterations--) {
    StableMath._calcOutGivenInNoInv(
        poolPairDataBigInt.amp,
        poolPairDataBigInt.balances,
        poolPairDataBigInt.tokenIndexIn,
        poolPairDataBigInt.tokenIndexOut,
        amt,
        poolPairDataBigInt.fee,
        invariant
    );
}
performance.mark('endSecond');

const obs = new PerformanceObserver((list, observer) => {
    console.log(list.getEntries()); // [0]);
    performance.clearMarks();
    observer.disconnect();
});
obs.observe({ entryTypes: ['measure'] });

performance.measure('NoOptimisation', 'start', 'end');
performance.measure('WithOptimisation', 'startSecond', 'endSecond');

Which results in an output like:

[
  PerformanceMeasure {
    name: 'NoOptimisation',
    entryType: 'measure',
    startTime: 2369.287365913391,
    duration: 35891.85489702225,
    detail: null
  },
  PerformanceMeasure {
    name: 'WithOptimisation',
    entryType: 'measure',
    startTime: 38261.19673395157,
    duration: 18529.005373954773,
    detail: null
  }
]

As well as having a nice output it also shows my optimisation worked pretty nicely!

Photo by Saffu on Unsplash

Forking Brilliant

Houston We Have A Problem

I want to check that a transaction will work on mainnet for an account I don’t control. In this case it’s for a large LP in the Balancer staBal3 pool and I want to check they could successfully migrates their staBal3 to the new bb-a-USD using a Relayer multicall with the params created by the SDK.

This definitely isn’t the most elegant way of doing things but it works!

Whale Hunting

The first thing I need to do is to find a large staBal3 LP account and figure out their BPT balance. I can use the Balancer Subgraph to query account pool shares for the staBal3 pool. Query looks like:

query MyQuery {
  poolShares(where: {poolId: "0x06df3b2bbb68adc8b0e302443692037ed9f91b42000000000000000000000063"}, orderBy: balance, orderDirection: desc) {
    id
    balance
  }
}

I then manually worked my way down the list of addresses until I found one that was an EOA: https://etherscan.io/address/0x4086e3e1e99a563989a9390facff553a4f29b6ee and at the time of investiagation this had a BPT balance of: 10205792.037653741889318463 (a cool $10.28mil!).

Exit Stage Right

The SDK helper function (relayer.exitPoolAndBatchSwap) that creates the call data requires an input param of expectedAmountsOut which in this case represents the DAI/USDC/USDT amounts out when exiting the staBal3 pool. Because I don’t have the maths required for this exposed yet a quick way to get this is to see the output amounts using Withdraw in the UI. There’s a very nice tool that allows us to simulate this when we don’t have control of the account of interest: https://www.impersonator.xyz/

Now that I’ve got all the info required I can generate the call data by using the helper function. In this case we get an array of call data which represent an exitPool call on staBal3 followed by a batchSwap that swaps the stables received from the exit to the bb-a-USD BPT.

The Magic

Tenderly has lots of useful features including Transaction Simulations. To begin I tried simulating the multicall call on the Mainnet Relayer but the tx failed highlighting a new issue – the account hasn’t approved the Balancer Relayer. To get around this I can use a Tenderly Fork – “Forks allow you to chain simulation and test out complex scenarios with live on-chain data”. This is cool because I can now fork the chain make an approval on the relayer from the account which then allows me to succesfully simulate the multicall!

Photo by Joel Muniz on Unsplash

Building an SDK 0.1.0 – Improving SOR data sourcing

Intro

A big focus for Balancer Labs this year is to make it really easy to build on top of the protocol. To aid in that we’re putting together the `@balancer-labs/sdk npm package. As the current lead in this project I thought I’d try and document some of the work to help keep track of the changes, thought process and learning along the way. It’ll also be useful as a reminder of what’s going on!

SOR v2

Some background

We already have the Smart Order Router (@balancer-labs/sor), a package that devs can use to source the optimal routing for a swap using Balancer liquidity. It’s used in Balancers front-end and other projects like Copper and is a solver for Gnosis BGP. It’s also used in the Beethoven front-end (a Balancer friendly fork on Fantom, cool project and team and worth checking out).

The SOR is also used and exposed by the SDK. It’s core to making swaps accesible but is also used for joining/exiting Boosted Pools which uses PhantomBpt and swaps (a topic for another time I think!).

SOR Data

The diagram below shows some of the core parts of the SOR v2.

SOR v2

To choose the optimal routes for a swap the SOR needs information about the Balancer pools and the price of assets. And as we can see from the diagram the sourcing of this data is currently very tightly coupled to the SOR. Pools data is retrieved from the Subgraph and updated with on-chain balances using a multicall. And asset pricing is retrieved from CoinGecko.

Recently Beethoven experienced a pretty large growth spurt and found there were some major issues retrieving data from the Subgraph. They also correctly pointed out that CoinGecko doesn’t always have the asset pricing (especially on Fantom) and this information could be available from other sources.

After some discussions with Daniel (a very helpful dev from Beethoven) it was agreed that a good approach would be to refactor the SOR to create composability of data fetching so the user is able to have more control over where data is coming from. With this approach, the SOR doesn’t need to know anything about CoinGecko or the Subgraph and the data could now come from anywhere (database, cache, on chain, etc.), and as long as it implements the interface, the SOR will work properly.

Changes – SOR v3

I came back from Christmas break and Daniel had made all the changes – friendly forks for the win 💪! The interface changes are breaking but the improvements are worth it – SOR 3.0.0.

Config

The goal was to remove all the chain specific config from the SOR and pass it in as a constructor parameter. This helps to avoid non-scalable hard-coded values and encorages a single source of truth. It also gives more flexibility for the variables and makes the code easier to test.

There is now the SorConfig type:

export interface SorConfig {
    chainId: number;
    weth: string;
    vault: string;
    staBal3Pool?: { id: string; address: string };
    wethStaBal3?: { id: string; address: string };
    usdcConnectingPool?: { id: string; usdc: string };
}

Pool Data

The goal here is to allow for flexibility in defining where the pool data is fetched from. We define a generic PoolDataService that has a single function getPools, which serves as a generic interface for fetching pool data. This allows allow for any number of custom services to be used without having to change anything in the SOR or SDK.

export interface PoolDataService {
    getPools(): Promise<SubgraphPoolBase[]>;
}

Approaching it this way means all the Subgraph and on-chain/multicall fetching logic is removed from the SOR. These will be added to the Balancer SDK as stand-alone services. But as a simple example this is a PoolDataService that retrieves data from Subgraph:

export class SubgraphPoolDataService implements PoolDataService {
    constructor(
        private readonly chainId: number,
        private readonly subgraphUrl: string
    ) {}

    public async getPools(): Promise<SubgraphPoolBase[]> {
        const response = await fetch(this.subgraphUrl, {
            method: 'POST',
            headers: {
                Accept: 'application/json',
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({ query: Query[this.chainId] }),
        });

        const { data } = await response.json();

        return data.pools ?? [];
    }
}

Asset Pricing

The goal here is to allow for flexibility in defining where token prices are fetched from. We define a generic TokenPriceService that has a single function getNativeAssetPriceInToken. Similar to the PoolDataService this offers flexibility in the service that can be used, i.e. CoingeckoTokenPriceService or SubgraphTokenPriceService.

export interface TokenPriceService {
    /**
     * This should return the price of the native asset (ETH) in the token defined by tokenAddress.
     * Example: BAL = $20 USD, ETH = $4,000 USD, then 1 ETH = 200 BAL. This function would return 200.
     * @param tokenAddress
     */
    getNativeAssetPriceInToken(tokenAddress: string): Promise<string>;
}

All the CoinGecko code is removed from the SOR (to be added to SDK). An example TokenPriceService using CoinGecko:

export class CoingeckoTokenPriceService implements TokenPriceService {
    constructor(private readonly chainId: number) {}

    public async getNativeAssetPriceInToken(
        tokenAddress: string
    ): Promise<string> {
        const ethPerToken = await this.getTokenPriceInNativeAsset(tokenAddress);

        // We get the price of token in terms of ETH
        // We want the price of 1 ETH in terms of the token base units
        return `${1 / parseFloat(ethPerToken)}`;
    }

    /**
     * @dev Assumes that the native asset has 18 decimals
     * @param tokenAddress - the address of the token contract
     * @returns the price of 1 ETH in terms of the token base units
     */
    async getTokenPriceInNativeAsset(tokenAddress: string): Promise<string> {
        const endpoint = `https://api.coingecko.com/api/v3/simple/token_price/${this.platformId}?contract_addresses=${tokenAddress}&vs_currencies=${this.nativeAssetId}`;

        const response = await fetch(endpoint, {
            headers: {
                Accept: 'application/json',
                'Content-Type': 'application/json',
            },
        });

        const data = await response.json();

        if (
            data[tokenAddress.toLowerCase()][this.nativeAssetId] === undefined
        ) {
            throw Error('No price returned from Coingecko');
        }

        return data[tokenAddress.toLowerCase()][this.nativeAssetId];
    }

    private get platformId(): string {
        switch (this.chainId) {
            case 1:
                return 'ethereum';
            case 42:
                return 'ethereum';
            case 137:
                return 'polygon-pos';
            case 42161:
                return 'arbitrum-one';
        }

        return '2';
    }

    private get nativeAssetId(): string {
        switch (this.chainId) {
            case 1:
                return 'eth';
            case 42:
                return 'eth';
            case 137:
                return '';
            case 42161:
                return 'eth';
        }

        return '';
    }
}

Final Outcome

After the changes the updated diagram shows how the SOR is more focused and less opinionated:

The plan for the Balancer front-end is to move away from using the SOR directly and use it via the SDK package. The SDK will have the data fetching functionality as serparate services (which can be used independetly for fetching pools, etc) and these will be passed to the SOR when the SDK is instantiated. BUT it’s also possible to use the SOR independendtly as shown in this swapExample.

This was a large and breaking change but with the continued issues with Subgraph and more teams using the SOR/SDK it was a neccessary upgrade. Many thanks to Daniel from the Beethoven team for pushing this through!