Run a local Lineth Stack

This quickstart guide walks you through starting a local LinethLineth (Formerly the Linea Stack) The open-source ZK-rollup stack, codebase, and technical protocol that's the foundation of Linea Mainnet. Operators can deploy this stack to launch their own Ethereum-compatible L2 or L3 networks. chain, deploying the required contracts, and verifying L1 finality. You will choose how the stack settles to L1 and how it proves blocks.

This quickstart is intended for operators, architects, and engineers evaluating how the stack behaves before designing a production deployment.

caution

This quickstart is not a production deployment model. It uses local-dev identity and mTLS material, generated quickstart wallets, dev-proof mode by default, and quickstart-only verifier configuration. Do not reuse generated or committed quickstart material in production.

What this quickstart runs

The quickstart runs a local Lineth Stack L2Layer 2 (L2) A separate blockchain that increases transaction speed and throughput, while deriving its security from Ethereum. L2s rely on Ethereum for data availability by posting their transaction data onto Ethereum. with these services. For component details, see Deployment components.

• Linea Besu sequencerSequencer The component of Linea's execution client responsible for ordering, building, and executing blocks in a way that allows the subsequent ZK proof to be made. It's implemented as a set of plugins extending Linea Besu, including the tracer and conflator. There's typically one sequencer per network. and an L2 Besu RPC followerRPC node A full node configured to expose JSON-RPC APIs to applications and users, optionally behind load balancers and RBAC. RPC nodes can be optimized for low-latency access to near-head state, or configured as archive nodes for historical queries.
• MaruMaru Linea's consensus layer client. Maru runs on validator nodes to coordinate block production with the execution layer, manage validator sets and consensus participation, and provide peer-to-peer networking for block propagation, using the Quorum Byzantine Fault Tolerance (QBFT) consensus algorithm. consensus layer client
• ShomeiShomei A state manager that communicates with Linea Besu, via a corresponding plugin, to maintain and update network state using sparse Merkle trees. Shomei is the component behind Lineth's state manager. state manager
• CoordinatorCoordinator Linea's coordination module for batching, proof generation, and finality submission. The coordinator monitors block production, manages conflation deadlines, batches blocks, combines batches into blobs, orchestrates execution, compression, and aggregation proofs, and submits proofs and data to the finalization layer. for batching, proof orchestration, L2 message data anchoring, and submissions
• PostmanPostman The service that relays messages between the canonical message service contracts on Linea and Ethereum. Postman listens for calls made to the contract on one network and passes the submitted information to the contract on the other network. It's currently centralized, but is intended to be decentralized. for L1-to-L2 and L2-to-L1 message relay
• Web3SignerWeb3Signer An open-source, remote signing service that externalizes private key management from nodes. Web3Signer integrates with enterprise-grade key stores and exposes HTTP-based signing APIs so consensus and execution clients can obtain signatures on blocks, attestations, and transactions without directly holding the private keys. for generated runtime signer keys used by the coordinator and Postman
• ProverProver The Lineth component that generates ZK proofs of state transitions, handling proof-generation requests from the coordinator and Linea Besu. The prover produces three types of proofs (execution, compression, and aggregation) and combines them into a zk-SNARK that the finalization layer verifies. Provers may be scaled horizontally to meet throughput requirements. for proof generation
• Local L2 Blockscout block explorer, including API backend and frontend

The L2 is always local. What differs between modes is where the stack settles its L1 finality: public Sepolia, which is the primary path, or a local development L1 that the stack runs for you for easier testing.

Prerequisites

The following is required for both Sepolia and local L1 mode:

Requirement	Minimum
Docker	v24+
Docker Compose	v2.19+
Shell	POSIX-compatible shell such as sh, bash, or zsh
RAM, dev-proof mode	8 GB Docker Desktop minimum
RAM, partial-proof mode	32 GB minimum assigned to Docker; 128 GB recommended
Disk	About 30 GB free

The following is required only for Sepolia mode:

Requirement	Minimum
Sepolia RPC	Reliable HTTPS endpoint: a paid RPC plan, or your own Sepolia node
Sepolia ETH	Enough for deployment and runtime account top-ups

note

These requirements may change as the Lineth Stack evolves. See the latest values in the monorepo.

For the normal quickstart flow, you do not need host Node.js, pnpm, Foundry, or Gradle; the required tooling runs in Docker.

