Lineth

This is the principal Lineth repository. It mainly includes the smart contracts covering Lineth's core functions, the prover in charge of generating ZK proofs, the coordinator responsible for multiple orchestrations, and the Postman to execute bridge messages.

It serves developers by making the Lineth stack open source under the Apache 2.0 and the MIT licenses.

What is Lineth?

Lineth is a enterprise-ready layer 2 network scaling Ethereum. It's secured with a zero-knowledge rollup, built on lattice-based cryptography, and powered by Consensys and the Linea Consortium. It's the technology powering the Linea Mainnet.

Lineth is compatible with the execution clients Besu or Geth. To run a full node, an execution client is paired with the consensus client Maru.

Get started

If you already have an understanding of the tech stack, use our Get Started guide.

For developers looking to build services locally (such as, the coordinator), see our detailed Local Development Guide.

Agent Documentation

For AI coding agents and developer tools:

• Canonical instructions: AGENTS.md
• Claude Code entry point: CLAUDE.md
• GitHub Copilot entry point: .github/copilot-instructions.md
• Cursor documentation index: .cursor/rules/documentation.mdc
• Cursor review/rule set: .cursor/BUGBOT.md

Release workflows

Releases are driven by GitHub Actions workflows under .github/workflows. There are two flavors: per-component releases and milestone releases.

Release tag and version

Release tag of each component is in the format of releases/[component]/v[semver] and the semver version is computed from the relevant Git history commit messages using Conventional Commits format by using git-cliff

Preview a component's changelog and next version locally

The workflows do not keep a per-component cliff.toml. A single cliff.template.toml is rendered at run time by substituting the component's conventional-commit scopes into its @@SCOPES@@ placeholder, then git-cliff is run with that component's --include-path filter. A commit therefore counts only when it is both in-scope and touches a component path (scope-and-path gating).

You can reproduce exactly what a workflow computes. Prerequisites: install git-cliff (brew install git-cliff or cargo install git-cliff) and fetch tags (git fetch --tags). Run from the repo root:

# 1. Render the template with the component's scopes injected.
#    (see the per-component table below for SCOPES / tag-pattern / include-paths)
SCOPES='coordinator|deps|misc'
sed "s#@@SCOPES@@#${SCOPES}#g" cliff.template.toml > /tmp/cliff.rendered.toml

# 2. Show the NEXT bumped version tag for the component.
git cliff --config /tmp/cliff.rendered.toml --unreleased --bumped-version \
  --tag-pattern 'releases/coordinator/v[0-9]+\.[0-9]+\.[0-9]+$' \
  --include-path 'coordinator/**'

# 3. Show the [unreleased] changelog for the component.
git cliff --config /tmp/cliff.rendered.toml --unreleased \
  --tag-pattern 'releases/coordinator/v[0-9]+\.[0-9]+\.[0-9]+$' \
  --include-path 'coordinator/**'

Swap SCOPES, the --tag-pattern component, and the --include-path set per component:

