diff --git a/docs/changelog/release-notes.mdx b/docs/changelog/release-notes.mdx index 91c251b89e..6d95493993 100644 --- a/docs/changelog/release-notes.mdx +++ b/docs/changelog/release-notes.mdx @@ -1250,7 +1250,7 @@ contracts are listed on the [Security audits](../protocol/reference/security-aud **Canonical Token Bridge** -Major changes are applied to the Canonical Token Bridge as described in our [documentation](../protocol/architecture/interoperability/canonical-token-bridge.mdx). +Major changes are applied to the Canonical Token Bridge as described in our [documentation](../protocol/architecture/bridge/canonical-token-bridge.mdx). - **L1 (Goerli)** diff --git a/docs/network/how-to/bridge.mdx b/docs/network/how-to/bridge.mdx index 1c3bc5176b..0865c7c9b5 100644 --- a/docs/network/how-to/bridge.mdx +++ b/docs/network/how-to/bridge.mdx @@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem"; The [Linea bridge app](https://linea.build/hub/bridge) provides multiple ways to get funds onto Linea: -- **Native bridge**: Built by our team to provide an interface for the [canonical token bridge](../../protocol/architecture/interoperability/canonical-token-bridge.mdx). +- **Native bridge**: Built by our team to provide an interface for the [canonical token bridge](../../protocol/architecture/bridge/canonical-token-bridge.mdx). **Best suited for tech operators, protocols, or moving large liquidity**, but also suitable for users that want to bridge ETH or ERC-20 tokens. - **All bridges**: A bridge aggregator powered by Li.Fi, supporting numerous networks (EVM chains and @@ -165,7 +165,7 @@ accessible via the icon next to settings in the top-right of the widget. USDC is handled differently by the native bridge. Since Linea has [native USDC](https://linea.build/blog/lineas-seamless-upgrade-to-native-usdc-a-game-changer-for-onchain-payments), the bridge uses the [Cross-Chain Transfer Protocol](https://circle.com/cross-chain-transfer-protocol) -(CCTP) rather than the [canonical token bridge](../../protocol/architecture/interoperability/canonical-token-bridge.mdx) +(CCTP) rather than the [canonical token bridge](../../protocol/architecture/bridge/canonical-token-bridge.mdx) that underpins other native bridge transfers. USDC transfers currently require [manual claiming](#manual-claiming). diff --git a/docs/protocol/architecture/interoperability/canonical-message-service.mdx b/docs/protocol/architecture/bridge/canonical-message-service.mdx similarity index 100% rename from docs/protocol/architecture/interoperability/canonical-message-service.mdx rename to docs/protocol/architecture/bridge/canonical-message-service.mdx diff --git a/docs/protocol/architecture/interoperability/canonical-token-bridge.mdx b/docs/protocol/architecture/bridge/canonical-token-bridge.mdx similarity index 100% rename from docs/protocol/architecture/interoperability/canonical-token-bridge.mdx rename to docs/protocol/architecture/bridge/canonical-token-bridge.mdx diff --git a/docs/protocol/architecture/interoperability/index.mdx b/docs/protocol/architecture/bridge/index.mdx similarity index 75% rename from docs/protocol/architecture/interoperability/index.mdx rename to docs/protocol/architecture/bridge/index.mdx index f3790afaf0..79e46c69f7 100644 --- a/docs/protocol/architecture/interoperability/index.mdx +++ b/docs/protocol/architecture/bridge/index.mdx @@ -1,13 +1,16 @@ --- -title: Interoperability -description: Cross-chain messaging and canonical token bridging between a Lineth network and its finalization layer. +title: Canonical bridge +description: >- + The canonical 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 network exchanges data and value with its -finalization layer through two protocol components: +finalization layer through the **canonical bridge**. +The canonical 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. @@ -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). ::: diff --git a/docs/protocol/architecture/coordinator/index.mdx b/docs/protocol/architecture/coordinator/index.mdx index e400681237..fd362f8809 100644 --- a/docs/protocol/architecture/coordinator/index.mdx +++ b/docs/protocol/architecture/coordinator/index.mdx @@ -36,7 +36,7 @@ and resume from the last persisted state after a restart. The coordinator handles two jobs outside the proving pipeline. It anchors incoming messages from the finalization layer on the network, so the -[canonical message service](../interoperability/canonical-message-service.mdx) can deliver them, and it +[canonical message service](../bridge/canonical-message-service.mdx) can deliver them, and it computes and propagates the gas pricing that the network's nodes advertise. :::info diff --git a/docs/protocol/architecture/index.mdx b/docs/protocol/architecture/index.mdx index 6e10672627..689c43b18c 100644 --- a/docs/protocol/architecture/index.mdx +++ b/docs/protocol/architecture/index.mdx @@ -250,7 +250,7 @@ on the Linea public network. ## Next steps - To understand the trust boundaries, and upgrade paths of this stack, see [protocol components](../../stack/deployment/core-components). -- Review bridge mechanics in the [message service](./interoperability/canonical-message-service.mdx). -- Review cross-chain settlement in the [canonical token bridge](./interoperability/canonical-token-bridge.mdx). +- Review bridge mechanics in the [message service](./bridge/canonical-message-service.mdx). +- Review cross-chain settlement in the [canonical token bridge](./bridge/canonical-token-bridge.mdx). - Understand protocol fees in [predictable pricing](../../network/overview/predictable-pricing.mdx) and [burn](../../network/overview/tokenomics.mdx#burning-mechanism). diff --git a/docs/protocol/architecture/smart-contracts.mdx b/docs/protocol/architecture/smart-contracts.mdx index b835a35b1d..ffebbdac0a 100644 --- a/docs/protocol/architecture/smart-contracts.mdx +++ b/docs/protocol/architecture/smart-contracts.mdx @@ -28,7 +28,7 @@ The finalization contract: [data submission model](./index.mdx#transaction-lifecycle) the deployment uses. - Anchors the Merkle roots of the messages the finalized blocks sent, and verifies the rolling hash of the messages the network received. - See [Message commitments](./interoperability/canonical-message-service.mdx#message-commitments). + See [Message commitments](./bridge/canonical-message-service.mdx#message-commitments). - Queues [forced transactions](../forced-transactions.mdx) submitted on the finalization layer, so they can be proven to have been processed by their deadline. @@ -48,7 +48,7 @@ Together they carry arbitrary calldata and native currency in both directions, a it can be checked against a commitment recorded by the finalization contract. Everything else that crosses chains, including the token bridge, is built on this pair. -See [Canonical message service](./interoperability/canonical-message-service.mdx). +See [Canonical message service](./bridge/canonical-message-service.mdx). ## Token bridge contracts @@ -56,7 +56,7 @@ A token bridge contract is deployed on each chain. They bridge ERC-20 tokens by escrowing the original on its home chain and minting a bridged equivalent on the other, sending each instruction through the message service. Minted supply is always matched by escrowed supply, so the bridge cannot mint tokens that were never locked. -See [Canonical token bridge](./interoperability/canonical-token-bridge.mdx). +See [Canonical token bridge](./bridge/canonical-token-bridge.mdx). ## Contract versioning diff --git a/docs/stack/deployment/access-control.mdx b/docs/stack/deployment/access-control.mdx index e157d352b8..428abca5c6 100644 --- a/docs/stack/deployment/access-control.mdx +++ b/docs/stack/deployment/access-control.mdx @@ -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 access controlled Lineth networks communicate + with each other using the Cross Ledger Interoperability Protocol (CLIP). - [Privacy and data visibility](../evaluate/validium.mdx): How private validium deployments use offchain data availability and controlled access. diff --git a/docs/stack/deployment/index.mdx b/docs/stack/deployment/index.mdx index 2d6e9ce176..6461c6e18a 100644 --- a/docs/stack/deployment/index.mdx +++ b/docs/stack/deployment/index.mdx @@ -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 the Cross Ledger Interoperability Protocol (CLIP).", href: "/stack/deployment/interoperability", }, { @@ -98,7 +98,7 @@ Lineth does not recommend a specific set of customizations. The following diagram illustrates an example architecture for a validium 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 @@ -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. diff --git a/docs/stack/deployment/interoperability.mdx b/docs/stack/deployment/interoperability.mdx index 1985e08263..e364f9c553 100644 --- a/docs/stack/deployment/interoperability.mdx +++ b/docs/stack/deployment/interoperability.mdx @@ -1,91 +1,53 @@ --- -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 the Cross Ledger Interoperability Protocol (CLIP) --- import GlossaryTerm from '@theme/GlossaryTerm'; -This page describes how two networks communicate with each other. +This page describes native interoperability between two networks. +Native interoperability is enabled via the Cross Ledger Interoperability Protocol (CLIP). +Each network's operator runs the CLIP plugin in their Lineth node and uses it to coordinate a cross-chain call. +There is no shared chain and no third-party bridge operator. -A Lineth network communicates with its -finalization layer through -[canonical interoperability](../../protocol/architecture/interoperability/index.mdx), using -the message service and token bridge. -Claiming is permissionless: anyone who can submit the claim can execute the message. - -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 +CLIP is a proprietary feature for institutional and enterprise deployments. +To request access, use the +[strategic inquiries form](https://linea.build/contact/inquiries). +::: -
-```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
layer"]:::neutral - U2["Lineth network
(unrestricted)"]:::core - L["Lineth network"]:::core - U1 -->|"send"| FLA - U2 -->|"claim"| FLA - - R["Lineth network
(restricted)"]:::core - L -->|"trusted bridge
with RBAC"| R -``` -
+:::note Other interoperability flows +Native interoperability refers to communication between two Lineth networks. +To communicate with a Lineth network's finalization layer, +use the [canonical bridge](../../protocol/architecture/bridge/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 use CLIP to 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 CLIP 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::
`; 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.
@@ -102,11 +64,11 @@ Two restricted networks can communicate with each other as follows: }}%% sequenceDiagram participant App as Wallets and apps - participant Src as Source access control endpoint + participant Src as Source network 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 @@ -130,15 +92,13 @@ 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 - and token bridging to the finalization layer. +- [Canonical bridge](../../protocol/architecture/bridge/index.mdx): Canonical message service + and token bridge to the finalization layer. diff --git a/docs/stack/evaluate/trust-model.mdx b/docs/stack/evaluate/trust-model.mdx index 7b53d63bbe..096952e523 100644 --- a/docs/stack/evaluate/trust-model.mdx +++ b/docs/stack/evaluate/trust-model.mdx @@ -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. diff --git a/redirects.json b/redirects.json index ca81e16627..3576f3f292 100644 --- a/redirects.json +++ b/redirects.json @@ -176,8 +176,16 @@ ] }, { - "to": "/protocol/architecture/interoperability/canonical-message-service", + "to": "/protocol/architecture/bridge", "from": [ + "/protocol/architecture/interoperability", + "/protocol/architecture/interoperability/index" + ] + }, + { + "to": "/protocol/architecture/bridge/canonical-message-service", + "from": [ + "/protocol/architecture/interoperability/canonical-message-service", "/protocol/architecture/interoperability/message-service", "/protocol/message-service", "/protocol/message-service/index", @@ -350,8 +358,9 @@ ] }, { - "to": "/protocol/architecture/interoperability/canonical-token-bridge", + "to": "/protocol/architecture/bridge/canonical-token-bridge", "from": [ + "/protocol/architecture/interoperability/canonical-token-bridge", "/architecture/bridges", "/architecture/stack/bridges", "/architecture/stack/bridges/canonical-token-bridge", diff --git a/sidebars.js b/sidebars.js index 82445ae5dd..5824f8345f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -388,13 +388,13 @@ const sidebars = { "protocol/architecture/state-manager", { type: "category", - label: "Interoperability", + label: "Canonical bridge", collapsible: true, collapsed: true, - link: { type: "doc", id: "protocol/architecture/interoperability/index" }, + link: { type: "doc", id: "protocol/architecture/bridge/index" }, items: [ - "protocol/architecture/interoperability/canonical-token-bridge", - "protocol/architecture/interoperability/canonical-message-service", + "protocol/architecture/bridge/canonical-token-bridge", + "protocol/architecture/bridge/canonical-message-service", ], }, "protocol/architecture/smart-contracts",