diff --git a/docs/protocol/architecture/rpc-services.mdx b/docs/protocol/architecture/rpc-services.mdx index 0ee88955c1..499726ee46 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). Two things distinguish one RPC node from another: which methods it serves, and how much state history it retains. Serving RPC is independent of a node's consensus role. diff --git a/docs/protocol/reference/zero-knowledge-glossary.mdx b/docs/protocol/reference/zero-knowledge-glossary.mdx index 020fb24b6d..e18de05fa5 100644 --- a/docs/protocol/reference/zero-knowledge-glossary.mdx +++ b/docs/protocol/reference/zero-knowledge-glossary.mdx @@ -202,10 +202,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..2612a3ef1d --- /dev/null +++ b/docs/stack/deployment/access-control.mdx @@ -0,0 +1,164 @@ +--- +title: Access control +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 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. +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 configure access control independently of +[deployment model](../evaluate/deployment-models.mdx) and +[data availability](data-availability-finalization.mdx). + +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": { + "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 neutral stroke-width:1.5px; + + CL["Wallets and apps"]:::neutral + EP["Access control RPC endpoint"]:::access + ND["Lineth node"]:::core + 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 endpoint restricts who +uses the operator's RPC; it does not hide onchain data. +A private validium keeps transaction data offchain, so the +endpoint is also the path to chain data. + +### Role-based access control (RBAC) + +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). + 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 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. + +This RBAC data is stored in a PostgreSQL database. +The access control endpoint reads that data when it evaluates a request. + +### Audit logs + +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. +- **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 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). +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 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. +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. diff --git a/docs/stack/deployment/high-availability.mdx b/docs/stack/deployment/high-availability.mdx index b2c2263820..4cdd91a501 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, 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 3746c9ab0c..003a2071e0 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 to restrict access to JSON-RPC using a single endpoint that authenticates callers and enforces RBAC permissions.", + 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 12fd6e0fda..b89e4b5f12 100644 --- a/docs/stack/evaluate/deployment-models.mdx +++ b/docs/stack/evaluate/deployment-models.mdx @@ -21,7 +21,7 @@ Consider these questions when choosing a deployment model: - [Data availability](../deployment/data-availability-finalization.mdx) guarantees: How important is onchain data availability for your participants? - Network topology: Do you need a private network with controlled membership? -- [Access control](../deployment/rbac.mdx): Do you need role-based access control (RBAC) on RPC endpoints and +- [Access control](../deployment/access-control.mdx): Do you need role-based access control (RBAC) on RPC endpoints and APIs? The following table compares how characteristics differ between public deployments and private validium deployments. @@ -56,7 +56,7 @@ RPC access is public, and node membership is not restricted. - 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 @@ -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, @@ -91,7 +91,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 e75b691d2c..734a6aff68 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 18906fa99c..9c6850b44b 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 - 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 97f2bcdb7a..1b237fc014 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 private validium 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,19 +49,16 @@ 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: +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. -- 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 -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 @@ -114,7 +111,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 9e3364462d..07265d4ccb 100644 --- a/src/lib/glossary.json +++ b/src/lib/glossary.json @@ -169,10 +169,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).