Component	SCOPES	--tag-pattern component	--include-path(s)
coordinator	coordinator|deps|misc	coordinator	coordinator/**
maru	maru|deps|misc	maru	maru/**
postman	postman|deps|misc	postman	postman/**
prover	prover|deps|misc	prover	prover/**
tx-exclusion-api	tx-exclusion-api|deps|misc	tx-exclusion-api	transaction-exclusion-api/**
linea-besu-package	linea-besu|tracer|sequencer|deps|misc	linea-besu-package	tracer/**, tracer-constraints/**, linea-besu/plugins/linea-sequencer/**, linea-besu/besu/**, linea-besu/package/**, gradle/libs.versions.toml
linea (milestone)	coordinator|linea-besu|tracer|sequencer|maru|prover|postman|tx-exclusion-api|deps|misc	linea	the union of every component path above

Notes:

• cliff.template.toml is not runnable as-is — the @@SCOPES@@ placeholder must be substituted first. An un-rendered template matches no commits and git-cliff reports "There is nothing to bump".
• --bumped-version prints the full next tag (e.g. releases/coordinator/v1.2.3); drop it (as in step 3) to render the changelog instead. If nothing qualifies, git-cliff prints "There is nothing to bump" — meaning no release would be cut.
• These are the same scopes and include-path values the workflows pass to the run-git-cliff-commands action, so the local result matches CI.

Per-component release

Each component has its own release workflow. Run the one that matches the component you want to ship:

Component	Workflow	Release tag pattern
linea-besu	.github/workflows/linea-besu-release.yml	releases/linea-besu-package/v[semver]
coordinator	.github/workflows/coordinator-release.yml	releases/coordinator/v[semver]
maru	.github/workflows/maru-release-manual.yml	releases/maru/v[semver]
postman	.github/workflows/postman-release.yml	releases/postman/v[semver]
prover	.github/workflows/prover-release.yml	releases/prover/v[semver]
tx-exclusion-api	.github/workflows/tx-exclusion-api-release.yml	releases/tx-exclusion-api/v[semver]

Notes:

• Branches. A per-component release can be cut from either main or a feature branch (e.g. for a hot-fix release).
• Feature-branch restriction. When the workflow is run from a feature branch, release_tag_suffix is required (e.g. producing releases/coordinator/v1.2.3-hotfix). Without a suffix the new tag could collide with tags produced from other branches.
• Docker image suffix. image_tag_suffix is optional.
• GitHub Release page. Each successful run publishes a GitHub Release containing the updated component CHANGELOG.md and the docker image pull instructions.

Milestone release

Milestone releases bundle every component into a single Lineth release.

• Workflow: .github/workflows/linea-milestone-release-with-dry-run.yml
• Release tag pattern: releases/linea/v[semver]
• Branch: can only be run from main.

Unified-cut behavior

For each component, the milestone workflow decides between two paths based on whether the component's release version has bumped at the milestone commit:

• Bumped → release the component. A new per-component release is cut as part of the milestone (new tag, docker image, GitHub Release page).
• Not bumped → do nothing. No new component release is cut. The existing docker image associated with the component's latest release tag will be shown on the milestone release page.

The milestone GitHub Release page aggregates the CHANGELOG entries from every component (newly released or carried over) and lists their docker image pull instructions.

Dry-run on a temporary branch before releasing on main

The milestone workflow defaults to running a dry run on a temporary branch forked from the latest main before touching main itself. This catches issues (e.g. failing e2e, docker push permission gaps, changelog generation errors) without leaving any artifacts on main. The job graph is:

1. create-temp-branch-and-dispatch-release — forks a new branch ci/milestone-dry-run-<timestamp> from origin/main and dispatches the linea-milestone-release.yml workflow against it. All artifacts (i.e. tags and GitHub releases) produced in the dispatched run will be thrown away later in later workflow.
2. manual-run-release-on-main — guarded by the run-release-on-main GitHub Environment, this job blocks on manual approval in the GitHub UI. Reviewers should:
   • Open the dispatched milestone run (URL is printed in the kickoff job's summary) and confirm every job (build, e2e, per-component gh-release, milestone gh-release) succeeded against the temp branch.
   • Spot-check the draft GitHub Releases that the dry run produced (they are clearly suffixed with -dry-run-<timestamp>).
   • Approve the environment gate to proceed with the real release on main, or reject to abort.
3. dry-run-release-cleanup — runs after the manual gate is approved. It waits for the dispatched dry-run to reach a terminal state and then removes every artifact the dry run created:
   • GitHub releases + git tags — enumerates tags reachable from the temp branch but not from origin/main and removed all of them with their associated releases.
   • Temp branch — git push origin --delete ci/milestone-dry-run-<timestamp>.
   • Please note that no images will be pushed to Docker Hub during dry run release.
4. milestone-release-on-main — only runs after the manual gate is approved. Calls linea-milestone-release.yml against main.

Looking for the Lineth code?

Linea's stack is made up of multiple repositories, these include:

• This repo, lineth-monorepo: The main repository for the Lineth stack & Linea network

Also maintains a set of Linea-Besu plugins for the sequencer and RPC nodes.

• linea-besu: Besu build configured for Linea (now in-tree; previously Consensys/linea-besu-upstream)
• tracer: Linea-Besu plugin which produces the traces that the constraint system applies and that serve as inputs to the prover (now in-tree; previously Consensys/linea-tracer)
• tracer-constraints: Implementation of the constraint system from the specification (now in-tree; previously Consensys/linea-constraints)
• maru: Consensus client for the Linea sequencer (now in-tree; previously Consensys/maru)
• linea-specification: Specification of the constraint system defining Linea's zkEVM

Linea abstracts away the complexity of this technical architecture to allow developers to:

• Bridge tokens
• Deploy a contract
• Run a node

... and more.

How to contribute

Contributions are welcome!

Guidelines for non-code and other trivial contributions

Please keep in mind that we do not accept non-code contributions like fixing comments, typos or some other trivial fixes. Although we appreciate the extra help, managing lots of these small contributions is unfeasible, and puts extra pressure in our continuous delivery systems (running all tests, etc). Feel free to open an issue pointing to any of those errors, and we will batch them into a single change.

1. Create an issue

If the proposed update is non-trivial, also tag us for discussion.

2. Submit the update as a pull request from your fork of this repo, and tag us for review.

Include the issue number in the pull request description and (optionally) in the branch name.

Consider starting with a "good first issue".

Commit message format

All commits must follow the Conventional Commits format, enforced locally by a Husky commit-msg hook:

<type>(<scope>): <short description>

[optional body]

[optional footer: Closes #<issue>, BREAKING CHANGE: ...]

Allowed types: feat, fix, docs, style, refactor, perf, test, chore, ci, revert, build

Required scope (one or multiple of):

Scope	Area
coordinator	Coordinator service
maru	Maru consensus client
prover	Prover
prover-ray	Prover Ray (RISC-V)
postman	Message bridging and executor
tx-exclusion-api	Transaction exclusion API
linea-besu	Linea-Besu package & plugins
tracer	Tracer
sequencer	Sequencer
state-recovery	State recovery
contracts	Smart contracts
sdk-core / sdk-ethers / sdk-viem	SDKs
jvm-libs	JVM shared libraries
blob-libs	Blob libraries
e2e	End-to-end tests
ci	CI/CD workflows
docker	Docker / compose
deps	Dependency updates
misc	For anything that does not have impact on deliverable, e.g docs, configs, AI agents, etc

Examples:

feat(coordinator): add retry logic for L1 message sending

Retries up to 3 times on transient network errors before failing.

Closes #456

chore(coordinator,sequencer,tracer,tx-exclusion-api): update to java 25

To write a single-line breaking change commit from the terminal:

git commit -m 'feat(coordinator)!: breaking changes'

To write a multi-line commit from the terminal:

git commit -m $'feat(coordinator): add retry logic\n\nRetries up to 3 times on transient network errors.\n\nCloses issue# 123'

To bypass the commit-msg hook: (USE WITH CAUTION)

git commit -m 'Just some trivial changes could find proper prefix and irrelevant to version change' --no-verify

Before contributing, ensure you're familiar with:

• Our contribution guide
• Our code of conduct
• The Besu contribution guide, for Besu:Linea related contributions
• Our security policy

PR title

PR titles must follow the same Conventional Commits format as commit messages (see Commit message format above for the allowed <type>(<scope>): <short description> shape, types, and scopes).

This matters because PRs are squash-merged into main: GitHub uses the PR title as the single resulting commit message on main. Our release tooling — git-cliff, which drives automated version bumps and CHANGELOG.md generation in the release workflows — parses those commit messages to decide the next semver bump and to categorize entries in the changelog. A non-conforming PR title turns into a non-conforming commit on main, which means:

• No automatic version bump for the affected component (git-cliff will skip it).
• Missing or miscategorized changelog entry on the next release.

Examples of good PR titles:

feat(coordinator): add retry logic for L1 message sending
fix(prover): correct integer overflow in trace builder
chore(linea-besu,sequencer): bump dependency versions
feat(coordinator)!: rename public API method (BREAKING CHANGE)

Please note that the lineth-monorepo GitHub CI will lint the PR title when new commits pushed to the PR branch, and the whole CI will fail if the PR title doesn't conform.

Useful links

• Linea docs managed from a public repo
• Linea blog
• Support
• X