Skip to content

docs(stack): add Trust model page #1477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Othryades wants to merge 6 commits into
base: main
Choose a base branch
from
+111 −0
Draft

docs(stack): add Trust model page #1477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dc663da
docs(stack): add Trust model page
Othryades May 3, 2026
fe59dda
docs(stack): fix trust model contradictions and formatting
Othryades May 3, 2026
5c826e9
docs(stack): fix trust model admonition and remaining separators
Othryades May 3, 2026
9de69e1
docs(stack): broaden DA framing, polish trust model copy
Othryades May 3, 2026
cd6401c
docs(stack): rework deployment-model trust table for clarity
Othryades May 3, 2026
9a84638
docs(stack): align deployment-mode terminology across page
Othryades May 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions docs/stack/how-it-works/trust-model.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
title: Trust model
description: >-
Trust assumptions, control responsibilities, and failure modes for Linea stack
deployments
sidebar_position: 3
image: /img/socialCards/trust-model.jpg
---

This page describes the trust assumptions, control responsibilities, and failure modes of a Linea Stack deployment. It is meant for architects and operators evaluating Linea Stack before deployment.

What this page covers: who operates each component, what each component can do unilaterally, what participants can independently verify, what happens when something fails, and how trust assumptions change across deployment models.

What this page does not cover: configuration flags, deployment topology, or component internals. For those, see [Core components](./core-components) and [Deployment models](./deployment-models).

## Trust assumptions per component

| Component | Operated by | Can do unilaterally | Cannot do | Independently verifiable by participants |
| --- | --- | --- | --- | --- |
| Sequencer | Operator | Order, delay, or omit transactions within a block | Forge state, since invalid blocks fail proof verification | Block contents and ordering, by running a full or archive node |
| Prover | Operator | Stall proof generation, halting finalization | Produce a valid proof for an invalid state transition | Proof verification by reading the verifier contract on the finalization layer |
| Coordinator | Operator | Stall the pipeline that conflates blocks, requests proofs, and submits them to L1 | Modify state independently of the sequencer or prover | L1 submission events |
| Data availability (rollup) | Ethereum | N/A | Withhold data, since DA is on L1 as EIP-4844 blobs | State reconstruction from L1 blobs |
| Data availability (validium) | Operator-run archive nodes or DA committee | Withhold data, halting recovery | Forge state, since proofs still verify on L1 | What participants observe via access to the operator's DA layer |
| Canonical bridge (to Ethereum / Linea-anchored chain) | Operator (admin keys) + protocol (proofs) | Pause bridging via pause roles; upgrade contracts | Forge messages, since both sides verify ZK proofs | Bridge events and proof verification on the finalization layer |
| Trusted bridge (to private or non-anchored chain) | Operator (admin keys) + trusted relayer | Pause bridging; relayer can withhold or delay messages | Forge messages, since the relayer signs over verified source-chain events | Bridge events on each side; no shared proof, so verifiability depends on trust in the relayer |
| System contracts | Operator (role holders) | Pause, upgrade, change verifier address, change rate limits | Bypass role gating, since every privileged function is role-gated | Role assignments and contract state on the finalization layer |
| Participant nodes | Each participant | Read state visible to them, broadcast transactions | Modify network state | Their own observed state, by running a node |

## Admin keys and upgrade authority

The Stack contracts ship with a fixed set of roles. Holders are decided by the operator at deploy time. The most consequential decisions:

| Role | What it can do | Recommended holder |
| --- | --- | --- |
| `DEFAULT_ADMIN_ROLE` | Grant or revoke any other role | Multisig or governance contract; assignable only at initialization |
| `OPERATOR_ROLE` | Submit blobs/calldata, finalize blocks | Day-to-day operator address |
| `SECURITY_COUNCIL_ROLE` | Reserved for governance pause/upgrade authority | Governance contract |
| `PAUSE_*_ROLE` / `UNPAUSE_*_ROLE` | Pause and unpause specific subsystems (L1↔L2, L2→L1, finalization, state submission, etc.) | Split between operator (pause) and governance (unpause) for fast incident containment |

Check warning on line 39 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'unpause'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'unpause'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 39, "column": 179}}}, "severity": "WARNING"}

Check warning on line 39 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'unpause'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'unpause'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 39, "column": 49}}}, "severity": "WARNING"}
| `VERIFIER_SETTER_ROLE` | Change the verifier contract for a given proof type | Governance contract |
| `RATE_LIMIT_SETTER_ROLE` | Change L2→L1 withdrawal rate limits | Governance contract |

Contracts are upgradeable via the OpenZeppelin upgradeable proxy pattern. Upgrade authority is held by `DEFAULT_ADMIN_ROLE`. There is no protocol-enforced timelock: operators must implement timelocks via the governance contract holding the role.

Check warning on line 43 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'timelocks'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'timelocks'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 43, "column": 191}}}, "severity": "WARNING"}

Check warning on line 43 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[write-good.ThereIs] Don't start a sentence with 'There is'.

Raw Output:
{"message": "[write-good.ThereIs] Don't start a sentence with 'There is'.", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 43, "column": 126}}}, "severity": "WARNING"}

:::warning

`DEFAULT_ADMIN_ROLE` cannot be assigned through `__Permissions_init`. It is set only via the explicit `defaultAdmin` initializer field. Plan the holder before initialization.

