Each network that Pyth is deployed on has some configuration stored on this repo as described below:
truffle-config.js contains list of different networks with their configuration that includes:
provider: The network provider is an HDWalletProvider with mnemonic stored in the $MNEMONIC
environment variable and the RPC URL of the network.network_id: Network ID of the chain.gas, gasPrice (optional): Usually RPCs estimate gas and gas price efficiently. Although some networks are not
good at it and you need to specify them manually.timeoutBlocks (optional): Number of blocks to wait for a transaction to make it to a block. If you specify a low
gas price the transaction will be sent but it will never get in a block. Sometimes the network gas price is volatile
(like Ethereum) and you need to wait longer than the default timeout.networkCheckTimeout (optional): RPC timeout for requests. Some RPCs might be very slow and you need to have this.confirmations (optional): Number of blocks to wait to consider the transaction final.from (optional): Public address of the mnemonic. Although it can be derived from provider some networks that
are not entirely EVM based need it..env.prod.<network> contains the contract specific configuration for each network. It contains:
MIGRATIONS_DIR: This is either ./migrations/prod or
./migrations/prod-receiver. The prod-receiver migrations should be used when you
need to deploy to a chain that is unsupported by the Wormhole network. The Wormhole Receiver contract acts as a
read-only Wormhole endpoint that can verify Wormhole messages even if the Wormhole network has not yet connected
the chain.MIGRATIONS_NETWORK: Network name in the truffle-config.js file.WORMHOLE_CHAIN_NAME: Chain name in Wormhole. It is either defined in the
Wormhole SDK constants
or is defined in Wormhole Receiver names. If the new
network requires a Receiver contract you need to update the latter file and add the network there.CLUSTER: Cluster of this network. It is either testnet or mainnet. There are some cluster specific
configuration that are loaded from .env.cluster.testnet or
.env.cluster.mainnet such as data and governance sources. It is also used to get
the wormhole contract address. You can override those variable in the network environment file.VALID_TIME_PERIOD_SECONDS: The period that we consider a price to be still valid since its publishTime
on Pythnet. For the time being, set this value to at least 60 seconds. If the network block time or transaction
landing time is high please increase this value accordingly. For example, Ethereum has the value of 120 seconds.
It is good to keep this value the same in testnet and mainnet clusters of the same network.
Please look at similar networks when you want to add a new network.If you wish to deploy to a new network you need to add the above confiugrations. You can find network_id and public
RPCs of most of the networks in ChainList. Rest of the parameters are optional and avoid
adding them unless it is necessary. Wormhole's
truffle-config.js
is a good reference too.
This is the deployment process:
migrations/prod to the Truffle development network first. You can do this by using the configuration
values in .env.prod.development.Pyth.sol and package.json.
Make sure to read the Upgrading the contract and Versioning
sections below.MNEMONIC environment variable like so: export MNEMONIC=$(cat path/to/mnemonic).third_party/pyth/multisig-wh-message-builder/keys/key.json.INFURA_KEY if you are deploying to a network that uses an Infura RPC.Deploy the new contract or changes using the 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 section below can help
in case of any error. Run the script like this: ./deploy.sh <network_a> <network_b> <...>. For example
to deploy changes to testnet networks you can run:
./deploy.sh bnb_testnet fantom_testnet mumbai
Upon contract upgrade/state change the script needs to be run a couple of times as the multisig owners need to approve the created transactions. Links to the multisig transactions are printed during the script execution and you can use them. You need to run the script when the transactions are approved. If the deployment script runs successfully you should see many ✅s and no ❌s with a successful message.
On first time deployments for a network with Wormhole Receiver contract, run this command:
npm run receiver-submit-guardian-sets -- --network <network>
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.
If you are deploying to a new network, please add the new contract address to consumer facing libraries and documentations. Please update the following resources:
(Optional) You can test the deployed contract by sending and fetching a price update as described in the Testing section below.
(Optional) Verify the contract as described in the Verifying the contract section.
networks directoryTruffle stores the address of the deployed contracts in the build artifacts, which can make local development difficult. We use truffle-deploy-registry to store the addresses separately from the artifacts, in the 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.
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.
When you are making changes to the storage, please make sure that your change to the contract won't cause any collision. For example:
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.
We use Semantic Versioning for our releases. When upgrading the contract, update the npm package version using
npm version <new version number> --no-git-tag-version. Also, modify the hard-coded value in version() method in
the Pyth.sol contract to the new version. Then, after your PR is merged in main, create a release like with tag pyth-evm-contract-v<x.y.z>. This will help developers to be able to track code changes easier.
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
Please first try verifying the contract using truffle as described in VERIFY.md. It that doesn't work
Try to manually verify the contract using the explorer UI. You can try to upload the standard json output in build/contracts
directory. If that doesn't work either, you can flatten the contract and try to verify it.
To flatten the contract, run the following command:
npx sol-merger contracts/pyth/PythUpgradable.sol
It will create a new file PythUpgradable_merged.sol which you can use in the explorer to verify the implementation contract (using exact sol version and optimization flag). After verifying implementation, you can verify the proxy.
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.