diff --git a/.env-sample b/.env-sample index d2667528..ecdcdc2d 100644 --- a/.env-sample +++ b/.env-sample @@ -8,6 +8,7 @@ CREATE2_FACTORY=0x4e59b44847b379578588920cA78FbF26c0B4956C # to use the 'custom' hardhat network, set the following variables CUSTOM_RPC_URL="http://127.0.0.1:8545" +CUSTOM_PRIVKEY="0x" CUSTOM_ETHERSCAN_API_KEY= CUSTOM_CHAINID=1337 CUSTOM_ETHERSCAN_API_URL= diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 00000000..b6366add --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,173 @@ +# How to deploy the RollupCreator factory contract and create new rollup chains? + +> [!IMPORTANT] +> The recommended way of creating new Arbitrum chains is through the Arbitrum Orbit SDK. Instructions are available in our [documentation portal](https://docs.arbitrum.io/launch-arbitrum-chain/arbitrum-chain-sdk-introduction). These instructions are targetted to readers who are familiar with the Nitro stack and the creation of Arbitrum chains. + +This short guide includes instructions to deploy the `RollupCreator` factory contract, as well as create new rollup chains using it. + +## 1. Setup project + +Clone this repository + +```shell +git clone https://github.com/offchainlabs/nitro-contracts +cd nitro-contracts +``` + +Checkout the appropriate release (e.g. v3.1.0) + +```shell +git checkout v3.1.0 +``` + +Install dependencies and build + +```shell +yarn install +yarn build +``` + +Make a copy of the .env-sample file + +```shell +cp .env-sample .env +``` + +Choose the network that you're going to deploy the contracts to. If it's not present in [../hardhat.config.ts](../hardhat.config.ts), use the `custom` network. + +Then set the environment variables needed. + +To set the RPC and deployer private key to use, follow these instructions + +```shell +# For any L1 network (mainnet, sepolia, holesky) we use an Infura endpoint, so set the key here +# For Arbitrum and Base networks, we use the public RPC +INFURA_KEY= + +# For any mainnet network (mainnet, arb1, arbnova, base), use `MAINNET_PRIVKEY` +# For any testnet network (sepolia, holesky, arbsepolia, basesepolia), use `DEVNET_PRIVKEY` +MAINNET_PRIVKEY= +DEVNET_PRIVKEY= + +# For any other network +CUSTOM_RPC_URL= +CUSTOM_PRIVKEY= +``` + +_Note: the additional env variables needed for each step are specified in the appropriate section._ + +## 2. Deploy the RollupCreator factory + +Set the following environment variable: + +```shell +# Owner of the RollupCreator factory contract, with ability to modify the templates after the first deployment +# (usually don't need to modify this value) +FACTORY_OWNER="0x000000000000000000000000000000000000dead" +``` + +Optionally, set these extra variables: + +```shell +# When deploying on L1, use 117964; When deploying on L2, use 104857 +# (defaults to 117964) +MAX_DATA_SIZE=117964 + +# Whether or not to verify the contracts deployed +# (defaults to false, i.e., verify the contracts) +DISABLE_VERIFICATION=true +``` + +_Note: if you choose to verify the contracts, follow the instructions in the section "Verification of contracts" below, to set the appropriate api key_ + +Finally deploy the RollupCreator factory contract and the templates, using the `--network` flag to specify hardhat network to use. + +> [!NOTE] +> The deployment script uses Create2 to deploy all contracts. If Arachnid's proxy is not deployed in the chain, you must deploy it first (follow instructions in its [github repository](https://github.com/Arachnid/deterministic-deployment-proxy/) to do so). If the proxy is deployed in a different address, you can specify it with the environment variable `CREATE2_FACTORY`. + +```shell +yarn run deploy-factory --network (arbSepolia | arb1 | custom | ...) +``` + +The script will output all deployed addresses. Write down the address of the RollupCreator contract created, as you'll need it in the next step. + +## 3. Create new rollup chains + +Set the following environment variables: + +```shell +# Address of the RollupCreator factory contract +ROLLUP_CREATOR_ADDRESS="0x" +# Address of the stake token to use for validation through the Rollup contract +# (this is usually set to the WETH token) +STAKE_TOKEN_ADDRESS="0x" +``` + +Additionally, if you're going to deploy a custom gas token chain, set the following variables: + +```shell +# Address of the token contract in the parent chain, to use as the native gas token of your chain +FEE_TOKEN_ADDRESS="0x" +# Address of the fee token pricer to use for the fee token +# (see instructions in https://docs.arbitrum.io/launch-arbitrum-chain/configure-your-chain/common-configurations/use-a-custom-gas-token-rollup to understand how pricers work) +FEE_TOKEN_PRICER_ADDRESS="0x" +``` + +Optionally, set this extra variable: + +```shell +# Whether or not to verify the contracts deployed +# (defaults to false, i.e., verify the contracts) +DISABLE_VERIFICATION=true +``` + +_Note: if you choose to verify the contracts, follow the instructions in the section "Verification of contracts" below, to set the appropriate api key_ + +Then, make a copy of the `config.example.ts` file to configure the initial parameters of your chain. + +```shell +cp scripts/config.example.ts scripts/config.ts +``` + +Modify the initial parameters of your chain. Make sure all addresses are set to wallets that you own. + +Finally, use the appropriate command to create your rollup chain, depending on the gas token of your chain. + +If you'll use ETH as the gas token of your chain, call the following command, using the `--network` flag to specify hardhat network to use. + +```shell +yarn run deploy-eth-rollup --network (arbSepolia | arb1 | custom | ...) +``` + +If you'll use a custom gas token for your chain, call the following command, using the `--network` flag to specify hardhat network to use. + +```shell +yarn run deploy-erc20-rollup --network (arbSepolia | arb1 | custom | ...) +``` + +The script will output all deployed addresses and the block at which the transaction executed. + +## Verification of contracts + +If you choose to verify the deployed contracts, you'll also need to set the key to use Etherscan's API (or the appropriate network's block explorer). + +```shell +# For deployments on an L1 +ETHERSCAN_API_KEY= + +# For deployments on Arbitrum One and Arbitrum Sepolia +ARBISCAN_API_KEY= + +# For deployments on Base or Base Sepolia +BASESCAN_API_KEY= + +# For deployments on other networks +CUSTOM_ETHERSCAN_API_KEY= +CUSTOM_CHAINID= +CUSTOM_ETHERSCAN_API_URL= +CUSTOM_ETHERSCAN_BROWSER_URL= +``` + +## TokenBridge deployment + +To deploy a token bridge for your chain, follow the instructions in the [token-bridge-contracts](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/docs/deployment.md) repository. diff --git a/hardhat.config.ts b/hardhat.config.ts index de89bbf8..4419e493 100644 --- a/hardhat.config.ts +++ b/hardhat.config.ts @@ -172,6 +172,9 @@ module.exports = { }, custom: { url: process.env['CUSTOM_RPC_URL'] || 'N/A', + accounts: process.env['CUSTOM_PRIVKEY'] + ? [process.env['CUSTOM_PRIVKEY']] + : [], }, geth: { url: 'http://localhost:8545', diff --git a/scripts/deployment.ts b/scripts/deployment.ts index 12a5b659..a8a11ac7 100644 --- a/scripts/deployment.ts +++ b/scripts/deployment.ts @@ -38,6 +38,13 @@ async function main() { console.log('Ignoring maxDataSize warning') } + // Verification of contracts + // (If undefined, default "true" is used; if anything other than "false" is set, verification is disabled) + const verifyContracts = + process.env.DISABLE_VERIFICATION === undefined + ? undefined + : process.env.DISABLE_VERIFICATION === 'false' + // Deploying all contracts const factoryOwner = process.env.FACTORY_OWNER if (!factoryOwner) { @@ -47,7 +54,7 @@ async function main() { signer, factoryOwner, ethers.BigNumber.from(maxDataSize), - true + verifyContracts ) }