From e313b8b9e6656eb875f9b32638da7094d2a17042 Mon Sep 17 00:00:00 2001 From: Alberto Date: Wed, 6 Mar 2024 10:43:33 +0100 Subject: [PATCH 1/6] docs: adding version history Co-Authored-By: fiddyresearch <11488427+bout3fiddy@users.noreply.github.com> --- README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/README.md b/README.md index 7d8e48d..8e7b4b8 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,57 @@ The Factory AMMs have a hardcoded `ADMIN_FEE`, set to 50% of the earned profits. In case of any issues that result in a borked AMM state, users can safely withdraw liquidity using `remove_liquidity` at balances proportional to the AMM balances. +# TriCrypto versions overview + + +The different implementations of Curve's CryptoSwap invariant AMM are noted in the following: + +0. The genesis cryptoswap invariant amm contracts: +a. [tricrypto2 (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/tricrypto/CurveCryptoSwap.vy) +b. [twocrypto (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/two/CurveCryptoSwap2ETH.vy) +1. [TricryptoNGWETH (1st gen)](https://github.com/curvefi/tricrypto-ng/blob/main/contracts/main/CurveTricryptoOptimizedWETH.vy) +2. [TwocryptoNG (second gen)](https://github.com/curvefi/twocrypto-ng/blob/main/contracts/main/CurveTwocryptoOptimized.vy) +3. [TricryptoNG (second gen)](https://github.com/curvefi/tricrypto-ng/blob/main/contracts/main/CurveTricryptoOptimized.vy) + +### From genesis to NG 1st gen + + +There are significant improvements from the genesis cryptoswap invariant AMM contract to the 1st gen (NG, or next gen). Gas costs are reduced by half between the genesis and the first gen implementations. This was a labor of love, requiring development work in the compiler, dev tools (titanoboa was basically built to build tricryptong), coordination with etherscan, coordination with math researchers to optimise math in tricrypto, come up with better cube roots, auditors coming up with their own optimisations etc. The optimisations are listed in the following: + +1. Replace [Bubble sort](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L20) with [dumb sorting](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L845) +2. [Bespoke cube root algorithm that costs 2000 gas on average](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L789). Implemented in [Snekmate](https://github.com/pcaversaccio/snekmate/blob/9f7eec740fcaf8e5d4397fc1cc79d507ff11d613/src/snekmate/utils/Math.vy#L490) as well. +3. Replace [expensive geometric mean](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L42) with [simple geometric mean](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L868) +4. Use unsafe math operations wherever it is safe to do so. [Old implementation](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L96) -> [new implementation with explanation for why we can do unsafe maths](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L431) +5. Replace [newton_y](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L172) for [mathematically verified analytical solution with fallback to newton method for edge cases](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L35). +6. [Bespoke and very cheap calculation of partial derivatives of x w.r.t y, which allows the calculation of state prices](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L539). This was a contribution from Taynan Richards of ChainSecurity, which [replaced the old and initially proposed version](https://github.com/curvefi/tricrypto-ng/commit/b3350d4b7e92d4e12720584b2d1aeb1d74b5a99f). + +The implementation of state prices allowed the creation of very good oracles that power today's curve stablecoin. State prices, as opposed to last traded prices which every other AMM or oracle uses, reduce the impact of price manipulation significantly. + +[TricryptoNGWETH](contracts/main/CurveTricddryptoOptimizedWETH.vy) is the first optimised implementation of the old 3-coin cryptoswap AMM which allowed native token transfers. + +### From NG 1st gen to NG 2nd gen + +Cryptoswap (like everything Curve has) is an ongoing process of improvement. It's immediate upgrade (almost a year or so after it's launch) removes some of the features and adds new ones. The features added in the second iteration of NG are simply features that come out of a natural progression of improving contracts after user feedback, experiences with speaking to auditors etc. There are no known vulnerabilities in the first NG implementation that prompted the second iteration of cryptoswap NG contracts. + +Some of the features removed from the first gen (in the second gen) are (not exhaustive list): + +1. [Native token transfers](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L394) +2. [Gulping of tokens (i.e. when the `self.balances` can be updated with a read of `coin.balanceOf(self)`).](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L1193) +3. [exchange_extended, which is exchanging after calling an external callback first).](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L477) +4. [Admin fees collected in LP tokens.](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L1223) +5. [exposed claim_admin_fees](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L786) +6. [commit-apply scheme for parameters](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L2033). New version simply applies parameters [which is quicker to do](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1994) (in one tx after governance approves). + +The second gen adds several new features including: + +1. [An xcp oracle to measure the amount of liquidity in the pool](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1705) +2. [fees are collected in individual tokens and not lp tokens.](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1216) +3. [Claiming individual tokens means LP token supply does not go up](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1173) +4. stricter conditions to claiming fees +a. [claim sparingly](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1116) +b. [do not claim in vprice goes below 1e18](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1182) +5. [exchange_received](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L409): swap tokens donated to the pool.The advantage of the new implementation is that, if tokens in the pool are rebasing, there is no `self.balances[i] = coins[i].balanceOf(self)` in the `self._claim_admin_fees()` method [like the old contract does](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L1197) + # For developers ### To run tests: From a3de69687b631825741022793d4cb5f8dedc8089 Mon Sep 17 00:00:00 2001 From: Alberto Date: Wed, 6 Mar 2024 10:56:15 +0100 Subject: [PATCH 2/6] docs: formatting --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8e7b4b8..48dd257 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,10 @@ In case of any issues that result in a borked AMM state, users can safely withdr The different implementations of Curve's CryptoSwap invariant AMM are noted in the following: 0. The genesis cryptoswap invariant amm contracts: -a. [tricrypto2 (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/tricrypto/CurveCryptoSwap.vy) -b. [twocrypto (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/two/CurveCryptoSwap2ETH.vy) + + a. [tricrypto2 (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/tricrypto/CurveCryptoSwap.vy) + + b. [twocrypto (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/two/CurveCryptoSwap2ETH.vy) 1. [TricryptoNGWETH (1st gen)](https://github.com/curvefi/tricrypto-ng/blob/main/contracts/main/CurveTricryptoOptimizedWETH.vy) 2. [TwocryptoNG (second gen)](https://github.com/curvefi/twocrypto-ng/blob/main/contracts/main/CurveTwocryptoOptimized.vy) 3. [TricryptoNG (second gen)](https://github.com/curvefi/tricrypto-ng/blob/main/contracts/main/CurveTricryptoOptimized.vy) @@ -69,8 +71,10 @@ The second gen adds several new features including: 2. [fees are collected in individual tokens and not lp tokens.](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1216) 3. [Claiming individual tokens means LP token supply does not go up](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1173) 4. stricter conditions to claiming fees -a. [claim sparingly](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1116) -b. [do not claim in vprice goes below 1e18](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1182) + + a. [claim sparingly](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1116) + + b. [do not claim in vprice goes below 1e18](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L1182) 5. [exchange_received](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimized.vy#L409): swap tokens donated to the pool.The advantage of the new implementation is that, if tokens in the pool are rebasing, there is no `self.balances[i] = coins[i].balanceOf(self)` in the `self._claim_admin_fees()` method [like the old contract does](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveTricryptoOptimizedWETH.vy#L1197) # For developers From d8d5c14d78fe789db9fcc112b43946d20b1039ff Mon Sep 17 00:00:00 2001 From: Alberto Date: Wed, 6 Mar 2024 11:38:25 +0100 Subject: [PATCH 3/6] docs: added blueprints to versions --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 48dd257..0efb4f3 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ There are significant improvements from the genesis cryptoswap invariant AMM con 4. Use unsafe math operations wherever it is safe to do so. [Old implementation](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L96) -> [new implementation with explanation for why we can do unsafe maths](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L431) 5. Replace [newton_y](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L172) for [mathematically verified analytical solution with fallback to newton method for edge cases](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L35). 6. [Bespoke and very cheap calculation of partial derivatives of x w.r.t y, which allows the calculation of state prices](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L539). This was a contribution from Taynan Richards of ChainSecurity, which [replaced the old and initially proposed version](https://github.com/curvefi/tricrypto-ng/commit/b3350d4b7e92d4e12720584b2d1aeb1d74b5a99f). +7. Introduce [Blueprint contracts](https://eips.ethereum.org/EIPS/eip-5202). This allowed factory deployed contracts to have immutables, since blueprint contracts are not like minimal proxies where immutables are not possible whatsoever. The implementation of state prices allowed the creation of very good oracles that power today's curve stablecoin. State prices, as opposed to last traded prices which every other AMM or oracle uses, reduce the impact of price manipulation significantly. From 5d349acdfb0000929cf31a86c81435d7b47996f0 Mon Sep 17 00:00:00 2001 From: Alberto Date: Wed, 6 Mar 2024 11:39:48 +0100 Subject: [PATCH 4/6] docs: syntax highlighting for snippet --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0efb4f3..4954b8a 100644 --- a/README.md +++ b/README.md @@ -82,8 +82,8 @@ The second gen adds several new features including: ### To run tests: -``` -> python -m pytest +```bash +python -m pytest ``` ### To contribute From a5d9f9d9967e60cab923f3c8f2753e26dd6f22f6 Mon Sep 17 00:00:00 2001 From: Alberto Date: Wed, 6 Mar 2024 13:11:45 +0100 Subject: [PATCH 5/6] docs: removing twocrypto versions --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index 4954b8a..aa9e57e 100644 --- a/README.md +++ b/README.md @@ -27,13 +27,8 @@ In case of any issues that result in a borked AMM state, users can safely withdr The different implementations of Curve's CryptoSwap invariant AMM are noted in the following: -0. The genesis cryptoswap invariant amm contracts: - - a. [tricrypto2 (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/tricrypto/CurveCryptoSwap.vy) - - b. [twocrypto (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/two/CurveCryptoSwap2ETH.vy) +0. [Tricrypto2 (genesis)](https://github.com/curvefi/curve-crypto-contract/blob/master/contracts/tricrypto/CurveCryptoSwap.vy) 1. [TricryptoNGWETH (1st gen)](https://github.com/curvefi/tricrypto-ng/blob/main/contracts/main/CurveTricryptoOptimizedWETH.vy) -2. [TwocryptoNG (second gen)](https://github.com/curvefi/twocrypto-ng/blob/main/contracts/main/CurveTwocryptoOptimized.vy) 3. [TricryptoNG (second gen)](https://github.com/curvefi/tricrypto-ng/blob/main/contracts/main/CurveTricryptoOptimized.vy) ### From genesis to NG 1st gen From 79ccd2f85a4c875a2ee4dfb8036bb50b207ab75f Mon Sep 17 00:00:00 2001 From: Alberto Date: Fri, 8 Mar 2024 21:23:38 +0100 Subject: [PATCH 6/6] chore: fixing ci --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index aa9e57e..5fcb222 100644 --- a/README.md +++ b/README.md @@ -42,14 +42,14 @@ There are significant improvements from the genesis cryptoswap invariant AMM con 4. Use unsafe math operations wherever it is safe to do so. [Old implementation](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L96) -> [new implementation with explanation for why we can do unsafe maths](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L431) 5. Replace [newton_y](https://github.com/curvefi/curve-crypto-contract/blob/d7d04cd9ae038970e40be850df99de8c1ff7241b/contracts/tricrypto/CurveCryptoMath3.vy#L172) for [mathematically verified analytical solution with fallback to newton method for edge cases](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L35). 6. [Bespoke and very cheap calculation of partial derivatives of x w.r.t y, which allows the calculation of state prices](https://github.com/curvefi/tricrypto-ng/blob/33707fc8b84e08786acf184fcfdb744eb4657a99/contracts/main/CurveCryptoMathOptimized3.vy#L539). This was a contribution from Taynan Richards of ChainSecurity, which [replaced the old and initially proposed version](https://github.com/curvefi/tricrypto-ng/commit/b3350d4b7e92d4e12720584b2d1aeb1d74b5a99f). -7. Introduce [Blueprint contracts](https://eips.ethereum.org/EIPS/eip-5202). This allowed factory deployed contracts to have immutables, since blueprint contracts are not like minimal proxies where immutables are not possible whatsoever. +7. Introduce [Blueprint contracts](https://eips.ethereum.org/EIPS/eip-5202). This allowed factory deployed contracts to have immutables, since blueprint contracts are not like minimal proxies where immutables are not possible whatsoever. The implementation of state prices allowed the creation of very good oracles that power today's curve stablecoin. State prices, as opposed to last traded prices which every other AMM or oracle uses, reduce the impact of price manipulation significantly. -[TricryptoNGWETH](contracts/main/CurveTricddryptoOptimizedWETH.vy) is the first optimised implementation of the old 3-coin cryptoswap AMM which allowed native token transfers. +[TricryptoNGWETH](contracts/main/CurveTricddryptoOptimizedWETH.vy) is the first optimised implementation of the old 3-coin cryptoswap AMM which allowed native token transfers. ### From NG 1st gen to NG 2nd gen - + Cryptoswap (like everything Curve has) is an ongoing process of improvement. It's immediate upgrade (almost a year or so after it's launch) removes some of the features and adds new ones. The features added in the second iteration of NG are simply features that come out of a natural progression of improving contracts after user feedback, experiences with speaking to auditors etc. There are no known vulnerabilities in the first NG implementation that prompted the second iteration of cryptoswap NG contracts. Some of the features removed from the first gen (in the second gen) are (not exhaustive list):