Document deployment interoperability

docs/protocol/architecture/interoperability/index.mdx

@@ -24,3 +24,8 @@ 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.
+
+:::note
+Two learn how two Lineth deployments communicate with each other, see
+[Deployment interoperability](../../../stack/deployment/deployment-interoperability.mdx).
+:::

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 <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.

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.

docs/stack/deployment/access-control.mdx

@@ -0,0 +1,166 @@
+---
+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": {
+    "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
+```
+</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
+
+- [Deployment interoperability](./deployment-interoperability.mdx): How two Lineth deployments
+  communicate with each other, and how an access controlled destination authorizes calls.
+- [Privacy and data visibility](../evaluate/validium.mdx): How private validium deployments use offchain
+  data availability and controlled access.
+- [Trust and responsibilities](../evaluate/trust-model.mdx): What participants can verify when access and
+  data availability are restricted.

docs/stack/deployment/deployment-interoperability.mdx

@@ -0,0 +1,129 @@
+---
+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 <GlossaryTerm term="Lineth" /> deployments communicate with each
+other.
+
+A Lineth network communicates with its
+<GlossaryTerm term="Finalization layer">finalization layer</GlossaryTerm> 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.
+
+<div class="mermaid-medium mermaid-deployment">
+```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["Lineth network"]:::core
+  FLA["Finalization<br/>layer"]:::neutral
+  U2["Lineth network<br/>(unrestricted)"]:::core
+  L["Lineth network"]:::core
+  U1 -->|"send"| FLA
+  U2 -->|"claim"| FLA
+
+  R["Lineth network<br/>(restricted)"]:::core
+  L -->|"trusted bridge<br/>with RBAC"| R
+```
+</div>
+
+## Communicating with a restricted network
+
+Two restricted networks can communicate with each other as follows:
+
+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.
+6. The destination access control endpoint records the decision on its append-only
+   access log.
+
+<div class="mermaid-large mermaid-deployment" style={{ marginBottom: "2rem" }}>
+```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
+```
+</div>
+
+:::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, its own permissions, and the peer
+deployment endpoints it has configured.
+
+:::
+
+## See also
+
+- [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.

docs/stack/deployment/high-availability.mdx

@@ -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
@@ -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,

docs/stack/deployment/index.mdx

@@ -51,8 +51,14 @@ 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",
+    },
+    {
+      text: "Deployment interoperability",
+      description:
+        "How two Lineth deployments communicate with each other, and how an access controlled destination authorizes calls.",
+      href: "/stack/deployment/deployment-interoperability",
     },
   ]}
 />
@@ -71,8 +77,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>
@@ -85,7 +90,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.
 
@@ -103,8 +108,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.