Integrating Balancer in your contracts

What is Balancer and how to use it

What is Balancer?

Balancer is very similar to Uniswap. If you're not familiar with Uniswap or Balancer yet, they are fully decentralized protocols for automated liquidity provision on Ethereum. An easier-to-understand description would be that they are decentralized exchanges (DEX) relying on external liquidity providers that can add tokens to smart contract pools and users can trade those directly.

Since Balancer is running on Ethereum, what we can trade are Ethereum ERC-20 tokens. Balancer - being fully decentralized - has no restrictions to which tokens can be added or even how many pools can be created per token.

"

Balancer Pools cannot be censored or whitelisted. Traders cannot be censored or whitelisted. Balancer Labs does not have the power to stop or edit the smart contracts in any way after they’ve been deployed. There is no upgradeability, admin functionalities, or backdoors in the contracts.

Balancer Labs

Balancer UI

What is different compared to Uniswap?

In Uniswap each pool contains exactly one token pair. That's why it also doesn't make sense to have multiple pools for the same pair. In contrast in Balancer you can have multiple tokens in a single pool with different relations. Take a look at https://pools.balancer.exchange/#/:

balancer-pools

You'll see that a pool can have different balances for each token. What that means for liquidity providers is that they can have exposure to different assets without having to deal with complicated and/or expensive rebalancing procedures over different pools. They can pick or even create a pool that suits their needs and provide liquidity for it.

After each trade the balances per token would usually change and destroy the nicely defined relations in a pool. That's why Balancer (hence the name) makes sure that after each trade a pool will be rebalanced.

How are pools rebalanced?

In each pool there's a multi-dimensional invariant function which defines swap prices between any two tokens in any pool. This is the heart of the mechanism and allows the rebalancing. Given defined prices for each token swap, a pool can be balanced the following:

Imagine a trade happens in a 50:50 DAI/WETH pool. Somebody just purchased DAI in the amount of 1% of the pool's liquidity. Now the pool balances are 49% DAI and 51% WETH. A conventional rebalancing now has to purchase back the missing DAI from some other place usually inferring a fee. Instead in Balancer, rational market actors actively buy WETH from the pool bringing it back to the old ratio. So instead of paying a fee, the pool actually receives fees in this mechanism.


Thanos Balance

Smart Order Routing (SOR)

The SOR is a conceptual way of dealing with pools to optimize the profit for a trader. They also have an off-chain JavaScript solution available, source code is here. You would use this in the frontend and you can see in the Exchange UI code, that's what they do.

The exact motivation behind SOR is perfectly described in the documentation:

'Since there might be many Balancer pools that contain a given pair, trading only with the most liquid pool is not ideal. The fact that after a one-pool-trade arbitrageurs can profit by levelling all pool prices means the one-pool trader left value on the table.

The ideal solution in a world where there were no gas costs or gas limits would be to trade with all pools available in the desired pair. The amount traded with each pool should move them all to the same new spot price. This would mean all pools would be in an arbitrage free state and no value could be further extracted by arbitrageurs (which always comes at the expense of the trader).

As there are incremental gas costs associated with interacting with each additional Balancer pool, SOR makes sure that the increase in the returns an incremental pool brings exceeds the incremental gas costs. This is an optimization problem that depends therefore on the gas fees paid to the Ethereum network: a higher gas price may cause SOR to select less pools than otherwise.'

Future versions

Albert Einstein Bronze
Gold Bitcoins
  • Bronze: The initial release from earlier this year.
  • Silver: Silver is currently in a design phase with an expected release date in late 2020.
  • Gold: Final version.


The Silver version will include most notably an on-chain SOR (unless this feature comes only in the Gold release).

Further Balancer resources

Integrating Balancer Bronze into contracts

Now to integrate Balancer, you need to choose a pool or a mix of pools. You could add the SOR feature to find the optimal pools to maximize every bit for the user. This is beyond the scope of the tutorial and not really required if users aren't transferring massive amounts of value.