The Lineth prover image is linux/amd64 only. On Apple Silicon, choose the Dev proofs prover mode, which is the default. Partial proving is much slower on M-series machines.

Steps

1. Configure and start the stack

Clone the Lineth monorepo, then run the wizard:

git clone https://github.com/LFDT-Lineth/lineth-monorepo.git
cd lineth-monorepo/docs/getting-started/lineth-stack
./scripts/start.sh --wizard

The wizard asks a series of questions, writes your .env file, and can start the stack for you. If a .env file already exists, the wizard backs it up before making changes.

The wizard asks for:

1. L1 mode: Local L1 or Sepolia. See Choose your L1 mode below.
2. Prover mode: Dev proofs (default, fast dummy proofs for laptops and demos) or Partial prover (real partial proving, resource-heavy).
3. Sepolia L1 RPC URL: asked only when you choose Sepolia mode.
4. Next step: what to do after writing .env:
   • Save .env only, and do not start now.
   • Save .env and start the stack, reusing any existing quickstart containers and volumes.
   • Save .env, clear existing quickstart state, then start the stack. This runs ./scripts/reset.sh first.
   • Cancel and leave .env unchanged.

When you choose to start, the wizard runs the same guided boot flow as ./scripts/start.sh --tail: it checks ports, checks the L1 network, generates runtime wallets, Web3Signer key config, L2 genesis, and service configuration, pulls Docker images, starts services, deploys contracts, prints links, waits for first finality, and prints the result.

Choose your L1 mode

Both modes exercise L1 finality. Sepolia is the primary path, since it settles against public Sepolia and exercises real public L1 finality. Local L1 is offered for ease of testing when you want a faster, self-contained run.

• Sepolia settles against public Sepolia. It needs a reliable Sepolia RPC endpoint, which can be either a paid RPC plan or your own local Sepolia node, plus a funded deployer account. Check current Sepolia gas conditions in your RPC provider or explorer before you start, and make sure the deployer has enough ETH to cover deployment and runtime top-ups at current gas. The quickstart currently requires at least 2 ETH on the generated deployer; 3 ETH gives more room during Sepolia congestion.
• Local L1 is offered for ease of testing. The stack runs a quickstart-scoped Besu and Teku L1 inside the same Compose stack, so there is no external RPC, no real ETH, and no public gas spend, which makes it handy for repeatable development, CI, and demos. The wizard clears L1_RPC_URL for this mode. Local L1 mode has no Etherscan and no public settlement; bridge and finality flows still run against contracts deployed on the local L1.

Fund the deployer in Sepolia mode

On a clean Sepolia checkout, the first start generates an encrypted deployer keystore under artifacts/accounts/deployer-keystore/, prints the generated deployer address and funding requirement, then exits before the Docker pull and startup.

Fund that generated Sepolia address, then start again:

./scripts/start.sh --tail

Keep the terminal open until it reports that first L1 finalization was observed.

2. Verify first finality

After first finality, check status and links:

./scripts/status.sh
./scripts/links.sh

Treat the run as successful when status.sh confirms:

• Deployed addresses are present
• Coordinator is reachable
• Prover request and response counts are above zero
• A blob transaction appears as Data Availability only
• A separate finalization transaction advances rollup currentL2BlockNumber

caution

Do not treat Submit Blobs as finalization. Blob submission publishes data for data availability. Only a successful finalizeBlocks transaction advances the Sepolia rollup finalized state.

In Sepolia mode, finalization may appear on Sepolia Etherscan as method selector 0x755bc62f instead of a decoded name. For the current quickstart rollup contract, that selector corresponds to finalizeBlocks(bytes,uint256,FinalizationDataV4). Etherscan may display the struct argument as tuple because Solidity structs are ABI-encoded as tuples.

3. (Optional) Run traffic and bridge smokes

Local L2 traffic and bridge smoke scripts are optional verification steps after first finality.

