Skip to content

contracts.mdx

Latest commit

 

History

History
194 lines (157 loc) · 21 KB

contracts.mdx

File metadata and controls

194 lines (157 loc) · 21 KB
section sdk
date Last Modified
title Scroll SDK Contracts
lang en
permalink sdk/technical-stack/contracts
excerpt Documents the contracts deployed to support the Scroll SDK.

import Aside from "../../../../../components/Aside.astro"

{/* TODO: Review full page before launch */}

Overview

Contracts deployed for a Scroll SDK chain include both contracts on the L1 (or basechain), and contracts deployed on the L2 (or SDK chain). Additionally, the L2 has "pre-deployed" contracts, matching those on Scroll.

Primary Contracts

Although there are many contracts deployed during a new chain deployment, the most important contracts to understand are below.

Rollup Contract

  • Deployed to L1 using a proxy and also called "Scroll Chain"
  • Accepts new batches and proofs posted by the rollup-relayer service by calling "Commit Batch" and "Finalize Batch" methods.
  • Keeps track of finalized State Roots and Withdraw Roots.
  • View on Etherscan | View Source

Scroll Message Queues

  • Deployed to L1 with a proxy and pre-deployed to L2
  • On L1, every deposit to the bridge is added as a message to the L1 message queue.
    • Messages are read by l2geth instances, including the sequencer, and brought into the Scroll chain via L1Message transaction types.
  • On L2, every withdrawal sent through the bridge is added as a message, and each block's resulting withdraw root is made available after finalization on the L1 Rollup Contract.
  • Messages are added to the queues exclusively by the Messenger contracts on L1 and L2.
  • View L1 Deployment on Etherscan | View Source
  • View L2 Deployment on Scrollscan | View Source

Gas Oracle Contracts

  • Deployed on L1 (as part of L1 Message Queue) and pre-deployed on L2
  • On L1, it tracks the gas fees on L2. This is needed since L1 transactions need to pay for their L2 gas upfront.
    • Stored l2BaseFee can only be updated by whitelisted addresses, TODO: is this done by gas-oracle on L1 and L2?
  • On L2, the contract keeps track of the fees on L1, allowing other contracts to know how the cost required to send a transaction back to L1
    • Stored l1BaseFee can only be updated by whitelisted addresses, TODO: is this done by gas-oracle on L1 and L2?
  • View L1 Deployment on Etherscan | View Source
  • View L2 Deployment on Scrollscan | View Source

Deployment Process

Contracts are deployed by the contracts chart. Deterministic addresses are used, with a salt used to generate the address of the contract. For every new deployment, a unique salt should be configured in config.toml.

During the configuration generation step, a simulation is first done to determine what address a contract will deploy to. This step is done during the creation of the config files for each service's chart and when the genesis.json file is created. Contract addresses are then used to set each service's configuration (see gen-configs.sh).

Then, before the contracts chart is installed, you will need to fund your SDK DEPLOYER account to deploy all contracts on L1 and L2 using actual transactions.

The contracts pod will connect to the L2 RPC and deploy the necessary contracts from the DEPLOYER account.

All contracts are available in the [scroll-contracts repo](https://github.com/scroll-tech/scroll-contracts), and [Docker files](https://github.com/scroll-tech/scroll-contracts/tree/feat-deterministic-deployment/docker) and [Foundry scripts](https://github.com/scroll-tech/scroll-contracts/tree/feat-deterministic-deployment/scripts/deterministic) used for deployment available in the `feat-deterministic-deployment` branch.

For manually deploying contracts without the reliance on a docker container, please review this guide.

Funding Deployment Accounts

In production deployments, you will need to manually fund the following wallet addresses from config.toml:

  • DEPLOYER_ADDR (only needs funded on L1) {/* - Suggested funds: (L1 basefee * VARIABLE * 10e-9) ETH */}
  • L1_COMMIT_SENDER_ADDR {/* - Suggested funds: (L1 basefee * VARIABLE * 10e-9) ETH */}
  • L1_FINALIZE_SENDER_ADDR {/* - Suggested funds: (L1 basefee * VARIABLE * 10e-9) ETH */}
  • L1_GAS_ORACLE_SENDER_ADDR {/* - Suggested funds: (L1 basefee * VARIABLE * 10e-9) ETH */}
  • L2_GAS_ORACLE_SENDER_ADDR (funded after L2 chain deployment) {/* - Suggested funds: (L1 basefee * VARIABLE * 10e-9) ETH */}

{/* TODO: Consider recommending an initial funding amount. */}

To fund an L1 addresses when using Anvil in a devnet, run scrollsdk helper fund-accounts --dev. Or, to manually set individual account balances, you can also run the command below, replacing the first param with the address.

curl --location 'http://l1-devnet.scrollsdk/' \
--header 'Content-Type: application/json' \
--data '{
  "jsonrpc":"2.0",
  "method":"anvil_setBalance",
  "params":["0x0000000005D6C5FCB0BA99480e585D2364e98000","0x3635C9ADC5DEA00000"],
  "id":0
}'

