What we learned on our journey: How to safely fork Liquity V2

The Nerite Protocol is a "friendly fork" of Liquity. Liquity V1 was rated as the safest stablecoin protocol ever by Bluechip (a stablecoin rating agency), so it makes an incredible base to add to and build a unique protocol with.

Through the process of building Nerite, participating in Liquity V2's public security audit contest, and working with other forks, our team has learned a lot about the protocol and how to fork it safely. The following is a list of helpful tips and tricks for anyone else who wants to fork Liquity V2 safely and is intended for more technical users and builders.

Steps Overview

1. Get the license from the Liquity team.
2. Decide on collaterals and pick the best oracles.
3. Write new oracle relayers.
4. Make other security updates specific to that collateral, chain, and other features you want. 
5. Write a new deployment script.
6. Test
7. Audit
8. Verify
9. Ship

Read the full readme on the Bold repo, and also write your own guide to how it works (like this one https://hackmd.io/XsKiM79ESk-SxUsnDjkDPA) for your own reference. You should know immediately which contracts are deployed once and which are deployed for each collateral branch, and what all of the core contracts do in the system.

Security tips and tricks:

1. If you are adding any new collateral types that increase the risk beyound accepting just ETH, wstETH, and rETH, then you need to add debt limits. Use the collateral branches to add a debt limits for each collateral type conservatively. Set high ones for ETH and much much lower for riskier assets.

2. Because of how the list of troves works for redemptions and gas constraints, you can only have up to 10 total collateral types without making massive changes. Do NOT add more than 10 collaterals unless you are prepared.

3. If the average deviation threshold of between oracle price and market price of an asset is expected to go above 50 BPs then you should raise the Base Redemption Fee above 50 BPs to prevent leaking value. This will effect the price that it is profitable to redeem at, so take that into account. If you raise this, the lower bound on peg will be lowered by that much. For example, if base redemption fee is 55BPs, peg floor will be $0.9945 instead of Liquity's $0.995. It may be optimal to have a different redemption fee per branch, but this is not supported in Liquity as is – check out the Ebisu fork.

4. If you are changing collateral types from the ones Liquity uses, double check your collateral tokens do NOT revert when a transfer of 0 tokens is made. Otherwise, this could break liquidations for when remaining col in a trove is 0. If you do have any tokens which revert on 0 transfer, the fix is easy. Add this to troveManager:

5. You NEED to read all of the "known issues" disclosed in the Liquity docs. Understand how they will effect your particular fork.

6. The repo comes with many test for your contracts, and uses the `deal()` cheatcode from forge. If you change the storage layout for BoldToken or make it a proxy, you may break these. Easily fix by replace `deal` with mints by pretending to be borrowerO 

7. If you are deploying on an L2 you should significantly lower the gas compensation fee for when users open a trove. If sending a transaction to liquidate a trove costs $0.10 then asking for a fee of $115 to cover this is not good. But be careful!! If you lower it too much to the cost of normal transactions that might not be enough to cover gas during highest demand periods, for example when ETH price is crashing and everyone is freaking out.

For example, a transaction on Arbitrum might cost less than $0.001 normally. But during peak demand in the middle of a crash that might increase to $25. If your gas compensation amount is set to only $0.01, that will not be enough to process liquidations when they are most important.

8. Study throttled launch redemptions: https://x.com/LiquityProtocol/status/1879852191495946475

9. Be careful with oracles. Be Careful With Oracles. **BE CAREFUL WITH ORACLES.** The stEthPerToken function which the liquity mainnet relayer uses is not available in L2 bridged versions of wsteth, so you will need to use an oracle to get this. You will probably need to re-write every oracle relayer. Double check all oracle params, functions, uptime, price deviations. 

10. Understand that the most likely way your protocol gets nuked is you accept a bad collateral or a token you accept does something crazy. Double check the implementations of all your collateral tokens and disclose centralization risks.

We hope these tips are helpful. If you ever want to ask us about what it's like to work with the Liquity team, how we like being a friendly fork, or anything related to Nerite, please join our discord.