First off, thanks for taking the time to contribute! ❤️
First off, thanks for taking the time to contribute!
We welcome and appreciate all kinds of contributions. Refer to the Table of Contents to discover various ways you can assist, as well as the procedures we follow for each type. Before you contribute, kindly review the appropriate section; this will streamline the process for both maintainers and contributors. We're excited to see your contributions! 🎉
...
...
@@ -12,6 +12,8 @@ We welcome and appreciate all kinds of contributions. Refer to the Table of Cont
-[Your First Code Contribution](#your-first-code-contribution)
-[Improving The Documentation](#improving-the-documentation)
-[Deploying on Devnet](#deploying-on-devnet)
-[Tools](#tools)
## I Have a Question
...
...
@@ -48,8 +50,10 @@ The best place to begin contributing is by looking through the issues with the `
Optimism's smart contracts are written in Solidity and we use [foundry](https://github.com/foundry-rs/foundry) as our development framework. To get started, you'll need to install several dependencies:
1.[pnpm](https://pnpm.io)
1. Make sure to `pnpm install`
1.[foundry](https://getfoundry.sh)
1. Foundry is built with [rust](https://www.rust-lang.org/tools/install), so if you decide to build it from source, you'll need to install the rust toolchain via `rustup`.
1. Foundry is built with [rust](https://www.rust-lang.org/tools/install), and this project uses a pinned version of foundry. Install the rust toolchain with `rustup`.
1. Make sure to install the version of foundry used by `ci-builder`, defined in the `.foundryrc` file in the root of this repo. Once you have `foundryup` installed, there is a helper to do this: `pnpm install:foundry`
1.[golang](https://golang.org/doc/install)
1.[python](https://www.python.org/downloads/)
...
...
@@ -73,3 +77,42 @@ Once you've read the styleguide and are ready to work on your PR, there are a pl
### Improving The Documentation
Documentation improvements are more than welcome! If you see a typo or feel that a code comment describes something poorly or incorrectly, please submit a PR with a fix.
### Deploying on Devnet
To deploy the smart contracts on a local devnet, run `make devnet-up` in the monorepo root.
### Tools
#### Layout Locking
We use a system called "layout locking" as a safety mechanism to prevent certain contract variables from being moved to different storage slots accidentally.
To lock a contract variable, add it to the `layout-lock.json` file which has the following format:
```json
{
"MyContractName":{
"myVariableName":{
"slot":1,
"offset":0,
"length":32
}
}
}
```
With the above config, the `validate-spacers` hardhat task will check that we have a contract called `MyContractName`, that the contract has a variable named `myVariableName`, and that the variable is in the correct position as defined in the lock file.
You should add things to the `layout-lock.json` file when you want those variables to **never** change.
Layout locking should be used in combination with diffing the `.storage-layout` file in CI.
#### Gas Snapshots
We use forge's `gas-snapshot` subcommand to produce a gas snapshot for most tests within our suite. CI will check that the gas snapshot has been updated properly when it runs, so make sure to run `pnpm gas-snapshot`!
#### Semver Locking
Many of our smart contracts are semantically versioned. To make sure that changes are not made to a contract without deliberately bumping its version, we commit to the source code and the creation bytecode of its dependencies in a lockfile. Consult the [Style Guide](./STYLE_GUIDE.md#Versioning) for more information about how our contracts are versioned.
#### Storage Snapshots
Due to the many proxied contracts in Optimism's protocol, we automate tracking the diff to storage layouts of the contracts in the project. This is to ensure that we don't break a proxy by upgrading its implementation to a contract with a different storage layout. To generate the storage lockfile, run `pnpm storage-snapshot`.
@@ -50,78 +50,29 @@ We export contract ABIs, contract source code, and contract deployment informati
npm install @eth-optimism/contracts-bedrock
```
## Development
## Contributing
### Dependencies
For all information about working on and contributing to Optimism's smart contracts, please see [CONTRIBUTING.md](./CONTRIBUTING.md)
We work on this repository with a combination of [Hardhat](https://hardhat.org) and [Foundry](https://getfoundry.sh/).
1. Install node modules with pnpm (v8) and Node.js (16+):
```shell
pnpm install
```
2. Install the correct version of foundry (defined in the .foundryrc file in the root of this repo.
```shell
pnpm install:foundry
```
### Build
```shell
pnpm build
```
### Tests
```shell
pnpm test
```
### Deployment
## Deployment
The smart contracts are deployed using `foundry` with a `hardhat-deploy` compatibility layer. When the contracts are deployed,
they will write a temp file to disk that can then be formatted into a `hardhat-deploy` style artifact by calling another script.
#### Configuration
### Configuration
Create or modify a file `<network-name>.json` inside of the [`deploy-config`](./deploy-config/) folder.
By default, the network name will be selected automatically based on the chainid. Alternatively, the `DEPLOYMENT_CONTEXT` env var can be used to override the network name.
The spec for the deploy config is defined by the `deployConfigSpec` located inside of the [`hardhat.config.ts`](./hardhat.config.ts).
#### Execution
### Execution
1. Set the env vars `ETH_RPC_URL`, `PRIVATE_KEY` and `ETHERSCAN_API_KEY` if contract verification is desired
1. Deploy the contracts with `forge script -vvv scripts/Deploy.s.sol:Deploy --rpc-url $ETH_RPC_URL --broadcast --private-key $PRIVATE_KEY`
Pass the `--verify` flag to verify the deployments automatically with Etherscan.
1. Generate the hardhat deploy artifacts with `forge script -vvv scripts/Deploy.s.sol:Deploy --sig 'sync()' --rpc-url $ETH_RPC_URL --broadcast --private-key $PRIVATE_KEY`
#### Deploying a single contract
### Deploying a single contract
All of the functions for deploying a single contract are `public` meaning that the `--sig` argument to `forge script` can be used to
target the deployment of a single contract.
## Tools
### Layout Locking
We use a system called "layout locking" as a safety mechanism to prevent certain contract variables from being moved to different storage slots accidentally.
To lock a contract variable, add it to the `layout-lock.json` file which has the following format:
```json
{
"MyContractName":{
"myVariableName":{
"slot":1,
"offset":0,
"length":32
}
}
}
```
With the above config, the `validate-spacers` hardhat task will check that we have a contract called `MyContractName`, that the contract has a variable named `myVariableName`, and that the variable is in the correct position as defined in the lock file.
You should add things to the `layout-lock.json` file when you want those variables to **never** change.
Layout locking should be used in combination with diffing the `.storage-layout` file in CI.
