# Create a custom AMM with a novel invariant

Balancer protocol provides developers with a modular architecture that enables the rapid development of custom AMMs.

AMMs built on Balancer inherit the security of the Balancer vault, and benefit from a streamlined development process. Balancer v3 was re-built from the ground up with developer experience as a core focus. Development teams can now focus on their product innovation without having to build an entire AMM.

This section is for developers looking to build a new custom pool type with a novel invariant. If you are looking to extend an existing pool type with hooks, start here.

# Build your custom AMM

At a high level, creating a custom AMM on Balancer protocol involves the implementation of five functions onSwap, computeInvariant and computeBalance as well as getMaximumSwapFeePercentage and getMinimumSwapFeePercentage. To expedite the development process, Balancer provides two contracts to inherit from:

• IBasePool.solopen in new window - This interface defines the required functions that every Balancer pool must implement
• BalancerPoolToken.solopen in new window - This contract implements the ERC20MultiToken standard that enables your pool contract to be ERC20 compliant while delegating BPT accounting to the vault. For more information, refer to BalancerPoolToken.

Both IBasePool and BalancerPoolToken are used across all core Balancer pools, even those implemented by Balancer Labs (ie: WeightedPoolopen in new window).

Below, we present a naive implementation of a two token ConstantProductPool & ConstantSumPool utilising (X * Y = K) & (X + Y = K) as a reference for walking through the required functions necessary to implement a custom AMM on Balancer protocol:

# Compute Invariant

Custom AMMs built on Balancer protocol are defined primarily by their invariant. Broadly speaking, an invariant is a mathematical function that defines how the AMM exchanges one asset for another. A few widely known invariants include Constant Product (X * Y = K)open in new window and Stableswapopen in new window.

Our two-token ConstantSumPool uses the constant sum invariant, or X + Y = K. To implement computeInvariant, we simply add the balances of the two tokens. For the ConstantProductPool the invariant calculation is the square root of the product of balances. This ensures invariant growth proportional to liquidity growth.

For additional references, refer to the WeightedPoolopen in new window and Stable Poolopen in new window implementations.

# Compute Balance

computeBalance returns the new balance of a pool token necessary to achieve an invariant change. It is essentially the inverse of the pool's invariant. The invariantRatio is the ratio of the new invariant (after an operation) to the old. computeBalance is used for liquidity operations where the token amount in/out is unknown, specifically AddLiquidityKind.SINGLE_TOKEN_EXACT_OUTopen in new window and RemoveLiquidityKind.SINGLE_TOKEN_EXACT_INopen in new window.

You can see the implementations of the ConstantProductPool and ConstantSumPool below:

For additional references, refer to the WeightedPoolopen in new window and StablePoolopen in new window implementations.

# On Swap

Although the outcome of onSwap could be determined using computeInvariant and computeBalance, it is highly likely that there is a more gas-efficient strategy. onSwap is provided as a means to facilitate lower cost swaps.

Balancer protocol supports two types of swaps:

• EXACT_IN - The user defines the exact amount of tokenIn they want to spend.
• EXACT_OUT - The user defines the exact amount of tokenOut they want to receive.

The minAmountOut or maxAmountIn are enforced by the vaultopen in new window .

When swapping tokens, our constant K must remain unchanged. Since our two-token ConstantSumPool uses the constant sum invariant (X + Y = K), the amount entering the pool will always equal the amount leaving the pool:

The PoolSwapParams struct definition can be found hereopen in new window.

For additional references, refer to the WeightedPoolopen in new window and StablePoolopen in new window implementations.

# Constructor arguments

At a minimum, your constructor should have the required arguments to instantiate the BalancerPoolToken:

• IVault vault: The address of the Balancer vault
• string name: ERC20 compliant name that will identify the pool token (BPT).
• string symbol: ERC20 compliant symbol that will identify the pool token (BPT).

constructor(IVault vault, string name, string symbol) BalancerPoolToken(vault, name, symbol) {}

The approach taken by Balancer Labs is to define a NewPoolParamsopen in new window struct to better organize the constructor arguments.

# Swap fees

The charging of swap fees is managed entirely by the Balancer vault. The pool is only responsible for declaring the swapFeePercentage for any given swap or unbalanced liquidity operation on registration as well as declaring an minimum and maximum swap fee percentage. For more information, see Swap feesopen in new window.

Balancer supports two types of swap fees:

• Static swap fee: Defined on vault.registerPool() and managed via calls to vault.setStaticSwapFeePercentage(). For more information, see Swap fee.
• Dynamic swap fee: are managed by a Hooks contract. If a swap with a pool uses the dynamic swap fee is determined on pool registration. A Hook flags that it supports dynamic fees on vault.registerPool(). For more information, see Dynamic swap fees.

# Hooks

Hooks as standalone contracts are not part of a custom pool's implementation. However they can be combined with custom pools. For a detailed understanding, see Hooks.

# Vault reentrancy

Hooks allow a pool to reenter the vault within the context of a pool operation. While onSwap, computeInvariant and computeBalance must be executed within a reentrancy guard, the vault is architected such that hooks operate outside of this requirement.

# Add / Remove liquidity

The implementation of computeInvariant and computeBalance allows a pool to support ALL Add/Remove liquidity types. For instances where your custom AMM has additional requirements for add/remove liquidity operations, Balancer provides support for AddLiquidityKind.CUSTOM and RemoveLiquidityKind.CUSTOM. An example custom liquidity operation can be found in Cron Finance'sopen in new window TWAMM implementation on Balancer v2, specifically when the pool registers long term ordersopen in new window.

When adding support for custom liquidity operations, it's recommended that your pool contract implement IPoolLiquidityopen in new window

contract ConstantSumPool is IBasePool, IPoolLiquidity, BalancerPoolToken {
    ...
}

# Add liquidity custom

For your AMM to support add liquidity custom, it must:

• Implement onAddLiquidityCustom, as defined hereopen in new window
• Set LiquidityManagement.supportsAddLiquidityCustom to true on pool register.

# Remove liquidity custom

For your AMM to support remove liquidity custom, it must:

• Implement onRemoveLiquidityCustom, as defined hereopen in new window
• Set LiquidityManagement.supportsRemoveLiquidityCustom to true on pool register.

# Remove support for built in liquidity operations

There may be instances where your AMM should not support specific built-in liquidity operations. If certain operations should be enabled in your custom pool is defined in LiquidityManagement. You can choose to:

• disable unbalanced liquidity add and removals
• enable add liquidity custom
• enable remove liquidity custom

To achieve this, the respective entry in the LiquidityManagement struct needs to be set.

struct LiquidityManagement {
    bool disableUnbalancedLiquidity;
    bool enableAddLiquidityCustom;
    bool enableRemoveLiquidityCustom;
}

These settings get passed into the pool registration flow.

# Testing your pool

Depending on the combination of liquidity operations you allow for your pool you need to ensure the correct amount of BPT get's minted whenever a user adds/removes liquidity unbalanced (which calls into computeInvariant) and proportional adds/removes (which does not call into the pool and solely relies on BasePoolMath.solopen in new window). Let's say your pool has reserves of [100, 100] and an addLiquidityProportional([50,50]) gets the user 100 BPT in return, if the user were to addLiquidityUnbalanced([50,50]) you must ensure that the amount of BPT that gets minted is the same as in the addLiquidityProportional([50,50]) operation. Consider also reading through liquidity invariant approximation to get more context on various combination of pool operations.

# Deploying your pool

See the guide to Deploy a Custom AMM Using a Factory.