Skip to content

Commit 389f343

Browse files
sarahschwartzuF4No
sarahschwartz
and
uF4No
authored
feat: add interop messaging guide (#442)
- Adds a new guide in the javascript SDK section for interop messaging. - Adds a new section for ZKsync Connect under "Unique Features" - Adds a column on the chains table for Gateway --------- Co-authored-by: Antonio <[email protected]>
1 parent 0764aed commit 389f343

File tree

24 files changed

+703
-95
lines changed

24 files changed

+703
-95
lines changed

‎components/ChainsList.vue‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ interface Chain {
1111
baseToken: string;
1212
pubdataMode: string;
1313
dataAvailability: string;
14+
onGateway?: boolean;
1415
}
1516
1617
const showTestnets = ref(false);
@@ -39,6 +40,10 @@ const columns = [
3940
key: 'dataAvailability',
4041
label: 'Data Availability',
4142
},
43+
{
44+
key: 'onGateway',
45+
label: 'On Gateway',
46+
},
4247
{
4348
key: 'links',
4449
label: 'Links',
@@ -130,6 +135,18 @@ const columns = [
130135
</div>
131136
</template>
132137

138+
<template #onGateway-data="{ row }">
139+
<div
140+
v-if="row.onGateway"
141+
class="flex justify-center"
142+
>
143+
<UIcon
144+
name="i-heroicons-check-circle-16-solid"
145+
class="h-5 w-5 text-green-600"
146+
/>
147+
</div>
148+
</template>
149+
133150
<template #links-data="{ row }">
134151
<div class="flex items-center space-x-3">
135152
<NuxtLink

‎content/00.zksync-network/30.unique-features/50.zksync-connect/00.index.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Overview
3+
description: Learn about how ZKsync Connect enables interoperable ZKsync chains.
4+
---
5+
6+
ZKsync Connect enables interoperability across ZKsync chains in the Elastic Network.
7+
Interop, or interoperability, is a way to communicate and transact between two ZKsync Stack chains.
8+
It is made possible by smart contracts that verify transactions across chains using Merkle proofs.
9+
10+
It allows you to:
11+
12+
1. **Observe messages**: Track when an interop message (think of it as a special event) is created on the source chain.
13+
1. **Send assets:** Transfer ERC20 tokens and other assets between chains.
14+
1. **Execute calls:** Call a contract on a remote chain with specific calldata and value.
15+
With interop, you automatically get an account (a.k.a. `aliasedAccount`) on each chain, which you can control from the source chain.
16+
1. **Execute bundles of calls:** Group multiple remote calls into a single bundle, ensuring all of them execute at once.
17+
1. **Execute transactions:** Create transactions on the source chain, which will automatically get executed on the destination chain,
18+
with options to choose from various cross-chain Paymaster solutions to handle gas fees.
19+
20+
## Enhanced user experience
21+
22+
Interoperability enhances the blockchain user experience by abstracting complex cross-chain interactions.
23+
Users do not need to manually bridge funds to another chain in the Elastic Network if they already have funds on one.
24+
25+
- **Reduced Complexity**: Users interact with a seamless interface that hides the underlying complexities of blockchain operations.
26+
- **Asset Bridging**: Relayers manage the process of bridging assets between chains,
27+
handling the necessary burning and minting of assets as they move across the ecosystem.
28+
- **Lower Fees**: By leveraging efficient relayers and minimizing manual operations,
29+
transaction costs are kept low, akin to standard gas fees within a single chain.
30+
31+
## Real-World Application: Crosschain Transactions
32+
33+
Consider a practical scenario where you want to swap ETH for DAI using a crosschain transaction on a defi platform:
34+
35+
1. **Transaction Initiation**: You initiate the transaction directly from your wallet.
36+
2. **Relayer Involvement**: A relayer picks up your ETH and deposits it into the defi chain.
37+
3. **Asset Swap**: On the defi chain, your ETH is automatically swapped for DAI.
38+
4. **Completion and Return**: The relayer then transfers the DAI back to your original chain.
39+
40+
This entire process is executed as a single transaction, making it feel as seamless as if no chain-switching occurred.
41+
The only difference a user might notice is a slightly longer confirmation time, depending on the specific ZKsync chain used.
42+
43+
![Interop Swap](/images/zk-stack/interop_swap_example.png)
44+
45+
## Transaction Lifecycle
46+
47+
An interop transaction in the Elastic Network follows these steps:
48+
49+
1. **Initiation**: A transaction is initiated on a ZKsync chain, aimed at crossing to another chain within the Elastic Network.
50+
2. **Settlement on L1**: The sending ZKsync chain compiles a cryptographic proof of the transaction and settles it onto Ethereum's Layer 1,
51+
anchoring the transaction's validity.
52+
3. **Transaction Root Update**: Ethereum's Layer 1 updates the Transaction Root, a cumulative record reflecting all
53+
transactions processed across the Elastic Network.
54+
4. **Root Importation**: The receiving ZKsync chain imports this updated Transaction Root through its consensus mechanism,
55+
akin to the way Layer 1 to Layer 2 messages are currently handled.
56+
5. **Transaction Submission**: A relayer submits the transaction along with a Merkle Proof to the receiving ZKsync chain.
57+
This proof connects the transaction to the newly updated Transaction Root.
58+
6. **Verification and Execution**: The receiving ZKsync chain verifies the transaction against the Transaction Root.
59+
If the verification is successful, the transaction is executed, and the relayer is compensated for their service.
60+
7. **Proof Settlement**: Finally, the receiving ZKsync chain settles its proof on L1, conclusively validating the transaction within the Elastic Network.
61+
62+
## Rollout Phases
63+
64+
There are three steps planned for rolling out full interoperability:
65+
66+
1. [Messaging](/zksync-network/unique-features/zksync-connect/messaging)
67+
1. Asset transfers and bundles
68+
1. Crosschain transactions
69+
70+
Currently only messaging is available as a part of the `v29` upgrade.
71+
Only chains that settle on top of [Gateway](/zksync-protocol/gateway/overview) have access to interop messaging.
72+
To see which chains use ZKsync Gateway, check the [Elastic Network Chains](/zksync-network/environment) table.
73+
74+
Limitations for this first state of interop include:
75+
76+
- No support for selecting destination chains
77+
- Lack of nullifiers or replay protection
78+
- No cancellation mechanism
79+
- No support for sending assets or calling contracts
80+
81+
These limitations will be addressed in steps 2 and 3 of full universal interoperability.

‎content/00.zksync-network/30.unique-features/50.zksync-connect/10.messaging.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Messaging
3+
description: Learn about how send and verify messages with ZKsync Connect.
4+
---
5+
6+
Interop messaging marks the first step of universal interoperability for the Elastic Network.
7+
Interop messaging enables sending and verifying messages across ZKsync chains via ZKsync Gateway.
8+
9+
An interop message consists of arbitrary data and has two simple properties:
10+
11+
1. Anyone can send a message.
12+
1. Anyone can verify that a given message was successfully sent on some chain.
13+
14+
One example use case for interop messaging would be to unlock experiences on a chain based on activities on another chain.
15+
16+
For a full step-by-step tutorial for sending and verifying interop messages using `zksync-ethers`,
17+
check out the [interop messages guide](/zksync-network/sdk/js/ethers/guides/interop-messages).
18+
19+
## Sending a message
20+
21+
To send a message, you can call the `sendToL1` function on the `L1Messenger` contract, which is pre-deployed on every ZKsync chain at address `0x00..008008`:
22+
23+
```solidity
24+
:code-import{filePath="hardhat-sol/contracts/InteropSendMessage.sol"}
25+
```
26+
27+
The message itself has no destination chain or address. It’s simply a payload created by a user or contract that gets broadcast.
28+
There is no expiration for when messages can be verified. They remain verifiable indefinitely.
29+
The function name `sendToL1` was kept from previous versions for simplicity, although it does not restrict messages from only being verified on the L1.
30+
31+
These messages are the foundation to unlock more complex crosschain activities in the future,
32+
like bridging assets and operate with contracts across different chains.
33+
34+
### Lifecycle of sending a message
35+
36+
1. **Send a Message:** The message is sent via the `sendToL1` method in the L1Messenger contract.
37+
The naming is leftover from a previous method, but this message first gets sent to Gateway.
38+
1. **Batch created:** The transaction gets included in a batch, which is sent to Gateway.
39+
1. **Chain-batch root added to Gateway Message Root:** The chain-batch root (which includes the log for the message)
40+
is added to Gateway’s global message root.
41+
The `MessageRoot` is a contract that collects messages from different chains and aggregates them into a single Merkle tree.
42+
1. **Event emitted:** ZKsync Gateway’s MessageRoot contract emits an event indicating that the interop root was updated.
43+
1. **Event detected:** EthWatch detects the event from a ZKsync chain, stores it in its database,and includes it in the next batch’s bootloader state.
44+
1. **New Root gets stored:** The bootloader calls the `L2InteropRootStorage` contract to update its stored interop roots.
45+
1. **Dependency verification:** The latest batch’s dependency roots are verified against ZKsync Gateway’s `MessageRoot`.
46+
At this point, the interop root for the batch is confirmed.
47+
48+
## Verifying a message
49+
50+
Messages can be verified using the `proveL2MessageInclusionShared` method
51+
in the L2 message verification contract deployed at `0x..10009` on each ZKsync chain.
52+
53+
```solidity
54+
:code-import{filePath="hardhat-sol/contracts/InteropVerification.sol"}
55+
```
56+
57+
### Lifecycle of verifying a message
58+
59+
1. **Proof Submission:** On any ZKsync chain that uses Gateway, the user calls proveL2MessageInclusionShared
60+
at the `L2_MESSAGE_VERIFICATION_ADDRESS` (`0x..10009`),
61+
supplying the message data and a proof of inclusion.
62+
Note, that this step could be done in the same batch as the dependency verification.
63+
1. Final Verification: The `L2InteropRootStorage` contract is triggered to verify the corresponding
64+
interop root inclusion on the chain where the proof was submitted.
65+
66+
For more detail about how interoperability works at the protocol level,
67+
visit the [protocol specifications](https://matter-labs.github.io/zksync-era/core/latest/specs/contracts/interop/overview.html) documentation.

‎content/00.zksync-network/30.unique-features/50.zksync-connect/_dir.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
title: ZKsync Connect

‎content/00.zksync-network/50.sdk/10.js/01.ethers/04.guides/04.interop-messages.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Interop Messages
3+
description: A guide for sending and verifying interop messages with ZKsync Connect.
4+
---
5+
6+
[ZKsync Connect](/zksync-network/unique-features/zksync-connect) enables sending and verifying messages across ZKsync chains via ZKsync Gateway.
7+
It is the first phase of universal interoperability for the Elastic Network.
8+
9+
An interop message consists of arbitrary data and has two simple properties:
10+
11+
1. Anyone can send a message.
12+
1. Anyone can verify that a given message was successfully sent on some chain.
13+
14+
The message itself has no destination chain or address.
15+
It’s simply a payload created by a user or contract that gets broadcast.
16+
There is no expiration for when messages can be verified.
17+
18+
Messages can only be sent and verified on ZKsync chains that use ZKsync Gateway.
19+
To set up a local multichain testing environment with Gateway, check out the [Running ZKsync Gateway locally guide](/zk-stack/running/gateway-settlement-layer).
20+
To see which testnet and mainnet chains use ZKsync Gateway, check the [Elastic Network Chains](/zksync-network/environment) table.
21+
22+
Before verifying a message, the transaction that the message was sent in must be executed in a batch,
23+
and the interop root must be updated on the target chain.
24+
The full flow for sending and verifying a message looks like this:
25+
26+
1. Send the message.
27+
1. Check that the message transaction is fully executed.
28+
1. Check that the gateway proof is ready.
29+
1. Check that the interop root is updated on the target chain.
30+
1. Verify the message.
31+
32+
## Sending a message
33+
34+
You can use the `InteropClient` along with the `sendMessage` method to send any message.
35+
The method accepts either a string or a `BytesLike` value, and returns the transaction hash.
36+
37+
```ts
38+
:code-import{filePath="hardhat-sol/scripts/interop/send-message.ts"}
39+
```
40+
41+
### Sending a message from a smart contract
42+
43+
To send a message from a smart contract, you can use the `sendToL1` method on the `L1Messenger` contract.
44+
45+
```solidity
46+
:code-import{filePath="hardhat-sol/contracts/InteropSendMessage.sol"}
47+
```
48+
49+
## Checking the execution status
50+
51+
To check the execution status of a message, you can use the `getMessageStatus` method.
52+
In order to verify a message, the status must first be `EXECUTED`.
53+
54+
```ts
55+
:code-import{filePath="hardhat-sol/scripts/interop/check-status.ts"}
56+
```
57+
58+
## Checking if the interop root is updated
59+
60+
In order to verify a message, the interop root must be updated on the target chain.
61+
To check if the interop root is ready, you can use the `getGwBlockForBatch` `waitForGatewayInteropRoot` methods.
62+
63+
```ts
64+
:code-import{filePath="hardhat-sol/scripts/interop/check-interop-root.ts"}
65+
```
66+
67+
## Verifying a Message
68+
69+
You can either verify a message using the SDK or onchain inside a smart contract.
70+
71+
### Offchain Verification
72+
73+
You can verify a message directly using the SDK by calling the `verifyMessage` method on the `InteropClient`.
74+
75+
```ts
76+
:code-import{filePath="hardhat-sol/scripts/interop/verify-message.ts"}
77+
```
78+
79+
To verify a message on a local chain,
80+
you must also send some transactions on the target chain in order to create a new batch so that the interop root gets updated.
81+
You can see an example of this below under "Local chains example".
82+
83+
### Onchain Verification
84+
85+
To verify a message inside a smart contract,
86+
you can fetch the input args for `proveL2MessageInclusionShared` using the `getVerificationArgs` method.
87+
88+
### Testnet example
89+
90+
```ts
91+
:code-import{filePath="hardhat-sol/scripts/interop/get-verification-args.ts"}
92+
```
93+
94+
### Local chains example
95+
96+
To verify a message on a local chain,
97+
you must also send some transactions on the target chain in order to create a new batch so that the interop root gets updated.
98+
You can see an example of this below:
99+
100+
```ts
101+
:code-import{filePath="hardhat-sol/scripts/interop/get-verification-args-local.ts"}
102+
```
103+
104+
### Verifying onchain
105+
106+
Once you have the input args, you can pass them into a contract function as shown in the example below:
107+
108+
#### Onchain verification script
109+
110+
```ts
111+
:code-import{filePath="hardhat-sol/scripts/interop/test-onchain-verification.ts"}
112+
```
113+
114+
#### Smart contract verification
115+
116+
```solidity
117+
:code-import{filePath="hardhat-sol/contracts/InteropVerification.sol"}
118+
```

‎content/10.zk-stack/10.zk-chains.md‎

Lines changed: 1 addition & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -50,47 +50,7 @@ It allows you to:
5050
1. **Execute transactions:** Create transactions on the source chain, which will automatically get executed on the destination chain,
5151
with options to choose from various cross-chain Paymaster solutions to handle gas fees.
5252

53-
### Enhanced user experience
54-
55-
Interoperability enhances the blockchain user experience by abstracting complex cross-chain interactions.
56-
Users do not need to manually bridge funds to another chain in the Elastic Network if they already have funds on one.
57-
58-
- **Reduced Complexity**: Users interact with a seamless interface that hides the underlying complexities of blockchain operations.
59-
- **Asset Bridging**: Relayers manage the process of bridging assets between chains,
60-
handling the necessary burning and minting of assets as they move across the ecosystem.
61-
- **Lower Fees**: By leveraging efficient relayers and minimizing manual operations,
62-
transaction costs are kept low, akin to standard gas fees within a single chain.
63-
64-
#### Real-World Application: Crosschain Transactions
65-
66-
Consider a practical scenario where you want to swap ETH for DAI using a crosschain transaction on a defi platform:
67-
68-
1. **Transaction Initiation**: You initiate the transaction directly from your wallet.
69-
2. **Relayer Involvement**: A relayer picks up your ETH and deposits it into the defi chain.
70-
3. **Asset Swap**: On the defi chain, your ETH is automatically swapped for DAI.
71-
4. **Completion and Return**: The relayer then transfers the DAI back to your original chain.
72-
73-
This entire process is executed as a single transaction, making it feel as seamless as if no chain-switching occurred.
74-
The only difference a user might notice is a slightly longer confirmation time, depending on the specific ZKsync chain used.
75-
76-
![Interop Swap](/images/zk-stack/interop_swap_example.png)
77-
78-
### Transaction Lifecycle
79-
80-
An interop transaction in the Elastic Network follows these steps:
81-
82-
1. **Initiation**: A transaction is initiated on a ZKsync chain, aimed at crossing to another chain within the Elastic Network.
83-
2. **Settlement on L1**: The sending ZKsync chain compiles a cryptographic proof of the transaction and settles it onto Ethereum's Layer 1,
84-
anchoring the transaction's validity.
85-
3. **Transaction Root Update**: Ethereum's Layer 1 updates the Transaction Root, a cumulative record reflecting all
86-
transactions processed across the Elastic Network.
87-
4. **Root Importation**: The receiving ZKsync chain imports this updated Transaction Root through its consensus mechanism,
88-
akin to the way Layer 1 to Layer 2 messages are currently handled.
89-
5. **Transaction Submission**: A relayer submits the transaction along with a Merkle Proof to the receiving ZKsync chain.
90-
This proof connects the transaction to the newly updated Transaction Root.
91-
6. **Verification and Execution**: The receiving ZKsync chain verifies the transaction against the Transaction Root.
92-
If the verification is successful, the transaction is executed, and the relayer is compensated for their service.
93-
7. **Proof Settlement**: Finally, the receiving ZKsync chain settles its proof on L1, conclusively validating the transaction within the Elastic Network.
53+
You can learn more about how interoperability works and how to use it in the [ZKsync Connect](/zksync-network/unique-features/zksync-connect) documentation.
9454

9555
---
9656

0 commit comments

Comments
 (0)