From 538f607548c268eb9d49f63c7362b1f585b46fb6 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Wed, 26 Aug 2026 11:01:37 -0700 Subject: [PATCH 1/6] Document access control stack and RBAC model --- docs/protocol/architecture/index.mdx | 16 +- docs/protocol/architecture/rpc-services.mdx | 3 +- .../reference/zero-knowledge-glossary.mdx | 4 - docs/stack/deployment/access-control.mdx | 183 ++++++++++++++++++ docs/stack/deployment/high-availability.mdx | 4 +- docs/stack/deployment/index.mdx | 12 +- docs/stack/deployment/rbac.mdx | 78 -------- docs/stack/evaluate/compliance.mdx | 4 +- docs/stack/evaluate/deployment-models.mdx | 10 +- docs/stack/evaluate/security.mdx | 2 +- docs/stack/evaluate/trust-model.mdx | 10 +- docs/stack/evaluate/validium.mdx | 18 +- redirects.json | 5 +- sidebars.js | 2 +- src/lib/glossary.json | 4 - .../lineth-deployment-architecture.svg | 10 +- static/llms.txt | 2 +- 17 files changed, 232 insertions(+), 135 deletions(-) create mode 100644 docs/stack/deployment/access-control.mdx delete mode 100644 docs/stack/deployment/rbac.mdx diff --git a/docs/protocol/architecture/index.mdx b/docs/protocol/architecture/index.mdx index 2956b751a7..0e4ed5a4a3 100644 --- a/docs/protocol/architecture/index.mdx +++ b/docs/protocol/architecture/index.mdx @@ -159,14 +159,20 @@ For more information about the system contracts, see [Smart contracts](./smart-c ### Block explorer The block explorer is an optional, operator-facing service used for inspection, troubleshooting, and -auditing. Linea Mainnet uses [Blockscout](https://github.com/blockscout/blockscout), an +auditing. + +Linea Mainnet uses [Blockscout](https://github.com/blockscout/blockscout), an open-source, self-hosted explorer that indexes chain data from execution nodes and presents it via a web interface. - The explorer connects to the network via JSON-RPC or WebSocket, continuously indexes blocks, -transactions, logs, and token data, and stores this information in a relational database. It allows -operators to inspect blocks and transactions, review contract activity, track bridge operations, and -monitor network health. +transactions, logs, and token data, and stores this information in a relational database. + +[Restricted deployments](../../stack/deployment/access-control.mdx) use a different block explorer setup: the explorer +is a backend-for-frontend that reads only through the privacy proxy, which evaluates role-based permissions +and retrieves data from a separate chain indexer. + +In either case, the explorer allows operators to inspect blocks and transactions, review contract +activity, track bridge operations, and monitor network health. Block explorers are not required for network operation and do not participate in consensus, execution, or finalization. They can be deployed, replaced, or omitted without affecting correctness diff --git a/docs/protocol/architecture/rpc-services.mdx b/docs/protocol/architecture/rpc-services.mdx index 74a978950d..d6595424cd 100644 --- a/docs/protocol/architecture/rpc-services.mdx +++ b/docs/protocol/architecture/rpc-services.mdx @@ -11,8 +11,7 @@ import GlossaryTerm from '@theme/GlossaryTerm'; RPC services expose the JSON-RPC interfaces that applications, users, and internal services use to read network data and submit transactions. Any node can serve them, publicly or only within the operator's network, and RPC -nodes are typically placed behind load balancers and access controls -(RBAC). +nodes are typically placed behind load balancers and [access control](../../stack/deployment/access-control.mdx). What distinguishes one RPC node from another is how much state history it retains. diff --git a/docs/protocol/reference/zero-knowledge-glossary.mdx b/docs/protocol/reference/zero-knowledge-glossary.mdx index f29366a8e8..672cacf7a8 100644 --- a/docs/protocol/reference/zero-knowledge-glossary.mdx +++ b/docs/protocol/reference/zero-knowledge-glossary.mdx @@ -187,10 +187,6 @@ While Ethereum may reorg, Linea does not. The zero knowledge validity proof crea Furthermore, Linea takes action to ensure that interoperability between the public network and the Layer 1 preserves the property of preventing block reorganizations. Before any interoperating transaction anchored to Layer 1 state (for example, a deposit of a token into the bridge), Linea will wait for the Layer 1 state to be finalized before committing the appropriate action on the Layer 2. This ensures that even a reorganization of Ethereum, which is an expected and normal part of operations, does not result in a reorganization of the Linea L2. -### Role-based access control (RBAC) - -Operator-configured access control for protected Lineth RPC, API, and tooling surfaces. RBAC determines which protected interfaces and data a participant can access, but it is not cryptographic privacy: it doesn't encrypt public-chain data, replace zero-knowledge proof verification, or provide data availability on its own. - ### Rollup A type of L2 scaling solution that batches multiple transactions and submits them to Ethereum in a single transaction. This allows for reductions in gas costs and increases in transaction throughput. There are optimistic and zero-knowledge rollups, which use different security methods to offer these scalability gains. diff --git a/docs/stack/deployment/access-control.mdx b/docs/stack/deployment/access-control.mdx new file mode 100644 index 0000000000..cc6b346a9d --- /dev/null +++ b/docs/stack/deployment/access-control.mdx @@ -0,0 +1,183 @@ +--- +title: Access control +description: >- + Operator-configured access policy for protected Lineth RPC, API, and tooling + surfaces +sidebar_position: 5 +image: /img/socialCards/access-control.jpg +--- + +import GlossaryTerm from '@theme/GlossaryTerm'; + +This page describes how a deployment can control access to JSON-RPC, APIs, +and tooling. +In a restricted deployment, a privacy proxy authenticates callers, evaluates role-based permissions, and +traces calls. + +For data visibility choices, see [Privacy and data visibility](../evaluate/validium.mdx). + +:::important + +Access control is not cryptographic privacy. +The privacy proxy limits who can use protected services and data surfaces, but it does not make public +chain data private, replace zero-knowledge proofs, or provide data availability. + +::: + +## Access control stack + +Operators can choose to configure access control, independent of +[deployment model](../evaluate/deployment-models.mdx) and +[data availability](data-availability-finalization.mdx). +The access control stack consists of the following services: + +- **Privacy proxy:** An [Open Privacy Suite](https://gateway-fm.github.io/open-privacy-suite/) JSON-RPC + reverse proxy. + Every wallet, app, and admin request to the Lineth node goes through it. + [RBAC](#role-based-access-control-rbac) records live in a PostgreSQL database. + A separate database records JSON-RPC access logs. +- **Block explorer:** Displays blocks, transactions, logs, and transfers in a web interface. + The explorer's API is a backend-for-frontend (BFF). + It holds no chain data of its own. + Every read goes to the proxy, which redacts the response for that caller. +- **Chain indexer:** Indexes blocks, transactions, and logs from the node and serves raw chain data over + gRPC on a trusted network. + It has no authentication, access policy, or redaction. + Only the proxy consumes the indexer. + +
+```mermaid +%%{init: { + "themeVariables": { + "fontFamily": "AtypText, sans-serif" + }, + "flowchart": { + "useMaxWidth": true, + "curve": "basis", + "nodeSpacing": 24, + "rankSpacing": 28, + "padding": 12, + "wrappingWidth": 200 + } +}}%% +flowchart TB + classDef core stroke-width:1.5px; + classDef access stroke-width:1.5px; + classDef control stroke-width:1.5px,stroke-dasharray:6 4; + classDef neutral stroke-width:1.5px; + + CL["Wallets, apps, and admin clients"]:::neutral + EX["Block explorer"]:::access + PX["Privacy proxy"]:::access + ND["Lineth node"]:::core + IDX["Chain indexer"]:::access + POL["RBAC database"]:::neutral + AUD["Access log"]:::neutral + + CL --> PX + EX -->|"every read"| PX + PX -->|"JSON-RPC"| ND + PX -->|"gRPC"| IDX + IDX -->|"indexes"| ND + PX -.-> POL + PX -.-> AUD +``` +
+ +A public or private deployment can configure access control. +In a public deployment, transaction data is posted to the +finalization layer, so the proxy restricts who uses +the operator's interfaces; it does not hide onchain data. +A private validium keeps transaction data offchain, so the +proxy is the path to chain data as well as the operator's interfaces. + +### Role-based access control (RBAC) + +The privacy proxy uses a role-based access control (RBAC) model: permissions are organization-scoped and group-centric. +After the proxy authenticates the caller, it checks the group's method allowlist, claims, and contract grants. + +- An **organization** is the tenant boundary. + Users, groups, and contract registrations belong to an organization. +- A **group** is a named collection of users that share one permission set. + Groups can be marked as organization admin or read-only admin. +- A **user** is an individual member of one or more groups, identified by a decentralized identifier (DID). + Optional flags cover KYC status and bans. + +A group's permission set includes: + +- **Method allowlist:** Which JSON-RPC methods members may call. +- **Claims:** Extra permissions on top of the method allowlist: `deploy` (create contracts), `upgrade` + (upgrade proxy contracts), and `admin` (includes deploy and upgrade). +- **Contract grants:** Per-group permission on a registered contract: this group may use this contract, + optionally limited to function selectors, parameter constraints, and event topics. + Contracts stay private until a grant exists. + - A missing function list means all functions on that contract are allowed. + - An empty function list means all functions on that contract are denied. + - An explicit list allows only those function selectors, optionally with parameter constraints (for + example, a parameter that must equal the caller's own address). + - Event rules can deny logs, allow all, or allow specific event topics. + +Operators manage organizations, groups, users, and contract grants through the proxy's admin API and dashboard. +See the [Open Privacy Suite RBAC docs](https://gateway-fm.github.io/open-privacy-suite/docs/rbac/) for more information. + +### Explorer and indexer + +A restricted deployment uses its own block explorer and chain indexer. +The explorer uses data from the indexer (blocks, transactions, logs, and transfers). +The indexer always stores real addresses and values, and returns whatever is requested. + +The privacy proxy sits between the explorer and chain indexer. +Only the proxy consumes the indexer, and every explorer read goes to the proxy, which applies the same +[RBAC](#role-based-access-control-rbac) permissions and redaction used on JSON-RPC. +Explorer responses must not be cached across callers, and you must not set a direct indexer URL. + +### Audit logs + +The privacy proxy writes two streams: + +- **Access log:** One record per JSON-RPC decision (allow or deny), stored in a database separate from + RBAC data, with a restricted append-only role and a hash chain over entries. +- **Control-plane audit:** One record each time an organization, group, user, membership, contract, or + contract grant is created, updated, deleted, assigned, or revoked. + These records live with the RBAC data. + +These logs are evidence that a request was allowed or denied under the active +[RBAC](#role-based-access-control-rbac) permissions at that time. + +## How a request is evaluated + +Clients send JSON-RPC requests to the proxy, not to the node. +A typical request is evaluated in this order: + +1. Authenticate the caller via JSON Web Token (JWT). +2. Reject globally blocked methods (including `debug_*` and `admin_*` namespaces, and multicall patterns + that would otherwise bypass contract grants). +3. Resolve the caller's organization, groups, and permissions. +4. Check the method against the group's RPC method allowlist. +5. If the call targets a contract, check that contract grant (and function selector, parameter, and event + rules where they exist). +6. Simulate the call with `debug_traceCall` and reject it if any internal `CALL`, `DELEGATECALL`, + `STATICCALL`, or `CREATE` target is outside the caller's organization. +7. Forward the request to the node, then redact the response before returning it. + +The proxy binds the call's sender to the authenticated account, so a caller cannot inherit another +account's onchain permissions by spoofing `from`. + +Evaluation is fail-closed: a missing permission, an unknown contract, a tracing failure, or an unreachable +node during simulation denies the request. +Denied JSON-RPC calls are returned to the client as a generic "method not found" error. +The detailed reason is written to the access log for operators. + +Anonymous, unauthenticated requests can be limited to claim-free metadata such as `eth_chainId` and `eth_blockNumber`. +They do not receive a view of private contracts or transaction data. + +## See also + +- [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. +- [Security and assurance](../evaluate/security.mdx): How the privacy proxy fits into operational security controls. +- [Deployment models](../evaluate/deployment-models.mdx): How access control factors into deployment design. +- [RPC services](../../protocol/architecture/rpc-services.mdx): How RPC services expose blockchain data and + can sit behind access controls. diff --git a/docs/stack/deployment/high-availability.mdx b/docs/stack/deployment/high-availability.mdx index b2c2263820..03eb4fd143 100644 --- a/docs/stack/deployment/high-availability.mdx +++ b/docs/stack/deployment/high-availability.mdx @@ -80,7 +80,7 @@ Each region runs a consensus client paired with a QBFT validator per region). Each region also runs public and/or private JSON-RPC gateways in front of -RPC nodes, with [access control](./rbac.mdx) where +RPC nodes, with [access control](./access-control.mdx) where required. For QBFT topology, latency, and setup, see [Multi-validator consensus](./distributed-sequencing.mdx) and @@ -109,7 +109,7 @@ This table summarizes which components run in which regions: In the example design, public RPC enters through a global entry point that routes each client to the nearest healthy region (for example, [AWS Global Accelerator](https://aws.amazon.com/global-accelerator/)), protected by a web -application firewall, then a regional load balancer, reverse proxy with [RBAC](./rbac.mdx), and +application firewall, then a regional load balancer, a privacy proxy for [access control](./access-control.mdx), and JSON-RPC routers to [near-head and archive nodes](../../protocol/architecture/rpc-services.mdx). Private RPC can use private connectivity into each region (for example, diff --git a/docs/stack/deployment/index.mdx b/docs/stack/deployment/index.mdx index 3746c9ab0c..2b92646017 100644 --- a/docs/stack/deployment/index.mdx +++ b/docs/stack/deployment/index.mdx @@ -51,8 +51,8 @@ Detailed production topology and supported tooling for a given deployment can be { text: "Access control", description: - "Operator-configured RBAC at the access edge for protected RPC, API, and tooling surfaces in restricted deployments.", - href: "/stack/deployment/rbac", + "How the access control stack works: privacy proxy at the RPC edge, RBAC permissions, block explorer, and chain indexer.", + href: "/stack/deployment/access-control", }, ]} /> @@ -71,8 +71,7 @@ Proofs and state commitments go to a chosen Operators also choose: -- [Access control](rbac.mdx): Public RPC, or RPC and APIs gated by - RBAC +- [Access control](access-control.mdx): Public RPC, or RPC and tooling gated by role-based permissions - [Data availability](data-availability-finalization.mdx#data-availability): Onchain (for example, [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) blobs) or offchain in a private validium @@ -85,7 +84,7 @@ Lineth does not recommend a specific set of customizations. ## Example architecture The following diagram illustrates an example architecture for a -validium deployment: RBAC at the edge, a private +validium deployment: access control at the edge, a private network boundary, and validium message relayers to other chains. A public deployment uses the same internal services; access and data availability differ. @@ -103,8 +102,7 @@ For regional placement, failover, and recovery, see [High availability](./high-a The example architecture flows as follows: 1. Clients reach the API portal, block explorer, and RPC. - This example gates that path with [RBAC](./rbac.mdx); a public deployment can expose RPC - without that gate. + This example gates that path with [access control](./access-control.mdx). 2. Those tools query near-head and archive RPC nodes, which read chain state from onchain contracts. diff --git a/docs/stack/deployment/rbac.mdx b/docs/stack/deployment/rbac.mdx deleted file mode 100644 index 742a830a96..0000000000 --- a/docs/stack/deployment/rbac.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Access control -description: >- - Operator-configured access policy for protected Lineth RPC, API, and tooling - surfaces -sidebar_position: 5 -image: /img/socialCards/access-control.jpg ---- - -import GlossaryTerm from '@theme/GlossaryTerm'; - -This page describes operator-configured access control for -protected RPC, API, and tooling surfaces. -For data visibility choices, see [Privacy and data visibility](../evaluate/validium.mdx). - -:::important - -RBAC is not cryptographic privacy. It controls access to protected services and data surfaces, but it -does not make public-chain data private, replace zero-knowledge proofs, or provide data availability. - -::: - -## What RBAC controls - -In a Lineth deployment, role-based access control (RBAC) can be used around operator-controlled access surfaces, including: - -- RPC endpoints that expose blockchain data or accept transactions -- APIs and API portals used to manage or interact with the deployment -- Explorer and tooling surfaces that show deployment data -- Participant access to data in deployments where visibility is intentionally restricted - -The operator decides which surfaces are exposed, who can use them, and how access is granted for the -deployment. - -## How RBAC fits with private validium - -In a public deployment, transaction data is designed for broad visibility, and public RPC access is -designed for broad availability. -In a private validium deployment, transaction data may be kept -offchain, and access to network functionality may be restricted. - -RBAC is one part of that controlled-access model. It can help limit access to RPC endpoints, APIs, -API portals, and related tooling. It works alongside other deployment choices such as private data -availability, network isolation, key management, and operator procedures. - -RBAC determines which protected interfaces and data a participant can access. In deployments that -use RBAC, the operator defines those access rules and can change them as part of operating the -deployment. - -## Visibility and verification - -Participants can still verify proof validity on the finalization layer. For transactions, blocks, -or state they are authorized to access, they may also verify that data against posted state roots -using the deployment's available data. RBAC does not change the proof system; it changes which -protected data and interfaces a participant can access. - -For the broader trust model, see [Trust model](../evaluate/trust-model.mdx). - -## Limitations - -RBAC should be described with these limits: - -- RBAC does not encrypt data or hide data that is published to a public chain or finalization layer. -- RBAC does not replace private data availability, data-retention, or selective-disclosure design. -- RBAC does not replace zero-knowledge proof verification, governance, admin-key security, key - management, monitoring, or incident response. -- RBAC does not guarantee that every participant can verify full state or history. Verification - depends on the deployment model, available data, and participant access. - -## Related docs - -- [Privacy](../evaluate/validium.mdx): how private validium deployments use offchain data availability and - controlled access. -- [Security](../evaluate/security.mdx): how RBAC fits into operational security controls. -- [Deployment models](../evaluate/deployment-models.mdx): how access control factors into - deployment design. -- [RPC services](../../protocol/architecture/rpc-services.mdx): how RPC services expose blockchain - data and can sit behind access controls. diff --git a/docs/stack/evaluate/compliance.mdx b/docs/stack/evaluate/compliance.mdx index 6d4a0d6317..274d37aef3 100644 --- a/docs/stack/evaluate/compliance.mdx +++ b/docs/stack/evaluate/compliance.mdx @@ -47,7 +47,7 @@ stored and who can see it, see [Privacy and data visibility](./validium.mdx). Operators are responsible for the controls a compliance program requires. Lineth provides mechanisms operators can configure, but does not own the program: -- Access policy: [RBAC](../deployment/rbac.mdx) on RPC endpoints and API surfaces controls +- Access policy: [RBAC](../deployment/access-control.mdx) on RPC endpoints and API surfaces controls who can read or submit - Data availability arrangement: operators choose where transaction data is stored and who can reconstruct it; see @@ -77,5 +77,5 @@ provides mechanisms operators can configure, but does not own the program: | Who operates what, and what can each component do? | [Trust and responsibilities](./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/rbac.mdx) | +| How is access to RPC and APIs controlled? | [Access control](../deployment/access-control.mdx) | | How do data availability and finalization choices interact? | [Data availability and finalization](../deployment/data-availability-finalization.mdx) | diff --git a/docs/stack/evaluate/deployment-models.mdx b/docs/stack/evaluate/deployment-models.mdx index 3c4586ee0f..a00568b12d 100644 --- a/docs/stack/evaluate/deployment-models.mdx +++ b/docs/stack/evaluate/deployment-models.mdx @@ -44,7 +44,7 @@ When configuring a deployment, consider: - Data availability guarantees: how important is onchain data availability for your participants? - Network topology: do you need a private network with controlled membership? -- Access control: do you need [RBAC](../deployment/rbac.mdx) on RPC endpoints and +- [Access control](../deployment/access-control.mdx): do you need RBAC on RPC endpoints and APIs? ## Public @@ -71,7 +71,7 @@ data availability. - Validator topology: if the deployment uses a [multi-validator QBFT design](../deployment/distributed-sequencing.mdx), at least 4 Maru validators are required to tolerate one faulty validator -- Access controls: whether to implement [RBAC](../deployment/rbac.mdx) on RPC +- [Access control](../deployment/access-control.mdx): whether to implement RBAC on RPC endpoints - [Key management](../../protocol/architecture/index.mdx#web3signer): remote signing backed by a hardware security module (HSM) or key management service @@ -90,8 +90,8 @@ and access-control design; Lineth does not certify a deployment as compliant. set - Data visibility: transaction details are not posted to the finalization layer; what participants can see depends on the deployment's data availability and - [RBAC](../deployment/rbac.mdx) configuration -- Access control: RPC endpoints protected by [RBAC](../deployment/rbac.mdx); only + access control configuration +- [Access control](../deployment/access-control.mdx): RPC endpoints protected by RBAC; only authorized participants can view data they are scoped to - [Finalization](../../network/overview/transaction-finality.mdx): state commitments and proofs are posted to the finalization layer @@ -121,7 +121,7 @@ what is not claimed. - Validator topology: at least 4 Maru validators are required for a [QBFT design](../deployment/distributed-sequencing.mdx) that tolerates one faulty validator -- Access controls: [RBAC](../deployment/rbac.mdx) on RPC endpoints and API portal +- [Access control](../deployment/access-control.mdx): RBAC on RPC endpoints and API portal - [Key management](../../protocol/architecture/index.mdx#web3signer): remote signing backed by a hardware security module (HSM) or key management service (KMS) diff --git a/docs/stack/evaluate/security.mdx b/docs/stack/evaluate/security.mdx index 432dc59643..66137562ec 100644 --- a/docs/stack/evaluate/security.mdx +++ b/docs/stack/evaluate/security.mdx @@ -57,7 +57,7 @@ Lineth does not ship a production security operations program. Operators are responsible for: - Infrastructure isolation and network security controls -- [Role-based access control (RBAC)](../deployment/rbac.mdx) for APIs and services. +- [Access control](../deployment/access-control.mdx) for JSON-RPC, APIs, and tooling. - Key management via KMS-backed signing and remote signing through [Web3Signer](../../protocol/architecture/index.mdx#web3signer). - Governance contracts or multisig controls for privileged roles, proxy diff --git a/docs/stack/evaluate/trust-model.mdx b/docs/stack/evaluate/trust-model.mdx index 916e1d7029..195f08ca92 100644 --- a/docs/stack/evaluate/trust-model.mdx +++ b/docs/stack/evaluate/trust-model.mdx @@ -17,7 +17,7 @@ For more information on deployment topology, see [Deployment components](../depl | 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 [RBAC](../deployment/rbac.mdx) deployments, transactions or blocks only to the extent participants have the relevant data and access | +| | | 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 | @@ -25,7 +25,7 @@ For more information on deployment topology, see [Deployment components](../depl | 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 [RBAC](../deployment/rbac.mdx) deployment necessarily runs a full or archive node | +| 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 @@ -69,7 +69,7 @@ A private validium on Linea Mainnet | 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/rbac.mdx) access cannot reconstruct or verify affected private data | Operator-defined wind-down procedure; depends on consortium agreement and is not protocol-enforced | +| 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 | @@ -91,12 +91,12 @@ The set of guarantees a participant can verify *without* trusting the operator d - 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 [RBAC](../deployment/rbac.mdx) settings may further limit which data each participant can observe. +- 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 Mainnet** - 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 [RBAC](../deployment/rbac.mdx) caveats as private validium on Ethereum, but proofs are verified on Linea Mainnet (which is itself proved to Ethereum). +- 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. ## See also diff --git a/docs/stack/evaluate/validium.mdx b/docs/stack/evaluate/validium.mdx index f5e297c782..96003f872d 100644 --- a/docs/stack/evaluate/validium.mdx +++ b/docs/stack/evaluate/validium.mdx @@ -10,7 +10,7 @@ import GlossaryTerm from '@theme/GlossaryTerm'; This page describes what a deployment publishes, retains offchain, makes visible, and allows participants to verify. -For access policy, see [Access control](../deployment/rbac.mdx). +For access policy, see [Access control](../deployment/access-control.mdx). For regulatory compliance, see [Compliance](./compliance.mdx). This page does not cover cryptographic private execution or private state. @@ -33,7 +33,7 @@ State commitments and proofs are posted onchain. Transaction data is not. | -------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- | | Finalization layer | State commitments, zk-SNARK proofs, bridge messages | Anyone reading the finalization layer | | Operator data availability layer | Transaction data, full ordered history | Participants the operator authorizes, per the deployment's data access model | -| RPC and API surfaces | State and transactions the caller is authorized to view | Callers with [RBAC](../deployment/rbac.mdx) permissions for the relevant endpoint | +| RPC and API surfaces | State and transactions the caller is authorized to view | Callers with [RBAC permissions](../deployment/access-control.mdx) for the relevant endpoint | Offchain data availability changes where transaction data lives. It does not by itself make transactions cryptographically private. A participant with access to @@ -49,18 +49,14 @@ participant can verify their own state against the onchain commitments using Unlike a public network, a validium does not give every participant a full view of all transactions or their ordering. Reconstruction or independent verification of full history requires access to the offchain data, which the -deployment's [RBAC](../deployment/rbac.mdx) and governance rules control. +deployment's [access control](../deployment/access-control.mdx) and governance rules control. ## Access control -[RBAC](../deployment/rbac.mdx) controls access to network functionality: +The [privacy proxy](../deployment/access-control.mdx) controls access to JSON-RPC, APIs, and tooling, +determined by role-based permissions. -- RPC endpoints: access controlled by API keys and permissions -- API portal: institution-level access controls -- Transaction visibility: participants see only transactions they are authorized - to view - -RBAC is an access policy. It controls who can call an endpoint or view data the +Access control restricts who can call an endpoint or view data the deployment exposes. It is not a cryptographic privacy mechanism and does not hide data from the operator or from participants who already hold the data. @@ -114,7 +110,7 @@ For the full trust assumptions, see ### Security features - Minimum node count: 4 nodes for QBFT fault tolerance -- Access controls: [RBAC](../deployment/rbac.mdx) on RPC and API endpoints +- [Access control](../deployment/access-control.mdx): Role-based permissions on JSON-RPC, APIs, and tooling - Key management: supports [Web3Signer](../../protocol/architecture/index.mdx#web3signer) remote signing backed by a hardware security module (HSM) or key management service (KMS) diff --git a/redirects.json b/redirects.json index 375e467f09..ca81e16627 100644 --- a/redirects.json +++ b/redirects.json @@ -1498,9 +1498,10 @@ ] }, { - "to": "/stack/deployment/rbac", + "to": "/stack/deployment/access-control", "from": [ - "/stack/features/rbac" + "/stack/features/rbac", + "/stack/deployment/rbac" ] }, { diff --git a/sidebars.js b/sidebars.js index 2d758b81bc..76e1fd9e03 100644 --- a/sidebars.js +++ b/sidebars.js @@ -480,7 +480,7 @@ const sidebars = { "stack/deployment/fast-finality", "stack/deployment/distributed-sequencing", "stack/deployment/high-availability", - "stack/deployment/rbac", + "stack/deployment/access-control", ], }, { diff --git a/src/lib/glossary.json b/src/lib/glossary.json index 79ab6e903c..282c289e37 100644 --- a/src/lib/glossary.json +++ b/src/lib/glossary.json @@ -157,10 +157,6 @@ "term": "Reorg", "definition": "A chain reorganization that occurs when the blockchain discards one recent branch of blocks and switches to a different, competing branch that the protocol now considers the canonical chain.\n\nEthereum’s Layer 1 uses the Gasper proof-of-stake consensus algorithm which is designed to minimize trust assumptions and maximize security. Gasper allows for global decentralized settlement, but finality takes 64 slots, or 12.8 minutes.\n\nWhile Ethereum may reorg, Linea does not. The zero knowledge validity proof created by Linea attests to a specific and correct L2 chain state, and any attempt to reorganize the L2 would invalidate the ZK proof and the state it testifies to on that's recorded on Ethereum. Therefore, L1 finality provides the firmest security guarantees against block reorganization by Linea.\n\nFurthermore, Linea takes action to ensure that interoperability between the public network and the Layer 1 preserves the property of preventing block reorganizations. Before any interoperating transaction anchored to Layer 1 state (for example, a deposit of a token into the bridge), Linea will wait for the Layer 1 state to be finalized before committing the appropriate action on the Layer 2. This ensures that even a reorganization of Ethereum, which is an expected and normal part of operations, does not result in a reorganization of the Linea L2." }, - { - "term": "Role-based access control (RBAC)", - "definition": "Operator-configured access control for protected Lineth RPC, API, and tooling surfaces. RBAC determines which protected interfaces and data a participant can access, but it is not cryptographic privacy: it doesn't encrypt public-chain data, replace zero-knowledge proof verification, or provide data availability on its own." - }, { "term": "Rollup", "definition": "A type of L2 scaling solution that batches multiple transactions and submits them to Ethereum in a single transaction. This allows for reductions in gas costs and increases in transaction throughput. There are optimistic and zero-knowledge rollups, which use different security methods to offer these scalability gains.\n\nRollup architecture is made up of the following components:\n\n- Rollup contract: contract on the L1 stores rollup blocks, monitors state updates on the rollup, and tracks user deposits\n- Offchain VM: computation and state storage on another virtual machine separate from the Ethereum Virtual Machine\n- Aggregators/sequencers/operators/validators: nodes that aggregate transactions, compress the underlying data, and publish the block on Ethereum\n- Verifier contract: contract on the L1 that verifies the validity proof" diff --git a/static/img/stack/deployment/lineth-deployment-architecture.svg b/static/img/stack/deployment/lineth-deployment-architecture.svg index b8fe5dc6f9..e00df99ac7 100644 --- a/static/img/stack/deployment/lineth-deployment-architecture.svg +++ b/static/img/stack/deployment/lineth-deployment-architecture.svg @@ -8,7 +8,7 @@ > Example Lineth validium deployment architecture - Trusted partners reach RBAC, which gates the API portal and block explorer + Trusted partners reach access control, which gates the API portal and block explorer inside the Lineth private network. Those tools query near-head and archive RPC nodes, which read onchain system contracts. Internal protocol services including the coordinator, execution services, and core services also @@ -37,12 +37,12 @@ Trusted partners - + RBAC + fill="var(--linea-text-primary)">Access control - + - + diff --git a/static/llms.txt b/static/llms.txt index 72c0b6fc29..a00180e79d 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -183,7 +183,7 @@ - [Data availability and finalization](https://docs.linea.build/stack/deployment/data-availability-finalization): How deployment choices affect data availability and finalization. - [Finality design](https://docs.linea.build/stack/deployment/fast-finality): Application-level and settlement finality choices. - [Multi-validator consensus](https://docs.linea.build/stack/deployment/distributed-sequencing): Maru QBFT design, fault-tolerance scope, topology, and latency trade-offs. -- [Access control](https://docs.linea.build/stack/deployment/rbac): Operator-configured access policy for protected surfaces. +- [Access control](https://docs.linea.build/stack/deployment/access-control): Operator-configured access policy for protected surfaces. - [Run a local Lineth Stack](https://docs.linea.build/stack/how-to/run-local-lineth-stack): Non-production local Stack workflow. - [Set up distributed sequencing](https://docs.linea.build/stack/how-to/set-up-distributed-sequencing): Set up and operate Maru multi-validator mode. - [Enable forced transactions](https://docs.linea.build/stack/how-to/enable-forced-transactions): Enable forced transactions on a Lineth deployment (not yet live). From 95a3fd8e975d33dd5ea3f7b20188adc0fe43b02e Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Wed, 26 Aug 2026 11:14:31 -0700 Subject: [PATCH 2/6] minor fixes --- docs/stack/deployment/access-control.mdx | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/stack/deployment/access-control.mdx b/docs/stack/deployment/access-control.mdx index cc6b346a9d..460232500c 100644 --- a/docs/stack/deployment/access-control.mdx +++ b/docs/stack/deployment/access-control.mdx @@ -1,9 +1,6 @@ --- title: Access control -description: >- - Operator-configured access policy for protected Lineth RPC, API, and tooling - surfaces -sidebar_position: 5 +description: How the access control stack works, including privacy proxy, RBAC model, and block explorer image: /img/socialCards/access-control.jpg --- @@ -71,16 +68,16 @@ flowchart TB PX["Privacy proxy"]:::access ND["Lineth node"]:::core IDX["Chain indexer"]:::access - POL["RBAC database"]:::neutral - AUD["Access log"]:::neutral + DB["RBAC database"]:::neutral + LOG["Access log"]:::neutral CL --> PX EX -->|"every read"| PX PX -->|"JSON-RPC"| ND PX -->|"gRPC"| IDX IDX -->|"indexes"| ND - PX -.-> POL - PX -.-> AUD + PX -.-> DB + PX -.-> LOG ``` @@ -177,7 +174,3 @@ They do not receive a view of private contracts or transaction data. data availability and controlled access. - [Trust and responsibilities](../evaluate/trust-model.mdx): What participants can verify when access and data availability are restricted. -- [Security and assurance](../evaluate/security.mdx): How the privacy proxy fits into operational security controls. -- [Deployment models](../evaluate/deployment-models.mdx): How access control factors into deployment design. -- [RPC services](../../protocol/architecture/rpc-services.mdx): How RPC services expose blockchain data and - can sit behind access controls. From e6f2a808c6b80a93eeb87190b34eafdbb1b54130 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Tue, 1 Sep 2026 14:22:06 -0700 Subject: [PATCH 3/6] address feedback --- docs/protocol/architecture/index.mdx | 16 +-- docs/stack/deployment/access-control.mdx | 130 +++++++++----------- docs/stack/deployment/high-availability.mdx | 2 +- docs/stack/deployment/index.mdx | 2 +- docs/stack/evaluate/validium.mdx | 9 +- 5 files changed, 71 insertions(+), 88 deletions(-) diff --git a/docs/protocol/architecture/index.mdx b/docs/protocol/architecture/index.mdx index 4646404698..1cae21be5d 100644 --- a/docs/protocol/architecture/index.mdx +++ b/docs/protocol/architecture/index.mdx @@ -163,20 +163,14 @@ For more information about the system contracts, see [Smart contracts](./smart-c ### Block explorer The block explorer is an optional, operator-facing service used for inspection, troubleshooting, and -auditing. - -Linea Mainnet uses [Blockscout](https://github.com/blockscout/blockscout), an +auditing. Linea Mainnet uses [Blockscout](https://github.com/blockscout/blockscout), an open-source, self-hosted explorer that indexes chain data from execution nodes and presents it via a web interface. -The explorer connects to the network via JSON-RPC or WebSocket, continuously indexes blocks, -transactions, logs, and token data, and stores this information in a relational database. -[Restricted deployments](../../stack/deployment/access-control.mdx) use a different block explorer setup: the explorer -is a backend-for-frontend that reads only through the privacy proxy, which evaluates role-based permissions -and retrieves data from a separate chain indexer. - -In either case, the explorer allows operators to inspect blocks and transactions, review contract -activity, track bridge operations, and monitor network health. +The explorer connects to the network via JSON-RPC or WebSocket, continuously indexes blocks, +transactions, logs, and token data, and stores this information in a relational database. It allows +operators to inspect blocks and transactions, review contract activity, track bridge operations, and +monitor network health. Block explorers are not required for network operation and do not participate in consensus, execution, or finalization. They can be deployed, replaced, or omitted without affecting correctness diff --git a/docs/stack/deployment/access-control.mdx b/docs/stack/deployment/access-control.mdx index 460232500c..2612a3ef1d 100644 --- a/docs/stack/deployment/access-control.mdx +++ b/docs/stack/deployment/access-control.mdx @@ -1,48 +1,49 @@ --- title: Access control -description: How the access control stack works, including privacy proxy, RBAC model, and block explorer +description: >- + How a restricted Lineth deployment exposes a single RPC endpoint that + enforces access control image: /img/socialCards/access-control.jpg --- import GlossaryTerm from '@theme/GlossaryTerm'; -This page describes how a deployment can control access to JSON-RPC, APIs, -and tooling. -In a restricted deployment, a privacy proxy authenticates callers, evaluates role-based permissions, and -traces calls. +This page describes how a deployment can restrict JSON-RPC access. +In a restricted deployment, clients send all reads and writes to a single RPC endpoint. +That endpoint authenticates callers and enforces role-based access control (RBAC) permissions. For data visibility choices, see [Privacy and data visibility](../evaluate/validium.mdx). :::important Access control is not cryptographic privacy. -The privacy proxy limits who can use protected services and data surfaces, but it does not make public -chain data private, replace zero-knowledge proofs, or provide data availability. +It limits who can use the operator's RPC, but it does not make public chain data private, replace +zero-knowledge proofs, or provide data availability. ::: ## Access control stack -Operators can choose to configure access control, independent of +Operators can configure access control independently of [deployment model](../evaluate/deployment-models.mdx) and [data availability](data-availability-finalization.mdx). -The access control stack consists of the following services: - -- **Privacy proxy:** An [Open Privacy Suite](https://gateway-fm.github.io/open-privacy-suite/) JSON-RPC - reverse proxy. - Every wallet, app, and admin request to the Lineth node goes through it. - [RBAC](#role-based-access-control-rbac) records live in a PostgreSQL database. - A separate database records JSON-RPC access logs. -- **Block explorer:** Displays blocks, transactions, logs, and transfers in a web interface. - The explorer's API is a backend-for-frontend (BFF). - It holds no chain data of its own. - Every read goes to the proxy, which redacts the response for that caller. -- **Chain indexer:** Indexes blocks, transactions, and logs from the node and serves raw chain data over - gRPC on a trusted network. - It has no authentication, access policy, or redaction. - Only the proxy consumes the indexer. - -
+ +A restricted deployment exposes **one RPC endpoint**. +Wallets, apps, and other clients access this endpoint, not the Lineth node directly. + +The access control endpoint: + +- Authenticates the caller. +- Enforces rules for who can call which JSON-RPC methods and which contracts. +- Forwards allowed requests to the node. +- Returns only data the caller is permitted to see. + +Permission data and JSON-RPC access logs are recorded in [audit databases](#audit-logs). + +Applications built on the stack must implement authentication to communicate with the +endpoint, as well as their own read and write flows on top of the endpoint. + +
```mermaid %%{init: { "themeVariables": { @@ -60,51 +61,48 @@ The access control stack consists of the following services: flowchart TB classDef core stroke-width:1.5px; classDef access stroke-width:1.5px; - classDef control stroke-width:1.5px,stroke-dasharray:6 4; classDef neutral stroke-width:1.5px; - CL["Wallets, apps, and admin clients"]:::neutral - EX["Block explorer"]:::access - PX["Privacy proxy"]:::access + CL["Wallets and apps"]:::neutral + EP["Access control RPC endpoint"]:::access ND["Lineth node"]:::core - IDX["Chain indexer"]:::access - DB["RBAC database"]:::neutral - LOG["Access log"]:::neutral - - CL --> PX - EX -->|"every read"| PX - PX -->|"JSON-RPC"| ND - PX -->|"gRPC"| IDX - IDX -->|"indexes"| ND - PX -.-> DB - PX -.-> LOG + POL["RBAC database"]:::control + AUD["Access log"]:::control + + CL -->|"authenticate, then read or write"| EP + EP -->|"allowed JSON-RPC"| ND + EP -.-> POL + EP -.-> AUD ```
A public or private deployment can configure access control. In a public deployment, transaction data is posted to the -finalization layer, so the proxy restricts who uses -the operator's interfaces; it does not hide onchain data. +finalization layer, so the endpoint restricts who +uses the operator's RPC; it does not hide onchain data. A private validium keeps transaction data offchain, so the -proxy is the path to chain data as well as the operator's interfaces. +endpoint is also the path to chain data. ### Role-based access control (RBAC) -The privacy proxy uses a role-based access control (RBAC) model: permissions are organization-scoped and group-centric. -After the proxy authenticates the caller, it checks the group's method allowlist, claims, and contract grants. +The endpoint evaluates a role-based access control (RBAC) model: permissions are +organization-scoped and group-centric. +After the endpoint authenticates the caller, it checks the group's method allowlist, claims, and +contract grants. - An **organization** is the tenant boundary. Users, groups, and contract registrations belong to an organization. - A **group** is a named collection of users that share one permission set. Groups can be marked as organization admin or read-only admin. -- A **user** is an individual member of one or more groups, identified by a decentralized identifier (DID). +- A **user** is an individual member of one or more groups, identified by a decentralized identifier + (DID). Optional flags cover KYC status and bans. A group's permission set includes: - **Method allowlist:** Which JSON-RPC methods members may call. - **Claims:** Extra permissions on top of the method allowlist: `deploy` (create contracts), `upgrade` - (upgrade proxy contracts), and `admin` (includes deploy and upgrade). + (upgrade contracts), and `admin` (includes deploy and upgrade). - **Contract grants:** Per-group permission on a registered contract: this group may use this contract, optionally limited to function selectors, parameter constraints, and event topics. Contracts stay private until a grant exists. @@ -114,23 +112,12 @@ A group's permission set includes: example, a parameter that must equal the caller's own address). - Event rules can deny logs, allow all, or allow specific event topics. -Operators manage organizations, groups, users, and contract grants through the proxy's admin API and dashboard. -See the [Open Privacy Suite RBAC docs](https://gateway-fm.github.io/open-privacy-suite/docs/rbac/) for more information. - -### Explorer and indexer - -A restricted deployment uses its own block explorer and chain indexer. -The explorer uses data from the indexer (blocks, transactions, logs, and transfers). -The indexer always stores real addresses and values, and returns whatever is requested. - -The privacy proxy sits between the explorer and chain indexer. -Only the proxy consumes the indexer, and every explorer read goes to the proxy, which applies the same -[RBAC](#role-based-access-control-rbac) permissions and redaction used on JSON-RPC. -Explorer responses must not be cached across callers, and you must not set a direct indexer URL. +This RBAC data is stored in a PostgreSQL database. +The access control endpoint reads that data when it evaluates a request. ### Audit logs -The privacy proxy writes two streams: +The access control endpoint writes two streams: - **Access log:** One record per JSON-RPC decision (allow or deny), stored in a database separate from RBAC data, with a restricted append-only role and a hash chain over entries. @@ -143,29 +130,30 @@ These logs are evidence that a request was allowed or denied under the active ## How a request is evaluated -Clients send JSON-RPC requests to the proxy, not to the node. -A typical request is evaluated in this order: +Clients send JSON-RPC requests to the access control endpoint, not to the Lineth node. +The endpoint evaluates a typical request in this order: 1. Authenticate the caller via JSON Web Token (JWT). -2. Reject globally blocked methods (including `debug_*` and `admin_*` namespaces, and multicall patterns - that would otherwise bypass contract grants). +2. Reject globally blocked methods (including `debug_*` and `admin_*` namespaces, and multicall + patterns that would otherwise bypass contract grants). 3. Resolve the caller's organization, groups, and permissions. 4. Check the method against the group's RPC method allowlist. -5. If the call targets a contract, check that contract grant (and function selector, parameter, and event - rules where they exist). +5. If the call targets a contract, check that contract grant (and function selector, parameter, and + event rules where they exist). 6. Simulate the call with `debug_traceCall` and reject it if any internal `CALL`, `DELEGATECALL`, `STATICCALL`, or `CREATE` target is outside the caller's organization. 7. Forward the request to the node, then redact the response before returning it. -The proxy binds the call's sender to the authenticated account, so a caller cannot inherit another +The endpoint binds the call's sender to the authenticated account, so a caller cannot inherit another account's onchain permissions by spoofing `from`. -Evaluation is fail-closed: a missing permission, an unknown contract, a tracing failure, or an unreachable -node during simulation denies the request. +Evaluation is fail-closed: a missing permission, an unknown contract, a tracing failure, or an +unreachable node during simulation denies the request. Denied JSON-RPC calls are returned to the client as a generic "method not found" error. The detailed reason is written to the access log for operators. -Anonymous, unauthenticated requests can be limited to claim-free metadata such as `eth_chainId` and `eth_blockNumber`. +Anonymous, unauthenticated requests can be limited to claim-free metadata such as `eth_chainId` and +`eth_blockNumber`. They do not receive a view of private contracts or transaction data. ## See also diff --git a/docs/stack/deployment/high-availability.mdx b/docs/stack/deployment/high-availability.mdx index 03eb4fd143..4cdd91a501 100644 --- a/docs/stack/deployment/high-availability.mdx +++ b/docs/stack/deployment/high-availability.mdx @@ -109,7 +109,7 @@ This table summarizes which components run in which regions: In the example design, public RPC enters through a global entry point that routes each client to the nearest healthy region (for example, [AWS Global Accelerator](https://aws.amazon.com/global-accelerator/)), protected by a web -application firewall, then a regional load balancer, a privacy proxy for [access control](./access-control.mdx), and +application firewall, then a regional load balancer, an [access control](./access-control.mdx) endpoint, and JSON-RPC routers to [near-head and archive nodes](../../protocol/architecture/rpc-services.mdx). Private RPC can use private connectivity into each region (for example, diff --git a/docs/stack/deployment/index.mdx b/docs/stack/deployment/index.mdx index 2b92646017..003a2071e0 100644 --- a/docs/stack/deployment/index.mdx +++ b/docs/stack/deployment/index.mdx @@ -51,7 +51,7 @@ Detailed production topology and supported tooling for a given deployment can be { text: "Access control", description: - "How the access control stack works: privacy proxy at the RPC edge, RBAC permissions, block explorer, and chain indexer.", + "How to restrict access to JSON-RPC using a single endpoint that authenticates callers and enforces RBAC permissions.", href: "/stack/deployment/access-control", }, ]} diff --git a/docs/stack/evaluate/validium.mdx b/docs/stack/evaluate/validium.mdx index 96003f872d..7d779b6bec 100644 --- a/docs/stack/evaluate/validium.mdx +++ b/docs/stack/evaluate/validium.mdx @@ -53,11 +53,12 @@ deployment's [access control](../deployment/access-control.mdx) and governance r ## Access control -The [privacy proxy](../deployment/access-control.mdx) controls access to JSON-RPC, APIs, and tooling, -determined by role-based permissions. +A private validium can restrict JSON-RPC access by configuring [access control](../deployment/access-control.mdx). +Clients send request to a single RPC endpoint that authenticates callers and enforces +RBAC permissions. -Access control restricts who can call an endpoint or view data the -deployment exposes. It is not a cryptographic privacy mechanism and does not +Access control restricts who can call RPC methods. +It is not a cryptographic privacy mechanism and does not hide data from the operator or from participants who already hold the data. ## Finalization layer options From fbf16b29f4115948aaf6c77c5c4d4d3f71acd5a6 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Wed, 2 Sep 2026 16:58:33 -0700 Subject: [PATCH 4/6] Document deployment interoperability --- .../architecture/interoperability/index.mdx | 6 + docs/stack/deployment/access-control.mdx | 4 + .../deployment-interoperability.mdx | 148 ++++++++++++++++++ docs/stack/deployment/index.mdx | 8 + sidebars.js | 1 + static/llms.txt | 1 + 6 files changed, 168 insertions(+) create mode 100644 docs/stack/deployment/deployment-interoperability.mdx diff --git a/docs/protocol/architecture/interoperability/index.mdx b/docs/protocol/architecture/interoperability/index.mdx index 8e348abd94..3079ead3cc 100644 --- a/docs/protocol/architecture/interoperability/index.mdx +++ b/docs/protocol/architecture/interoperability/index.mdx @@ -24,3 +24,9 @@ blocks that sent them are finalized. From the finalization layer to the Lineth network, messages are recorded on the network first, and checked against the finalization layer at the next finalization. See [Message commitments](./canonical-message-service.mdx#message-commitments) for more information. + +This section is the **network to finalization layer** axis. +Calls between two Lineth deployments use a different mechanism. +On a restricted destination, the access control endpoint authorizes the call instead of +permissionless claiming. +See [Deployment interoperability](../../../stack/deployment/deployment-interoperability.mdx). diff --git a/docs/stack/deployment/access-control.mdx b/docs/stack/deployment/access-control.mdx index 2612a3ef1d..d84b2db0ea 100644 --- a/docs/stack/deployment/access-control.mdx +++ b/docs/stack/deployment/access-control.mdx @@ -13,6 +13,8 @@ In a restricted deployment, clients send all reads and writes to a single RPC en That endpoint authenticates callers and enforces role-based access control (RBAC) permissions. For data visibility choices, see [Privacy and data visibility](../evaluate/validium.mdx). +For calls between two Lineth deployments, see +[Deployment interoperability](./deployment-interoperability.mdx). :::important @@ -158,6 +160,8 @@ They do not receive a view of private contracts or transaction data. ## See also +- [Deployment interoperability](./deployment-interoperability.mdx): How two Lineth deployments + exchange calls, and how a restricted destination authorizes them against this permission model. - [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 diff --git a/docs/stack/deployment/deployment-interoperability.mdx b/docs/stack/deployment/deployment-interoperability.mdx new file mode 100644 index 0000000000..0c776854a1 --- /dev/null +++ b/docs/stack/deployment/deployment-interoperability.mdx @@ -0,0 +1,148 @@ +--- +title: Deployment interoperability +description: >- + How two Lineth deployments exchange contract calls, and how a restricted + destination authorizes those calls +--- + +import GlossaryTerm from '@theme/GlossaryTerm'; + +This page describes how two deployments communicate with each +other. + +A Lineth network communicates with its +finalization layer through +[canonical interoperability](../../protocol/architecture/interoperability/index.mdx), using +the message service and token bridge. +Claiming is permissionless: anyone who can submit the claim can execute the message. + +When a Lineth network wants to communicate with another Lineth network that is not +[access controlled](access-control.mdx) (unrestricted), and the networks share a +finalization layer, they can use canonical interoperability: the source network sends a +message to the finalization layer, and the destination network claims it from the finalization layer. + +When a Lineth network wants to communicate with an [access controlled](access-control.mdx) (restricted) +network, or the two deployments do not share a finalization layer, they communicate +directly with each other over a trusted bridge. +The destination network's access control endpoint checks the inbound call against role-based +access control (RBAC) permissions before it accepts the call. + +
+```mermaid +%%{init: { + "themeVariables": { + "fontFamily": "AtypText, sans-serif" + }, + "flowchart": { + "useMaxWidth": true, + "curve": "linear", + "nodeSpacing": 24, + "rankSpacing": 36, + "padding": 12, + "wrappingWidth": 160 + } +}}%% +flowchart TD + classDef core stroke-width:1.5px; + classDef neutral stroke-width:1.5px; + + U1["Unrestricted
network"]:::core + FLA["Finalization
layer"]:::neutral + U2["Unrestricted
network"]:::core + U1 -->|"claim"| FLA + U2 -->|"send"| FLA + + R["Restricted
network"]:::core + U1 -->|"trusted bridge
with RBAC"| R +``` +
+ +## Communicating with a restricted network + +Two restricted networks can communicate with each other as follows: + +1. Each operator onboards organizations, groups, and users at that deployment's + [access control](./access-control.mdx) endpoint, and registers the contracts those groups may use. +2. Users present credentials to the endpoint and send reads and writes to that RPC. + Wallets and apps do not talk to the Lineth node directly. +3. The destination operator configures that node with the access control endpoint's + address and the admin credential the endpoint expects. + Set both, or set neither. + If only one is set, the node refuses to start, so a half-configured check cannot skip + authorization or reject every inbound call. + If neither is set, inbound calls are allowed without asking the endpoint. +4. A user (or contract) stages a cross-chain call to a peer deployment. +5. The two deployments run a two-phase commit: **prepare**, then **commit** or **abort**. + In the prepare phase, they simulate the inbound call until both sides agree on the same + result. +6. The policy subject is the source address: `msg.sender` at the cross-chain root, not `tx.origin`. + The destination qualifies that address with the source chain and looks it up in its own org, + group, and contract grant records. +7. In the commit phase, the destination asks its access control endpoint whether that agreed + call would be allowed as a live RPC request. + If the endpoint allows the call, both sides commit. + If it denies the call, or if the endpoint is unreachable, both sides abort. + Evaluation is fail-closed. +8. Both deployments record the decision on their append-only access logs. + +
+```mermaid +%%{init: { + "themeVariables": { + "fontFamily": "AtypText, sans-serif" + }, + "sequence": { + "useMaxWidth": true, + "actorMargin": 16, + "width": 160 + } +}}%% +sequenceDiagram + participant App as Wallets and apps + participant Src as Source access control endpoint + participant Dest as Destination deployment + participant DestEP as Destination access control endpoint + + App->>Src: Authenticate, then stage the call + Src->>Dest: Prepare + Dest->>DestEP: Is this root call allowed? + DestEP->>DestEP: Check grants for msg.sender + alt Allowed + DestEP-->>Dest: Allow + Dest-->>Src: Commit + else Denied or unreachable + DestEP-->>Dest: Deny + Dest-->>Src: Abort + end + DestEP->>DestEP: Write access log +``` +
+ +The destination allowlists which contracts may be called cross-chain by using the same contract +grants as live RPC. +The source deployment still enforces per-user access before the call is staged. +There is not a separate permission list for cross-chain calls. + +:::info Trust assumptions and networking + +Deployment interoperability is a [trusted bridge](../evaluate/trust-model.mdx): there is no shared proof across the two +Lineth networks that replaces operator and relayer trust. +Each side trusts its own access control configuration (if any), its own permissions, and the peer +deployment endpoints it has configured. + +The wire between peer deployments is gRPC. +Mutual TLS is not required today. +Until it is, run that channel on an isolated operator network and restrict it with firewalls; do +not expose peer endpoints to the public internet. + +::: + +## See also + +- [Access control](./access-control.mdx): Permission model, request pipeline, and audit. +- [Interoperability](../../protocol/architecture/interoperability/index.mdx): Canonical messaging + and token bridging to the finalization layer. +- [Trust and responsibilities](../evaluate/trust-model.mdx): Trusted-bridge row and what + participants can verify. +- [Privacy and data visibility](../evaluate/validium.mdx): Offchain data availability versus access + policy. diff --git a/docs/stack/deployment/index.mdx b/docs/stack/deployment/index.mdx index 003a2071e0..c0fa1309f7 100644 --- a/docs/stack/deployment/index.mdx +++ b/docs/stack/deployment/index.mdx @@ -54,6 +54,12 @@ Detailed production topology and supported tooling for a given deployment can be "How to restrict access to JSON-RPC using a single endpoint that authenticates callers and enforces RBAC permissions.", href: "/stack/deployment/access-control", }, + { + text: "Deployment interoperability", + description: + "Peer Lineth calls over a two-phase commit, distinct from canonical bridging. A restricted destination authorizes the call against the same access control as live RPC.", + href: "/stack/deployment/deployment-interoperability", + }, ]} /> @@ -118,6 +124,8 @@ The example architecture flows as follows: 6. Interoperability with the finalization layer uses the [canonical token bridge and message service](../../protocol/architecture/interoperability/index.mdx). This example also shows validium message relayers to other enterprise or public chains. + Calls between two Lineth deployments are a separate path; see + [Deployment interoperability](./deployment-interoperability.mdx). See [Trust and responsibilities](../evaluate/trust-model.mdx) for who operates each component, what it can do, and what participants can verify. diff --git a/sidebars.js b/sidebars.js index 76e1fd9e03..d52b27435b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -481,6 +481,7 @@ const sidebars = { "stack/deployment/distributed-sequencing", "stack/deployment/high-availability", "stack/deployment/access-control", + "stack/deployment/deployment-interoperability", ], }, { diff --git a/static/llms.txt b/static/llms.txt index a00180e79d..088d083e01 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -184,6 +184,7 @@ - [Finality design](https://docs.linea.build/stack/deployment/fast-finality): Application-level and settlement finality choices. - [Multi-validator consensus](https://docs.linea.build/stack/deployment/distributed-sequencing): Maru QBFT design, fault-tolerance scope, topology, and latency trade-offs. - [Access control](https://docs.linea.build/stack/deployment/access-control): Operator-configured access policy for protected surfaces. +- [Deployment interoperability](https://docs.linea.build/stack/deployment/deployment-interoperability): Peer Lineth calls; a restricted destination authorizes them against access control. - [Run a local Lineth Stack](https://docs.linea.build/stack/how-to/run-local-lineth-stack): Non-production local Stack workflow. - [Set up distributed sequencing](https://docs.linea.build/stack/how-to/set-up-distributed-sequencing): Set up and operate Maru multi-validator mode. - [Enable forced transactions](https://docs.linea.build/stack/how-to/enable-forced-transactions): Enable forced transactions on a Lineth deployment (not yet live). From e2be145b9ad3e5e1a0d19d9349a45e67c516c5e6 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Thu, 3 Sep 2026 09:19:32 -0700 Subject: [PATCH 5/6] fix link --- docs/stack/evaluate/deployment-models.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/stack/evaluate/deployment-models.mdx b/docs/stack/evaluate/deployment-models.mdx index 1c9cc47766..b89e4b5f12 100644 --- a/docs/stack/evaluate/deployment-models.mdx +++ b/docs/stack/evaluate/deployment-models.mdx @@ -66,7 +66,7 @@ RPC access is public, and node membership is not restricted. A private validium keeps transaction data offchain, using proofs to support state-transition correctness and finalization. -RPC endpoints are protected by [RBAC](../deployment/rbac.mdx), and node membership is controlled. +RPC endpoints are protected by [access control](../deployment/access-control.mdx), and node membership is controlled. Whether this model suits a regulated environment depends on the operator's own compliance, privacy, From 1baf168e5411c39aab5e95d48e1cf10a69581691 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Thu, 3 Sep 2026 10:25:23 -0700 Subject: [PATCH 6/6] edits --- .../architecture/interoperability/index.mdx | 9 ++- docs/stack/deployment/access-control.mdx | 4 +- .../deployment-interoperability.mdx | 71 +++++++------------ docs/stack/deployment/index.mdx | 4 +- 4 files changed, 32 insertions(+), 56 deletions(-) diff --git a/docs/protocol/architecture/interoperability/index.mdx b/docs/protocol/architecture/interoperability/index.mdx index 3079ead3cc..77d05a42df 100644 --- a/docs/protocol/architecture/interoperability/index.mdx +++ b/docs/protocol/architecture/interoperability/index.mdx @@ -25,8 +25,7 @@ From the finalization layer to the Lineth network, messages are recorded on the the finalization layer at the next finalization. See [Message commitments](./canonical-message-service.mdx#message-commitments) for more information. -This section is the **network to finalization layer** axis. -Calls between two Lineth deployments use a different mechanism. -On a restricted destination, the access control endpoint authorizes the call instead of -permissionless claiming. -See [Deployment interoperability](../../../stack/deployment/deployment-interoperability.mdx). +:::note +Two learn how two Lineth deployments communicate with each other, see +[Deployment interoperability](../../../stack/deployment/deployment-interoperability.mdx). +::: diff --git a/docs/stack/deployment/access-control.mdx b/docs/stack/deployment/access-control.mdx index d84b2db0ea..8bbf2706f7 100644 --- a/docs/stack/deployment/access-control.mdx +++ b/docs/stack/deployment/access-control.mdx @@ -13,8 +13,6 @@ In a restricted deployment, clients send all reads and writes to a single RPC en That endpoint authenticates callers and enforces role-based access control (RBAC) permissions. For data visibility choices, see [Privacy and data visibility](../evaluate/validium.mdx). -For calls between two Lineth deployments, see -[Deployment interoperability](./deployment-interoperability.mdx). :::important @@ -161,7 +159,7 @@ They do not receive a view of private contracts or transaction data. ## See also - [Deployment interoperability](./deployment-interoperability.mdx): How two Lineth deployments - exchange calls, and how a restricted destination authorizes them against this permission model. + 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 diff --git a/docs/stack/deployment/deployment-interoperability.mdx b/docs/stack/deployment/deployment-interoperability.mdx index 0c776854a1..25458ac9b8 100644 --- a/docs/stack/deployment/deployment-interoperability.mdx +++ b/docs/stack/deployment/deployment-interoperability.mdx @@ -27,7 +27,7 @@ directly with each other over a trusted bridge. The destination network's access control endpoint checks the inbound call against role-based access control (RBAC) permissions before it accepts the call. -
+
```mermaid %%{init: { "themeVariables": { @@ -46,14 +46,15 @@ flowchart TD classDef core stroke-width:1.5px; classDef neutral stroke-width:1.5px; - U1["Unrestricted
network"]:::core + U1["Lineth network"]:::core FLA["Finalization
layer"]:::neutral - U2["Unrestricted
network"]:::core - U1 -->|"claim"| FLA - U2 -->|"send"| FLA + U2["Lineth network
(unrestricted)"]:::core + L["Lineth network"]:::core + U1 -->|"send"| FLA + U2 -->|"claim"| FLA - R["Restricted
network"]:::core - U1 -->|"trusted bridge
with RBAC"| R + R["Lineth network
(restricted)"]:::core + L -->|"trusted bridge
with RBAC"| R ```
@@ -61,29 +62,23 @@ flowchart TD Two restricted networks can communicate with each other as follows: -1. Each operator onboards organizations, groups, and users at that deployment's - [access control](./access-control.mdx) endpoint, and registers the contracts those groups may use. -2. Users present credentials to the endpoint and send reads and writes to that RPC. - Wallets and apps do not talk to the Lineth node directly. -3. The destination operator configures that node with the access control endpoint's - address and the admin credential the endpoint expects. - Set both, or set neither. - If only one is set, the node refuses to start, so a half-configured check cannot skip - authorization or reject every inbound call. - If neither is set, inbound calls are allowed without asking the endpoint. -4. A user (or contract) stages a cross-chain call to a peer deployment. -5. The two deployments run a two-phase commit: **prepare**, then **commit** or **abort**. - In the prepare phase, they simulate the inbound call until both sides agree on the same - result. -6. The policy subject is the source address: `msg.sender` at the cross-chain root, not `tx.origin`. - The destination qualifies that address with the source chain and looks it up in its own org, - group, and contract grant records. -7. In the commit phase, the destination asks its access control endpoint whether that agreed - call would be allowed as a live RPC request. +1. Operators of each network configure [role-based access control (RBAC)](./access-control.mdx) + permissions for their network. + They onboard organizations, groups, and users; and register the contracts those groups may use. +2. Each operator configures their Lineth node so its access control endpoint can evaluate the permissions + of inbound cross-chain calls. + The configuration requires the endpoint's address and an admin credential. +3. A user (or contract) from one network initiates a cross-chain call to the other network. +4. The two networks run a two-phase commit: **prepare**, then **commit** or **abort**. + In the prepare phase, they simulate the call until both sides agree on the same result. +5. In the commit phase, the destination asks its access control endpoint whether that + agreed call would be allowed as a live RPC request. + The endpoint evaluates the original caller against the destination's own RBAC policy: + `msg.sender` of the cross-chain call, not `tx.origin` of the source transaction. If the endpoint allows the call, both sides commit. If it denies the call, or if the endpoint is unreachable, both sides abort. - Evaluation is fail-closed. -8. Both deployments record the decision on their append-only access logs. +6. The destination access control endpoint records the decision on its append-only + access log.
```mermaid @@ -118,31 +113,17 @@ sequenceDiagram ```
-The destination allowlists which contracts may be called cross-chain by using the same contract -grants as live RPC. -The source deployment still enforces per-user access before the call is staged. -There is not a separate permission list for cross-chain calls. - -:::info Trust assumptions and networking +:::info Trust assumptions Deployment interoperability is a [trusted bridge](../evaluate/trust-model.mdx): there is no shared proof across the two Lineth networks that replaces operator and relayer trust. -Each side trusts its own access control configuration (if any), its own permissions, and the peer +Each side trusts its own access control configuration, its own permissions, and the peer deployment endpoints it has configured. -The wire between peer deployments is gRPC. -Mutual TLS is not required today. -Until it is, run that channel on an isolated operator network and restrict it with firewalls; do -not expose peer endpoints to the public internet. - ::: ## See also -- [Access control](./access-control.mdx): Permission model, request pipeline, and audit. +- [Access control](./access-control.mdx): The access control stack for restricted deployments. - [Interoperability](../../protocol/architecture/interoperability/index.mdx): Canonical messaging and token bridging to the finalization layer. -- [Trust and responsibilities](../evaluate/trust-model.mdx): Trusted-bridge row and what - participants can verify. -- [Privacy and data visibility](../evaluate/validium.mdx): Offchain data availability versus access - policy. diff --git a/docs/stack/deployment/index.mdx b/docs/stack/deployment/index.mdx index c0fa1309f7..fe9efcf2db 100644 --- a/docs/stack/deployment/index.mdx +++ b/docs/stack/deployment/index.mdx @@ -57,7 +57,7 @@ Detailed production topology and supported tooling for a given deployment can be { text: "Deployment interoperability", description: - "Peer Lineth calls over a two-phase commit, distinct from canonical bridging. A restricted destination authorizes the call against the same access control as live RPC.", + "How two Lineth deployments communicate with each other, and how an access controlled destination authorizes calls.", href: "/stack/deployment/deployment-interoperability", }, ]} @@ -124,8 +124,6 @@ The example architecture flows as follows: 6. Interoperability with the finalization layer uses the [canonical token bridge and message service](../../protocol/architecture/interoperability/index.mdx). This example also shows validium message relayers to other enterprise or public chains. - Calls between two Lineth deployments are a separate path; see - [Deployment interoperability](./deployment-interoperability.mdx). See [Trust and responsibilities](../evaluate/trust-model.mdx) for who operates each component, what it can do, and what participants can verify.