diff --git a/docs/protocol/architecture/prover/trusted-setup.mdx b/docs/protocol/architecture/prover/trusted-setup.mdx index 4c4fa14892..43ded74da7 100644 --- a/docs/protocol/architecture/prover/trusted-setup.mdx +++ b/docs/protocol/architecture/prover/trusted-setup.mdx @@ -59,4 +59,4 @@ That ceremony is complete and does not require ongoing MPC participation during ## See also - [Trace expansion and proving](./index.mdx) -- [Trust and responsibilities](/stack/evaluate/trust-model) +- [Trust model](/stack/evaluate/trust-model) diff --git a/docs/protocol/architecture/smart-contracts.mdx b/docs/protocol/architecture/smart-contracts.mdx index af2dd3a79e..b835a35b1d 100644 --- a/docs/protocol/architecture/smart-contracts.mdx +++ b/docs/protocol/architecture/smart-contracts.mdx @@ -22,7 +22,7 @@ is the network's onchain root of trust: nothing the network claims about its own until this contract has recorded it. The finalization contract: -- Verifies the proof submitted for each range of blocks, and records the +- Calls a verifier contract to check the proof submitted for each range of blocks, and records the resulting finalized state. - Accepts the transaction data the network publishes, through whichever [data submission model](./index.mdx#transaction-lifecycle) the deployment uses. @@ -66,7 +66,7 @@ Lineth's upgradeable contracts, including the finalization contract, message ser pattern (v4.x): state lives in a proxy, and an upgrade replaces the implementation the proxy delegates to. Who holds upgrade authority is a deployment decision, not a protocol one. -See [Trust and responsibilities](../../stack/evaluate/trust-model.mdx) for how that authority is scoped. +See [Trust model](../../stack/evaluate/trust-model.mdx) for how that authority is scoped. :::note Linea Mainnet diff --git a/docs/protocol/reference/security-audits.mdx b/docs/protocol/reference/security-audits.mdx index 42ba71d4a9..b5f7f2ffa1 100644 --- a/docs/protocol/reference/security-audits.mdx +++ b/docs/protocol/reference/security-audits.mdx @@ -32,4 +32,4 @@ Each report identifies the component and code revision reviewed at the time of t - [Prover architecture](../architecture/prover) - [Smart contracts](../architecture/smart-contracts) - [Security and assurance](/stack/evaluate/security) -- [Trust and responsibilities](/stack/evaluate/trust-model) +- [Trust model](/stack/evaluate/trust-model) diff --git a/docs/protocol/reference/zero-knowledge-glossary.mdx b/docs/protocol/reference/zero-knowledge-glossary.mdx index e18de05fa5..ae52075af8 100644 --- a/docs/protocol/reference/zero-knowledge-glossary.mdx +++ b/docs/protocol/reference/zero-knowledge-glossary.mdx @@ -245,6 +245,10 @@ The point at which a block is confirmed and committed on the L2 itself, before i The Lineth component that maintains the network's state representation for proof generation and recovery. It consists of a Besu node with the Shomei plugin and a Shomei node that uses sparse Merkle trees to track state changes block by block, generate Merkle proofs for state transitions, and serve `linea_getProof` RPC requests. +### System contracts + +The onchain contracts Lineth deploys on the finalization layer and on the network. They include the finalization contract, which calls a verifier to check proofs and records the finalized state, and the message service and token bridge contracts, which move messages and tokens between the two chains. + ### Tracer The Linea Besu plugin, part of the sequencer, that generates the execution traces the prover needs to create zero-knowledge proofs. The tracer provides trace counts for batch-size calculations and produces conflated trace files as prover input. diff --git a/docs/stack/deployment/access-control.mdx b/docs/stack/deployment/access-control.mdx index 6bd0a44423..21db453ca5 100644 --- a/docs/stack/deployment/access-control.mdx +++ b/docs/stack/deployment/access-control.mdx @@ -171,5 +171,3 @@ They do not receive a view of private contracts or transaction data. communicate with each other, and how an access controlled destination authorizes calls. - [Privacy and data visibility](../evaluate/validium.mdx): How private validium deployments use offchain data availability and controlled access. -- [Trust and responsibilities](../evaluate/trust-model.mdx): What participants can verify when access and - data availability are restricted. diff --git a/docs/stack/deployment/distributed-sequencing.mdx b/docs/stack/deployment/distributed-sequencing.mdx index be27a3dda5..737a97cec3 100644 --- a/docs/stack/deployment/distributed-sequencing.mdx +++ b/docs/stack/deployment/distributed-sequencing.mdx @@ -175,6 +175,5 @@ consensus overhead) so transactions of typical complexity have room to execute. ## See also -- [Trust and responsibilities](../evaluate/trust-model.mdx) - [Finality design](./fast-finality.mdx) - [Set up distributed sequencing](../how-to/set-up-distributed-sequencing.mdx) diff --git a/docs/stack/deployment/index.mdx b/docs/stack/deployment/index.mdx index aa8c8df047..30798e3cce 100644 --- a/docs/stack/deployment/index.mdx +++ b/docs/stack/deployment/index.mdx @@ -133,5 +133,5 @@ The example architecture flows as follows: [canonical token bridge and message service](../../protocol/architecture/interoperability/index.mdx). This example also shows validium message relayers to other enterprise or public chains. -See [Trust and responsibilities](../evaluate/trust-model.mdx) for who operates each component, what it -can do, and what participants can verify. +See [Trust model](../evaluate/trust-model.mdx) to understand what each deployment component can do and +what participants can verify. diff --git a/docs/stack/deployment/key-management.mdx b/docs/stack/deployment/key-management.mdx index cf62548072..08ce41d8ea 100644 --- a/docs/stack/deployment/key-management.mdx +++ b/docs/stack/deployment/key-management.mdx @@ -45,7 +45,7 @@ Do not reuse one key across roles. Submission from that address stalls or can be issued by an attacker until - OPERATOR_ROLE is revoked + OPERATOR_ROLE is revoked @@ -59,7 +59,7 @@ Do not reuse one key across roles. Finalization from that address stalls or can be issued by an attacker until - OPERATOR_ROLE is revoked + OPERATOR_ROLE is revoked @@ -136,10 +136,10 @@ Do not reuse one key across roles. Coordinator blob and aggregation signers must use an Ethereum address that -holds the rollup contracts' [`OPERATOR_ROLE`](../evaluate/trust-model.mdx#admin-keys-and-upgrade-authority). +holds the rollup contracts' [`OPERATOR_ROLE`](../evaluate/trust-model.mdx#system-contract-roles). Custody (how the key is stored) does not grant that role. Keep signer addresses aligned with the role holders in -[Admin keys and upgrade authority](../evaluate/trust-model.mdx#admin-keys-and-upgrade-authority). +[System contract roles](../evaluate/trust-model.mdx#system-contract-roles). ## Key custody options @@ -239,7 +239,7 @@ Operators own the following controls: (IAM) policies or a signer access control list (ACL), network isolation, and credential rotation for anyone allowed to sign. - **Onchain authorization**: Grant the signer address the role it needs - ([`OPERATOR_ROLE`](../evaluate/trust-model.mdx#admin-keys-and-upgrade-authority) for coordinator submission), + ([`OPERATOR_ROLE`](../evaluate/trust-model.mdx#system-contract-roles) for coordinator submission), and revoke it when the key is retired. - **Access review and audit**: Review who can use the KMS key, Web3Signer API, and onchain roles. Retain and review signer and KMS audit logs against your @@ -250,7 +250,7 @@ Operators own the following controls: - **Operational signers** (coordinator, Postman, sequencer liveness plugin) sign as a specific Ethereum address. Changing the key changes the sender unless the new material is the same key pair. If you change the address, update the matching - onchain role (for example, [`OPERATOR_ROLE`](../evaluate/trust-model.mdx#admin-keys-and-upgrade-authority) + onchain role (for example, [`OPERATOR_ROLE`](../evaluate/trust-model.mdx#system-contract-roles) for coordinator submission) before the old key is retired, or submission reverts. Web3Signer can load a replacement key in its store while components keep calling the same endpoint. - In the open-source stack, **Maru validator keys** are mounted as files. @@ -258,11 +258,10 @@ Operators own the following controls: [coordinated genesis update](../how-to/set-up-distributed-sequencing.mdx#manage-the-validator-set). When Lineth supplies AWS KMS signing for an enterprise deployment, the validator key lives in the KMS. The local key file is still used for P2P identity. - - **Contract admin keys** ([`DEFAULT_ADMIN_ROLE`](../evaluate/trust-model.mdx#admin-keys-and-upgrade-authority) + - **Contract admin keys** ([`DEFAULT_ADMIN_ROLE`](../evaluate/trust-model.mdx#system-contract-roles) and related roles) are rotated by granting a new holder and revoking the old one through the deployment's - governance or multisig process. See - [Failure modes and recovery](../evaluate/trust-model.mdx#failure-modes-and-recovery). + governance or multisig process. For [high availability](high-availability.mdx) placement, hardware-backed keys that stay in an HSM boundary can be used from more than one region without a new key ceremony. @@ -270,5 +269,5 @@ boundary can be used from more than one region without a new key ceremony. ## See also - [Access control](./access-control.mdx): How to restrict access to JSON-RPC, APIs, and tooling. -- [Trust and responsibilities](../evaluate/trust-model.mdx): Onchain roles and +- [Trust model](../evaluate/trust-model.mdx): Onchain roles and component trust boundaries. diff --git a/docs/stack/evaluate/compliance.mdx b/docs/stack/evaluate/compliance.mdx index 314017f5d0..594a2d4cea 100644 --- a/docs/stack/evaluate/compliance.mdx +++ b/docs/stack/evaluate/compliance.mdx @@ -39,7 +39,7 @@ compliance design: What participants can verify depends on the deployment model. For the trust and verification boundaries, see -[Trust and responsibilities](./trust-model.mdx). For where data is +[Trust model](./trust-model.mdx). For where data is stored and who can see it, see [Privacy and data visibility](./validium.mdx). ## Operator-owned compliance controls @@ -74,7 +74,7 @@ provides mechanisms operators can configure, but does not own the program: | Question | Page | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -| Who operates what, and what can each component do? | [Trust and responsibilities](./trust-model.mdx) | +| What can each component do, and what can participants verify? | [Trust model](./trust-model.mdx) | | Who can see what data? | [Privacy and data visibility](./validium.mdx) | | What is protocol versus operator, and what evidence exists? | [Security and assurance](./security.mdx) | | How is access to RPC and APIs controlled? | [Access control](../deployment/access-control.mdx) | diff --git a/docs/stack/evaluate/deployment-models.mdx b/docs/stack/evaluate/deployment-models.mdx index 4464af73b9..276e6a56e6 100644 --- a/docs/stack/evaluate/deployment-models.mdx +++ b/docs/stack/evaluate/deployment-models.mdx @@ -99,7 +99,7 @@ what is not claimed. ## See also -- [Trust and responsibilities](./trust-model.mdx): Trust assumptions and guarantees for each deployment model +- [Trust model](./trust-model.mdx): Trust assumptions for each deployment model - [Privacy and data visibility](./validium.mdx): What a private validium publishes and who can see it - [Data availability and finalization](../deployment/data-availability-finalization.mdx): Where transaction data is stored in each deployment model, and where proofs settle diff --git a/docs/stack/evaluate/index.mdx b/docs/stack/evaluate/index.mdx index 5980fcbf86..04f7744ef6 100644 --- a/docs/stack/evaluate/index.mdx +++ b/docs/stack/evaluate/index.mdx @@ -23,9 +23,9 @@ your use case. href: "/stack/evaluate/deployment-models", }, { - text: "Trust and responsibilities", + text: "Trust model", description: - "Learn who operates each component, what each component can do, and what participants can verify.", + "Understand what each deployment component can do, what participants can verify, and privileged contract roles.", href: "/stack/evaluate/trust-model", }, { diff --git a/docs/stack/evaluate/security.mdx b/docs/stack/evaluate/security.mdx index 2839b3dd90..3f28cccecd 100644 --- a/docs/stack/evaluate/security.mdx +++ b/docs/stack/evaluate/security.mdx @@ -48,7 +48,7 @@ Under the configured deployment model, Lineth provides: tied to verified state transitions in the normal protocol path. For the trust boundaries behind each of these, see -[Trust and responsibilities](./trust-model.mdx). +[Trust model](./trust-model.mdx). ## Operator-controlled security surfaces @@ -56,8 +56,9 @@ For the trust boundaries behind each of these, see Lineth does not ship a production security operations program. Operators are responsible for: -- Infrastructure isolation and network security controls +- Infrastructure isolation and network security controls. - [Access control](../deployment/access-control.mdx) for JSON-RPC, APIs, and tooling. +- Offchain data availability and access, in a private validium. - [Key management](../deployment/key-management.mdx) via KMS-backed signing and remote signing through [Web3Signer](../../protocol/architecture/index.mdx#web3signer). @@ -93,7 +94,7 @@ The following public materials are the available assurance evidence for the Line computation (MPC) ceremonies and structured reference strings used by the proving system - [Security audits](../../protocol/reference/security-audits.mdx): The published audit reports for reviewed components and revisions -- [Trust and responsibilities](./trust-model.mdx): Component-level trust boundaries and +- [Trust model](./trust-model.mdx): Component-level trust boundaries and failure modes - [Smart contracts](../../protocol/architecture/smart-contracts.mdx): The onchain contracts a deployment uses diff --git a/docs/stack/evaluate/trust-model.mdx b/docs/stack/evaluate/trust-model.mdx index 9c6850b44b..7b53d63bbe 100644 --- a/docs/stack/evaluate/trust-model.mdx +++ b/docs/stack/evaluate/trust-model.mdx @@ -1,111 +1,179 @@ --- -title: Trust and responsibilities +title: Trust model description: >- - Trust assumptions, control responsibilities, and failure modes for Lineth + Trust assumptions, privileged roles, and failure modes for Lineth deployments -sidebar_position: 3 image: /img/socialCards/trust-and-responsibilities.jpg --- import GlossaryTerm from '@theme/GlossaryTerm'; -This page describes who operates each component, what each component can do, what participants can verify, what happens when dependencies fail, and how trust assumptions change across deployment models. - -For more information on deployment topology, see [Deployment components](../deployment/core-components.mdx) and [Deployment models](./deployment-models.mdx). - -## Trust assumptions per component - -| Component | Operated by | Can do unilaterally | Cannot do | Independently verifiable by participants | -| --- | --- | --- | --- | --- | -| | | Order, delay, or omit transactions within a block | Forge state, since invalid blocks fail proof verification | Public rollup block contents and ordering by running a full or archive node; in validium or [restricted](../deployment/access-control.mdx) deployments, transactions or blocks only to the extent participants have the relevant data and access | -| | 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 | -| | Operator | Stall the pipeline that conflates blocks, requests proofs, and submits them to the finalization layer | Modify state independently of the sequencer or prover | Submission events on the finalization layer | -| 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 the finalization layer | Data and state claims that participants are authorized to access, including checks with [Merkle proofs](/protocol/architecture/state-manager#merkle-trees) against posted state roots | -| Canonical bridge (to Ethereum / Linea-anchored chain) | Operator (admin keys) + protocol (proofs) | Pause bridging via pause roles; upgrade contracts through the proxy upgrade path | In the normal protocol path, process unproved messages, since messages are tied to verified state transitions | Bridge events, proof verification, role assignments, proxy admin, and implementation addresses 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 | In the normal relayer path, process messages that are not signed over source-chain events | Bridge events on each side; no shared proof, so verifiability depends on trust in the relayer, its keys, and the bridge upgrade/admin model | -| System contracts | Operator (role holders) + proxy upgrade authority | Pause, change verifier address, change rate limits, and upgrade contracts through the proxy upgrade path | Bypass role gating in the deployed implementation, since privileged functions are role-gated | Role assignments, contract state, proxy admin, and implementation addresses on the finalization layer | -| Participant nodes | Each participant | Read state visible to them, broadcast transactions | Modify network state | Their own observed state, subject to the deployment's data access model; not every participant in a validium or [restricted](../deployment/access-control.mdx) deployment necessarily runs a full or archive 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. A governance contract is the high-security onchain control path that can hold privileged roles or proxy admin authority for a deployment. In production-oriented deployments, governance and upgrade authority should sit behind an appropriately secured multisig, governance contract, or timelock, and may involve multiple independent parties. +This page describes the trust model in a +deployment: what each component can do, what participants can verify, privileged contract roles, +and how to recover when a dependency fails. + +For protocol guarantees and operator-controlled security measures, see +[Security and assurance](./security.mdx). + +## Trust assumptions + +In a public deployment and a private validium, the +operator runs the +[deployment components](../deployment/core-components.mdx). +In both deployment models, the components can take these actions: + +- The sequencer can order, delay, or omit transactions within a block. +- The prover can stall proof generation, which halts finalization. +- The coordinator can stall the pipeline that conflates blocks, requests proofs, and submits them to + the finalization layer. +- The system contracts can pause subsystems, change the verifier address, change rate limits, + and upgrade contracts through the proxy upgrade path (and, on a + canonical bridge, pause and upgrade [contract roles](#system-contract-roles)). + +In both models, the components **cannot**: + +- Forge state. Invalid blocks fail proof verification. +- Produce a valid proof for an invalid state transition. +- Modify state independently of the sequencer or prover. +- Process canonical bridge messages that are not tied to a verified state commitment, unless + a privileged role upgrades or reconfigures the contracts. +- Bypass the contract roles in the deployed implementation. + Privileged functions require the matching role. + +Each participant can read state visible to them and broadcast transactions. +They cannot modify network state. +What a participant can see through the operator's RPC depends on the deployment's +[access control](../deployment/access-control.mdx) configuration. +Access control does not hide data already posted onchain. + +When the deployment uses +QBFT, +block production depends on the validator set: with `3f+1` validators, at most `f` can fail +or deviate. +See [Multi-validator consensus](../deployment/distributed-sequencing.mdx). + +### What participants can verify + +In every deployment, participants can check that a proof was accepted by reading the +[finalization contract](../../protocol/architecture/smart-contracts.mdx#finalization-contract) on +the finalization layer. +They can also read submission events, [contract role](#system-contract-roles) assignments, contract state, proxy admin, +implementation addresses, and canonical bridge events on that layer. + +In a public deployment, transaction data is posted onchain to the finalization layer. +While that data remains available, the operator cannot withhold data availability. +When the finalization layer is Ethereum, transaction data is posted as +[EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) blobs. +Participants can reconstruct state from those blobs while they are retained; +long-term reconstruction needs independent archival. +Participants can also verify public rollup block contents and ordering by running a +full node, and can verify their own observed state +from that public data. + +In a private validium, transaction data stays +offchain. +Data availability (DA) is operated by +archive nodes or a DA committee. +Those providers can withhold data, which halts recovery, but they cannot forge state, because +proofs still verify on the finalization layer. +Participants can verify data and state claims they are authorized to access, including checks with +[Merkle proofs](/protocol/architecture/state-manager#merkle-trees) against posted state roots. +A Merkle proof can support inclusion of authorized data. +It does not by itself establish global transaction ordering for participants who do not have the +full ordered data set. + +### Trusted bridge + +A deployment's operator and a trusted relayer may operate a bridge to a private or non-anchored chain. +The operator holds the [contract roles](#system-contract-roles) that can pause or upgrade the bridge. +The relayer can withhold or delay messages. +In the normal relayer path, the bridge cannot process messages that are not signed over +source-chain events. +Participants can verify bridge events on each side. +There is no shared proof, so verifiability depends on trust in the relayer, its keys, +and those pause and upgrade roles. + +### Finalization layer + +A deployment inherits its finalization layer's finality. +The deployment carries its own sequencer, prover, contract role, and verifier assumptions. + +If the finalization layer is Linea Mainnet, the deployment also depends on Linea Mainnet operating the +same component stack, plus Linea's Security Council and its bridge to Ethereum. +Verifying the chain end-to-end requires verifying both the deployment's proof on Linea +Mainnet and Linea Mainnet's proofs on Ethereum. +See [Linea Mainnet risk disclosures](/network/risk-disclosures). + +## System contract roles + +The system contracts use onchain roles to gate privileged functions: pause, finalize, change the +verifier, and grant other roles. +The protocol defines what each role can do. +The operator chooses which addresses hold them at deploy time. + +Replacing the contract implementation is a separate power. +It belongs to whoever controls the proxy admin, not automatically to `DEFAULT_ADMIN_ROLE`. + +In production deployments, both role holders and proxy admin control should sit behind a +multisig, governance contract, or timelock, and may involve multiple independent parties. | Role | What it can do | Recommended holder | | --- | --- | --- | -| `DEFAULT_ADMIN_ROLE` | Grant or revoke AccessControl roles | High-security multisig or governance contract; initial holder set during initialization | +| `DEFAULT_ADMIN_ROLE` | Grant or revoke other roles | High-security multisig or governance contract; initial holder set during initialization | | `OPERATOR_ROLE` | Submit blobs/calldata, finalize blocks | Day-to-day operator address | | `SECURITY_COUNCIL_ROLE` | Reserved for governance pause/upgrade authority | High-security governance contract or multisig | | `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 | | `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 Transparent Upgradeable Proxy pattern](/protocol/architecture/smart-contracts#contract-versioning). Proxy upgrade authority is separate from `DEFAULT_ADMIN_ROLE` and depends on who controls the proxy admin or governance contract for the deployment. Operators should place upgrade authority behind an appropriate multisig, governance contract, or timelock. The [Linea Security Council transaction record](/changelog/security-council-record) shows a public Linea example of multisig-governed security and upgrade operations. +Contracts are upgradeable via the +[OpenZeppelin Transparent Upgradeable Proxy pattern](/protocol/architecture/smart-contracts#contract-versioning). +The [Linea Security Council transaction record](/changelog/security-council-record) shows a public +Linea example of multisig-governed role and upgrade operations. :::warning -`DEFAULT_ADMIN_ROLE` cannot be assigned through `__Permissions_init`. The initial holder is set via the explicit `defaultAdmin` initializer field. Plan the initial holder before initialization. +`DEFAULT_ADMIN_ROLE` cannot be assigned through `__Permissions_init`. +The initial holder is set via the explicit `defaultAdmin` initializer field. +Plan the initial holder before initialization. ::: -For the full list of roles, see [LineaRollup contracts reference](/network/build/contracts). - -## Trust assumptions per deployment model - -| Trust dimension | Public deployment on Ethereum | Private validium on Ethereum | Private validium on 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, plus admin and upgrade authority for pauses, verifier configuration, and contract upgrades | Same as public deployment | Canonical bridge to Linea Mainnet (proofs plus admin and upgrade authority), plus Linea Mainnet's own bridge and governance assumptions | -| Inherited trust assumptions | Ethereum L1 finality, plus the deployment's sequencer, prover, admin key, verifier configuration, and upgrade-authority assumptions | Ethereum L1 finality, plus the deployment's sequencer, prover, admin key, verifier, upgrade, and DA assumptions | Ethereum L1 + Linea Mainnet finality, plus Linea Mainnet sequencer, prover, Security Council, admin key, verifier, upgrade, and bridge assumptions | -| State reconstruction without operator | Yes, while L1 blob data is available; long-term reconstruction requires independent archival of EIP-4844 blob data | No, depends on operator-run DA and the deployment's data access model | No, depends on operator-run DA and the deployment's data access model | - -A private validium on 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 | -| --- | --- | --- | -| Sequencer halt | Block production stops; pending transactions not included | Operator restart or failover to redundant sequencer infrastructure. In distributed sequencing or validator consensus deployments, recovery follows the configured QBFT or validator process. | -| Prover stall | Proofs not generated; finalization stops; soft-finalized blocks remain on L2 but not finalized to the finalization layer | Operator restart or failover to an alternate prover instance where deployed | -| Coordinator stall | Submission to the finalization layer stops; same effect as prover stall downstream | Operator restart or failover to an alternate coordinator instance where deployed | -| DA withhold (validium) | Participants without the required DA or [RBAC](../deployment/access-control.mdx) access cannot reconstruct or verify affected private data | Operator-defined wind-down procedure; depends on consortium agreement and is not protocol-enforced | -| Finality layer reorg | Affects depth of finality on the selected finalization layer | Wait for the required finality depth on the selected finalization layer | -| Admin key compromise | Compromised role can act within its scope until revoked; `DEFAULT_ADMIN_ROLE` compromise affects all roles | Revoke or rotate compromised authority through the deployment's governance or multisig process; use emergency pause roles where available | - -## What participants can independently verify - -The set of guarantees a participant can verify *without* trusting the operator depends on the deployment model. - -### Public deployment on Ethereum - -- Proof validity and state-transition correctness, by reading the verifier contract on L1. A valid proof means the operator cannot finalize an invalid state transition through the normal proof path. -- Full transaction history while L1 blobs are retained, by reading L1 blobs and reconstructing L2 state. After EIP-4844 blob expiry, long-term reconstruction depends on independent archival of blob data. -- Bridge events and message status, on L1. -- Contract role assignments and admin actions, on L1. - -### Private validium on Ethereum - -- Proof validity and state-transition correctness, by reading the verifier contract on L1. A valid proof means the operator cannot finalize an invalid state transition through the normal proof path. -- That a state transition was proved, even if its transaction contents are private. -- Transactions or blocks they are authorized to access, using the relevant data and [Merkle proofs](/protocol/architecture/state-manager#merkle-trees) against posted state roots. This does not by itself establish global transaction ordering for participants who do not have access to the full ordered data set. -- Bridge events on L1. -- Their own observed state, by running a node or using an authorized interface where the deployment grants access. -- They cannot reconstruct full state or history without the required operator DA access. This is the validium trade-off, and [access control](../deployment/access-control.mdx) settings may further limit which data each participant can observe. - -### Private validium on Linea - -- Proof validity and state-transition correctness, by reading the verifier contract on Linea Mainnet. A valid proof means the operator cannot finalize an invalid state transition through the normal proof path. -- Same validium and [access control](../deployment/access-control.mdx) caveats as private validium on Ethereum, but proofs are verified on Linea Mainnet (which is itself proved to Ethereum). -- Verifying the chain end-to-end requires verifying both the private validium proof on Linea Mainnet and Linea Mainnet's proofs on Ethereum. +Role constants are defined on the smart contract reference pages, including +[LineaRollup](/api/linea-smart-contracts/linearollup), +[ZkEvmV2](/api/linea-smart-contracts/zkevmv2) (`OPERATOR_ROLE`), +[LineaRollupPauseManager](/api/linea-smart-contracts/lib/linearolluppausemanager), and +[RateLimiter](/api/linea-smart-contracts/messageservice/lib/ratelimiter) +(`RATE_LIMIT_SETTER_ROLE`). +Linea Mainnet deployed addresses are on [Contracts](/network/build/contracts). + +## Failures and recovery + +If the sequencer, prover, or coordinator stalls, the operator restarts the affected service or +fails over to redundant infrastructure. +See [High availability](../deployment/high-availability.mdx). + +Each failure has the following effect on participants: + +- **Sequencer halt**: Block production stops, and pending transactions are not included. + In a [multi-validator](../deployment/distributed-sequencing.mdx) deployment, restore quorum as + described in [Set up distributed sequencing](../how-to/set-up-distributed-sequencing.mdx#restore-lost-quorum). +- **Prover stall**: Proofs are not generated and finalization stops. + Soft-finalized blocks remain on the Lineth network. +- **Coordinator stall**: Submission to the finalization layer stops, with the same downstream effect + as a prover stall. +- **Finalization layer reorg**: Wait for the required finality depth on the finalization layer. +- **Admin key compromise**: The compromised role can act within its scope until revoked. + `DEFAULT_ADMIN_ROLE` compromise affects all roles. + Revoke or rotate authority through the deployment's governance or multisig process, and use + emergency pause roles where available. +- **Data availability (DA) withheld in a private validium**: Participants without the required DA or + [access control](../deployment/access-control.mdx) permissions cannot reconstruct or verify affected private data. + Operators define a wind-down procedure (this depends on a consortium agreement and is not enforced + by the Lineth protocol). ## See also -- [Linea Mainnet risk disclosures](/network/risk-disclosures): applies when finalizing to Linea Mainnet -- [Core components](../deployment/core-components.mdx) -- [High availability](../deployment/high-availability.mdx) -- [Deployment models](./deployment-models.mdx) -- [Security and assurance](/stack/evaluate/security) -- [LineaRollup contracts reference](/network/build/contracts) -- [Merkle trees](/protocol/architecture/state-manager#merkle-trees) -- [Linea Security Council transaction record](/changelog/security-council-record) +- [Security and assurance](./security.mdx): Protocol guarantees, operator controls, and published + assurance evidence. +- [Deployment models](./deployment-models.mdx): Comparison and tradeoffs between a public deployment and private validium. diff --git a/docs/stack/evaluate/validium.mdx b/docs/stack/evaluate/validium.mdx index 795edea8c6..ab70015c0d 100644 --- a/docs/stack/evaluate/validium.mdx +++ b/docs/stack/evaluate/validium.mdx @@ -95,20 +95,10 @@ Private validium deployments include: ## Trust and security -### Trust assumptions +Trust assumptions for a private validium, including data availability, the validator set, and the +finalization layer, are on [Trust model](./trust-model.mdx#trust-assumptions). -Private validium requires trust in: - -- Data availability providers: they must make data available when needed -- Validator set: must follow consensus protocol (QBFT provides fault tolerance - with `3f+1` validators) -- Finalization layer: the deployment inherits the finality assumptions of the - selected finalization layer - -For the full trust assumptions, see -[Trust and responsibilities](./trust-model.mdx). - -### Security features +Security features include: - Minimum node count: 4 nodes for QBFT fault tolerance - [Access control](../deployment/access-control.mdx): Role-based permissions on JSON-RPC, APIs, and tooling @@ -117,13 +107,6 @@ For the full trust assumptions, see backed by a hardware security module (HSM) or key management service (KMS) - Network isolation: private network topology -### Data availability - -Where deployments use a private node set for data storage, participants must -trust that data availability providers will make data available when needed, or -operate under a consortium model that gives them direct access to the data -required for verification and recovery. - ## Next steps - Learn more about selecting a diff --git a/sidebars.js b/sidebars.js index 7522b3a162..e99a62d181 100644 --- a/sidebars.js +++ b/sidebars.js @@ -454,7 +454,7 @@ const sidebars = { { type: "doc", id: "stack/evaluate/trust-model", - label: "Trust and responsibilities", + label: "Trust model", }, { type: "doc", diff --git a/src/lib/glossary.json b/src/lib/glossary.json index 07265d4ccb..9b1a4fba60 100644 --- a/src/lib/glossary.json +++ b/src/lib/glossary.json @@ -205,6 +205,10 @@ "term": "State manager", "definition": "The Lineth component that maintains the network's state representation for proof generation and recovery. It consists of a Besu node with the Shomei plugin and a Shomei node that uses sparse Merkle trees to track state changes block by block, generate Merkle proofs for state transitions, and serve `linea_getProof` RPC requests." }, + { + "term": "System contracts", + "definition": "The onchain contracts Lineth deploys on the finalization layer and on the network. They include the finalization contract, which calls a verifier to check proofs and records the finalized state, and the message service and token bridge contracts, which move messages and tokens between the two chains." + }, { "term": "Tracer", "definition": "The Linea Besu plugin, part of the sequencer, that generates the execution traces the prover needs to create zero-knowledge proofs. The tracer provides trace counts for batch-size calculations and produces conflated trace files as prover input." diff --git a/static/llms.txt b/static/llms.txt index 9647352a5e..c93334a53a 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -174,7 +174,7 @@ - [Stack overview](https://docs.linea.build/stack): What Lineth is and who it is for. - [Evaluate Lineth](https://docs.linea.build/stack/evaluate): Evidence paths for evaluating a Lineth deployment. - [Deployment models](https://docs.linea.build/stack/evaluate/deployment-models): Public deployments, private validium deployments, and operator design trade-offs. -- [Trust and responsibilities](https://docs.linea.build/stack/evaluate/trust-model): Trust assumptions, authority, and failure boundaries. +- [Trust model](https://docs.linea.build/stack/evaluate/trust-model): Trust assumptions, authority, and failure boundaries. - [Privacy and data visibility](https://docs.linea.build/stack/evaluate/validium): What is published, retained offchain, visible, and verifiable. - [Security and assurance](https://docs.linea.build/stack/evaluate/security): Protocol guarantees, operator controls, and assurance evidence. - [Compliance](https://docs.linea.build/stack/evaluate/compliance): Protocol evidence operators can use in a compliance program, and what Lineth does not claim.