If you want to do this via SOR, install the @balancer-labs/sor package in the frontend app. Use it to find out the optimal swap strategy. The result will be an array of Swap definitions (how much to trade in which pool). Then you can pass these Swap definitions to the smart contract and execute each one.

We will instead be doing only a single swap. Let's use again DAI and WETH in the Kovan testnet. You can interact with the Kovan contracts in the frontend via:


Let's choose the DAI/WETH/MKR pool: https://kovan.pools.balancer.exchange/#/pool/0x1492b5b01350b7c867185a643f2e59f7be279fd3/. For a mainnet contract, make sure that the pool has very high liquidity if you're using only a single pool. Now let's try and enable ETH payments that are actually converted to DAI, so a user has the choice between paying in DAI or in ETH:


Adding ETH payments as alternative

function pay(uint paymentAmountInDai) public payable {
      if (msg.value > 0) {
          _swapEthForDai(paymentAmountInDai);
      } else {
          require(daiToken.transferFrom(msg.sender, address(this), paymentAmountInDai));
      }

      // do something with that DAI
      ...
}

A simple check like this at the beginning of your function will be enough. Now as for the _swapEthForDai function, it will look like something this:

Converting the ETH to DAI

function _swapEthForDai(uint daiAmount) private {
    _wrapEth(); // wrap ETH and approve to balancer pool

    PoolInterface(bPool).swapExactAmountOut(
        address(weth),
        type(uint).max, // maxAmountIn, set to max -> use all sent ETH
        address(daiToken),
        daiAmount,
        type(uint).max // maxPrice, set to max -> accept any swap prices
    );

    require(daiToken.transfer(msg.sender, daiToken.balanceOf(address(this))), "ERR_TRANSFER_FAILED");
    _refundLeftoverEth();
}

There are several things to unpack here.

  • WETH: You might notice that we are using WETH here. In Balancer there are no direct ETH pairs, all ETH must be converted to WETH first.
  • swapExactAmountOut: This function can be used to receive an exact amount of tokens for it. Any leftover tokens not required will be refunded, so make sure you have the fallback function in your contract. If you instead want the other way around to use an exact amount of ETH to pay, use the swapExactAmountIn.
  • Refund: Once the trade is finished, we can return any leftover ETH to the user. This sends out all ETH from the contract, so if your contract might have an ETH balance for other reasons, make sure to change this.

Wrapping the initial ETH

As for the _wrapEth function, you simply deposit the the ETH into the WETH contract and approve it for the balancer pool:

function _wrapEth() private {
    weth.deposit{ value: msg.value }();
    
    if (weth.allowance(address(this), address(bPool)) < msg.value) {
        weth.approve(address(bPool), type(uint).max);
    }
}

Refunding leftover ETH

The opposite is happening inside _refundLeftoverEth, we withdraw any leftover WETH and then return any ETH to the user.

function _refundLeftoverEth() private {
    uint wethBalance = weth.balanceOf(address(this));

    if (wethBalance > 0) {
        // refund leftover ETH
        weth.withdraw(wethBalance);
        (bool success,) = msg.sender.call{ value: wethBalance }("");
        require(success, "ERR_ETH_FAILED");
    }
}

And let's not forget to add a fallback function to receive refunded ETH:

receive() external payable {}

And lastly, you'll also need the interface definitions:

interface PoolInterface {
    function swapExactAmountIn(address, uint, address, uint, uint) external returns (uint, uint);
    function swapExactAmountOut(address, uint, address, uint, uint) external returns (uint, uint);
}

interface TokenInterface {
    function balanceOf(address) external returns (uint);
    function allowance(address, address) external returns (uint);
    function approve(address, uint) external returns (bool);
    function transfer(address, uint) external returns (bool);
    function transferFrom(address, address, uint) external returns (bool);
    function deposit() external payable;
    function withdraw(uint) external;
}

What do you think of Balancer? Have you tried it before? Let me know in the comments and ask anything if you need further help.

g

Markus Waas

Solidity Developer

