base
diff --git a/‎.env‎
Lines changed: 0 additions & 1 deletion b/‎.env‎
Lines changed: 0 additions & 1 deletion
diff --git a/‎.github/workflows/test.yml‎
Lines changed: 17 additions & 13 deletions b/‎.github/workflows/test.yml‎
Lines changed: 17 additions & 13 deletions
diff --git a/‎.gitignore‎
Lines changed: 44 additions & 4 deletions b/‎.gitignore‎
Lines changed: 44 additions & 4 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 97 additions & 64 deletions b/‎CLAUDE.md‎
Lines changed: 97 additions & 64 deletions
diff --git a/‎Makefile‎
Lines changed: 20 additions & 20 deletions b/‎Makefile‎
Lines changed: 20 additions & 20 deletions
diff --git a/‎book/.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎book/.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎book/LICENSE‎
Lines changed: 21 additions & 0 deletions b/‎book/LICENSE‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎book/book.toml‎
Lines changed: 18 additions & 0 deletions b/‎book/book.toml‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎book/custom.css‎
Lines changed: 5 additions & 0 deletions b/‎book/custom.css‎
Lines changed: 5 additions & 0 deletions
@@ -1,2 +1 @@
-OP_COMMIT=3056348b21a07e584225310bbc27f1adce5ca2a9
 BASE_MAINNET_URL=https://mainnet.base.org
@@ -28,25 +28,29 @@ jobs:
         with:
           version: stable
 
-      - name: Show Forge version
-        run: |
-          forge --version
+      - name: Install Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        with:
+          go-version-file: scripts/go-ffi/go.mod
+          cache-dependency-path: scripts/go-ffi/go.sum
 
-      - name: Run Forge fmt
-        run: |
-          forge fmt --check
-        id: fmt
+      - name: Install just
+        run: curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+
+      - name: Show Forge version
+        run: forge --version
 
       - name: Install dependencies
-        run: |
-          make deps
+        run: make deps
+
+      - name: Run Forge fmt check
+        run: just lint-check
+        id: fmt
 
       - name: Run Forge build
-        run: |
-          forge build --sizes
+        run: just forge-build
         id: build
 
       - name: Run Forge tests
-        run: |
-          forge test -vvv
+        run: just test
         id: test
@@ -1,8 +1,48 @@
-lib/**
-cache/***
-out/**
+# Artifacts and Cache
+artifacts
+forge-artifacts
+cache
+broadcast
+kout-proofs
+test/kontrol/logs
+out
+lib
 
-.gitmodules
+# Metrics
+coverage.out
+.resource-metering.csv
 
+# Testing State
+.testdata
+kontrol_prove_report.xml
+
+# Scripts
+scripts/go-ffi/go-ffi
+scripts/go-ffi/go-ffi-cannon64
+
+# Environment Variables
+.envrc
+!.envrc.example
+
+# Deployments
+deployments/900
+deployments/901
+deployments/hardhat
+deployments/getting-started
+deployments/*/.deploy
+deployments/1337
+deployments/31337-deploy.json
+deployments/kontrol.json
+deployments/kontrol.jsonReversed
+deployments/kontrol-fp.json
+deployments/kontrol-fp.jsonReversed
+deployments/1-deploy.json
+
+# Getting Started guide deploy config
+deploy-config/getting-started.json
+
+# IDE
 /.idea/
+
+# OS
 .DS_Store
