The Uniswap Labs team believes the future of Web3 is multi-chain, that’s why in early 2022 we released the scripts and instructions for the community to deploy the V3 Protocol to chains that have received a license exemption via governance vote.
To continue removing Uniswap Labs as a dependency from this process and turn more power over to the community, we are releasing the complete set of instructions for deploying the V3 Protocol to a governance approved chain, and integrating seamlessly into the ecosystem.
After following the instructions presented in the below sections, networks who have received approval from Uniswap Governance will have the Uniswap V3 protocol running fully on their EVM chain meaning the following is true:
- All contracts in the @uniswap/v3-core and @uniswap/v3-periphery repos are deployed to the new host chain
- Sub Graphs and Token Lists have been created and deployed
- The app.uniswap.org and info.uniswap.org sites include all supported functionality on the newly deployed EVM chain
- Uniswap Governance on the Ethereum Mainnet governs an established message bridge with the deployment on the new host chain
Teams should follow these steps sequentially for best results.
The first step in setting up Uniswap V3 on a new EVM chain is to deploy the smart contracts that make up the protocol. For convenience, the Uniswap Labs team has created a set of deployment scripts and management CLI that will coordinate and deploy the necessary contracts to a new EVM chain.
All you need to do is create the account to deploy with, fund it for gas fees (40-50M gas required), then run one command in the CLI. The script will sequentially deploy each contract, creating checkpoints as it goes that can be reverted back to in case any issues arise.
To start a deployment follow the detailed CLI instructions here → https://github.com/Uniswap/deploy-v3
The Graph is one of the most popular blockchain data indexing tools. If the chain you deployed to supports it, it is highly recommended that you set up a Sub Graph to index Uniswap activity on the new chain.
Having a Subgraph for your deployment not only allows integrators to access fast, reliable data, but will also make integrating with existing parts of the Uniswap Ecosystem, like info.uniswap.org a seamless experience.
Setting up a "Sub Graph" to index the Uniswap Protocol on a newly deployed chain allows users to easily query data about Uniswap activity on the new deployment and even build integrations with fast reliable data access.
The best way to set up your Subgraph is to start with an existing one from another chain and edit it to correspond to yours. You'll then submit that to The Graph and it will start indexing.
When you're ready to start setting up your Subgraph, follow these detailed instructions → Setting up a Subgraph.
The Uniswap Smart Order Router is a package that calculates the most efficient swap route off chain and produces calldata to execute that trade. The Smart Order Router is the system that calculates trade routes for https://app.uniswap.org so enabling new deployments in it is required to have them on the site.
To add a new deployment to the Smart Order Router you'll need to explicitly add references to new deployments in the open source package. Specific instructions of what to update can be found here → https://github.com/Uniswap/smart-order-router#adding-a-new-chain
Once your changes have been tested locally, open a PR in the repo to merge them in.
Token Lists are another key primitive in the Uniswap and larger DeFi eco-system. Token Lists are a simple schema for identifying supported tokens on a dApp.
{
"name": "Example Token List",
"timestamp": "2022-03-01T22:44:18.339Z",
"version": {
"major": 4,
"minor": 2,
"patch": 0
},
"tokens": [
{
"logoURI": "https://logo.io",
"chainId": 42161,
"address": "0x7cb16cb78ea464aD35c8a50ABF95dff3c9e09d5d",
"name": "0xBitcoin Token",
"symbol": "0xBTC",
"decimals": 8,
"extensions": {}
},
...
]
}
As a next step in the deployment of a new chain, you will author a token list to represent the tokens supported on your chain and host it (preferably on IPFS or another decentralized system). With an up to date Token List, you can easily manage the tokens supported in the Uniswap App as well as in dApps across the ecosystem.
Follow the instructions in the Token Lists Package to author, validate and host your token list. You'll need a valid Token List to proceed with future steps.
The Interface is one of the most used dApps in web3 and is where over 60% of Uniswap trading occurs. To access this user base, you’ll need to update the open source App code to include the newly deployed chain.
Uniswap App Repo → https://github.com/Uniswap/interface
To access these user bases, you’ll need to update the open source code to include the newly deployed chain:
- Uniswap App Repo → https://github.com/Uniswap/interface
- Uniswap Widgets Repo → https://github.com/Uniswap/widgets
The recent Celo integration included the changes required to support future EVM compatible chains with alternative contract addresses. While there will likely be nuances with each new integration, you can follow the basic steps (below) and reference the Celo PR to guide you when making changes.
At a high level, the steps you'll complete are:
- Add respective constants and links:
- chainId, chain name, contract addresses, chain info, token lists, etc. (these can be found under the ./src/constants dir)
- the v3-subgraph URL (see ./state/data/slice)
- native token logo (see ./assets/svg)
- explorer link (see ./utils/getExplorerLink.ts)
- RPC URL (see ./utils/switchChain)
- The Uniswap interface currency selector has a section for the most common base assets, these respective tokens are hard coded into the interface (see ./constants/tokens). Follow the pattern there to add 4-8 tokens as well as support for the native asset. Afterwards, add those tokens as common bases (see ./constants/routing)
- Look and feel
- update the background colors (see src/theme)
- update the network alert (see src/components/NetworkAlert)
Once the necessary changes are made, and you've tested the integration locally, submit a PR from your branch to Uniswap/interface main for review (make sure to follow the Uniswap PR guidelines).
The info.uniswap.org is another key piece of the Uniswap Ecosystem, where users go to get reliable data. Having a working Subgraph is a requirement for this step. If The Graph does not yet support your chain, these instructions will not work for you. You may either proceed without adding your chain to info.uniswap.org or feel free to propose another solution to support it.
If you were able to get a Subgraph working you can proceed to add your chain to the Info site. The process will be similar to updating the Interface, we recommend referencing the changes made for the recent (Celo integration) to better understand the changes required.
At a high level, the changes will be:
- Add the respective chains subgraph clients (follow the pattern in ./apollo/client.ts)
- Add constants and links:
- chain id to supported chain id (see ./constants/chains.ts)
- token list (see ./constants/lists.ts)
- Multicall contract address (see ./constants/multicall)
- explorer link (see ./src/utils)
- Look and feel
- similar to the interface, add the logo svg (see assets/images)
- add the network info (see constants/networks)
- display the logo follow the pattern in ./components/CurrencyLogo
- display native currency price (see ./components/header/TopBar.tsx)
- Add the network to the network dropdown (./menu/NetworkDropdown)
Once you've made the changes and tested them locally, submit a PR to the open source Info Repo.
[ Coming Soon ]
- Compile the list of deployed addresses from the deploy-v3 script.
- Ensure that all of the contracts are verified on your blockchain explorer (i.e. Etherscan).
- Pull down the deployed bytecode for each contract(i.e. from Etherscan or a tool like Cast.
- Compare the bytecode to the mainnet deployment. The only differences should be the contract immutables, including addresses of other deployment contracts.
- Test the deployment! Some important cases to consider:
- Swapping native asset -> ERC20 and ERC20 -> native asset through the SwapRouter
- Adding and removing liquidity with native asset through the NonfungiblePositionManager