More great blog posts from Markus Waas

  • xDai

    How to use xDai in your Dapp

    Deploying and onboarding users to xDai to avoid the high gas costs

    Gas costs are exploding again, ETH2.0 is still too far away and people are now looking at layer 2 solutions. Here's a good overview of existing layer 2 projects: https://github.com/Awesome-Layer-2/awesome-layer-2 . Today we will take a closer look at xDai as a solution for your Dapp. What are...

  • 15 Stacks

    Stack Too Deep

    Three words of horror

    You just have to add one tiny change in your contracts. You think this will take you only a few seconds. And you are right, adding the code took you less than a minute. All happy about your coding speed you enter the compile command. With such a small change, you are confident your code is...

  • Chainlink Thumbnail

    Integrating the new Chainlink contracts

    How to use the new price feeder oracles

    By now you've probably heard of Chainlink. Maybe you are even participating the current hackathon ? In any case adding their new contracts to retrieve price feed data is surprisingly simple. But how does it work? Oracles and decentralization If you're confused about oracles, you're not alone. The...

  • TheGraph

    TheGraph: Fixing the Web3 data querying

    Why we need TheGraph and how to use it

    Previously we looked at the big picture of Solidity and the create-eth-app which already mentioned TheGraph before. This time we will take a closer look at TheGraph which essentially became part of the standard stack for developing Dapps in the last year. But let's first see how we would do...

  • truffle buidler typescript

    Adding Typescript to Truffle and Buidler

    How to use TypeChain to utilize the powers of Typescript in your project

    Unlike compiled languages, you pretty much have no safeguards when running JavaScript code. You'll only notice errors during runtime and you won't get autocompletion during coding. With Typescript you can get proper typechecking as long as the used library exports its types. Most Ethereum...

  • mousetrap

    Navigating the pitfalls of securely interacting with ERC20 tokens

    Figuring out how to securely interact might be harder than you think

    You would think calling a few functions on an ERC-20 token is the simplest thing to do, right? Unfortunately I have some bad news, it's not. There are several things to consider and some errors are still pretty common. Let's start with the easy ones. Let's take a very common token: ... Now to...

  • Aave

    Why you should automatically generate interests from user funds

    How to integrate Aave and similar systems in your contracts

    If you're writing contracts that use, hold or manage user funds, you might want to consider using those funds for generating free extra income. What's the catch? That's right, it's basically free money and leaving funds unused in a contract is wasting a lot of potential. The way these...

  • Matic Logo

    How to use Matic in your Dapp

    Deploying and onboarding users to Matic to avoid the high gas costs

    Gas costs are exploding again, ETH2.0 is still too far away and people are now looking at layer 2 solutions. Here's a good overview of existing layer 2 projects: https://github.com/Awesome-Layer-2/awesome-layer-2 . Today we will take a closer look at Matic as a solution for your Dapp. Why Matic...

  • Migrating from Truffle to Buidler

    And why you should probably keep both.

    Why Buidler? Proper debugging is a pain with Truffle. Events are way too difficult to use as logging and they don't even work for reverted transactions (when you would need them most). Buidler gives you a console.log for your contracts which is a game changer. And you'll also get stack traces...

  • Factory

    Contract factories and clones

    How to deploy contracts within contracts as easily and gas-efficient as possible

    The factory design pattern is a pretty common pattern used in programming. The idea is simple, instead of creating objects directly, you have an object (the factory) that creates objects for you. In the case of Solidity, an object is a smart contract and so a factory will deploy new contracts for...

  • IPFS logo

    How to use IPFS in your Dapp?

    Using the interplanetary file system in your frontend and contracts

    You may have heard about IPFS before, the Interplanetary File System. The concept has existed for quite some time now, but with IPFS you'll get a more reliable data storage, thanks to their internal use of blockchain technology. Filecoin is a new system that is incentivizing storage for IPFS...

  • tiny-kitten

    Downsizing contracts to fight the contract size limit

    What can you do to prevent your contracts from getting too large?

    Why is there a limit? On November 22, 2016 the Spurious Dragon hard-fork introduced EIP-170 which added a smart contract size limit of 24.576 kb. For you as a Solidity developer this means when you add more and more functionality to your contract, at some point you will reach the limit and when...

  • EXTCODEHASH

    Using EXTCODEHASH to secure your systems

    How to safely integrate anyone's smart contract

    What is the EXTCODEHASH? The EVM opcode EXTCODEHASH was added on February 28, 2019 . Not only does it help to reduce external function calls for compiled Solidity contracts, it also adds additional functionality. It gives you the hash of the code from an address. Since only contract addresses...

  • Uniswap

    Using the new Uniswap v2 in your contracts

    What's new in Uniswap v2 and how to integrate Uniswap v2

    What is UniSwap? If you're not familiar with Uniswap yet, it's a fully decentralized protocol for automated liquidity provision on Ethereum. An easier-to-understand description would be that it's a decentralized exchange (DEX) relying on external liquidity providers that can add tokens to smart...

  • Continuous Integration

    Solidity and Truffle Continuous Integration Setup

    How to setup Travis or Circle CI for Truffle testing along with useful plugins.

    Continuous integration (CI) with Truffle is great for developing once you have a basic set of tests implemented. It allows you to run very long tests, ensure all tests pass before merging a pull request and to keep track of various statistics using additional tools. We will use the Truffle...

  • Devcon 6

    Upcoming Devcon 2021 and other events

    The Ethereum Foundation just announced the next Devcon in 2021 in Colombia

    Biggest virtual hackathon almost finished First of all, the current HackMoney event has come to an end and it has been a massive success. One can only imagine what kind of cool projects people have built in a 30 days hackathon. All final projects can be seen at:...

  • ERC-2020

    The Year of the 20: Creating an ERC20 in 2020

    How to use the latest and best tools to create an ERC-20 token contract

    You know what an ERC-20 is, you probably have created your own versions of it several times (if not, have a look at: ERC-20 ). But how would you start in 2020 using the latest tools? Let's create a new ERC-2020 token contract with some basic functionality which focuses on simplicity and latest...

  • hiring

    How to get a Solidity developer job?

    There are many ways to get a Solidity job and it might be easier than you think!

    You have mastered the basics of Solidity, created your first few useful projects and now want to get your hands on some real-world projects. Getting a Solidity developer job might be easier than you think. There are generally plenty of options to choose from and often times not a lot of...

  • People making fun

    Design Pattern Solidity: Mock contracts for testing

    Why you should make fun of your contracts

    Mock objects are a common design pattern in object-oriented programming. Coming from the old French word 'mocquer' with the meaning of 'making fun of', it evolved to 'imitating something real' which is actually what we are doing in programming. Please only make fun of your smart contracts if you...

  • React and Ethereum

    Kickstart your Dapp frontend development with create-eth-app

    An overview on how to use the app and its features

    Last time we looked at the big picture of Solidity and already mentioned the create-eth-app . Now you will find out how to use it, what features are integrated and additional ideas on how to expand on it. Started by Paul Razvan Berg, the founder of sablier , this app will kickstart your frontend...

  • Solidity Overview

    The big picture of Solidity and Blockchain development in 2020

    Overview of the most important technologies, services and tools that you need to know

    Now, I do not know about you, but I remember when I first started with Solidity development being very confused by all the tools and services and how they work in connection with one another. If you are like me, this overview will help you understand the big picture of Solidity development. As I...

  • Design Pattern Solidity: Free up unused storage

    Why you should clean up after yourself

    You may or may not be used to a garbage collectors in your previous programming language. There is no such thing in Solidity and even if there was a similar concept, you would still be better off managing state data yourself. Only you as a programmer can know exactly which data will not be used...

  • How to setup Solidity Developer Environment on Windows

    What you need to know about developing on Windows

    Using Windows for development, especially for Solidity development, can be a pain sometimes, but it does not have to be. Once you have configured your environment properly, it can actually be extremely efficient and Windows is a very, very stable OS, so your overall experience can be amazing. The...

  • Avoiding out of gas for Truffle tests

    How you do not have to worry about gas in tests anymore

    You have probably seen this error message a lot of times: Error: VM Exception while processing transaction: out of gas Disclaimer : Unfortunately, this does not always actually mean what it is saying when using Truffle , especially for older versions. It can occur for various reasons and might be...

  • Design Pattern Solidity: Stages

    How you can design stages in your contract

    Closely related to the concept of finite-state machines, this pattern will help you restrict functions in your contract. You will find a lot of situations where it might be useful. Any time a contract should allow function calls only in certain stages. Let's look at an example: contract Pool {...

  • Web3 1.2.5: Revert reason strings

    How to use the new feature

    A new Web3 version was just released and it comes with a new feature that should make your life easier. With the latest version 1.2.5 , you can now see the the revert reason if you use the new handleRevert option. You can activate it easily by using web3.eth.handleRevert = true . Now when you use...

  • Gaining back control of the internet

    How Ocelot is decentralizing cloud computing

    I recently came across an ambitious company that will completely redefine the way we are using the internet. Or rather, the way we are using its underlying infrastructure which ultimately is the internet. While looking at their offering, I also learned how to get anonymous cloud machines, you...

  • Devcon 5 - Review

    Impressions from the conference

    I had a lot to catch up on after Devcon. Also things didn't go quite as planned, so please excuse my delayed review! This year's Devcon was certainly stormy with a big typhoon warning already on day 1. Luckily (for us, not the people in Tokyo), it went right past Osaka. Nevertheless, a lot of...

  • Devcon 5 - Information, Events, Links, Telegram

    What you need to know

    Devcon 5 is coming up soon and there are already lots of events available, information about Osaka and more. Here is a short overview: Events Events Calendar Events Google Docs Events Kickback Most events are in all three, but if you really want to see all, you will have to look at all three...

  • Design Pattern Solidity: Off-chain beats on-chain

    Why you should do as much as possible off-chain

    As you might have realized, Ethereum transactions are anything but cheap. In particular, if you are computing complex things or storing a lot of data. That means sometimes we cannot put all logic inside Solidity. Instead, we can utilize off-chain computations to help us. A very simple example...

  • Design Pattern Solidity: Initialize Contract after Deployment

    How to use the Initializable pattern

    There are a few reasons why you might want to initialize a contract after deployment and not directly by passing constructor arguments. But first let's look at an example: contract MyCrowdsale { uint256 rate; function initialize(uint256 _rate) public { rate = _rate; } } What's the advantage over...

  • Consensys Blockchain Jobs Report

    What the current blockchain job market looks like

    Consensys published their blockchain jobs report which you can checkout in their Blockchain Developer Job Kit . The most interesting aspects are Blockchain developer jobs have been growing at a rate of 33x of the previous year according to LinkedIns jobs report Typical salary is about...

  • Provable — Randomness Oracle

    How the Oraclize random number generator works

    One particularly interesting approach by Provable is the usage of a hardware security device, namely the Ledger Nano S. It uses a trusted execution environment to generate random numbers and provides a Provable Connector Contract as interface. How to use the Provable Randomness Oracle? Use the...

  • Solidity Design Patterns: Multiply before Dividing

    Why the correct order matters!

    There has been a lot of progress since the beginning of Ethereum about best practices in Solidity. Unfortunately, I have the feeling that most of the knowledge is within the circle of experienced people and there aren’t that many online resources about it. That is why I would like to start this...

  • Devcon 5 Applications closing in one week

    Devcon 5 Applications closing

    Watch out for the Devcon 5 applications. You only have one week left to apply either as Buidler Student Scholarship Press Devcon is by far the biggest and most impressive Ethereum conference in the world. And it's full of developers! I am especially excited about the cool location this year in...

  • Randomness and the Blockchain

    How to achieve secure randomness for Solidity smart contracts?

    When we talk about randomness and blockchain, these are really two problems: How to generate randomness in smart contracts? How to produce randomness for proof-of-stake (POS) systems? Or more generally, how to produce trusted randomness in public distributed systems? There is some overlap of...