@@ -4,67 +4,100 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This repository contains Solidity smart contracts and deployment scripts for Base, an Ethereum L2 using Optimism's bedrock architecture. The codebase includes revenue sharing contracts, smart escrow functionality, fee vault fixes, multisig deployment utilities, and challenger contracts.
-
-## Environment Setup
-
-Before working with this codebase:
-1. Ensure you have an `.env` file with `OP_COMMIT` variable set (required for dependency management)
-2. Run `make deps` to install all dependencies including Optimism contracts at the specified commit
-
-## Common Commands
-
-### Development Commands
-- `make deps` - Install all dependencies (foundry, OpenZeppelin, Optimism contracts)
-- `make test` - Run all tests with verbose output and FFI enabled
-- `forge build` - Build all contracts
-- `make bindings` - Generate Go bindings for BalanceTracker and FeeDisburser contracts
-
-### Setup Commands
-- `make install-foundry` - Install Foundry toolkit (if not already installed)
-- `make clean-lib` - Clean lib directory
-
-## Architecture Overview
-
-### Core Contract Categories
-
-1. **Revenue Share System** (`src/revenue-share/`)
-   - `BalanceTracker.sol` - Manages funding of system addresses and profit distribution
-   - `FeeDisburser.sol` - Handles fee disbursement logic
-
-2. **Smart Escrow** (`src/smart-escrow/`)
-   - `SmartEscrow.sol` - Vesting contract for OP token payments with termination capabilities
-
-3. **Fee Vault Fixes** (`src/fee-vault-fixes/`)
-   - `FeeVault.sol` - Enhanced fee vault implementation
-
-4. **Challenger System** (`src/`)
-   - `Challenger1of2.sol` - Deprecated 1-of-2 challenger contract (pre-fault proofs)
-
-5. **Multisig Utilities** (`script/universal/`)
-   - Complete multisig deployment and management system with nested and double-nested capabilities
-   - Includes signature handling, simulation, and deployment scripts
-
-### Test Structure
-- Tests mirror the `src/` directory structure
-- Uses Foundry's testing framework with FFI enabled
-- Common test utilities in `test/CommonTest.t.sol`
-- Mock contracts available in `test/*/mocks/` directories
-
-### Dependencies
-- Built on Foundry with Solidity 0.8.15
-- Uses OpenZeppelin contracts v4.9.3 for core functionality
-- Integrates with Optimism bedrock contracts (version specified by OP_COMMIT)
-- Includes Solmate and Solady for additional utilities
-
-### Contract Deployment
-- L1 and L2 deployment scripts in `script/deploy/`
-- Test deployment scripts for both layers
-- Universal deployment utilities for cross-chain operations
-
-## Important Notes
-
-- This repository primarily extends Optimism's bedrock contracts rather than replacing them
-- The OP_COMMIT environment variable controls which version of Optimism contracts to use
-- Contracts use 999999 optimizer runs for maximum gas efficiency
-- All contracts target Solidity 0.8.15 for consistency
+Base contracts repository — an Optimism Bedrock-based L2 blockchain. Contains Solidity smart contracts for Base's L1 and L2 infrastructure, built on top of Optimism's contracts-bedrock (op-contracts/v6.0.0-rc.2). Uses Foundry (Forge) as the build/test framework.
+
+## Build & Development Commands
+
+All commands use `just` (justfile) unless noted. The Makefile handles initial setup only.
+
+### Setup
+```bash
+make install-foundry    # Install Foundry toolchain
+make deps               # Install all Solidity dependencies (forge install + manual clones)
+just build-go-ffi       # Build the Go FFI tool (required before running tests)
+```
+
+### Building
+```bash
+just build              # Production build (runs lint-fix first, optimizer_runs=999999)
+just build-dev          # Fast dev build (FOUNDRY_PROFILE=lite, no optimization)
+just build-source       # Build src/ only (skip tests and scripts)
+```
+
+### Testing
+```bash
+just test               # Run all tests (builds go-ffi first)
+just test-dev           # Fast dev tests (lite profile, 8 fuzz runs)
+just test -- --match-test "test_myFunction"        # Run a single test by name
+just test -- --match-contract "MyContract"          # Run tests in a specific contract
+just test -- --match-path "test/L1/*"               # Run tests matching a path
+just test-rerun         # Re-run only failed tests with verbose output
+just test-upgrade       # Fork tests against mainnet/sepolia (requires ETH_RPC_URL)
+just coverage           # Coverage report
+```
+
+### Linting & Formatting
+```bash
+just lint               # Format + check (forge fmt)
+just lint-check         # Check only (no auto-fix)
+forge fmt               # Direct format command
+```
+Line length: 120 chars. Multiline function headers: all params on separate lines.
+
+### Pre-PR Workflow
+```bash
+just pre-pr             # Full workflow: build-dev, lint, build-source, all checks
+just pre-pr --clean     # Same but cleans build artifacts first
+just check              # Run all validation checks without building
+```
+
+### Snapshots & Semver
+```bash
+just snapshots          # Regenerate ABI/storage snapshots and semver-lock
+just snapshots-check    # Verify snapshots are up to date
+```
+
+## Architecture
+
+### Contract Structure (src/)
+- **L1/**: Ethereum mainnet contracts — `OPContractsManager.sol` (central upgrade manager), `OptimismPortal2.sol` (proof finalization), `SystemConfig.sol`, `SuperchainConfig.sol`
+- **L2/**: L2 contracts — `L1Block.sol`, `L2StandardBridge.sol`, `CrossL2Inbox.sol`, `SuperchainERC20.sol`
+- **dispute/**: Fault proof game contracts with v1, v2, and zk variants
+- **cannon/**: Cannon VM contracts (MIPS-based fault proof execution)
+- **universal/**: Cross-chain utilities (bridges, messengers)
+- **libraries/**: Shared libraries — `Constants.sol`, `Predeploys.sol` (canonical L2 addresses), `Preinstalls.sol`
+- **periphery/**: Non-core contracts (drippie, faucet, monitoring)
+- **safe/**: Safe multisig extensions
+- **governance/**, **recovery/**, **revenue-share/**, **smart-escrow/**: Domain-specific contracts
+
+### Interfaces (interfaces/)
+Separate directory for contract interfaces, mirroring the src/ structure. Go checks (`scripts/checks/interfaces`) validate that interfaces match their implementations.
+
+### Test Structure (test/)
+- Mirrors `src/` directory layout
+- `CommonTest.t.sol`: Base test class with standard accounts (alice, bob, admin, deployer)
+- `test/setup/Setup.sol`: Full system deployment setup using `Deploy.s.sol`
+- `test/setup/FeatureFlags.sol`: Development feature gating for tests
+- `test/mocks/`: 20+ mock contracts
+- `test/invariants/`: Property-based invariant tests
+- `test/kontrol/`: K framework formal verification proofs
+- FFI enabled: tests can call external programs via `scripts/go-ffi/`
+
+### Deployment (scripts/)
+- `scripts/deploy/Deploy.s.sol`: Main deployment script
+- Input/Output pattern (`BaseDeployIO.sol`): Modular deployment composition
+- `deploy-config/`: JSON configs per network (mainnet.json, sepolia.json, hardhat.json)
+- `scripts/L2Genesis.s.sol`: L2 genesis state generation
+
+## Key Patterns
+
+- **Proxy pattern**: EIP-1967 transparent proxies for upgradeability
+- **Compilation restrictions**: Dispute game contracts and OPContractsManager use 5000 optimizer runs (not 999999) due to size constraints. The `lite` profile mirrors these restrictions with 0 runs.
+- **Foundry profiles**: `default` (production), `lite` (dev), `ci` (128 fuzz runs), `ciheavy` (20000 fuzz runs)
+- **Semver tracking**: Contracts use semantic versioning tracked in `snapshots/semver-lock.json`
+- **Storage spacers**: Validated by `scripts/checks/spacers` to prevent storage layout conflicts in upgradeable contracts
+- **Solidity version**: 0.8.15 for main contracts, some use ^0.8.0
+
+## CI
+
+GitHub Actions runs on PR: `forge fmt --check` → `make deps` → `forge build --sizes` → `forge test -vvv` with `FOUNDRY_PROFILE=ci`.
@@ -1,4 +1,4 @@
-include .env
+-include .env
 
 ##
 # Solidity Setup / Testing
@@ -9,13 +9,24 @@ install-foundry:
 	~/.foundry/bin/foundryup
 
 .PHONY: deps
-deps: clean-lib checkout-op-commit
-	forge install --no-git github.com/foundry-rs/forge-std \
-		github.com/OpenZeppelin/openzeppelin-contracts@v4.9.3 \
-		github.com/OpenZeppelin/openzeppelin-contracts-upgradeable@v4.7.3 \
-		github.com/rari-capital/solmate@8f9b23f8838670afda0fd8983f2c41e8037ae6bc \
-		github.com/Vectorized/solady@862a0afd3e66917f50e987e91886b9b90c4018a1 \
-		github.com/safe-global/safe-smart-account@v1.4.1-3
+deps: clean-lib
+	forge install --no-git \
+		github.com/foundry-rs/forge-std@6853b9ec7df5dc0c213b05ae67785ad4f4baa0ea \
+		github.com/runtimeverification/kontrol-cheatcodes@2c48ae1ab44228c199dca29414c0b4b18a3434e6 \
+		github.com/ethereum-optimism/lib-keccak@3b1e7bbb4cc23e9228097cfebe42aedaf3b8f2b9 \
+		github.com/OpenZeppelin/openzeppelin-contracts@ecd2ca2cd7cac116f7a37d0e474bbb3d7d5e1c4d \
+		github.com/OpenZeppelin/openzeppelin-contracts-upgradeable@0a2cb9a445c365870ed7a8ab461b12acf3e27d63 \
+		github.com/transmissions11/solmate@8f9b23f8838670afda0fd8983f2c41e8037ae6bc \
+		github.com/safe-global/safe-contracts@bf943f80fec5ac647159d26161446ac5d716a294 \
+		github.com/Vectorized/solady@502cc1ea718e6fa73b380635ee0868b0740595f0
+	forge install --no-git \
+		github.com/ethereum-optimism/superchain-registry@84bce73573f130008d84bae6e924163bab589a11
+	@# openzeppelin-contracts-v5 and solady-v0.0.245 use the same orgs as their
+	@# counterparts but are pinned to different commits, so we clone them manually.
+	git clone --no-checkout https://github.com/OpenZeppelin/openzeppelin-contracts.git lib/openzeppelin-contracts-v5 && \
+		cd lib/openzeppelin-contracts-v5 && git checkout dbb6104ce834628e473d2173bbc9d47f81a9eec3
+	git clone --no-checkout https://github.com/Vectorized/solady.git lib/solady-v0.0.245 && \
+		cd lib/solady-v0.0.245 && git checkout e0ef35adb0ccd1032794731a995cb599bba7b537
 
 .PHONY: test
 test:
@@ -25,22 +36,11 @@ test:
 clean-lib:
 	rm -rf lib
 
-.PHONY: checkout-op-commit
-checkout-op-commit:
-	[ -n "$(OP_COMMIT)" ] || (echo "OP_COMMIT must be set in .env" && exit 1)
-	rm -rf lib/optimism
-	mkdir -p lib/optimism
-	cd lib/optimism; \
-	git init; \
-	git remote add origin https://github.com/ethereum-optimism/optimism.git; \
-	git fetch --depth=1 origin $(OP_COMMIT); \
-	git reset --hard FETCH_HEAD
-
 .PHONY: bindings
 bindings:
 	go install github.com/ethereum/go-ethereum/cmd/abigen@v1.15.8
 	forge build
 	mkdir -p bindings
 	abigen --abi out/BalanceTracker.sol/BalanceTracker.abi.json --pkg bindings --type BalanceTracker --out bindings/balance_tracker.go
 	abigen --abi out/FeeDisburser.sol/FeeDisburser.abi.json --pkg bindings --type FeeDisburser --out bindings/fee_disburser.go
-	cd bindings && go mod tidy
+	cd bindings && go mod tidy
@@ -0,0 +1 @@
+book
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Optimism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,18 @@
+[book]
+authors = ["Optimism Contributors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "OP Stack Smart Contracts"
+
+[output.html]
+site-url = "/contracts-bedrock/"
+git-repository-url = "https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/book"
+edit-url-template = "https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/book/{path}"
+additional-css = ["custom.css"]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
+
+[preprocessor]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
@@ -0,0 +1,5 @@
+.content main {
+  max-width: 85%;
+  margin-left: auto;
+  margin-right: auto;
+}
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1 @@`
`1`		`-OP_COMMIT=3056348b21a07e584225310bbc27f1adce5ca2a9`
`2`	`1`	`BASE_MAINNET_URL=https://mainnet.base.org`