From 2858d56f473d582b2d3b30af5ade5ee9156fb903 Mon Sep 17 00:00:00 2001 From: Jayant Krishnamurthy Date: Wed, 27 Sep 2023 06:08:00 -0700 Subject: [PATCH] Update docs these instructions are old --- target_chains/ethereum/contracts/Deploying.md | 192 ------------------ 1 file changed, 192 deletions(-) delete mode 100644 target_chains/ethereum/contracts/Deploying.md diff --git a/target_chains/ethereum/contracts/Deploying.md b/target_chains/ethereum/contracts/Deploying.md deleted file mode 100644 index 27362aca..00000000 --- a/target_chains/ethereum/contracts/Deploying.md +++ /dev/null @@ -1,192 +0,0 @@ -# Deploying Contracts to Production - -## EVM network configuration - -Each network that Pyth is deployed on has some configuration stored on this repo in the contract manager package as described below: - -1. Chain configuration in [EvmChains.yaml](../../../contract_manager/store/chains/EvmChains.yaml) contains: - - `id`: id of the chain. This will be used for identifying which chain we want to deploy to. - - `wormholeChainName`: Chain name in Wormhole. It is either defined in the - [Wormhole SDK constants](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/sdk/js/src/utils/consts.ts) - or is defined in [Wormhole Receiver names](../../../governance/xc_admin/packages/xc_admin_common/src/chains.ts). If the new - network requires a Receiver contract you need to update the latter file and add the network there. - - `mainnet`: A boolean which indicates whether the network is `mainnet` or `testnet`/`devnet`. - - `rpcUrl`: RPC endpoint of the network. - - `networkId`: id of the network. Used in RPC calls. -2. Contract configuration in [EvmContracts.yaml](../../../contract_manager/store/contracts/EvmContracts.yaml) contains: - - `address`: The address the pyth contract is deployed on (this will refer to the proxy contract). - - `chain`: Name of the chain (`id` field in chain configuration) the contract is deployed on. - -If you wish to deploy to a new network you need to add the chain configurations as described above. You can find `networkId` and public -RPCs of most of the networks in [ChainList](https://chainlist.org/). Rest of the parameters are optional and avoid -adding them unless it is necessary. Wormhole's -[truffle-config.js](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/truffle-config.js) -is a good reference too. - -## Deployment - -This is the deployment process: - -1. Follow the installation instructions in the [README.md](./README.md). -2. As a sanity check on deploying changes for the first time, it is recommended to deploy the migrations - in `migrations/prod-receiver` to the Truffle `development` network first. You can do this by using the configuration - values in [`.env.prod.development`](.env.prod.development). -3. If you have changed the contract make sure that: - - The change is not breaking the storage. - - If it is making a backward incompatible change, the legacy methods/storages are still used. For example, - if the PriceInfos are now stored in a separate storage slot, the old PriceInfo should be accessible when - the new one is not populated. - - the contract version is updated both in [`Pyth.sol`](./contracts/pyth/Pyth.sol) and [`package.json`](./package.json). - Make sure to read the [Upgrading the contract](#upgrading-the-contract) and [Versioning](#versioning) - sections below. -4. Prepare the required keys for deployment. You can find more information about them on notion. Then: - - Export the secret recovery phrase for the deployment account. Please store it in a file and read - the file into `MNEMONIC` environment variable like so: `export MNEMONIC=$(cat path/to/mnemonic)`. -5. Make sure the deployment account has proper balance on this network and top it up if needed. Search - for testnet faucets if it is a testnet network. Sometimes you need to bridge the network token (e.g., L2s). -6. Add the required chain configuration in the contract manager file [EvmChains.yaml](../../../contract_manager/store/chains/EvmChains.yaml) -7. Deploy the new contract or changes using the [`deploy.sh`](./deploy.sh) script. - You might need to repeat this script because of busy RPCs. Repeating would not cause any problem even - if the changes are already made. Also, sometimes the gases are not adjusted and it will cause the tx to - remain on the mempool for a long time (so there is no progress until timeout). Please update them with - the network explorer gas tracker. Tips in the [Troubleshooting](#troubleshooting) section below can help - in case of any error. Run the script like this: `./deploy.sh <...>`. For example - to deploy changes to testnet networks you can run: - ```bash - ./deploy.sh bnb_testnet fantom_testnet mumbai - ``` -8. On first time deployments for a **mainnet** network with Wormhole Receiver contract, run this command: - ```bash - npm run receiver-submit-guardian-sets -- --network - ``` -9. As a result of this process for some files (with the network id in their name) in `networks` and directory might change - which need to be committed (if they are result of a production deployment). Create a PR for them. -10. If you are deploying to a new network, please add the new contract address to consumer facing libraries - and documentations. The deployment script should automatically add the contract to the contract manager store. Please update the following resources: - - [Pyth Gitbook EVM Page](https://github.com/pyth-network/documentation/blob/main/pages/documentation/pythnet-price-feeds/evm.mdx) - - [pyth-evm-js package](../sdk/js/) -11. (Optional) You can test the deployed contract by sending and fetching a price update as described in the - [Testing](#testing) section below. -12. (Optional) Verify the contract as described in the [Verifying the contract](#verifying-the-contract) section. - -### `networks` directory - -Truffle stores the address of the deployed contracts in the build artifacts, which can make local development difficult. We use [`truffle-deploy-registry`](https://github.com/MedXProtocol/truffle-deploy-registry) to store the addresses separately from the artifacts, in the [`networks`](networks) directory. When we need to perform operations on the deployed contracts, such as performing additional migrations, we can run `npx apply-registry` to populate the artifacts with the correct addresses. - -Each file in the network directory is named after the network id and contains address of Migration contract and PythUpgradable contract -(and Wormhole Receiver if we use `prod-receiver`). If you are upgrading the contract it should not change. In case you are deploying to a new network make sure to commit this file. - -### Upgrading the contract - -To upgrade the contract you should bump the version of the contract and the npm package to the new version and run the deployment -process described above. Please bump the version properly as described in [the section below](#versioning). - -**When you are making changes to the storage, please make sure that your change to the contract won't cause any collision**. For example: - -- Renaming a variable is fine. -- Changing a variable type to another type with the same size is ok. -- Appending to the contract variables is ok. If the last variable is a struct, it is also fine - to append to that struct. -- Appending to a mapping value is ok as the contract stores mapping values in a random (hashed) location. - -Anything other than the operations above will probably cause a collision. Please refer to Open Zeppelin Upgradeable -(documentations)[https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable] for more information. - -### Upgrading the Wormhole guardian set in the Wormhole receiver contracts - -If the Wormhole guardian set is going to change, you need to update the guardian set in the Wormhole receiver -contracts. You should do it before the guardians start publishing VAAs with the new guardian set and not earlier than 24 hours before that -to avoid any possible downtime. After updating the guardian set there is a 24 hour windows that the contracts -will accept VAAs from both the old and the new index. So, you will need to do it when you are certain that Guardians -will start publishing with the new set soon. - -To update the guardian set update the -[`receiverSubmitGuardianSetUpgrades.js`](./scripts/receiverSubmitGuardianSetUpgrades.js) script and add the new VAA and comment out the previous upgrades. -Then, run it like below on the networks with Wormhole receiver contract: - -``` -npm run receiver-submit-guardian-sets -- --network -``` - -You should create a PR to add this VAA to the repo for future deployments on new networks with Wormhole receiver contract. - -### Versioning - -We use [Semantic Versioning](https://semver.org/) for our releases. When upgrading the contract, update the npm package version using -`npm version --no-git-tag-version`. Also, modify the hard-coded value in `version()` method in -[the `Pyth.sol` contract](./contracts/pyth/Pyth.sol) to the new version. Then, after your PR is merged in main, create a release like with tag `pyth-evm-contract-v`. This will help developers to be able to track code changes easier. - -# Testing - -The [pyth-js][] repository contains an example with documentation and a code sample showing how to relay your own prices to a -target Pyth network. Once you have relayed a price, you can verify the price feed has been updated by doing: - -``` -$ npx truffle console --network $MIGRATIONS_NETWORK -> let p = await PythUpgradable.deployed() -> p.queryPriceFeed("0xf9c0172ba10dfa4d19088d94f5bf61d3b54d5bd7483a322a982e1373ee8ea31b") // BTC Testnet or any other address -``` - -[pyth-js]: https://github.com/pyth-network/pyth-js/tree/main/pyth-evm-js#evmrelay - -# Contract verification - -## Creating verification assets for a new release - -We include artifacts required for verifying the contract in each release. To create these artifacts, run the following commands: - -``` -npx sol-merger contracts/pyth/PythUpgradable.sol -npx sol-merger contracts/pyth/ReceiverImplementation.sol -npx truffle run stdjsonin PythUpgradable -npx truffle run stdjsonin ReceiverImplementation -``` - -These commands create the files `contracts/pyth/PythUpgradable_merged.sol`, `contracts/pyth/ReceiverImplementation_merged.sol`, `PythUpgradable-input.json`, and `ReceiverImplementation-input.json` respectively. -The `.sol` files are the flattened version of the contracts, and the `.json` files are the standard json input of the contracts. - -Please include all of these in the release. - -## Verifying the contract - -Read [VERIFY.md](./VERIFY.md) for how to use these files to verify the contract. - -# Troubleshooting - -- If you get `digital envelope routines::unsupported` error, it means you are using a new Node version and it does not work because - the truffle dependency is old. As a workaround, you can use the legacy openssl implementation by running this command: - `export NODE_OPTIONS=--openssl-legacy-provider`. -- Sometimes the truffle might fail during the dry-run (e.g., in Ethereum). It is because openzeppelin does not have the required metadata for forking. To fix it please - follow the suggestion [here](https://github.com/OpenZeppelin/openzeppelin-upgrades/issues/241#issuecomment-1192657444). -- Sometimes due to rpc problems or insufficient gas the migration is not executed completely. It is better to avoid doing multiple transactions in one - migration. However, if it happens, you can comment out the part that is already ran (you can double check in the explorer), and re-run the migration. - You can avoid gas problems by choosing a much higher gas than what is showed on the network gas tracker. Also, you can find other rpc nodes from - [here](https://chainlist.org/) - -# Deploy/Upgrade on zkSync networks - -Although zkSync is EVM compatible, their binary format is different than solc output. So, we need to use their libraries to -compile it to their binary format (zk-solc) and deploy it. As of this writing they only support hardhat. To deploy a fresh -contract or a new contract do the following steps in addition to the steps described above: - -1. Update the [`hardhad.config.ts`](./hardhat.config.ts) file. -2. Add the required chain configuration in the contract manager files as described above. -3. Run `npx hardhat clean && npx hardhat compile` to have a clean compile the contracts. -4. Prepare the enviornment: - -- Export the secret recovery phrase for the deployment account. Please store it in a file and read - the file into `MNEMONIC` environment variable like so: `export MNEMONIC=$(cat path/to/mnemonic)`. -- Create the env settings by running `node create-env.js zksync` and verifying the `.env` file. - -5. If you wish to deploy the contract run `npx hardhat deploy-zksync --network --script deploy/zkSyncDeploy` to deploy it to the new network. Otherwise - run `npx hardhat deploy-zksync --network --script deploy/zkSyncDeployNewPythImpl.ts` to get a new implementation address. Then put it in - `..new_impl` file and run the deployment script to handle the rest of the changes. - -# Deploy/Upgrade on Canto - -Canto network rewards some percentage of the gas usage to the contracts. To enable the rewards we have modified the contract upon -deployment to register its own address as the receiver of the rewards and also assigned Pyth to received Wormhole Receiver rewards -too. The registration only happens once for contract. The contracts are registered with token id 654. We don't need to register -the contracts upon upgrades because the proxy address doesn't change. The contract changes for registration are stored in -[this diff](./canto-deployment-patch.diff) for future reference. Please note that if we switch to another Wormhole Receiver -(a new address) we will need to register the new contract.