Check warning on line 47 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'initializer'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'initializer'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 47, "column": 118}}}, "severity": "WARNING"}

:::

For the full list of roles, see [LineaRollup contracts reference](/network/build/contracts).

## Trust assumptions per deployment model

| Trust dimension | Rollup, finalized to Ethereum | Validium, finalized to Ethereum | Validium, finalized to Linea Mainnet |
| --- | --- | --- | --- |
| Data availability provided by | Ethereum (EIP-4844 blobs) | Operator-run archive nodes or DA committee | Operator-run archive nodes or DA committee |
| Finalization layer | Ethereum | Ethereum | Linea Mainnet (which itself anchors to Ethereum) |
| Bridge trust to the finalization layer | Canonical bridge: ZK proofs + admin keys for upgrades/pauses | Same as rollup | Canonical bridge to Linea Mainnet (proofs + admin keys), plus Linea Mainnet's own canonical bridge to Ethereum |
| Inherited trust assumptions | Ethereum L1 only | Ethereum L1 only | Ethereum L1 + Linea Mainnet (sequencer, prover, Security Council, admin keys) |
| State reconstruction without operator | Yes, from L1 blobs | No, depends on operator-run DA | No, depends on operator-run DA |

A validium finalized to Linea Mainnet inherits Linea Mainnet's trust assumptions in addition to its own. See [Linea Mainnet risk disclosures](/network/risk-disclosures) for those.

## Failure modes and recovery

| Failure | Participant impact | Recovery path | Status |
| --- | --- | --- | --- |
| Sequencer halt | Block production stops; pending transactions not included | Operator restart; multi-sequencer setups via distributed sequencing (QBFT) | Single-sequencer is the default; multi-sequencer is operator-implemented |
| Prover stall | Proofs not generated; finalization stops; soft-finalized blocks remain on L2 but not finalized to L1 | Operator restart; alternate prover instance | Single-prover is the default |
| Coordinator stall | L1 submission stops; same effect as prover stall downstream | Operator restart | Single-coordinator is the default |

Check warning on line 71 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of "coordinator" (may not apply for start of sentence).

Raw Output:
{"message": "[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of \"coordinator\" (may not apply for start of sentence).", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 71, "column": 111}}}, "severity": "WARNING"}
| DA withhold (validium) | Participants cannot reconstruct state independently; new state still verifiable via proof | Operator-defined wind-down procedure; depends on consortium agreement | Operator-defined; not protocol-enforced |
| Finality layer reorg | Affects depth of L1 finality; ZK proofs once accepted on L1 cannot be reorged without breaking L1 | Wait for L1 finality depth | Inherent to L1 finality model |
| Admin key compromise | Compromised role can act within its scope until revoked; `DEFAULT_ADMIN_ROLE` compromise affects all roles | Multi-sig key revocation via Web3Signer or equivalent KMS; emergency pause via `PAUSE_ALL_ROLE`; contract pause via the multi-sig governance contract | Operator-implemented |
| Bridge halt | Cross-chain transfers stop | Pause roles can halt bridging; resumption via unpause role | Live |

Check warning on line 75 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'unpause'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'unpause'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 75, "column": 92}}}, "severity": "WARNING"}
| Forced transaction (escape hatch) | Allows participants to bypass a censoring sequencer | L1-submitted forced transactions, gated by `AddressFilter` | Not yet live; planned |

The default deployment topology assumes single-instance sequencer, prover, and coordinator. For high availability, operators run multi-instance setups via distributed sequencing (QBFT).

Check warning on line 78 in docs/stack/how-it-works/trust-model.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of "coordinator" (may not apply for start of sentence).

Raw Output:
{"message": "[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of \"coordinator\" (may not apply for start of sentence).", "location": {"path": "docs/stack/how-it-works/trust-model.mdx", "range": {"start": {"line": 78, "column": 80}}}, "severity": "WARNING"}

## What participants can independently verify

The set of guarantees a participant can verify *without* trusting the operator depends on the deployment model.

**Rollup, finalized to Ethereum**

- Full transaction history, by reading L1 blobs and reconstructing L2 state.
- Proof validity, by reading the verifier contract on L1.
- Bridge events and message status, on L1.
- Contract role assignments and admin actions, on L1.

**Validium, finalized to Ethereum**

- Proof validity, by reading the verifier contract on L1.
- That a state transition was proved, even if its contents are private.
- Bridge events on L1.
- Their own observed state, by running a node with access to the operator's DA layer.
- They cannot reconstruct state without access to the operator's DA layer. This is the validium trade-off.

**Validium, finalized to Linea Mainnet**

- Same as validium finalized to Ethereum, but proofs are verified on Linea Mainnet (which is itself proved to Ethereum).
- Verifying the L3 chain end-to-end requires verifying both the L3 proof on Linea Mainnet and Linea Mainnet's proofs on Ethereum.

## See also

- [Linea Mainnet risk disclosures](/network/risk-disclosures): applies when finalizing to Linea Mainnet
- [Core components](./core-components)
- [Deployment models](./deployment-models)
- [Security](/stack/features/security)
- [LineaRollup contracts reference](/network/build/contracts)
1 change: 1 addition & 0 deletions sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,7 @@ const sidebars = {
label: "Protocol components",
},
"stack/how-it-works/deployment-models",
"stack/how-it-works/trust-model",
"stack/how-it-works/data-availability-finalization",
],
},
Expand Down
Loading