Arbitrum Nitro Contracts

repository·develop·Indexed 41 days ago

https://github.com/offchainlabs/nitro-contracts

Smart contract codebase for the Arbitrum Nitro rollup, including rollup contracts, fraud proof contracts, and interfaces for interacting with precompiles. Version 3.2.0 provides tools for deploying the RollupCreator factory, creating new rollup chains with ETH or custom ERC20 gas tokens, and configuring Hardhat for various L1 and L2 networks.

Tokens: 3K
Snippets: 8
Records: 13
Agent score: 99%

What's inside Arbitrum Nitro

Setup the nitro-contracts project

develop

To prepare the environment for deploying Nitro contracts, clone the repository, checkout your desired release, install dependencies, and build the project. You must also initialize an environment file from the sample provided.

# Clone and enter the repository
git clone https://github.com/offchainlabs/nitro-contracts
cd nitro-contracts

# Checkout a specific release (e.g., develop or v3.1.1)
git checkout develop

# Install dependencies and build
yarn install
yarn build:all

# Initialize environment variables
cp .env-sample .env

git clone https://github.com/offchainlabs/nitro-contracts
cd nitro-contracts
git checkout develop
yarn install
yarn build:all
cp .env-sample .env

Deploy the RollupCreator factory contract
develop
The RollupCreator factory contract and its templates are deployed using a script that utilizes Create2 for deterministic deployment.
Prerequisites: If the chain does not have Arachnid's proxy deployed, you must deploy it first. If the proxy is at a non-standard address, set the CREATE2_FACTORY environment variable.
Configuration Variables:
- FACTORY_OWNER: The address with authority to modify templates after the first deployment (defaults to 0x00000000000000000000000000000000dead).
- MAX_DATA_SIZE: Set to 117964 for L1 deployments, or 104857 for L2 deployments (defaults to 117964).
- DISABLE_VERIFICATION: Set to true to skip contract verification (defaults to false).
Execution: Run the deployment script specifying the target network via the --network flag.
```
yarn run deploy-factory --network (arbSepolia | arb1 | custom | ...)
```
https://github.com/offchainlabs/nitro-contracts/blob/develop/docs/deployment.md
Create new rollup chains
develop
After deploying the RollupCreator factory, you can use it to create new rollup chains.
1. Configure Chain Parameters
Set the following required environment variables:
- ROLLUP_CREATOR_ADDRESS: The address of the deployed RollupCreator factory.
- STAKE_TOKEN_ADDRESS: The address of the stake token (e.g., WETH) used for validation.
For Custom Gas Token Chains: If your chain uses a token other than the native gas token, set:
- FEE_TOKEN_ADDRESS: The address of the token contract in the parent chain.
- FEE_TOKEN_PRICER_ADDRESS: The address of the fee token pricer.
2. Configure the Chain Script
Copy the example configuration file to your local directory and modify the parameters to match your ownership and chain requirements:
```
cp scripts/config.example.ts scripts/config.ts
```
3. Execute Deployment
Depending on your gas token choice, run one of the following commands:
- ETH as Gas Token:
  yarn run deploy-eth-rollup --network <network_name>
- Custom ERC20 as Gas Token:
  yarn run deploy-erc20-rollup --network <network_name>
