Skip to content

Clarify native interop docs #1725

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

Merged
alexandratran merged 5 commits into from
Oct 1, 2026
Merged

Clarify native interop docs #1725

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
61ba958
Clarify native interop docs
alexandratran Sep 28, 2026
cf7e355
broaden page to apply to both restricted and unrestricted networks
alexandratran Sep 28, 2026
ce8f1d9
Merge branch 'main' into interop-trusted-bridge
alexandratran Sep 30, 2026
c3cf426
add clip and change bridge term
alexandratran Sep 30, 2026
ff787e1
minor edits
alexandratran Sep 30, 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
13 changes: 8 additions & 5 deletions docs/protocol/architecture/interoperability/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
---
title: Interoperability
description: Cross-chain messaging and canonical token bridging between a Lineth network and its finalization layer.
title: Native bridge
description: >-
The native bridge between a Lineth network and its finalization layer, using
the canonical message service and token bridge.
image: /img/socialCards/interoperability.jpg
---

import GlossaryTerm from '@theme/GlossaryTerm';

A <GlossaryTerm term="Lineth" /> network exchanges data and value with its
<GlossaryTerm term="Finalization layer">finalization layer</GlossaryTerm> through two protocol components:
<GlossaryTerm term="Finalization layer">finalization layer</GlossaryTerm> through the **native bridge**.
The native bridge is two protocol components:

