Run a local Lineth Stack

The Lineth Stack quickstart starts a local L2 chain, deploys the required contracts, and verifies L1 finality through finalizeBlocks. A guided wizard walks you through the configuration, so you choose how the stack settles to L1 and how it proves blocks, then start it from a single command.

Lineth Stack is the Linea zk-rollup stack documented in this Stack section. This quickstart is intended for operators, architects, and engineers evaluating how the stack behaves before designing a deeper 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 L2 with these services. For component details, see Protocol components.

• Linea Besu sequencer and an L2 Besu RPC follower
• Maru consensus layer client
• Shomei state manager
• Coordinator for batching, proof orchestration, L2 message data anchoring, and submissions
• Postman for L1-to-L2 and L2-to-L1 message relay
• Web3Signer for generated runtime signer keys used by Coordinator and Postman
• Prover 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.

Before you start

Required for all modes. These are quickstart minimums for the monorepo stack:

These requirements are quickstart guidance and may change as the Lineth Stack evolves. For the latest values, check the Lineth Stack docs in the monorepo before running the stack.

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

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

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.

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 is the recommended way to configure the quickstart. It asks a short 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.

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.

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.

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/.

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.

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.