If your shell reports permission denied for a script, make it executable from the Lineth Stack directory, for example chmod +x scripts/*.sh scripts/traffic-generation/*.sh scripts/smoke-test/*.sh, then retry.

Run local L2 traffic when you want visible Blockscout activity:

./scripts/traffic-generation/send-l2-test-tx.sh
./scripts/traffic-generation/send-l2-erc20-transfer.sh
./scripts/traffic-generation/generate-l2-erc20-traffic.sh start
./scripts/traffic-generation/generate-l2-erc20-traffic.sh logs
./scripts/traffic-generation/generate-l2-erc20-traffic.sh stop

The demo ERC20Example token is not part of base boot. Traffic and ERC20 bridge smoke scripts deploy or reuse it on demand.

Run bridge smoke tests when you want to verify message relay and TokenBridge flows:

./scripts/smoke-test/smoke-bridge-message.sh
./scripts/smoke-test/smoke-bridge-erc20-l1-to-l2.sh
./scripts/smoke-test/smoke-bridge-erc20-l2-to-l1.sh
./scripts/smoke-test/smoke-bridge-message-l2-to-l1.sh

These scripts cover generic message relay in both directions and ERC20 TokenBridge deposit and withdrawal. They do not test ETH withdrawals. In Sepolia mode, bridge smokes spend real Sepolia gas.

4. Generated files

The quickstart writes generated runtime files under artifacts/. These include generated wallets, Web3Signer key config, L2 genesis files, rendered service configuration, deployment addresses, and timing data.

Do not edit these files manually during a normal run. Use ./scripts/reset.sh to regenerate them. Keep .env as the single runtime config file, and do not commit .env or files under artifacts/.

5. Export evidence

Export a local support bundle when you need files to share or archive:

./scripts/export-output.sh

The command writes lineth-output/, including addresses, useful links, finality status, smoke-test status if smoke tests were run, deploy logs, and timing evidence. The output directory is ignored by git.

6. Stop or reset

Stop the stack while keeping state:

docker compose --env-file versions.env --env-file .env --profile stack-partial-prover stop

The raw Compose commands use --profile stack-partial-prover because it is the quickstart's main Compose profile. The default PROVER_DEV_OVERRIDE=true still runs dev-proof behavior inside that profile.

Add --profile local-l1 when stopping a stack started in local L1 mode.

Wipe generated artifacts, Docker volumes, chain data, and deploy caches:

./scripts/reset.sh

./scripts/reset.sh preserves the generated Sepolia deployer keystore by default, so funded test ETH is not stranded by routine local resets. Use ./scripts/reset.sh --forget-deployer only when you intentionally want a new generated Sepolia deployer.

Advanced

Configure .env manually

The wizard is the recommended path, but you can configure the quickstart by hand if you prefer to edit .env directly or script the setup. Copy the example file, set the values for your mode, then start with --tail:

cp .env.example .env
$EDITOR .env

For Sepolia mode, set:

L1_MODE=sepolia
L1_RPC_URL=https://sepolia.infura.io/v3/<your-project-id>

For local L1 mode, set:

L1_MODE=local
PROVER_DEV_OVERRIDE=true

In local L1 mode, L1_RPC_URL can stay empty and Sepolia deployer settings are ignored. Then start the stack:

./scripts/start.sh --tail

Advanced debugging

Use raw Compose logs only when debugging. The official start flow is the wizard or ./scripts/start.sh --tail.

The stack-partial-prover profile name is the quickstart Compose profile name; it does not mean PROVER_DEV_OVERRIDE=false is enabled.

docker compose --env-file versions.env --env-file .env --profile stack-partial-prover logs -f --tail=120

Add --profile local-l1 when reading raw Compose logs for a stack started in local L1 mode, especially if you need local L1 service logs.

For a narrower service log view:

docker compose --env-file versions.env --env-file .env --profile stack-partial-prover logs -f --tail=120 \
  deploy-contracts coordinator prover postman sequencer shomei l2-node-besu

Reattach to the guided progress view with:

./scripts/watch.sh

Known limitations

• This quickstart is monorepo-bound. Deploy tooling uses contracts and scripts from the repository checkout.
• Sepolia is the supported public L1 finality path. Using another external L1 requires configuration and timing review.
• Local L1 mode provides local L1 finality for development and testing; it does not prove public Sepolia finality.
• L1 contracts are owned by the generated deployer account. Timelock and Security Council flows are out of scope.
• Dev-proof mode is the recommended evaluation path. Partial proving is opt-in and resource-heavy.
• Full proving is out of scope.
• This quickstart supports Rollup mode only.
• The verifier setup is quickstart-only and does not represent production verifier configuration.
• ERC20 bridge deposit and withdrawal smokes are included; ETH withdrawal smoke is not included.

Next steps

• Review the Trust model.
• Compare deployment models.
• Understand Data Availability and finalization.
• Review the protocol components.