How scroll-tech/scroll-contracts works
Project type and purpose
• This is a blockchain smart-contract project implementing the Scroll L1 (Ethereum) ↔ L2 (Scroll rollup) bridge and rollup system.
• It includes:
• L1 contracts for message passing, rollup finalization, gateways.
• L2 contracts for message passing, gateways, predeploys.
• Shared libraries for hashing, proofs, codecs.
• Deployment scripting (Hardhat, Foundry).
• Integration and unit tests.
File structure
• Top level: configuration (.env, eslint, prettier, foundry.toml, hardhat.config.ts).
• Directories:
• lib/ holds external submodules (ds-test, forge-std, solmate).
• scripts/ contains deployment scripts for Foundry and Hardhat.
• hardhat-test/ holds integration tests using Hardhat.
• src/ contains the Solidity code, organized by:
– L1/ (gateways, rollup, messenger)
– L2/ (gateways, predeploys, messenger)
– libraries/ (verifier binaries, Poseidon, PatriciaMerkleTrie, common codecs)
– gas-swap, rate-limiter, batch-bridge, interfaces, mocks, misc
• src/test/ duplicates Solidity unit tests.
README for additional insights
• Confirms L1 vs L2 separation and contract responsibilities.
• Specifies toolchain: Node.js + Yarn, Foundry for build and unit tests, Hardhat for integration.
Main components and their interactions
a. On-Chain Components
• Ethereum L1:
– L1ScrollMessenger: receives proof commitments from L2 and finalizes them
– Rollup contracts (data availability, state root commit)
– Gateway router + token gateways (USDCGateway, others) to move tokens/chains messages
• Scroll L2:
– L2ScrollMessenger: passes user messages to L1
– Gateway router + token gateways to accept deposits and route withdrawals
– Predeploys: system contracts pre-loaded at genesis
– Utility contracts (gas-swap, rate-limiter)
• Shared libraries:
– Verifier libraries (PLONK, Poseidon hash, PatriciaMerkleTrie) used by rollup and gateways for proof verification
b. Off-Chain Components
• Deployment scripts (scripts/hardhat, scripts/foundry) that compile, deploy, and configure contracts
• Testing frameworks:
– Foundry (forge build/test) for unit tests
– Hardhat (npx hardhat test) for integration tests
• GitHub Actions workflows for CI (contracts.yml, docker-release)
c. Data flows
• User deposits on L1 → L1Gateway → L2 predeploy → credited on L2
• User triggers withdrawal on L2 → L2Gateway → proof generated off-chain → L1ScrollMessenger finalizes on L1
• Rollup sequencer submits batch commitment → proof verification via verifier libs on L1 rollup contract → L1 records state root
Architectural patterns and principles
• Layer separation: L1 vs L2 codebases clearly isolated in directories
• Modular gateways: a router delegates to specific token gateway contracts
• Library approach: cryptographic primitives and verifier binaries stored separately and imported
• Scripts + multi-toolchain build: support both Foundry (Rust-based) and Hardhat (TypeScript) flows
Relevant technologies and frameworks
• Solidity (contracts in src/)
• Foundry (forge build, forge test)
• Hardhat (npx hardhat compile, test)
• TypeScript (scripts/, hardhat.config.ts)
• Submodules: ds-test, forge-std, solmate
• Verifier binaries (plonk, poseidon) under src/libraries/verifier