```
# For ETH gas token
yarn run deploy-eth-rollup --network arbSepolia

# For custom ERC20 gas token
yarn run deploy-erc20-rollup --network arbSepolia
```
https://github.com/offchainlabs/nitro-contracts/blob/develop/docs/deployment.md
Find deployed Arbitrum Nitro contract addresses
develop
If you are looking for the deployed addresses of the core Nitro contracts on existing Arbitrum chains, refer to the official Arbitrum documentation at: https://docs.arbitrum.io/for-devs/dev-tools-and-resources/chain-info#core-contracts
https://github.com/offchainlabs/nitro-contracts/blob/develop/README.md
Compile Arbitrum Nitro Rollup Contracts locally
develop
To compile the smart contracts for the Arbitrum Nitro rollup and fraud proofs on your local machine, clone the repository, install dependencies using yarn, and run the build command. This package includes the rollup contracts, fraud proof contracts, and precompile interfaces.
```
git clone https://github.com/offchainlabs/nitro-contracts
cd nitro-contracts
yarn install
yarn build
```
https://github.com/offchainlabs/nitro-contracts/blob/develop/README.md
Configure environment variables for deployment
develop
Deployment requires setting specific environment variables in your .env file based on the target network and deployment type.
RPC and Private Key Configuration
- L1 Networks (mainnet, sepolia, holesky): Set INFURA_KEY.
- Arbitrum and Base Networks: Uses public RPC (no key required).
- Mainnet Networks (mainnet, arb1, arbnova, base): Set MAINNET_PRIVKEY.
- Testnet Networks (sepolia, holesky, arbsepolia, basesepolia): Set DEVNET_PRIVKEY.
- Other Networks: Set CUSTOM_RPC_URL and CUSTOM_PRIVKEY.
Contract Verification
To verify contracts on Etherscan or other explorers, set:
- ETHERSCAN_API_KEY: The API key for the explorer.
- CUSTOM_CHAINID, CUSTOM_ETHERSCAN_API_URL, and CUSTOM_ETHERSCAN_BROWSER_URL: Required if using a custom network.
To skip verification, set DISABLE_VERIFICATION=true.
https://github.com/offchainlabs/nitro-contracts/blob/develop/docs/deployment.md
Configure Slither analysis settings
develop
The slither.config.json file defines the configuration for the Slither static analysis tool used in this repository. It controls which vulnerabilities are reported and which file paths are ignored during the analysis process.
Available configuration keys:
- exclude_dependencies: When true, excludes dependencies from the analysis.
- exclude_informational: When true, excludes informational-level findings.
- exclude_low: When true, excludes low-severity findings.
- exclude_optimization: When true, excludes optimization-related findings.
- filter_paths: A regex string defining paths to be excluded from the analysis (e.g., test helpers, mocks, or node_modules).
```
{
  "exclude_dependencies": true,
  "exclude_informational": true,
  "exclude_low": true,
  "exclude_optimization": true,
  "filter_paths": "src/test-helpers/|src/mocks/|node_modules/"
}
```
https://github.com/offchainlabs/nitro-contracts/blob/develop/slither.config.json

Configure Hardhat networks and environment variables

develop

The project defines several networks for deployment and testing. Most networks require specific environment variables for RPC URLs and private keys.

Required Environment Variables

INFURA_KEY: Used for mainnet, sepolia, holesky, and hardhat (forking).
MAINNET_PRIVKEY: Used for mainnet, arb1, nova, and base.
DEVNET_PRIVKEY: Used for sepolia, holesky, arbRinkeby, arbGoerliRollup, arbSepolia, baseSepolia, and custom.
SHOULD_FORK: Set to '1' to enable mainnet forking on the hardhat network.
CUSTOM_RPC_URL & CUSTOM_PRIVKEY: Used for the custom network.

Supported Networks

Network	URL / Provider	Accounts Source
`hardhat`	Local (with optional Infura forking)	Default accounts
`mainnet`	Infura	`MAINNET_PRIVKEY`
`sepolia`	Infura	`DEVNET_PRIVKEY`
`holesky`	Infura	`DEVNET_PRIVKEY`
`arbRinkeby`	`https://rinkeby.arbitrum.io/rpc`	`DEVNET_PRIVKEY`
`arbGoerliRollup`	`https://goerli-rollup.arbitrum.io/rpc`	`DEVNET_PRIVKEY`
`arbSepolia`	`https://sepolia-rollup.arbitrum.io/rpc`	`DEVNET_PRIVKEY`
`arb1`	`https://arb1.arbitrum.io/rpc`	`MAINNET_PRIVKEY`
`nova`	`https://nova.arbitrum.io/rpc`	`MAINNET_PRIVKEY`
`base`	`https://mainnet.base.org`	`MAINNET_PRIVKEY`
`baseSepolia`	`https://sepolia.base.org`	`DEVNET_PRIVKEY`
`custom`	`CUSTOM_RPC_URL`	`CUSTOM_PRIVKEY`
`geth`	`http://localhost:8545`	N/A

