Skip to content

Document access control stack and RBAC model #1690

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
alexandratran wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Document access control stack and RBAC model #1690

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
538f607
Document access control stack and RBAC model
alexandratran Aug 26, 2026
81c0686
Merge branch 'main' into rbac-interop
alexandratran Aug 26, 2026
95a3fd8
minor fixes
alexandratran Aug 26, 2026
954aaee
Merge branch 'main' into rbac-interop
alexandratran Sep 1, 2026
e6f2a80
address feedback
alexandratran Sep 1, 2026
351cde9
Merge branch 'main' into rbac-interop
alexandratran Sep 2, 2026
7c7c6b3
Merge branch 'main' into rbac-interop
alexandratran Sep 3, 2026
e2be145
fix link
alexandratran Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/protocol/architecture/rpc-services.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <GlossaryTerm term="Lineth" /> node can serve them, publicly or only within the operator's network, and RPC
nodes are typically placed behind load balancers and access controls
(<GlossaryTerm term="Role-based access control (RBAC)">RBAC</GlossaryTerm>).
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.
Expand Down
4 changes: 0 additions & 4 deletions docs/protocol/reference/zero-knowledge-glossary.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
164 changes: 164 additions & 0 deletions docs/stack/deployment/access-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <GlossaryTerm term="Lineth" /> 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.

<div class="mermaid-medium mermaid-deployment" style={{ marginBottom: "2rem" }}>
```mermaid
%%{init: {
"themeVariables": {

Check warning on line 49 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'themeVariables'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 49, "column": 4}}}, "severity": "WARNING"}
"fontFamily": "AtypText, sans-serif"

Check warning on line 50 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'fontFamily'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 50, "column": 6}}}, "severity": "WARNING"}
},
"flowchart": {
"useMaxWidth": true,
"curve": "basis",
"nodeSpacing": 24,

Check warning on line 55 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'nodeSpacing'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 55, "column": 6}}}, "severity": "WARNING"}
"rankSpacing": 28,

Check warning on line 56 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'rankSpacing'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 56, "column": 6}}}, "severity": "WARNING"}
"padding": 12,
"wrappingWidth": 200

Check warning on line 58 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'wrappingWidth'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 58, "column": 6}}}, "severity": "WARNING"}
}
}}%%
flowchart TB
classDef core stroke-width:1.5px;

Check warning on line 62 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'classDef'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 62, "column": 3}}}, "severity": "WARNING"}
classDef access stroke-width:1.5px;

Check warning on line 63 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'classDef'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 63, "column": 3}}}, "severity": "WARNING"}
classDef neutral stroke-width:1.5px;

Check warning on line 64 in docs/stack/deployment/access-control.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

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

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'classDef'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/stack/deployment/access-control.mdx", "range": {"start": {"line": 64, "column": 3}}}, "severity": "WARNING"}

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
```
</div>

A public or private deployment can configure access control.
In a public deployment, transaction data is posted to the
<GlossaryTerm term="Finalization layer">finalization layer</GlossaryTerm>, so the endpoint restricts who
uses the operator's RPC; it does not hide onchain data.
A <GlossaryTerm term="Validium">private validium</GlossaryTerm> 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.
4 changes: 2 additions & 2 deletions docs/stack/deployment/high-availability.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Each region runs a <GlossaryTerm term="Maru" /> consensus client paired with a
<GlossaryTerm term="Quorum Byzantine Fault Tolerance (QBFT)">QBFT</GlossaryTerm>
validator per region).
Each region also runs public and/or private JSON-RPC gateways in front of
<GlossaryTerm term="RPC node">RPC nodes</GlossaryTerm>, with [access control](./rbac.mdx) where
<GlossaryTerm term="RPC node">RPC nodes</GlossaryTerm>, with [access control](./access-control.mdx) where
required.
For QBFT topology, latency, and setup, see
[Multi-validator consensus](./distributed-sequencing.mdx) and
Expand Down Expand Up @@ -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,
Expand Down
12 changes: 5 additions & 7 deletions docs/stack/deployment/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
},
]}
/>
Expand All @@ -71,8 +71,7 @@ Proofs and state commitments go to a chosen

<GlossaryTerm term="Operator">Operators</GlossaryTerm> also choose:

- [Access control](rbac.mdx): Public RPC, or RPC and APIs gated by
<GlossaryTerm term="Role-based access control (RBAC)">RBAC</GlossaryTerm>
- [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
<GlossaryTerm term="Validium">private validium</GlossaryTerm>
Expand All @@ -85,7 +84,7 @@ Lineth does not recommend a specific set of customizations.
## Example architecture

The following diagram illustrates an example architecture for a
<GlossaryTerm term="Validium">validium</GlossaryTerm> deployment: RBAC at the edge, a private
<GlossaryTerm term="Validium">validium</GlossaryTerm> 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.

Expand All @@ -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
<GlossaryTerm term="RPC node">RPC nodes</GlossaryTerm>, which read chain state from
onchain contracts.
Expand Down
78 changes: 0 additions & 78 deletions docs/stack/deployment/rbac.mdx
View file
Open in desktop

This file was deleted.

4 changes: 2 additions & 2 deletions docs/stack/evaluate/compliance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ stored and who can see it, see [Privacy and data visibility](./validium.mdx).
<GlossaryTerm term="Operator">Operators</GlossaryTerm> 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
Expand Down Expand Up @@ -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) |
Loading
Loading