- [Canonical token bridge](./canonical-token-bridge.mdx): A pair of lock-and-mint contracts for bridging any
ERC-20 token.
Expand All @@ -26,6 +29,6 @@ the finalization layer at the next finalization.
See [Message commitments](./canonical-message-service.mdx#message-commitments) for more information.

:::tip
To learn how two Lineth deployments communicate with each other, see
[Deployment interoperability](../../../stack/deployment/interoperability.mdx).
To learn how two Lineth networks communicate with each other, see
[native interoperability](../../../stack/deployment/interoperability.mdx).
:::
4 changes: 2 additions & 2 deletions docs/stack/deployment/access-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ They do not receive a view of private contracts or transaction data.

## See also

- [Lineth-to-Lineth interoperability](./interoperability.mdx): How two Lineth networks
communicate with each other, and how an access controlled destination authorizes calls.
- [Native interoperability](./interoperability.mdx): How two Lineth networks communicate with
each other using native interoperability, and how an access controlled destination authorizes a call.
- [Privacy and data visibility](../evaluate/validium.mdx): How private validium deployments use offchain
data availability and controlled access.
11 changes: 5 additions & 6 deletions docs/stack/deployment/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,9 @@ Detailed production topology and supported tooling for a given deployment can be
href: "/stack/deployment/access-control",
},
{
text: "Lineth-to-Lineth interoperability",
text: "Native interoperability",
description:
"How two Lineth networks communicate with each other, and how an access controlled destination authorizes calls.",
"How two Lineth networks communicate with each other using native interoperability.",
href: "/stack/deployment/interoperability",
},
{
Expand Down Expand Up @@ -98,7 +98,7 @@ Lineth does not recommend a specific set of customizations.

The following diagram illustrates an example architecture for a
<GlossaryTerm term="Validium">validium</GlossaryTerm> deployment: access control at the edge, a private
network boundary, and validium message relayers to other chains.
network boundary, and message relayers to other chains.
A public deployment uses the same internal services; access and data availability differ.

In this example, transaction data stays offchain in the operator's private node set, and is not
Expand Down Expand Up @@ -128,9 +128,8 @@ The example architecture flows as follows:
finalization layer contracts.
This validium example does not post transaction data; a public deployment posts it onchain.
See [Data availability and finalization](./data-availability-finalization.mdx).
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.
6. Lineth networks can communicate with each other using [native interoperability](interoperability.mdx).
This example also shows message relayers to other non-Lineth enterprise or public chains.

See [Trust model](../evaluate/trust-model.mdx) to understand what each deployment component can do and
what participants can verify.
120 changes: 41 additions & 79 deletions docs/stack/deployment/interoperability.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,91 +1,52 @@
---
title: Lineth-to-Lineth interoperability
sidebar_label: Lineth-to-Lineth interop
title: Native interoperability
description: >-
How two Lineth deployments exchange contract calls, and how a restricted
destination authorizes those calls
Native interoperability between two Lineth networks using a prepare-agree-commit plugin
---

import GlossaryTerm from '@theme/GlossaryTerm';

This page describes how two <GlossaryTerm term="Lineth" /> networks communicate with each other.
This page describes native interoperability between two <GlossaryTerm term="Lineth" /> networks.

Check warning on line 9 in docs/stack/deployment/interoperability.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'twonetworks'? 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 'twonetworks'? 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/interoperability.mdx", "range": {"start": {"line": 9, "column": 53}}}, "severity": "WARNING"}
Each network's operator runs a plugin in their Lineth node, and use it to coordinate a cross-chain call.
There is no shared chain and no third-party bridge operator.

Check warning on line 11 in docs/stack/deployment/interoperability.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[write-good.ThereIs] Don't start a sentence with 'There is'.

Raw Output:
{"message": "[write-good.ThereIs] Don't start a sentence with 'There is'.", "location": {"path": "docs/stack/deployment/interoperability.mdx", "range": {"start": {"line": 11, "column": 1}}}, "severity": "WARNING"}

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.

To communicate between two Lineth networks, use canonical interoperability when both of these are true:

- The deployments share a finalization layer.
- The destination is not [access controlled](access-control.mdx) (unrestricted).

The source network sends a message to the finalization layer, and the destination
network claims it.

Communicate directly using a trusted bridge when either of these is true:

- The deployments do not share a finalization layer.
- The destination is [access controlled](access-control.mdx) (restricted).

On a restricted destination, its access control endpoint checks the inbound
call against role-based access control (RBAC) permissions before the destination network
accepts the call.
:::tip Lineth for institutions
Native interoperability is a proprietary feature for institutional and enterprise deployments.
To request access, use the
[strategic inquiries form](https://linea.build/contact/inquiries).
:::

<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>
:::note Other interoperability flows
Native interoperability refers to communication between two Lineth networks.
To communicate with a Lineth network's <GlossaryTerm term="Finalization layer">finalization layer</GlossaryTerm>,
use the [native bridge](../../protocol/architecture/interoperability/index.mdx).
To communicate with a non-Lineth network, use a bridge or relayer such as [Chainlink CCIP](https://docs.chain.link/ccip).
:::

## Communicating with a restricted network
## Native interoperability flow

Two restricted networks can communicate with each other as follows:
Two Lineth networks communicate with each other as follows:

1. Operators of each network configure [role-based access control (RBAC)](./access-control.mdx)
permissions for their network.
permissions for their network, if required.
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**.
2. Each operator enables the native interoperability plugin on their Lineth node, deploys and
registers the contracts it requires, and connects it to the peer network's node.
3. If their network is restricted (access controlled), each operator configures the plugin with the
address of their access control endpoint, so it can ask the endpoint to evaluate the permissions of
inbound cross-chain calls.
4. A user (or contract) from one network initiates a cross-chain call to the other network.
5. 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.
6. In the commit phase, both sides commit.
If the destination is restricted, it first asks its access control endpoint whether that agreed call
would be allowed as a live RPC request.
The endpoint evaluates that caller against the destination's own RBAC policy.
The subject is the source contract on the source chain, represented as a chain-based
decentralized identifier (DID) such as `did:pkh:eip155:<source-chain>:<address>`;
it is 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
If the endpoint denies the call, or if the endpoint is unreachable, both sides abort instead.
7. If the destination is restricted, its access control endpoint records the decision on its append-only
access log.

<div class="mermaid-large mermaid-deployment" style={{ marginBottom: "2rem" }}>
Expand All @@ -102,11 +63,11 @@
}}%%
sequenceDiagram
participant App as Wallets and apps
participant Src as Source access control endpoint
participant Src as Source network

Check warning on line 66 in docs/stack/deployment/interoperability.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'Src'? 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 'Src'? 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/interoperability.mdx", "range": {"start": {"line": 66, "column": 15}}}, "severity": "WARNING"}
participant Dest as Destination network
participant DestEP as Destination access control endpoint

App->>Src: Authenticate, then stage the call
App->>Src: Initiate the call
Src->>Dest: Prepare
Dest->>DestEP: Is this root call allowed?
DestEP->>DestEP: Check grants for source contract DID
Expand All @@ -123,22 +84,23 @@

:::warning Known limitation

Currently, the access control endpoint only evaluates the **root** cross-chain call; nested calls made during execution
on the destination are not separately evaluated.
Currently, the access control endpoint only evaluates the **root** cross-chain
call; nested calls made during execution on the destination are not separately
evaluated.

:::

:::info Trust assumptions

Communicating directly between networks using the process outlined here 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.
Each side checks that it included the agreed call and that both plugins computed the same
result from the exchanged simulation.
There is no shared proof across the two Lineth networks that replaces trust in the peer
operator and the peer endpoints you configured.

:::

## See also

- [Access control](./access-control.mdx): The access control stack for restricted deployments.
- [Interoperability](../../protocol/architecture/interoperability/index.mdx): Canonical messaging
- [Native bridge](../../protocol/architecture/interoperability/index.mdx): Message service
and token bridging to the finalization layer.
11 changes: 0 additions & 11 deletions docs/stack/evaluate/trust-model.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,17 +82,6 @@ A Merkle proof can support inclusion of authorized data.
It does not by itself establish global transaction ordering for participants who do not have the
full ordered data set.

### Trusted bridge

A deployment's operator and a trusted relayer may operate a bridge to a private or non-anchored chain.
The operator holds the [contract roles](#system-contract-roles) that can pause or upgrade the bridge.
The relayer can withhold or delay messages.
In the normal relayer path, the bridge cannot process messages that are not signed over
source-chain events.
Participants can verify bridge events on each side.
There is no shared proof, so verifiability depends on trust in the relayer, its keys,
and those pause and upgrade roles.

### Finalization layer

A deployment inherits its finalization layer's finality.
Expand Down
2 changes: 1 addition & 1 deletion sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,7 +388,7 @@ const sidebars = {
"protocol/architecture/state-manager",
{
type: "category",
label: "Interoperability",
label: "Native bridge",
collapsible: true,
collapsed: true,
link: { type: "doc", id: "protocol/architecture/interoperability/index" },
Expand Down
Loading