Skip to content

Commit 51958f6

Browse files
authored
docs: interop docs update (#3366)
## What ❔ <!-- What are the changes this PR brings about? --> <!-- Example: This PR adds a PR template to the repo. --> <!-- (For bigger PRs adding more context is appreciated) --> ## Why ❔ <!-- Why are these changes done? What goal do they contribute to? What are the principles behind them? --> <!-- Example: PR templates ensure PR reviewers, observers, and future iterators are in context about the evolution of repos. --> ## Checklist <!-- Check your PR fulfills the following items. --> <!-- For draft PRs check the boxes as you complete them. --> - [ ] PR title corresponds to the body of PR (we generate changelog entries from PRs). - [ ] Tests for the changes have been added / updated. - [ ] Documentation comments have been added / updated. - [ ] Code has been formatted via `zkstack dev fmt` and `zkstack dev lint`.
1 parent 003316e commit 51958f6

File tree

3 files changed

+21
-26
lines changed

3 files changed

+21
-26
lines changed
-41.9 KB
Loading

docs/src/specs/interop/interopmessages.md

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,9 @@ This `interopHash` serves as a globally unique identifier that can be used on an
5656
#### How do I get the proof
5757

5858
You’ll notice that **verifyInteropMessage** has a second argument — a proof that you need to provide. This proof is a
59-
Merkle tree proof (more details below). You can obtain it by querying the Settlement Layer (Gateway) or generating it
60-
off-chain by examining the Gateway state on L1.
59+
Merkle tree proof (more details below). You can obtain it by querying the
60+
[chain](https://docs.zksync.io/build/api-reference/zks-rpc#zks_getl2tol1msgproof) , or generate it off-chain - by
61+
looking at the chain's state on L1
6162

6263
#### How does the interop message differ from other layers (InteropTransactions, InteropCalls)
6364

@@ -129,49 +130,43 @@ from them at the end of the batch, and sends this tree to the SettlementLayer (G
129130

130131
![sendtol1.png](../img/sendtol1.png)
131132

132-
The Gateway will verify the hashes of the messages to ensure it has received the correct preimages. Once the proof for
133-
the batch is submitted (or more accurately, during the "execute" step), it will add the root of the Merkle tree to its
134-
`globalRoot`.
133+
The settlement layer receives the messages and once the proof for the batch is submitted (or more accurately, during the
134+
"execute" step), it will add the root of the Merkle tree to its `messageRoot` (sometimes called `globalRoot`).
135135

136136
![globalroot.png](../img/globalroot.png)
137137

138-
The `globalRoot` is the root of the Merkle tree that includes all messages from all chains. Each chain regularly reads
139-
the globalRoot value from the Gateway to stay synchronized.
138+
The `messageRoot` is the root of the Merkle tree that includes all messages from all chains. Each chain regularly reads
139+
the messageRoot value from the Gateway to stay synchronized.
140140

141141
![gateway.png](../img/gateway.png)
142142

143143
If a user wants to call `verifyInteropMessage` on a chain, they first need to query the Gateway for the Merkle path from
144-
the batch they are interested in up to the `globalRoot`. Once they have this path, they can provide it as an argument
144+
the batch they are interested in up to the `messageRoot`. Once they have this path, they can provide it as an argument
145145
when calling a method on the destination chain (such as the `openSignup` method in our example).
146146

147147
![proofmerklepath.png](../img/proofmerklepath.png)
148148

149-
#### What if the Gateway doesn’t respond
149+
#### What if Chain doesn’t provide the proof
150150

151-
If the Gateway doesn’t respond, users can manually re-create the Merkle proof using data available on L1. Every
151+
If the chain doesn’t respond, users can manually re-create the Merkle proof using data available on L1. Every
152152
interopMessage is also sent to L1.
153153

154-
#### Global roots change frequently
154+
#### Message roots change frequently
155155

156-
Yes, global roots update continuously as new chains prove their blocks. However, chains retain historical global roots
156+
Yes, message roots update continuously as new chains prove their blocks. However, chains retain historical message roots
157157
for a reasonable period (around 24 hours) to ensure that recently generated Merkle paths remain valid.
158158

159-
#### Is this secure? Could a chain operator, like Chain D, use a different global root
159+
#### Is this secure? Could a chain operator, like Chain D, use a different message root
160160

161-
Yes, it’s secure. If a malicious operator on Chain D attempted to use a different global root, they wouldn’t be able to
161+
Yes, it’s secure. If a malicious operator on Chain D attempted to use a different message root, they wouldn’t be able to
162162
submit the proof for their new batch to the Gateway. This is because the proof’s public inputs must include the valid
163-
global root.
164-
165-
#### What if the Gateway is malicious
166-
167-
If the Gateway behaves maliciously, it wouldn’t be able to submit its batches to L1, as the proof would fail
168-
verification. A separate section will cover interop transaction security in more detail.
163+
message root.
169164

170165
### Other Features
171166

172167
#### Dependency Set
173168

174-
- In ElasticChain, this is implicitly handled by the Gateway. Any chain that is part of the global root can exchange
169+
- In ElasticChain, this is implicitly handled by the Gateway. Any chain that is part of the message root can exchange
175170
messages with any other chain, effectively forming an undirected graph.
176171

177172
#### Timestamps and Expiration

docs/src/specs/interop/overview.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -112,14 +112,14 @@ The step-by-step process and exact details will be covered in the next section.
112112

113113
## Technical Details
114114

115-
### How is Interop Different from a Bridge
115+
### How does native bridging differ from a third party bridging
116116

117117
Bridges generally fall into two categories: Native and Third-Party.
118118

119119
#### 1. Native Bridges
120120

121-
Native bridges enable asset transfers “up and down” (from L2 to L1 and vice versa). In contrast, interop allows direct
122-
transfers between different L2s.
121+
Native bridges enable asset transfers “up and down” (from L2 to L1 and vice versa), but interop (which is also a form of
122+
native bridging) allows you to move them between different L2s.
123123

124124
Instead of doing a "round trip" (L2 → L1 → another L2), interop lets you move assets directly between two L2s, saving
125125
both time and cost.
@@ -129,8 +129,8 @@ both time and cost.
129129
Third-party bridges enable transfers between two L2s, but they rely on their own liquidity. While you, as the user,
130130
receive assets on the destination chain instantly, these assets come from the bridge’s liquidity pool.
131131

132-
Bridge operators then rebalance using native bridging, which requires maintaining token reserves on both sides. This
133-
adds costs for the bridge operators, often resulting in higher fees for users.
132+
Bridge operators then rebalance using native bridging, which requires maintaining token reserves on both sides. Without
133+
interop this adds costs for the bridge operators, often resulting in higher fees for users.
134134

135135
The good news is that third-party bridges can use interop to improve their token transfers by utilizing the
136136
**InteropMessage** layer.

0 commit comments

Comments
 (0)