Skip to content

Commit

Permalink
docs: interop docs update (#3366)
Browse files Browse the repository at this point in the history
## 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`.
  • Loading branch information
kelemeno authored Dec 11, 2024
1 parent 003316e commit 51958f6
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 26 deletions.
Binary file modified docs/src/specs/img/verifyinteropmsg.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
37 changes: 16 additions & 21 deletions docs/src/specs/interop/interopmessages.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,9 @@ This `interopHash` serves as a globally unique identifier that can be used on an
#### How do I get the proof

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

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

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

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

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

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

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

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

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

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

#### What if the Gateway doesn’t respond
#### What if Chain doesn’t provide the proof

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

#### Global roots change frequently
#### Message roots change frequently

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

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

Yes, it’s secure. If a malicious operator on Chain D attempted to use a different global root, they wouldn’t be able to
Yes, it’s secure. If a malicious operator on Chain D attempted to use a different message root, they wouldn’t be able to
submit the proof for their new batch to the Gateway. This is because the proof’s public inputs must include the valid
global root.

#### What if the Gateway is malicious

If the Gateway behaves maliciously, it wouldn’t be able to submit its batches to L1, as the proof would fail
verification. A separate section will cover interop transaction security in more detail.
message root.

### Other Features

#### Dependency Set

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

#### Timestamps and Expiration
Expand Down
10 changes: 5 additions & 5 deletions docs/src/specs/interop/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,14 +112,14 @@ The step-by-step process and exact details will be covered in the next section.

## Technical Details

### How is Interop Different from a Bridge
### How does native bridging differ from a third party bridging

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

#### 1. Native Bridges

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

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

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

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

0 comments on commit 51958f6

Please sign in to comment.