diff --git a/docs/.vuepress/configs/navbar/index.ts b/docs/.vuepress/configs/navbar/index.ts index eb5a95de..49072d28 100644 --- a/docs/.vuepress/configs/navbar/index.ts +++ b/docs/.vuepress/configs/navbar/index.ts @@ -49,6 +49,7 @@ export const navbar: NavbarConfig = [ text: 'APIs', link: '/reference/contracts/apis/vault', }, + '/reference/contracts/security', '/reference/contracts/error-codes', '/reference/contracts/query-functions', ], @@ -85,6 +86,7 @@ export const navbar: NavbarConfig = [ children: [ '/reference/math/weighted-math', '/reference/math/stable-math', + '/reference/math/linear-math', ], }, { diff --git a/docs/.vuepress/public/images/relayer-chained-call.webp b/docs/.vuepress/public/images/relayer-chained-call.webp new file mode 100644 index 00000000..8db50ff6 Binary files /dev/null and b/docs/.vuepress/public/images/relayer-chained-call.webp differ diff --git a/docs/.vuepress/public/images/sor-path-example.png b/docs/.vuepress/public/images/sor-path-example.png new file mode 100644 index 00000000..b22855c3 Binary files /dev/null and b/docs/.vuepress/public/images/sor-path-example.png differ diff --git a/docs/concepts/advanced/preminted-bpt.md b/docs/concepts/advanced/preminted-bpt.md index 7108aa99..b7db0095 100644 --- a/docs/concepts/advanced/preminted-bpt.md +++ b/docs/concepts/advanced/preminted-bpt.md @@ -1 +1,9 @@ -# Preminted BPT \ No newline at end of file +# Preminted BPT + +## Overview + +Preminted BPT is a relatively new concept in the evolution of Balancer pool design. As [pool composability](/concepts/pools/#pool-composability) became more commonplace with nested pools, the need to go from an asset in a pool to the BPT (normally referred to as a `join`) grew. This not only makes it difficult to include as part of a complex multihop `batchSwap` but also introduced additional gas costs since a `join` will mint new BPT. + +Preminted BPT means that the pool mints the max `2**(111)` BPT upon creation and the BPT is included as one of the tokens in the pool itself. The pool's arithmetic behaves as if it didn't exist, and the BPT total supply is not a useful value. Instead a `virtual supply` (how much BPT is actually owned outside the Vault) is used. + +Pools with Preminted BPTs like [Composable Stable Pools](/concepts/pools/composable-stable.md) can then allow an user to `swap` from a token in the pool to the BPT of the pool, while previously this was only possible with a `join` operation. diff --git a/docs/concepts/advanced/relayers.md b/docs/concepts/advanced/relayers.md index e2a385e4..a13d2097 100644 --- a/docs/concepts/advanced/relayers.md +++ b/docs/concepts/advanced/relayers.md @@ -1 +1,68 @@ # Relayers + +## Overview + +A relayer is a contract that is authorized by the protocol and allows 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, improving the UX. + +For security reasons, a Relayer has to be authorized by the Balancer DAO before it can be used, and even after authorization, 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](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/standalone-utils/contracts/relayer/BalancerRelayer.sol), which is the single point of entry via the multicall function, and a library contract, such as the [VaultActions](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/standalone-utils/contracts/relayer/VaultActions.sol), which defines the allowed behavior of the relayer, for example — [VaultActions](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/standalone-utils/contracts/relayer/VaultActions.sol), [LidoWrapping](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/standalone-utils/contracts/relayer/LidoWrapping.sol), [GaugeActions](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/standalone-utils/contracts/relayer/GaugeActions.sol). + +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 pseudocode demonstrating how an authorization, exitPool and swap can be chained and called via the multicall function: + +```ts +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 the [hasApprovedRelayer](/reference/contracts/apis/vault.md#hasapprovedrelayer) on the Vault can be used. + +A Relayer can also be approved by using the `setRelayerApproval` function from the [BaseRelayerLibrary](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/standalone-utils/contracts/relayer/BaseRelayerLibrary.sol) contract. Here a signed authorisation message from the user is passed as an input parameter. This allows the 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 one 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: + +![Relayer Chained Call](/images/relayer-chained-call.webp) + +An [OutputReference](https://github.com/balancer-labs/balancer-v2-monorepo/blob/8ac66717502b00122a3fcdf78e6d555c54528c3c/pkg/standalone-utils/contracts/relayer/VaultActions.sol#L39) consists of an index and a key: + +```solidity +struct OutputReference { + uint256 index; + uint256 key; +} +``` + +Where the key is the slot the value will be stored at. The 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. + +Migrating 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-usd pool using `batchSwaps` + a. DAI -> bbausdBpt + b. USDC -> bbausdBpt + c. USDT -> bbausdBpt +4. stake bbausdBpt 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. + +A full example of this can be found [here](https://github.com/balancer-labs/balancer-sdk/blob/develop/balancer-js/src/modules/zaps/bbausd2-migrations/stabal3.integration.spec.ts#L120-L183) diff --git a/docs/concepts/advanced/smart-order-router.md b/docs/concepts/advanced/smart-order-router.md index b9127993..28da687f 100644 --- a/docs/concepts/advanced/smart-order-router.md +++ b/docs/concepts/advanced/smart-order-router.md @@ -1 +1,13 @@ -# Smart Order Router \ No newline at end of file +# Smart Order Router + +## Overview + +The Smart Order Router (SOR) finds the best prices for Balancer traders. For given input and output tokens, the SOR finds the optimal trades whether that is a direct swap in one pool, or a combination of trades hopping through multiple pools. + +![SOR Path Split Example](/images/sor-path-example.png) + +::: tip Under Development + +The current SOR is being upgraded with a new alogrithm and architecture to improve speed and reliability. This page will be filled out upon release + +::: diff --git a/docs/concepts/governance/multisig.md b/docs/concepts/governance/multisig.md index f836d250..a9b41fbc 100644 --- a/docs/concepts/governance/multisig.md +++ b/docs/concepts/governance/multisig.md @@ -1,15 +1,20 @@ # Multisig +::: tip Multisig Permissions + +The core of Balancer smart contracts are immutable and do not use proxies or other upgrade mechanisms. The Multisig does **not** have custody of, nor control over, funds from liquidity providers that lie inside Balancer Protocol contracts. Balancer V2 was designed so that even if a multisig goes rogue, all the liquidity is safe and can be withdrawn by their rightful owners. Specific permisions can be found in the article below. +::: + ## The Multisigs and their addresses Here is a list of the currently active Balancer Multisigs as of February 2023: | Name |
Purpose
| Chain | Address | Signer Set | -|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|-------------------------------------------------------------------| +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------- | | Protocol Fees Multisig | Collect fees, and set A-Factors and Fees on pools (default pool-owner, except on mainnet where a separate Multisig is used to set fees. | [MAINNET](https://gnosis-safe.io/app/eth:0x7c68c42De679ffB0f16216154C996C354cF1161B/home), [ARBI](https://gnosis-safe.io/app/arb1:0x7c68c42De679ffB0f16216154C996C354cF1161B/home), [POLYGON](https://gnosis-safe.io/app/matic:0x7c68c42De679ffB0f16216154C996C354cF1161B/home) | `0x7c68c42De679ffB0f16216154C996C354cF1161B` | [BAL Maxis](#operational-multisigs-signer-set-aka-balancer-maxis) | | Mainnet Fee Setter | Default pool owner for Mainnet that can set A-Factors and protocol fees. | [MAINNET](https://gnosis-safe.io/app/eth:0xf4A80929163C5179Ca042E1B292F5EFBBE3D89e6/home) | `0xf4A80929163C5179Ca042E1B292F5EFBBE3D89e6` | [BAL Maxis](#operational-multisigs-signer-set-aka-balancer-maxis) | | DAO Multlsig | Funding BIPs, killing of gauges, veBAL whitelisting | [MAINNET](https://gnosis-safe.io/app/eth:0x10A19e7eE7d7F8a52822f6817de8ea18204F2e4f/home) | `0x10A19e7eE7d7F8a52822f6817de8ea18204F2e4f` | [DAO Signers](#dao-multisig-signer-set) | -| LM Multisig | Used to manage gauges and Reward Tokens and manage liquidity supplied to multichain (bridge). New Gauge requests go here. | [MAINNET](https://gnosis-safe.io/app/eth:0xc38c5f97B34E175FFd35407fc91a937300E33860/home), [ARBI](https://gnosis-safe.io/app/arb1:0xc38c5f97B34E175FFd35407fc91a937300E33860/home), [POLYGON](https://gnosis-safe.io/app/matic:0xc38c5f97B34E175FFd35407fc91a937300E33860/home) | `0xc38c5f97B34E175FFd35407fc91a937300E33860` | [BAL Maxis](#operational-multisigs-signer-set-aka-balancer-maxis) | +| LM Multisig | Used to manage gauges and Reward Tokens and manage liquidity supplied to multichain (bridge). New Gauge requests go here. | [MAINNET](https://gnosis-safe.io/app/eth:0xc38c5f97B34E175FFd35407fc91a937300E33860/home), [ARBI](https://gnosis-safe.io/app/arb1:0xc38c5f97B34E175FFd35407fc91a937300E33860/home), [POLYGON](https://gnosis-safe.io/app/matic:0xc38c5f97B34E175FFd35407fc91a937300E33860/home) | `0xc38c5f97B34E175FFd35407fc91a937300E33860` | [BAL Maxis](#operational-multisigs-signer-set-aka-balancer-maxis) | | Linear Pool Control | Manage limits on Mainnet Linear Pools | [MAINNET](https://gnosis-safe.io/app/eth:0x75a52c0e32397A3FC0c052E2CeB3479802713Cf4/home) | `0x75a52c0e32397A3FC0c052E2CeB3479802713Cf4` | [BAL Maxis](#operational-multisigs-signer-set-aka-balancer-maxis) | | Maxi Payments | Holds the Maxi Budget and is used to pay people and expenses. | [MAINNET](https://gnosis-safe.io/app/eth:0x166f54F44F271407f24AA1BE415a730035637325/home) | `0x166f54F44F271407f24AA1BE415a730035637325` | [BAL Maxis](#operational-multisigs-signer-set-aka-balancer-maxis) | | Managed Treasury | Holds treasury funds managed by Karpatkey as per [BIP-162](https://forum.balancer.fi/t/bip-162-karpatkey-investment-strategy) | [MAINNET](https://app.safe.global/eth:0x0EFcCBb9E2C09Ea29551879bd9Da32362b32fc89/home) | `0x0EFcCBb9E2C09Ea29551879bd9Da32362b32fc89` | [DAO Signers](#dao-multisig-signer-set) | @@ -21,56 +26,60 @@ Here is a list of the currently active Balancer Multisigs as of February 2023: Since its inception, the long term vision for the Balancer Protocol is to be fully governed by BAL token holders, while token ownership is aimed to be widely spread across the Balancer community. But getting to that ideal, long-term vision of a truly decentralized and effective governance is no easy task. Protocol governance is a highly complex and rapidly evolving topic. The whole crypto ecosystem is still in the very early days of trying to figure out: -* which mechanisms and processes work best -* the necessary infrastructure, tooling, and user interfaces -* the risks and concerns associated with each approach + +- which mechanisms and processes work best +- the necessary infrastructure, tooling, and user interfaces +- the risks and concerns associated with each approach Experimentation has been running wild in all directions: -* vote delegation -* minimum quorum -* specialized committees -* continuous voting -* augmented voting power via token lock -* off-chain voting for signaling / polling -* on-chain actions from off-chain voting by way of oracles -* upgradeable smart contracts -* time delays on sensitive actions -* emergency actions via Multisig \(e.g. pause, shutdown\) -* legal entities \(e.g. foundation\) providing support for the DAO -* tools for DAO treasury management -* token issuance to cover protocol expenses -* incentivized voting -* incentivized off-chain engagement \(e.g. forum participation\) -* and so on… +- vote delegation +- minimum quorum +- specialized committees +- continuous voting +- augmented voting power via token lock +- off-chain voting for signaling / polling +- on-chain actions from off-chain voting by way of oracles +- upgradeable smart contracts +- time delays on sensitive actions +- emergency actions via Multisig \(e.g. pause, shutdown\) +- legal entities \(e.g. foundation\) providing support for the DAO +- tools for DAO treasury management +- token issuance to cover protocol expenses +- incentivized voting +- incentivized off-chain engagement \(e.g. forum participation\) +- and so on… While also actively experimenting with governance-related initiatives, the Balancer community has leaned towards the more cautious and thoughtful approach of not trying to rush the path to full decentralization, so each step towards a mature on-chain governance will be taken with due care, having learned from others’ experiences. -Balancer V1 contracts are immutable, so up until now, there have been no core protocol parameters to tweak/change. Instead, our governance has focused on a fair, inclusive BAL token distribution, which is carried out mainly through the protocol’s liquidity mining. BAL holders have tweaked liquidity mining via off-chain voting. And to make that possible, Balancer Labs proudly developed in-house an open-source tool called Snapshot, which became the widely popular gold standard for off-chain voting in blockchain land. [Snapshot](https://snapshot.org/#/) was so successful that was as its own initiative. It has become a standard for DeFi governance. +Balancer V1 contracts are immutable, so up until now, there have been no core protocol parameters to tweak/change. Instead, our governance has focused on a fair, inclusive BAL token distribution, which is carried out mainly through the protocol’s liquidity mining. BAL holders have tweaked liquidity mining via off-chain voting. And to make that possible, Balancer Labs proudly developed in-house an open-source tool called Snapshot, which became the widely popular gold standard for off-chain voting in blockchain land. [Snapshot](https://snapshot.org/#/) was so successful that was as its own initiative. It has become a standard for DeFi governance. Balancer V2 contracts, on the other hand, do allow for some tweaking of core protocol parameters, for instance, in turning on protocol fees. As a placeholder for a future on-chain DAO, such limited admin powers has been initially granted to a Multisig. -Balancer strives to continue to automate operations and governance execution. While the eventual goal is still to move the entire governance and execution on-chain, the current Multisigs have proven themselves as reliable executors of the wishes of veBAL voters. In the long run, BAL holders are expected to retire the Multisig in favor of a full-fledged Balancer DAO. +Balancer strives to continue to automate operations and governance execution. While the eventual goal is still to move the entire governance and execution on-chain, the current Multisigs have proven themselves as reliable executors of the wishes of veBAL voters. In the long run, BAL holders are expected to retire the Multisig in favor of a full-fledged Balancer DAO. ## Current state of Multisig Operations -Balancer Governance has grown to into a system managed by a collection of Multisigs, which are activated by 2 different signer sets. First of all, a very important point: the Multisigs do NOT have decision making power, as their role is to simply enact and operate on-chain the decisions BAL holders make via off-chain voting and assist community members in the governance process. -Further, fee collection and processing requires tokens to be swept from the vault and traded for dollars. This is an example of an operational pratice, defined by governance, that requires regular onchain intevention. The Balancer Maxis currently operate these processes through Multisigs, with a goal to automate as much as possible. +Balancer Governance has grown to into a system managed by a collection of Multisigs, which are activated by 2 different signer sets. First of all, a very important point: the Multisigs do NOT have decision making power, as their role is to simply enact and operate on-chain the decisions BAL holders make via off-chain voting and assist community members in the governance process. + +Further, fee collection and processing requires tokens to be swept from the vault and traded for dollars. This is an example of an operational pratice, defined by governance, that requires regular onchain intevention. The Balancer Maxis currently operate these processes through Multisigs, with a goal to automate as much as possible. All Balancer Multisigs are deployed using [Gnosis Safe](https://gnosis-safe.io/), the most battle-tested Multisig contract on Ethereum. The DAO and Treasury Multisigs with the ability to change protocol operations or access to treasury funds are require 6-of-11 singers to process transactions. The signer structure of the Multisigs may change if voted on through the governance process. -Over time, various functions have been delegated to different Multisigs. The Balancer Maxis working group is responsible for ensuring the application of governance on chain. The [Balancer Multisig Ops Repo](https://github.com/BalancerMaxis/Multisig-ops) describes all Multisigs and operations as well as the external touch-points available. +Over time, various functions have been delegated to different Multisigs. The Balancer Maxis working group is responsible for ensuring the application of governance on chain. The [Balancer Multisig Ops Repo](https://github.com/BalancerMaxis/Multisig-ops) describes all Multisigs and operations as well as the external touch-points available. ## The Signers -Balancer’s Multisig signers are a diverse set of widely respected community members. These are the current signers as of February 2023: -**Note that the list below was last updated in February 2023. The Maxis keep an up-to-date list of their signers and Multisigs [here](https://github.com/BalancerMaxis/Multisig-ops)** +Balancer’s Multisig signers are a diverse set of widely respected community members. These are the current signers as of February 2023: + +**Note that the list below was last updated in February 2023. The Maxis keep an up-to-date list of their signers and Multisigs [here](https://github.com/BalancerMaxis/Multisig-ops)** ### DAO Multisig Signer Set + The DAO Multisig Signer Set and associated Multisigs is reserved for major changes to protcool operations, and management of treasury funds. | Signer | Association | Address | -|----------------------------------------------------|--------------------------|-----------------------------------------------| +| -------------------------------------------------- | ------------------------ | --------------------------------------------- | | [Alexander Lange](https://twitter.com/AlexLangeVC) | \(Inflection\) | `0x3ABDc84Dd15b0058B281D7e26CCc3932cfb268aA` | | [0xMaki](https://twitter.com/0xMaki) | \(LayerZero, AURA, DCV\) | `0x285b7EEa81a5B66B62e7276a24c1e0F83F7409c1` | | [Solarcurve](https://twitter.com/0xSolarcurve) | \(Balancer Maxis\) | `0x512fce9B07Ce64590849115EE6B32fd40eC0f5F3` | @@ -80,42 +89,39 @@ The DAO Multisig Signer Set and associated Multisigs is reserved for major chang | [Trent McConaghy](https://twitter.com/trentmc0) | \(Ocean Protocol\) | `0x478eC43c6867c2884f87B21c164f1fD1308bD9a3` | | [Stefan](https://twitter.com/StefanDGeorge) | \(Gnosis\) | `0x9F7dfAb2222A473284205cdDF08a677726d786A0` | | [bonustrack87](https://twitter.com/bonustrack87) | \(Snapshot\) | `0x9BE6ff2A1D5139Eda96339E2644dC1F05d803600` | - | [nanexcool](https://twitter.com/nanexcool) | \(Ethereum OG\) | ` 0x823DF0278e4998cD0D06FB857fBD51e85b18A250` | - | [David Gerai](https://twitter.com/davgarai) | \(Nostra Finance\) | ` 0xAc1aA53108712d7f38093A67d380aD54B562a650` | +| [nanexcool](https://twitter.com/nanexcool) | \(Ethereum OG\) | ` 0x823DF0278e4998cD0D06FB857fBD51e85b18A250` | +| [David Gerai](https://twitter.com/davgarai) | \(Nostra Finance\) | ` 0xAc1aA53108712d7f38093A67d380aD54B562a650` | **DAO Multisigs always require 6/11 signers to execute a transaction.** -Beyond those current signers, [BIP-16](https://forum.balancer.fi/t/bip-16-update-dao-Multisig-replacement-list/3361) laid out a group of backup signers who could replace current signers without further governance. Note that since BIP-16, Moniur has become an active member of the DAO Multisig. - - +Beyond those current signers, [BIP-16](https://forum.balancer.fi/t/bip-16-update-dao-Multisig-replacement-list/3361) laid out a group of backup signers who could replace current signers without further governance. Note that since BIP-16, Moniur has become an active member of the DAO Multisig. ### Operational Multisigs Signer Set AKA Balancer Maxis -The Balancer Maxis operate a number of Multisigs with a reduced signer requirement, which are used for the regular operation of the protocol, as well as adding gauges to veBAL. +The Balancer Maxis operate a number of Multisigs with a reduced signer requirement, which are used for the regular operation of the protocol, as well as adding gauges to veBAL. -| Signer | Discord Handle | Address | -|--------------|-----------------|---------------------------------------------| -| Solarcurve | solarcurve#5075 | `0x512fce9B07Ce64590849115EE6B32fd40eC0f5F3` | -| Zen Dragon | Zen Dragon#2923 | `0x7c2eA10D3e5922ba3bBBafa39Dc0677353D2AF17` | -| Zekraken | zekraken#0645 | `0xafFC70b81D54F229A5F50ec07e2c76D2AAAD07Ae` | -| Mike B | d_w_b_w_d#0685 | `0xc4591c41e01a7a654B5427f39Bbd1dEe5bD45D1D` | -| Xeonus | Xeonus#4620 | `0x7019Be4E4eB74cA5F61224FeAf687d2b43998516` | -| Danko | 0xDanko#3565 | `0x200550cAD164E8e0Cb544A9c7Dc5c833122C1438` | -| Tritium | Trtiium#0069 | `0xcf4fF1e03830D692F52EB094c52A5A6A2181Ab3F` | +| Signer | Discord Handle | Address | +| ---------- | --------------- | -------------------------------------------- | +| Solarcurve | solarcurve#5075 | `0x512fce9B07Ce64590849115EE6B32fd40eC0f5F3` | +| Zen Dragon | Zen Dragon#2923 | `0x7c2eA10D3e5922ba3bBBafa39Dc0677353D2AF17` | +| Zekraken | zekraken#0645 | `0xafFC70b81D54F229A5F50ec07e2c76D2AAAD07Ae` | +| Mike B | d_w_b_w_d#0685 | `0xc4591c41e01a7a654B5427f39Bbd1dEe5bD45D1D` | +| Xeonus | Xeonus#4620 | `0x7019Be4E4eB74cA5F61224FeAf687d2b43998516` | +| Danko | 0xDanko#3565 | `0x200550cAD164E8e0Cb544A9c7Dc5c833122C1438` | +| Tritium | Trtiium#0069 | `0xcf4fF1e03830D692F52EB094c52A5A6A2181Ab3F` | **The Balancer Maxi Multisig set requires 2 or 3 out of 7 signers to execute, depending on the security level of the Multisig.** -The Balancer Maxis are ratified by a BIP each quarter. [BIP-145](https://forum.balancer.fi/t/bip-145-fund-the-balancer-maxis-for-q1-2023/) is a recent example of such governance. - +The Balancer Maxis are ratified by a BIP each quarter. [BIP-145](https://forum.balancer.fi/t/bip-145-fund-the-balancer-maxis-for-q1-2023/) is a recent example of such governance. ## Signer Duties -All signers are expected to sign an Ethereum transaction ratifying each decision made by BAL holders through snapshot votes. This signature is expected to be done within the two weeks after the snapshot vote was concluded. Signers are encouraged to sign open requests even if they have already reached a quorum in order to signal their liveliness. +All signers are expected to sign an Ethereum transaction ratifying each decision made by BAL holders through snapshot votes. This signature is expected to be done within the two weeks after the snapshot vote was concluded. Signers are encouraged to sign open requests even if they have already reached a quorum in order to signal their liveliness. A signer shall lose his/her role \(by action of the remaining Multisig signers excluding him/her\) in case he/she: -* acts against BAL token holders’ off-chain voting; -* goes through 3 months or 2 votes \(whichever takes longer\) without performing any of their signer duties. +- acts against BAL token holders’ off-chain voting; +- goes through 3 months or 2 votes \(whichever takes longer\) without performing any of their signer duties. ## Multisig Powers @@ -123,18 +129,13 @@ V2 smart contracts can grant some specific powers to an “admin” address, whi These powers are: -* set a share of swap fees to be diverted to the protocol \(hard capped at 50% of the swap fee\) -* set a flash loan fee -* extract from the vault collected protocol fees and/or excess balances \(e.g. airdrops\), to any destination -* set the address of the oracle implementation -* set relayer addresses: relayers are \(user opt-in, audited\) contracts that can make calls to the vault -(with the transaction “sender” being any arbitrary address\) and use the sender’s ERC20 vault allowance, -internal balance or BPTs on their behalf -* set dynamic-fee controllers: addresses \(initially assigned to Gauntlet\) that may change the swap fee for pools -created by the dynamic-fee pool factory that will be deployed by Balancer Labs -* Add and removal of veBAL gauges - -## Access to User Deposits - -It’s worth highlighting that the Multisig does **not** have custody of, nor control over, funds from liquidity providers that lie inside Balancer Protocol contracts. Balancer V2 was designed so that even if the Multisig goes rogue, all the liquidity is safe and can be withdrawn by their rightful owners. - +- set a share of swap fees to be diverted to the protocol \(hard capped at 50% of the swap fee\) +- set a flash loan fee +- extract from the vault collected protocol fees and/or excess balances \(e.g. airdrops\), to any destination +- set the address of the oracle implementation +- set relayer addresses: relayers are \(user opt-in, audited\) contracts that can make calls to the vault + (with the transaction “sender” being any arbitrary address\) and use the sender’s ERC20 vault allowance, + internal balance or BPTs on their behalf +- set dynamic-fee controllers: addresses \(initially assigned to Gauntlet\) that may change the swap fee for pools + created by the dynamic-fee pool factory that will be deployed by Balancer Labs +- Add and removal of veBAL gauges diff --git a/docs/concepts/pools/linear.md b/docs/concepts/pools/linear.md index c9cb1eb5..cdd005ae 100644 --- a/docs/concepts/pools/linear.md +++ b/docs/concepts/pools/linear.md @@ -1 +1,25 @@ +--- +references: + - details: Linear Math + link: /reference/math/linear-math +--- + # Linear Pools + +## Overview + +Linear pools are designed to facilitate swaps between assets and their yield bearing, wrapped counterparts. For example, DAI and aDAI from Aave. The pools use [Linear Math](/reference/math/linear-math.md) and are usually used as a component in a [Boosted Pool](./boosted.md). Linear pools have set ranges to decide how much of the native token should be kept available for swaps vs the yield bearing counterpart. They use a positive/negative fee mechanism to incentivize arbitrageurs to maintain a desired ratio between the two tokens. + +## Subtypes + +Since there are lots of ways to generate yield in Defi there are different interfaces for yield bearing tokens. [ERC-4626](https://ethereum.org/en/developers/docs/standards/tokens/erc-4626/) is a standard to unify the API for tokenized yield-bearing vaults and is the primary Linear pool type. A complete list with links to the codebase: + +- [ERC4626 Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/erc4626-linear-pool/ERC4626LinearPool.sol) +- [Aave V2 Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/aave-v2-linear-pool/AaveLinearPool.sol) +- [Euler Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/euler-linear-pool/EulerLinearPool.sol) +- [Yearn Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/yearn-linear-pool/YearnLinearPool.sol) +- [Beefy Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/beefy-linear-pool/BeefyLinearPool.sol) +- [Gearbox Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/gearbox-linear-pool/GearboxLinearPool.sol) +- [Silo Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/silo-linear-pool/SiloLinearPool.sol) +- [Reaper Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/reaper-linear-pool/ReaperLinearPool.sol) +- [Tetu Linear Pools](https://github.com/orbcollective/linear-pools/blob/master/packages/linear-pools/contracts/tetu-lineat-pool/TetuLinearPool.sol) diff --git a/docs/concepts/pools/more/configuration.md b/docs/concepts/pools/more/configuration.md index 5f906f62..87b666c4 100644 --- a/docs/concepts/pools/more/configuration.md +++ b/docs/concepts/pools/more/configuration.md @@ -10,7 +10,9 @@ Balancer is a flexibile protocol and as such there are many choices an user or p ## Pool Types -TODO +Choosing the type of pool to use is straightforward based on a few simple factors. The primary being the expected price variations between the tokens in the pool. For most non-stable assets a [Weighted Pool](/concepts/pools/weighted.md) is the right choice. For assets that are stable like stablecoins or assets that are stable against each other with a known price rate (ex: wstETH/weth), a [Composable Stable Pool](/concepts/pools/stable.md) allows for much deeper liquidity. + +The Balancer Dapp has a [pool creation interface](https://app.balancer.fi/#/ethereum/pool/create) for weighted pools. For stable pool creation, reach out to our devs on [Discord](https://discord.balancer.fi/) for assistance. ## Token Composition @@ -22,4 +24,14 @@ In general weighted pools should stick to 2 tokens and pair with a "core routing ## Fees -TODO +There a few choices to make when setting the swap fees for a new pool: + +1. Should the fee be permanently fixed? +2. If variable who should control the updates? + - Balancer Governance + - A set address or contract +3. What should the swap fee amount be? + +To set a permanent fee, an `owner` of `0x0000000000000000000000000000000000000000` is set upon pool creation. However in general the recommendation is to allow Balancer governance (and delegated addresses) to dynamically adjust the fees. This is done by setting an owner of `0xba1ba1ba1ba1ba1ba1ba1ba1ba1ba1ba1ba1ba1b`. + +There are lots of discussion and research around how to best set a swap fee amount, but a general rule of thumb is for stable assets it should be lower (ex: `0.1%`) and non-stable pairs should be higher (ex: `0.3%`). diff --git a/docs/concepts/pools/weighted.md b/docs/concepts/pools/weighted.md index 2d89e10d..f230c7bf 100644 --- a/docs/concepts/pools/weighted.md +++ b/docs/concepts/pools/weighted.md @@ -9,9 +9,38 @@ references: ## Overview -Weighted Pools are highly versatile and configurable pools. Weighted Pools use [Weighted Math](/reference/math/weighted-math.md), which makes them great for general cases, including tokens that don't necessarily have any price correlation (ex. DAI/WETH). Unlike pools in other DeFi protocols that only provide 50/50 weightings, Balancer Weighted Pools enable users to build pools with different token counts and weightings, such as pools with 80/20 or 60/20/20 weightings. - -![](/images/weighted-pool-pie.svg) +Weighted Pools are an extension of the classical $x * y = k$ AMM pools popularized by Uniswap v1. Weighted Pools use [Weighted Math](/reference/math/weighted-math.md), which makes them great for general cases, including tokens that don't necessarily have any price correlation (ex. DAI/WETH). Unlike pools in other AMMs that only provide 50/50 weightings, Balancer Weighted Pools enable users to build pools with more than two tokens and custom weightings, such as pools with 80/20 or 60/20/20 weightings. + +::: chart Weighted Pool + +```json +{ + "type": "pie", + "data": { + "labels": ["WETH", "BAL", "DAI"], + "datasets": [ + { + "label": "%", + "data": [33, 33, 33], + "backgroundColor": [ + "rgba(255, 99, 132, 0.2)", + "rgba(54, 162, 235, 0.2)", + "rgba(255, 206, 86, 0.2)" + ], + "borderColor": [ + "rgba(255, 99, 132, 1)", + "rgba(54, 162, 235, 1)", + "rgba(255, 206, 86, 1)" + ], + "borderWidth": 1 + } + ] + }, + "options": {} +} +``` + +::: ## Advantages @@ -21,10 +50,8 @@ Weighted Pools allow users to choose their levels of exposure to certain assets For example if a user wants to provide liquidity for WBTC and WETH, they can choose the weight that most aligns with their strategy. A pool more heavily favoring WBTC implies they expect bigger gains for WBTC, while a pool more heavily favoring WETH implies bigger gains for WETH. An evenly balanced pool is a good choice for assets that are expected to remain proportional in value in the long run. -#### Impermanent Loss - -Impermanent Loss is the difference in value between holding a set of assets and providing liquidity for those same assets. +### Impermanent Loss -Some people find the word "Impermanent" misleading and prefer to call it "Divergence Loss" or "Rebalancing Loss" because one token may perpetually out-value another token, and the loss may become... permanent. +[Impermanent Loss](/concepts/advanced/impermanent-loss.md) is the difference in value between holding a set of assets and providing liquidity for those same assets. For pools that heavily weight one token over another, there is far less impermanent loss, but this doesn't come for free; very asymmetric pools do have higher slippage when making trades due to the fact that one side has much less liquidity. 80/20 pools have emerged as a happy medium when balancing liquidity an Impermanent Loss mitigation. diff --git a/docs/reference/contracts/deployment-addresses/arbitrum.md b/docs/reference/contracts/deployment-addresses/arbitrum.md index 96bfd822..fc971be7 100644 --- a/docs/reference/contracts/deployment-addresses/arbitrum.md +++ b/docs/reference/contracts/deployment-addresses/arbitrum.md @@ -29,11 +29,11 @@ For more information on specific deployments as well as changelogs for different ## Pool Factories -| Contract | Address | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | To be deployed shortly | -| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | To be deployed shortly | -| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | +| Contract | Address | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | [0xf1665E19bc105BE4EDD3739F88315cC699cc5b65](https://arbiscan.io/address/0xf1665E19bc105BE4EDD3739F88315cC699cc5b65) | +| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | [0x1c99324EDC771c82A0DCCB780CC7DDA0045E50e7](https://arbiscan.io/address/0x1c99324EDC771c82A0DCCB780CC7DDA0045E50e7) | +| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | ## BAL / veBAL / Liquidity Mining diff --git a/docs/reference/contracts/deployment-addresses/goerli.md b/docs/reference/contracts/deployment-addresses/goerli.md index 161a54c4..5cfdd370 100644 --- a/docs/reference/contracts/deployment-addresses/goerli.md +++ b/docs/reference/contracts/deployment-addresses/goerli.md @@ -30,11 +30,11 @@ For more information on specific deployments as well as changelogs for different ## Pool Factories -| Contract | Address | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | To be deployed shortly | -| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | To be deployed shortly | -| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | +| Contract | Address | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | [0x26575A44755E0aaa969FDda1E4291Df22C5624Ea](https://goerli.etherscan.io/address/0x26575A44755E0aaa969FDda1E4291Df22C5624Ea) | +| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | [0xbfD9769b061E57e478690299011A028194D66e3C](https://goerli.etherscan.io/address/0xbfD9769b061E57e478690299011A028194D66e3C) | +| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | ## BAL / veBAL / Liquidity Mining diff --git a/docs/reference/contracts/deployment-addresses/mainnet.md b/docs/reference/contracts/deployment-addresses/mainnet.md index 6f701210..44e105e9 100644 --- a/docs/reference/contracts/deployment-addresses/mainnet.md +++ b/docs/reference/contracts/deployment-addresses/mainnet.md @@ -30,11 +30,11 @@ For more information on specific deployments as well as changelogs for different ## Pool Factories -| Contract | Address | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | To be deployed shortly | -| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | To be deployed shortly | -| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | +| Contract | Address | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | [0x5Dd94Da3644DDD055fcf6B3E1aa310Bb7801EB8b](https://etherscan.io/address/0x5Dd94Da3644DDD055fcf6B3E1aa310Bb7801EB8b) | +| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | [0xdba127fBc23fb20F5929C546af220A991b5C6e01](https://etherscan.io/address/0xdba127fBc23fb20F5929C546af220A991b5C6e01) | +| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | ## BAL / veBAL / Liquidity Mining diff --git a/docs/reference/contracts/deployment-addresses/optimism.md b/docs/reference/contracts/deployment-addresses/optimism.md index 76a5cf48..5e5c1383 100644 --- a/docs/reference/contracts/deployment-addresses/optimism.md +++ b/docs/reference/contracts/deployment-addresses/optimism.md @@ -33,11 +33,11 @@ The Optimism deployment is a joint venture between Balancer and Beethoven teams. ## Pool Factories -| Contract | Address | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | To be deployed shortly | -| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | To be deployed shortly | -| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | +| Contract | Address | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | [0xA0DAbEBAAd1b243BBb243f933013d560819eB66f](https://optimistic.etherscan.io/address/0xA0DAbEBAAd1b243BBb243f933013d560819eB66f) | +| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | [0xe2E901AB09f37884BA31622dF3Ca7FC19AA443Be](https://optimistic.etherscan.io/address/0xe2E901AB09f37884BA31622dF3Ca7FC19AA443Be) | +| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | ## BAL / veBAL / Liquidity Mining diff --git a/docs/reference/contracts/deployment-addresses/polygon.md b/docs/reference/contracts/deployment-addresses/polygon.md index 79e86f04..26d00f12 100644 --- a/docs/reference/contracts/deployment-addresses/polygon.md +++ b/docs/reference/contracts/deployment-addresses/polygon.md @@ -29,11 +29,11 @@ For more information on specific deployments as well as changelogs for different ## Pool Factories -| Contract | Address | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | To be deployed shortly | -| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | To be deployed shortly | -| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | +| Contract | Address | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [WeightedPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/WeightedPoolFactory.sol) (v3) | [0x82e4cFaef85b1B6299935340c964C942280327f4](https://polygonscan.com/address/0x82e4cFaef85b1B6299935340c964C942280327f4) | +| [ComposableStablePoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-stable/contracts/ComposableStablePoolFactory.sol) (v3) | [0x7bc6C0E73EDAa66eF3F6E2f27b0EE8661834c6C9](https://polygonscan.com/address/0x7bc6C0E73EDAa66eF3F6E2f27b0EE8661834c6C9) | +| [LiquidityBootstrappingPoolFactory](https://github.com/balancer-labs/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/lbp/LiquidityBootstrappingPoolFactory.sol) | | ## BAL / veBAL / Liquidity Mining diff --git a/docs/reference/math/linear-math.md b/docs/reference/math/linear-math.md index bf6ef91d..9179fe69 100644 --- a/docs/reference/math/linear-math.md +++ b/docs/reference/math/linear-math.md @@ -1,71 +1,84 @@ +--- +order: 3 +--- + # Linear Math ## Overview Linear math is designed to facilitate swaps between assets and their yield bearing, wrapped counterparts. For example, DAI and aDAI from Aave. This pairing is done using the identity function, with consideration for the exchange rate between the main (unwrapped) and wrapped assets. Linear pools are the base layer for boosted pools. -## Implementations +## Implementations ### TypeScript Developers can use the TypeScript math implementations used by the Smart Order router -* [linearMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/linearPool/linearMath.ts) +- [linearMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/linearPool/linearMath.ts) -## Invariant +## Invariant -The invariant of the linear math function is trivial in nature, similar to the constant sum invariant. The main difference being the exchange rate, or rate provider, being utilized for the wrapped tokens. +The invariant of the linear math function is trivial in nature, similar to the constant sum invariant. The main difference being the exchange rate, or rate provider, being utilized for the wrapped tokens. -$$ I = \sum_{t}({B_{t}*R_{t}}) $$ +$$ I = \sum*{t}({B*{t}\*R\_{t}}) $$ -Where +Where -* $t$ ranges over the tokens in the pool -* $B_t$ is the nominal balance of the token in the pool -* $R_t$​ is the rate provider or exchange rate. For the main, unwrapped token R = 1 +- $t$ ranges over the tokens in the pool +- $B_t$ is the nominal balance of the token in the pool +- $R_t$​ is the rate provider or exchange rate. For the main, unwrapped token R = 1 ## Spot Price Spot price is independent of the balances, and will depend on the exchange rates between the underlying assets only. This is defined as: -$$ SP_{i}^{o} = {\frac{R_{i}}{R_{o}}} $$ -* $R_i$ is the rate provider of token $i$ going into the pool -* $R_o$ is the rate provider of token $o$ coming out of the pool +$$ SP*{i}^{o} = {\frac{R*{i}}{R\_{o}}} $$ + +- $R_i$ is the rate provider of token $i$ going into the pool +- $R_o$ is the rate provider of token $o$ coming out of the pool ## Trade Equations For linear pools, the unique factor of the trade equations is the swap fees. The fee structure incentivizes traders to maintain the unwrapped balance of the tokens in the pool to remain between an upper ($T_{2}$) and lower ($T_{1}$) boundary. The trade equations can best be described by the following piece wise functions. ### outGivenIn -$$ A_{o} = + +$$ +A_{o} = \begin{cases} A_{i} * \frac{R_{i}}{R_{o}} & T_{1}\leq x\leq T_{2} \\ \\ A_{i} * \frac{R_{i}}{R_{o}} * (1 - \phi) & x\leq T_{1} \ or \ T_{2}\leq x \ \ \ When \ trade \ pushes \ pool \ out \ of \ bounds \\ \\ A_{i} * \frac{R_{i}}{R_{o}} * (1 + \phi) & x\leq T_{1} \ or \ T_{2}\leq x \ \ \ When \ trade \ pushes \ pool \ towards \ bounds\\ \end{cases} $$ -Where: -* $A_{o}$ is the amount out. This represents the number of tokens a user will receive from a swap. -* $A_{i}$ is the amount in. This represents the number of tokens a user will sell to perform a swap. -* $R_{i}$ The rate provider value, or exchange rate of the token in. -* $R_{o}$ The rate provider value, or exchange rate of the token out. -* $\phi$ - Represents the swap fee of the pool. -* $T_{1}$ The lower target boundary of the unwrapped token balance -* $T_{2}$ The upper target boundary of the unwrapped token balance -* $x$ is the unwrapped token balance within the pool. + +Where: + +- $A_{o}$ is the amount out. This represents the number of tokens a user will receive from a swap. +- $A_{i}$ is the amount in. This represents the number of tokens a user will sell to perform a swap. +- $R_{i}$ The rate provider value, or exchange rate of the token in. +- $R_{o}$ The rate provider value, or exchange rate of the token out. +- $\phi$ - Represents the swap fee of the pool. +- $T_{1}$ The lower target boundary of the unwrapped token balance +- $T_{2}$ The upper target boundary of the unwrapped token balance +- $x$ is the unwrapped token balance within the pool. ### inGivenOut -$$ A_{i} = + +$$ +A_{i} = \begin{cases} A_{o} * \frac{R_{o}}{R_{i}} & T_{1}\leq x\leq T_{2} \\ \\ A_{o} * \frac{R_{o}}{R_{i}} * (1 - \phi) & x\leq T_{1} \ or \ T_{2}\leq x \ \ \ When \ trade \ pushes \ pool \ out \ of \ bounds \\ \\ A_{o} * \frac{R_{o}}{R_{i}} * (1 + \phi) & x\leq T_{1} \ or \ T_{2}\leq x \ \ \ When \ trade \ pushes \ pool \ towards \ bounds\\ \end{cases} $$ -Where: -* $A_{i}$ is the amount in. This represents the number of tokens a user will sell to perform a swap. -* $R_{i}$ The rate provider value, or exchange rate of the token in. -* $R_{o}$ The rate provider value, or exchange rate of the token out. -* $\phi$ - Represents the swap fee of the pool. -* $T_{1}$ The lower target boundary of the unwrapped token balance -* $T_{2}$ The upper target boundary of the unwrapped token balance -* $x$ is the unwrapped token balance within the pool. \ No newline at end of file + +Where: + +- $A_{i}$ is the amount in. This represents the number of tokens a user will sell to perform a swap. +- $R_{i}$ The rate provider value, or exchange rate of the token in. +- $R_{o}$ The rate provider value, or exchange rate of the token out. +- $\phi$ - Represents the swap fee of the pool. +- $T_{1}$ The lower target boundary of the unwrapped token balance +- $T_{2}$ The upper target boundary of the unwrapped token balance +- $x$ is the unwrapped token balance within the pool. diff --git a/docs/reference/math/stable-math.md b/docs/reference/math/stable-math.md index 87bd265b..ef2d9d9e 100644 --- a/docs/reference/math/stable-math.md +++ b/docs/reference/math/stable-math.md @@ -1,3 +1,7 @@ +--- +order: 2 +--- + # Stable Math ## Overview @@ -10,8 +14,8 @@ Stable Math is designed to allow for swaps between any assets that have the same Developers can use the TypeScript math implementations used by the Smart Order router -* [stableMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/stablePool/stableMath.ts) -* [metaStableMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/metaStablePool/metaStableMath.ts) +- [stableMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/stablePool/stableMath.ts) +- [metaStableMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/metaStablePool/metaStableMath.ts) ## Invariant @@ -23,9 +27,9 @@ $$ Where: -* $n$ is the number of tokens -* $x_i$ is is balance of token $i$ -* $A$ is the amplification parameter +- $n$ is the number of tokens +- $x_i$ is is balance of token $i$ +- $A$ is the amplification parameter ## Trade Equations @@ -43,13 +47,13 @@ $$ Where: -* $x'_i$ is the **ending** amount of each token -* $a_{out}$is the amount out -* $x_{out}$is the **starting** amount of the output token -* $y = x'_{out}$is the **ending** amount of the output token -* $D$ is the pool invariant -* $A$ is the amplification parameter -* $n$ is the number of tokens +- $x'_i$ is the **ending** amount of each token +- $a_{out}$is the amount out +- $x_{out}$is the **starting** amount of the output token +- $y = x'_{out}$is the **ending** amount of the output token +- $D$ is the pool invariant +- $A$ is the amplification parameter +- $n$ is the number of tokens ### inGivenOut @@ -63,10 +67,10 @@ $$ Where: -* $x'_i$ is the **ending** amount of each token -* $a_{in}$is the amount in -* $x_{in}$is the **starting** amount of the input token -* $y = x'_{in}$is the **ending** amount of the input token -* $D$ is the pool invariant -* $A$ is the amplification parameter -* $n$ is the number of tokens +- $x'_i$ is the **ending** amount of each token +- $a_{in}$is the amount in +- $x_{in}$is the **starting** amount of the input token +- $y = x'_{in}$is the **ending** amount of the input token +- $D$ is the pool invariant +- $A$ is the amplification parameter +- $n$ is the number of tokens diff --git a/docs/reference/math/weighted-math.md b/docs/reference/math/weighted-math.md index 37e46c7b..76bb3b8e 100644 --- a/docs/reference/math/weighted-math.md +++ b/docs/reference/math/weighted-math.md @@ -1,3 +1,7 @@ +--- +order: 1 +--- + # Weighted Math ## Overview @@ -14,13 +18,13 @@ For more formulas and derivations of the below formulas, please refer to the [Ba Developers can use the TypeScript math implementations used by the Smart Order router -* [weightedMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/weightedPool/weightedMath.ts) +- [weightedMath.ts](https://github.com/balancer-labs/balancer-sor/blob/john/v2-package-linear/src/pools/weightedPool/weightedMath.ts) ### Python There are also Python implementations in progress -* [weightedMath.py](https://github.com/officialnico/balancerv2cad/blob/main/src/balancerv2cad/WeightedMath.py) +- [weightedMath.py](https://github.com/officialnico/balancerv2cad/blob/main/src/balancerv2cad/WeightedMath.py) ## Invariant @@ -32,9 +36,9 @@ $$ Where -* $t$ ranges over the tokens in the pool -* $B_t$ is the balance of the token in the pool -* $W_t$​is the normalized weight of the tokens, such that the sum of all normalized weights is 1. +- $t$ ranges over the tokens in the pool +- $B_t$ is the balance of the token in the pool +- $W_t$​is the normalized weight of the tokens, such that the sum of all normalized weights is 1. ## Spot Price @@ -44,10 +48,10 @@ $$ SP^o_i = \frac{\frac{B_i}{W_i}}{\frac{B_o}{W_o}} $$ -* $B_i$ is the balance of token $i$, the token being sold by the trader which is going into the pool -* $B_o$ is the balance of token $o$, the token being bought by the trader which is going out of the pool -* $W_i$ is the weight of token $i$ -* $W_o$ is the weight of token $o$ +- $B_i$ is the balance of token $i$, the token being sold by the trader which is going into the pool +- $B_o$ is the balance of token $o$, the token being bought by the trader which is going out of the pool +- $W_i$ is the weight of token $i$ +- $W_o$ is the weight of token $o$ ### Spot Price with Swap Fees