To fund an L2 address directly via the L1 bridge, you can run the command below, replacing the RPC and setting a private key of an account funded on L1 and a recipient address on L2.

cast send --rpc-url https://rpc2.sepolia.org  --private-key "$PRIVATE_KEY" "$L1_GATEWAY_ROUTER_PROXY_ADDR" "depositETH(address,uint256,uint256)" "$L2_RECIPIENT_ADDR" "1ether" "300000" --value "1.1ether"

You can also use the interactive scrollsdk helper fund-accounts --layer=2 [--private-key=<private-key>] command to fund an L2 address, optionally passing a private key as funder.

Contracts Deployed

In the table below, we document every contract deployed for Scroll, including a link to the deployment for Scroll's mainnet. Not all of these are used by default for Scroll SDK.

{/* */}

Contract Name Description
L1_WETH_ADDR The WETH contract on L1.
L2_WETH_ADDR The WETH contract on L2.
L1_PLONK_VERIFIER_V0_ADDR The PLONK verifier version 0 on L1.
L1_ZKEVM_VERIFIER_V0_ADDR The zkEVM verifier version 0 on L1.
L1_PLONK_VERIFIER_V1_ADDR The PLONK verifier version 1 on L1.
L1_ZKEVM_VERIFIER_V1_ADDR The zkEVM verifier version 1 on L1.
L1_PLONK_VERIFIER_V2_ADDR The PLONK verifier version 2 on L1.
L1_ZKEVM_VERIFIER_V2_ADDR The zkEVM verifier version 2 on L1.
L1_MULTIPLE_VERSION_ROLLUP_VERIFIER_ADDR The multiple version rollup verifier on L1.
L1_PROXY_ADMIN_ADDR The proxy admin contract on L1.
L1_PROXY_IMPLEMENTATION_PLACEHOLDER_ADDR The proxy implementation placeholder on L1.
L1_WHITELIST_ADDR The whitelist contract on L1.
L1_MESSAGE_QUEUE_IMPLEMENTATION_ADDR The message queue implementation on L1.
L1_MESSAGE_QUEUE_PROXY_ADDR The message queue proxy on L1.
L2_GAS_PRICE_ORACLE_IMPLEMENTATION_ADDR The gas price oracle implementation on L1.
L2_GAS_PRICE_ORACLE_PROXY_ADDR The gas price oracle proxy on L1.
L1_SCROLL_CHAIN_IMPLEMENTATION_ADDR The Scroll chain implementation on L1.
L1_SCROLL_CHAIN_PROXY_ADDR The Scroll chain proxy on L1.
L1_ETH_GATEWAY_IMPLEMENTATION_ADDR The ETH gateway implementation on L1.
L1_ETH_GATEWAY_PROXY_ADDR The ETH gateway proxy on L1.
L1_WETH_GATEWAY_IMPLEMENTATION_ADDR The WETH gateway implementation on L1.
L1_WETH_GATEWAY_PROXY_ADDR The WETH gateway proxy on L1.
L1_STANDARD_ERC20_GATEWAY_IMPLEMENTATION_ADDR The standard ERC20 gateway implementation on L1.
L1_STANDARD_ERC20_GATEWAY_PROXY_ADDR The standard ERC20 gateway proxy on L1.
L1_GATEWAY_ROUTER_IMPLEMENTATION_ADDR The gateway router implementation on L1.
L1_GATEWAY_ROUTER_PROXY_ADDR The gateway router proxy on L1.
L1_SCROLL_MESSENGER_IMPLEMENTATION_ADDR The Scroll messenger implementation on L1.
L1_SCROLL_MESSENGER_PROXY_ADDR The Scroll messenger proxy on L1.
L1_ENFORCED_TX_GATEWAY_IMPLEMENTATION_ADDR The enforced transaction gateway implementation on L1.
L1_ENFORCED_TX_GATEWAY_PROXY_ADDR The enforced transaction gateway proxy on L1.
L1_CUSTOM_ERC20_GATEWAY_IMPLEMENTATION_ADDR The custom ERC20 gateway implementation on L1.
L1_CUSTOM_ERC20_GATEWAY_PROXY_ADDR The custom ERC20 gateway proxy on L1.
L1_ERC721_GATEWAY_IMPLEMENTATION_ADDR The ERC721 gateway implementation on L1.
L1_ERC721_GATEWAY_PROXY_ADDR The ERC721 gateway proxy on L1.
L1_ERC1155_GATEWAY_IMPLEMENTATION_ADDR The ERC1155 gateway implementation on L1.
L1_ERC1155_GATEWAY_PROXY_ADDR The ERC1155 gateway proxy on L1.
L1_SCROLL_OWNER_ADDR The Scroll owner contract on L1.
L1_1D_TIMELOCK_ADDR The 1-day timelock contract on L1.
L1_7D_TIMELOCK_ADDR The 7-day timelock contract on L1.
L1_14D_TIMELOCK_ADDR The 14-day timelock contract on L1.
L1_GAS_PRICE_ORACLE_ADDR The gas price oracle contract on L2.
L2_MESSAGE_QUEUE_ADDR The message queue contract on L2.
L2_TX_FEE_VAULT_ADDR The transaction fee vault contract on L2.
L2_WHITELIST_ADDR The whitelist contract on L2.
L2_PROXY_ADMIN_ADDR The proxy admin contract on L2.
L2_PROXY_IMPLEMENTATION_PLACEHOLDER_ADDR The proxy implementation placeholder on L2.
L2_SCROLL_MESSENGER_IMPLEMENTATION_ADDR The Scroll messenger implementation on L2.
L2_SCROLL_MESSENGER_PROXY_ADDR The Scroll messenger proxy on L2.
L2_ETH_GATEWAY_IMPLEMENTATION_ADDR The ETH gateway implementation on L2.
L2_ETH_GATEWAY_PROXY_ADDR The ETH gateway proxy on L2.
L2_WETH_GATEWAY_IMPLEMENTATION_ADDR The WETH gateway implementation on L2.
L2_WETH_GATEWAY_PROXY_ADDR The WETH gateway proxy on L2.
L2_STANDARD_ERC20_GATEWAY_IMPLEMENTATION_ADDR The standard ERC20 gateway implementation on L2.
L2_STANDARD_ERC20_GATEWAY_PROXY_ADDR The standard ERC20 gateway proxy on L2.
L2_GATEWAY_ROUTER_IMPLEMENTATION_ADDR The gateway router implementation on L2.
L2_GATEWAY_ROUTER_PROXY_ADDR The gateway router proxy on L2.
L2_SCROLL_STANDARD_ERC20_ADDR The Scroll standard ERC20 contract on L2.
L2_SCROLL_STANDARD_ERC20_FACTORY_ADDR The Scroll standard ERC20 factory contract on L2.
L2_CUSTOM_ERC20_GATEWAY_IMPLEMENTATION_ADDR The custom ERC20 gateway implementation on L2.
L2_CUSTOM_ERC20_GATEWAY_PROXY_ADDR The custom ERC20 gateway proxy on L2.
L2_ERC721_GATEWAY_IMPLEMENTATION_ADDR The ERC721 gateway implementation on L2.
L2_ERC721_GATEWAY_PROXY_ADDR The ERC721 gateway proxy on L2.
L2_ERC1155_GATEWAY_IMPLEMENTATION_ADDR The ERC1155 gateway implementation on L2.
L2_ERC1155_GATEWAY_PROXY_ADDR The ERC1155 gateway proxy on L2.
L2_SCROLL_OWNER_ADDR The Scroll owner contract on L2.
L2_1D_TIMELOCK_ADDR The 1-day timelock contract on L2.
L2_7D_TIMELOCK_ADDR The 7-day timelock contract on L2.
L2_14D_TIMELOCK_ADDR The 14-day timelock contract on L2.
SCROLL_CHAIN_COMMITMENT_VERIFIER_ADDR The Scroll chain commitment verifier contract.
POSEIDON_UNIT2_ADDR The Poseidon unit 2 contract.
L1_BATCH_BRIDGE_GATEWAY_PROXY_ADDR The Batch Deposit proxy contract on L1.
L1_BATCH_BRIDGE_GATEWAY_IMPLEMENTATION_ADDR The Batch Deposit implementation on L1.
L2_BATCH_BRIDGE_GATEWAY_PROXY_ADDR The Batch Deposit proxy contract on L2.
L2_BATCH_BRIDGE_GATEWAY_IMPLEMENTATION_ADDR The Batch Deposit implementation on L2.