diff --git a/README.md b/README.md
index 7d8e48d..5fcb222 100644
--- a/README.md
+++ b/README.md
@@ -22,12 +22,63 @@ 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. [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)
+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).
+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.
+
+### 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:
 
-```
-> python -m pytest
+```bash
+python -m pytest
 ```
 
 ### To contribute