Skip to content

N
nebula
Commit 176c4d96 authored by Kelvin Fichter's avatar Kelvin Fichter
Browse files
Options

main(ct): finish updating contracts readme 

Updates various parts of the contracts README, primarily making sure
that the process for deploying the contracts is up to date.
parent 6f633f91
Hide whitespace changes
Inline Side-by-side
Showing with 65 additions and 78 deletions
packages/contracts/README.md
View file @ 176c4d96
...@@ -10,8 +10,6 @@ If neither `EVM` nor `OVM` are listed, the contract is likely intended to be use ...@@ -10,8 +10,6 @@ If neither `EVM` nor `OVM` are listed, the contract is likely intended to be use
## Usage (npm) ## Usage (npm)
You can import `@eth-optimism/contracts` to use the Optimism contracts within your own codebase. You can import `@eth-optimism/contracts` to use the Optimism contracts within your own codebase.
We currently only export `@eth-optimism/contracts` via `npm`.
Install via `npm` or `yarn`: Install via `npm` or `yarn`:
```shell ```shell
...@@ -92,98 +90,87 @@ yarn build:contracts ...@@ -92,98 +90,87 @@ yarn build:contracts
``` ```
### Deploying the Contracts ### Deploying the Contracts
To deploy the contracts first clone, install, and build the contracts package.
Next set the following env vars: #### Required environment variables
You must set the following environment variables to execute a deployment:
```bash ```bash
CONTRACTS_TARGET_NETWORK=... # Name for the network to deploy to ("mainnet", "kovan", etc.)
CONTRACTS_DEPLOYER_KEY=... export CONTRACTS_TARGET_NETWORK=...
CONTRACTS_RPC_URL=...
```
Then to perform the actual deployment run: # Private key that will send deployment transactions
export CONTRACTS_DEPLOYER_KEY=...
```bash # RPC URL connected to the L1 chain we're deploying to
npx hardhat deploy \ export CONTRACTS_RPC_URL=...
--network ... \ # `network` MUST equal your env var `CONTRACTS_TARGET_NETWORK`
--ovm-address-manager-owner ... \ # Your Etherscan API key for the L1 network
--ovm-proposer-address ... \ export ETHERSCAN_API_KEY=...
--ovm-relayer-address ... \
--ovm-sequencer-address ... \
--scc-fraud-proof-window ... \
--scc-sequencer-publish-window ...
``` ```
This will deploy the contracts to the network specified in your env and create #### Creating a deployment script
an artifacts directory in `./deployments`.
To view all deployment options run: Before you can carry out a deployment, you must create a deployment script.
See [mainnet.sh](./scripts/deploy-scripts/mainnet.sh) for an example deployment script.
We recommend duplicating an existing deployment script and modifying it to satisfy your requirements.
```bash Most variables within the deploy script are relatively self-explanatory.
npx hardhat deploy --help If you intend to upgrade an existing system you **MUST** [include the following argument](https://github.com/ethereum-optimism/optimism/blob/6f633f915b34a46ac14430724bed9722af8bd05e/packages/contracts/scripts/deploy-scripts/mainnet.sh#L33) in the deploy script:
Hardhat version 2.2.1
Usage: hardhat [GLOBAL OPTIONS] deploy [--ctc-force-inclusion-period-seconds <INT>] [--ctc-max-transaction-gas-limit <INT>] --deploy-scripts <STRING> [--em-max-gas-per-queue-per-epoch <INT>] [--em-max-transaction-gas-limit <INT>] [--em-min-transaction-gas-limit <INT>] [--em-ovm-chain-id <INT>] [--em-seconds-per-epoch <INT>] --export <STRING> --export-all <STRING> --gasprice <STRING> [--l1-block-time-seconds <INT>] [--no-compile] [--no-impersonation] --ovm-address-manager-owner <STRING> --ovm-proposer-address <STRING> --ovm-relayer-address <STRING> --ovm-sequencer-address <STRING> [--reset] [--scc-fraud-proof-window <INT>] [--scc-sequencer-publish-window <INT>] [--silent] --tags <STRING> [--watch] --write <BOOLEAN>
OPTIONS:
--ctc-force-inclusion-period-seconds Number of seconds that the sequencer has to include transactions before the L1 queue. (default: 2592000)
--ctc-max-transaction-gas-limit Max gas limit for L1 queue transactions. (default: 9000000)
--deploy-scripts override deploy script folder path
--em-max-gas-per-queue-per-epoch Maximum gas allowed in a given queue for each epoch. (default: 250000000)
--em-max-transaction-gas-limit Maximum allowed transaction gas limit. (default: 9000000)
--em-min-transaction-gas-limit Minimum allowed transaction gas limit. (default: 50000)
--em-ovm-chain-id Chain ID for the L2 network. (default: 420)
--em-seconds-per-epoch Number of seconds in each epoch. (default: 0)
--export export current network deployments
--export-all export all deployments into one file
--gasprice gas price to use for transactions
--l1-block-time-seconds Number of seconds on average between every L1 block. (default: 15)
--no-compile disable pre compilation
--no-impersonation do not impersonate unknown accounts
--ovm-address-manager-owner Address that will own the Lib_AddressManager. Must be provided or this deployment will fail.
--ovm-proposer-address Address of the account that will propose state roots. Must be provided or this deployment will fail.
--ovm-relayer-address Address of the message relayer. Must be provided or this deployment will fail.
--ovm-sequencer-address Address of the sequencer. Must be provided or this deployment will fail.
--reset whether to delete deployments files first
--scc-fraud-proof-window Number of seconds until a transaction is considered finalized. (default: 604800)
--scc-sequencer-publish-window Number of seconds that the sequencer is exclusively allowed to post state roots. (default: 1800)
--silent whether to remove log
--tags specify which deploy script to execute via tags, separated by commas
--watch redeploy on every change of contract or deploy script
--write whether to write deployments to file
deploy: Deploy contracts
For global options help run: hardhat help
```
### Verifying Deployments on Etherscan
If you are using a network which Etherscan supports you can verify your contracts with:
```bash ```
npx hardhat etherscan-verify --api-key ... --network ... --tags upgrade
``` ```
### Other hardhat tasks If you are deploying a system from scratch, you should **NOT** include `--tags upgrade` or you will fail to deploy several contracts.
To whitelist deployers on Mainnet you must have the whitelist Owner wallet connected, then run: #### Executing a deployment
```bash
npx hardhat whitelist \
--use-ledger true \
--contracts-rpc-url https://mainnet.optimism.io \
--address ... \ # address to whitelist
```
To withdraw ETH fees to L1 on Mainnet, run: Once you've created your deploy script, simply run the script to trigger a deployment.
```bash During the deployment process, you will be asked to transfer ownership of several contracts to a special contract address.
npx hardhat withdraw-fees \ You will also be asked to verify various configuration values.
--use-ledger \ # The ledger to withdraw fees with. Ensure this wallet has ETH on L2 to pay the tx fee. This is a safety mechanism to make sure that actions within an upgrade are performed atomically.
--contracts-rpc-url https://mainnet.optimism.io \ Ownership of these addresses will be automatically returned to the original owner address once the upgrade is complete.
The original owner can always recover ownership from the upgrade contract in an emergency.
Please read these instructions carefully, verify each of the presented configuration values, and carefully confirm that the contract you are giving ownership to has not been compromised (e.g., check the code on Etherscan).
After your deployment is complete, your new contracts will be written to an artifacts directory in `./deployments/<name>`.
Your contracts will also be automatically verified as part of the deployment script.
#### Creating a genesis file
Optimism expects that certain contracts (called "predeploys") be deployed to the L2 network at pre-determined addresses.
Doing this requires that you generate a special genesis file to be used by your corresponding L2Geth nodes.
You must first create a genesis generation script.
Like in the deploy script, we recommend starting from an [existing script](./scripts/deploy-scripts/mainnet-genesis.sh).
Modify each of the values within this script to match the values of your own deployment, taking any L1 contract addresses from the `./deployments/<name>` folder that was just generated or modified.
Execute this script to generate the genesis file.
You will find this genesis file at `./dist/dumps/state-dump.latest.json`.
You can then ingest this file via `geth init`.
### Hardhat tasks
#### Whitelisting
Optimism has removed the whitelist from the Optimism mainnet.
However, if you are running your own network and still wish to use the whitelist, you can manage the whitelist with the `whitelist` task.
Run the following to get help text for the `whitelist` command:
```
npx hardhat whitelist --help
``` ```
#### Withdrawing fees
Any wallet can trigger a withdrawal of fees within the `SequencerFeeWallet` contract on L2 back to L1 as long as a threshold balance has been reached.
Fees within the wallet will return to a fixed address on L1.
Run the following to get help text for the `withdraw-fees` command:
```
npx hardhat withdraw-fees --help
```
## Security ## Security
Please refer to our [Security Policy](https://github.com/ethereum-optimism/.github/security/policy) for information about how to disclose security issues with this code. Please refer to our [Security Policy](https://github.com/ethereum-optimism/.github/security/policy) for information about how to disclose security issues with this code.
We also maintain a [bug bounty program via Immunefi](https://immunefi.com/bounty/optimism/) with a maximum payout of $2,000,042 for critical bug reports.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment