docs: improve deployment instructions (#413)

Co-authored-by: Francisco de Borja Aranda Castillejo <[email protected]>
Co-authored-by: skosito <[email protected]>

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

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();
 

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();
 

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 
-```
+```
+
+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