Configure Typechain and Gas Reporting
develop
The project includes automated type generation and gas reporting.
Typechain
Generates TypeScript types for your contracts.
- outDir: build/types
- target: ethers-v5
Gas Reporter
Reports gas usage for tests. It can be disabled using the DISABLE_GAS_REPORTER environment variable.
```
typechain: {
  outDir: 'build/types',
  target: 'ethers-v5',
},
gasReporter: {
  enabled: process.env.DISABLE_GAS_REPORTER ? false : true,
},
```
https://github.com/offchainlabs/nitro-contracts/blob/develop/hardhat.config.ts
Configure Solidity compiler settings and overrides
develop
The project uses Hardhat's solidity configuration to manage multiple compiler versions and specific settings for individual contracts.
By default, the project uses Solidity 0.8.17 with the following commonSetting applied to most contracts:
- metadata.bytecodeHash: 'none'
- optimizer.enabled: true
- optimizer.runs: 2000
- evmVersion: 'london'
Specific contracts can be assigned different optimizer runs via overrides to optimize for deployment cost or runtime gas:
- src/rollup/RollupUserLogic.sol: 20 runs
- src/rollup/RollupAdminLogic.sol: 20 runs
- src/challengeV2/EdgeChallengeManager.sol: 200 runs
If the environment variable INTERFACE_TESTER_SOLC_VERSION is set, the configuration adds an additional compiler version and applies an override to src/test-helpers/InterfaceCompatibilityTester.sol using that version.
```
const solidity: SolidityConfig = {
  compilers: [
    {
      version: '0.8.17',
      settings: {
        metadata: { bytecodeHash: 'none' },
        optimizer: { enabled: true, runs: 2000 },
        evmVersion: 'london',
      },
    },
  ],
  overrides: {
    'src/rollup/RollupUserLogic.sol': {
      version: '0.8.17',
      settings: {
        metadata: { bytecodeHash: 'none' },
        optimizer: { enabled: true, runs: 20 },
        evmVersion: 'london',
      },
    },
    // ... other overrides
  },
}
```
https://github.com/offchainlabs/nitro-contracts/blob/develop/hardhat.config.ts
Configure Etherscan and Sourcify for contract verification
develop
To verify contracts on Etherscan or Sourcify, configure the etherscan block in hardhat.config.ts.
- apiKey: Set via process.env['ETHERSCAN_API_KEY'].
- sourcify.enabled: Set to true by default.
Custom Chains
The configuration includes support for custom chain definitions, which is useful for networks like nova or user-defined custom chains:
- nova: Chain ID 42170, API URL https://api.etherscan.io/v2/api, Browser URL https://nova.arbiscan.io/.
- custom: Uses CUSTOM_CHAINID, CUSTOM_ETHERSCAN_API_URL, and CUSTOM_ETHERSCAN_BROWSER_URL from environment variables.
```
etherscan: {
  apiKey: process.env['ETHERSCAN_API_KEY'],
  sourcify: {
    enabled: true
  },
  customChains: [
    {
      network: 'nova',
      chainId: 42170,
      urls: {
        apiURL: 'https://api.etherscan.io/v2/api',
        browserURL: 'https://nova.arbiscan.io/',
      },
    },
    // ...
  ],
}
```
https://github.com/offchainlabs/nitro-contracts/blob/develop/hardhat.config.ts
Locate Token Bridge contracts
develop
The token bridge contracts are maintained in a separate repository. You can find them here: https://github.com/OffchainLabs/token-bridge-contracts
https://github.com/offchainlabs/nitro-contracts/blob/develop/README.md

Arbitrum Nitro Contracts

What's inside Arbitrum Nitro

1. Configure Chain Parameters

2. Configure the Chain Script

3. Execute Deployment

RPC and Private Key Configuration

Contract Verification

Required Environment Variables

Supported Networks

Typechain

Gas Reporter

Custom Chains