From ec0a19711da7983c5c89a7d75c66b0caac1ac56b Mon Sep 17 00:00:00 2001
From: Lucas Bertrand <lucas.bertrand.22@gmail.com>
Date: Thu, 24 Oct 2024 16:17:25 +0200
Subject: [PATCH] docs: improve deployment instructions (#413)

Co-authored-by: Francisco de Borja Aranda Castillejo <borja@zetachain.com>
Co-authored-by: skosito <skostic9242@gmail.com>
---
 v2/README.md                                  |   8 +-
 .../deterministic/DeployERC20Custody.s.sol    |   4 +-
 .../deterministic/DeployGatewayEVM.s.sol      |   4 +-
 v2/scripts/deploy/deterministic/readme.md     |  36 ------
 v2/scripts/deploy/readme.md                   | 112 +++++++++++++++++-
 5 files changed, 118 insertions(+), 46 deletions(-)
 delete mode 100644 v2/scripts/deploy/deterministic/readme.md

diff --git a/v2/README.md b/v2/README.md
index 8b192b3e..706a7a69 100644
--- a/v2/README.md
+++ b/v2/README.md
@@ -41,12 +41,18 @@ $ forge snapshot
 $ anvil
 ```
 
-### Deploy using script
+### Deploy
 
 ```shell
 $ forge script script/<DeployScript>.s.sol:<DeployScript> --rpc-url <your_rpc_url> --private-key <your_private_key>
 ```
 
+##### More detailed instructions
+
+To view detailed instructions on how to deploy the contracts, please refer to the [Deployment Guide](./scripts/deploy/readme.md).
+
+This guide covers all steps required to deploy the contracts, including environment setup, commands, and best practices.
+
 ### Cast
 
 ```shell
diff --git a/v2/scripts/deploy/deterministic/DeployERC20Custody.s.sol b/v2/scripts/deploy/deterministic/DeployERC20Custody.s.sol
index f90cb404..43c8a135 100644
--- a/v2/scripts/deploy/deterministic/DeployERC20Custody.s.sol
+++ b/v2/scripts/deploy/deterministic/DeployERC20Custody.s.sol
@@ -14,8 +14,8 @@ contract DeployERC20Custody is Script {
         address expectedImplAddress;
         address expectedProxyAddress;
 
-        bytes32 implSalt = keccak256("ERC20Custody");
-        bytes32 proxySalt = keccak256("ERC20CustodyProxy");
+        bytes32 implSalt = keccak256("ERC20Custody-2");
+        bytes32 proxySalt = keccak256("ERC20CustodyProxy-2");
 
         vm.startBroadcast();
 
diff --git a/v2/scripts/deploy/deterministic/DeployGatewayEVM.s.sol b/v2/scripts/deploy/deterministic/DeployGatewayEVM.s.sol
index ea60091c..dc047dfa 100644
--- a/v2/scripts/deploy/deterministic/DeployGatewayEVM.s.sol
+++ b/v2/scripts/deploy/deterministic/DeployGatewayEVM.s.sol
@@ -15,8 +15,8 @@ contract DeployGatewayEVM is Script {
         address expectedImplAddress;
         address expectedProxyAddress;
 
-        bytes32 implSalt = keccak256("GatewayEVM");
-        bytes32 proxySalt = keccak256("GatewayEVMProxy");
+        bytes32 implSalt = keccak256("GatewayEVM-2");
+        bytes32 proxySalt = keccak256("GatewayEVMProxy-2");
 
         vm.startBroadcast();
 
diff --git a/v2/scripts/deploy/deterministic/readme.md b/v2/scripts/deploy/deterministic/readme.md
deleted file mode 100644
index 88f635d2..00000000
--- a/v2/scripts/deploy/deterministic/readme.md
+++ /dev/null
@@ -1,36 +0,0 @@
-## Deterministic deployments
-
-`DeployGatewayEVM` script uses create2 with Foundry (https://book.getfoundry.sh/tutorials/create2-tutorial) to perform deterministic deployment of `GatewayEVM` contracts.
-This ensures that on every EVM chain `GatewayEVM` contract will be on same address.
-
-Since UUPS proxy is used for `GatewayEVM` contract, both implementation and `ERC1967Proxy` are deployed using above technique:
-
-- calculate expected address
-- adding a salt to deployment
-- basic assertions to verify that deployed address is same as expected
-
-Remaining deployment script work in similar way as `GatewayEVM` but much simpler because there is no proxy.
-
-`UpgradeGatewayEVM` script uses OpenZeppelin's Foundry Upgrades plugin (https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades), to upgrade `GatewayEVM`:
-
-- deploy new implementation (doesn't need to be deterministic since proxy address doesn't change)
-- use plugin to upgrade proxy
-
-To execute deployment script, following format is needed:
-
-```
-forge script scripts/deploy/deterministic/<Script>.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast 
-```
-
-To automatically verify contracts deployed with above scripts, verifier options are needed. Example for `GatewayEVM` which will deploy and verify both implementation and proxy contracts (it is the same for other scripts):
-
-- etherscan
-```
-forge script scripts/deploy/deterministic/DeployGatewayEVM.s.sol --private-key <PRIVATE_KEY> --rpc-url <RPC_URL> --verify --etherscan-api-key <ETHERSCAN_API_KEY> --chain-id <CHAIN_ID> --broadcast 
-```
-
-- blockscout
-```
-
-forge script scripts/deploy/deterministic/DeployGatewayEVM.s.sol --private-key <PRIVATE_KEY> --rpc-url <RPC_URL> --verify --verifier blockscout --verifier-url <VERIFIER_URL> --chain-id <CHAIN_ID> --broadcast
-```
\ No newline at end of file
diff --git a/v2/scripts/deploy/readme.md b/v2/scripts/deploy/readme.md
index 3d1f58dd..b2bae376 100644
--- a/v2/scripts/deploy/readme.md
+++ b/v2/scripts/deploy/readme.md
@@ -1,10 +1,112 @@
-## Deployment scripts
+# Deployment
 
-Note: `.env` file should be set up and updated during deployments according to expected env variables in scripts, check `.env.sample` for example on how it should look like.
-Currently, `.env.sample` is set with test env variables that can be used to test scripts locally with `anvil` using first account private key.
+This directory contains script to deploy the protocol contracts on ZetaChain and connected chains.
 
-To execute deployment script, following format is needed:
+To execute a deployment script, the general format is:
 
 ```
 forge script scripts/deploy/<Script>.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast 
-```
\ No newline at end of file
+```
+
+A `.env` file should be set up and updated during deployments according to expected env variables in scripts, check `.env.sample` for example on how it should look like.
+Currently, `.env.sample` is set with test env variables that can be used to test scripts locally with `anvil` using first account private key.
+
+
+## Deploying the protocol contracts on connected chains
+
+The GatewayEVM and ERC20Custody contracts must be deployed to setup a new environment on a connected chain.
+
+**GatewayEVM**
+
+The following environment variables must be set in the `.env` file:
+
+- `TSS_ADDRESS`: address of the TSS used on the network
+- `GATEWAY_ADMIN_ADDRESS_EVM`: address of the admin
+- `ZETA_ERC20_EVM`: address of the ZETA token on the network
+
+Once setup, the contract can be deployed:
+
+```
+forge script scripts/deploy/deterministic/DeployGatewayEVM.s.sol \
+  --private-key <PRIVATE_KEY> \
+  --rpc-url <RPC_URL> \
+  --verify \
+  --etherscan-api-key <ETHERSCAN_API_KEY> \
+  --chain-id <CHAIN_ID> \
+  --broadcast
+```
+
+Note: `verify` and `etherscan-api-key` options are optional for the contract deployment itself. Some other explorers require different options, for example Blockscout:
+```
+  --verify \
+  --verifier blockscout \
+  --verifier-url <VERIFIER_URL> \
+```
+
+**ERC20Custody**
+
+In addition to the previous environment variables, the following environment variables must be set:
+
+- `ERC20_CUSTODY_ADMIN_ADDRESS_EVM`: address of the admin
+- `GATEWAY_PROXY_EVM`: address of the **proxy** gateway contract deployed in previous step
+
+Once setup, the contract can be deployed:
+
+```
+forge script scripts/deploy/deterministic/DeployERC20Custody.s.sol \
+  --private-key <PRIVATE_KEY> \
+  --rpc-url <RPC_URL> \
+  --verify \
+  --etherscan-api-key <ETHERSCAN_API_KEY> \
+  --chain-id <CHAIN_ID> \
+  --broadcast
+```
+
+## Deploying the protocol contracts on ZetaChain
+
+Since ZRC20s are deployed by the protocol, only the `GatewayZEVM` contract needs to be deployed manually on ZetaChain.
+
+The following environment variables must be set in the `.env` file:
+
+- `GATEWAY_ADMIN_ADDRESS_ZEVM`: address of the admin 
+- `WZETA`: wrapped ZETA contract address
+
+Once setup, the contract can be deployed:
+
+```
+forge script scripts/deploy/deterministic/DeployGatewayZEVM.s.sol \
+  --private-key <PRIVATE_KEY> \
+  --rpc-url <RPC_URL> \
+  --verify \
+  --verifier blockscout \
+  --verifier-url <VERIFIER_URL> \
+  --chain-id <CHAIN_ID> \
+  --broadcast
+```
+
+## Deterministic deployments
+
+Deployment scripts in `deterministic` uses create2 with Foundry (https://book.getfoundry.sh/tutorials/create2-tutorial) to perform deterministic deployment of contracts.
+This ensures that the GatewayEVM contract will have the same address on every EVM chain.
+
+Since UUPS proxy is used for the contracts, both implementation and `ERC1967Proxy` are deployed using above technique:
+
+- calculate expected address
+- adding a salt to deployment
+- basic assertions to verify that deployed address is same as expected
+
+The contract can be upgraded with the following documentation: https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades. It requires:
+
+- deploy new implementation (doesn't need to be deterministic since proxy address doesn't change)
+- use plugin to upgrade proxy
+
+
+## All deployment scripts
+
+- `deterministic/DeployERC20Custody.s.sol`: deploy the ERC20 custody contract on a connected chain
+- `deterministic/DeployGatewayEVM.s.sol`: deploy the gateway contract on a connected chain
+- `deterministic/DeployGatewayZEVM.s.sol`: deploy the gateway contract on ZetaChain
+- `deterministic/TestERC20.s.sol`: deploy a ERC20 for test purpose
+- `deterministic/ZetaConnectorNonNative.s.sol`: deploy the ZETA connector contract on a connected chain, currently not used
+- `deterministic/UpgradeGatewayEVM.s.sol`: upgrade the GatewayEVM contract to a test contract implementation, used for test purposes only
+- `DeployZRC20.s.sol`: deploy a ZRC20 for test purpose
\ No newline at end of file