You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/specs/interop/interoptransactions.md
+65-42Lines changed: 65 additions & 42 deletions
Original file line number
Diff line number
Diff line change
@@ -2,30 +2,37 @@
2
2
3
3
## Basics
4
4
5
-
The **InteropTransaction** sits at the top of our interop stack, acting as the “delivery” mechanism for **Interop Bundles**.
5
+
The **InteropTransaction** sits at the top of our interop stack, acting as the “delivery” mechanism for **Interop
6
+
Bundles**.
6
7
7
8
Think of it like a car that picks up our "hitchhiker" bundles and carries them to their destination.
8
9
9
10
10
11
11
-
**Note:** Interop Transactions aren’t the only way to execute a bundle. Once an interop bundle is created on the source chain, users can simply send a regular transaction on the destination chain to execute it.
12
+
**Note:** Interop Transactions aren’t the only way to execute a bundle. Once an interop bundle is created on the source
13
+
chain, users can simply send a regular transaction on the destination chain to execute it.
12
14
13
-
However, this approach can be inconvenient as it requires users to have funds on the destination chain to cover gas fees and to configure the necessary network settings (like the RPC address).
15
+
However, this approach can be inconvenient as it requires users to have funds on the destination chain to cover gas fees
16
+
and to configure the necessary network settings (like the RPC address).
14
17
15
-
**InteropTransactions** simplify this process by handling everything from the source chain. They allow you to select which **interopBundle** to execute, specify gas details (such as gas amount and gas price), and determine who will cover the gas costs. This can be achieved using tokens on the source chain or through a paymaster.
18
+
**InteropTransactions** simplify this process by handling everything from the source chain. They allow you to select
19
+
which **interopBundle** to execute, specify gas details (such as gas amount and gas price), and determine who will cover
20
+
the gas costs. This can be achieved using tokens on the source chain or through a paymaster.
16
21
17
-
Once configured, the transaction will automatically execute, either by the chain operator, the gateway, or off-chain tools.
22
+
Once configured, the transaction will automatically execute, either by the chain operator, the gateway, or off-chain
23
+
tools.
18
24
19
25
An **InteropTransaction** contains two pointers to bundles:
20
26
21
-
-**feesBundle**: Holds interop calls to cover fees.
22
-
-**bundleHash**: Contains the main execution.
27
+
-**feesBundle**: Holds interop calls to cover fees.
28
+
-**bundleHash**: Contains the main execution.
23
29
24
30
25
31
26
32
## Interface
27
33
28
-
The function `sendInteropTransaction` provides all the options. For simpler use cases, refer to the helper methods defined later in the article.
34
+
The function `sendInteropTransaction` provides all the options. For simpler use cases, refer to the helper methods
35
+
defined later in the article.
29
36
30
37
```solidity
31
38
contract InteropCenter {
@@ -57,60 +64,70 @@ contract InteropCenter {
57
64
}
58
65
```
59
66
60
-
After creating the **InteropBundle**, you can simply call `sendInteropTransaction` to create the complete transaction that will execute the bundle.
67
+
After creating the **InteropBundle**, you can simply call `sendInteropTransaction` to create the complete transaction
68
+
that will execute the bundle.
61
69
62
70
## Retries
63
71
64
-
If your transaction fails to execute the bundle (e.g., due to a low gas limit) or isn’t included at all (e.g., due to too low gasPrice), you can send another transaction to **attempt to execute the same bundle again**.
72
+
If your transaction fails to execute the bundle (e.g., due to a low gas limit) or isn’t included at all (e.g., due to
73
+
too low gasPrice), you can send another transaction to **attempt to execute the same bundle again**.
65
74
66
75
Simply call `sendInteropTransaction` again with updated gas settings.
67
76
68
-
69
77
### Example of Retrying
70
78
71
-
Here’s a concrete example: Suppose you created a bundle to perform a swap that includes transferring 100 ETH, executing the swap, and transferring some tokens back.
79
+
Here’s a concrete example: Suppose you created a bundle to perform a swap that includes transferring 100 ETH, executing
80
+
the swap, and transferring some tokens back.
72
81
73
-
You attempted to send the interop transaction with a low gas limit (e.g., 100). Since you didn’t have any base tokens on the destination chain, you created a separate bundle to transfer a small fee (e.g., 0.0001) to cover the gas.
82
+
You attempted to send the interop transaction with a low gas limit (e.g., 100). Since you didn’t have any base tokens on
83
+
the destination chain, you created a separate bundle to transfer a small fee (e.g., 0.0001) to cover the gas.
74
84
75
-
You sent your first interop transaction to the destination chain, but it failed due to insufficient gas. However, your “fee bundle” was successfully executed, as it covered the gas cost for the failed attempt.
85
+
You sent your first interop transaction to the destination chain, but it failed due to insufficient gas. However, your
86
+
“fee bundle” was successfully executed, as it covered the gas cost for the failed attempt.
76
87
77
88
Now, you have two options: either cancel the execution bundle (the one with 100 ETH) or retry.
78
89
79
-
To retry, you decide to set a higher gas limit (e.g., 10,000) and create another fee transfer (e.g., 0.01) but use **the same execution bundle** as before.
90
+
To retry, you decide to set a higher gas limit (e.g., 10,000) and create another fee transfer (e.g., 0.01) but use **the
91
+
same execution bundle** as before.
80
92
81
-
This time, the transaction succeeds — the swap completes on the destination chain, and the resulting tokens are successfully transferred back to the source chain.
93
+
This time, the transaction succeeds — the swap completes on the destination chain, and the resulting tokens are
94
+
successfully transferred back to the source chain.
82
95
83
96
84
97
85
98
## Fees & Restrictions
86
99
87
-
Using an **InteropBundle** for fee payments offers flexibility, allowing users to transfer a small amount to cover the fees while keeping the main assets in the execution bundle itself.
100
+
Using an **InteropBundle** for fee payments offers flexibility, allowing users to transfer a small amount to cover the
101
+
fees while keeping the main assets in the execution bundle itself.
88
102
89
103
### Restrictions
90
104
91
-
This flexibility comes with trade-offs, similar to the validation phases in **Account Abstraction** or **ERC4337**, primarily designed to prevent DoS attacks. Key restrictions include:
105
+
This flexibility comes with trade-offs, similar to the validation phases in **Account Abstraction** or **ERC4337**,
106
+
primarily designed to prevent DoS attacks. Key restrictions include:
92
107
93
-
-**Lower gas limits**
108
+
-**Lower gas limits**
94
109
-**Limited access to specific slots**
95
110
96
-
Additionally, when the `INTEROP_CENTER` constructs an **InteropTransaction**, it enforces extra restrictions on **feePaymentBundles**:
111
+
Additionally, when the `INTEROP_CENTER` constructs an **InteropTransaction**, it enforces extra restrictions on
112
+
**feePaymentBundles**:
97
113
98
114
-**Restricted Executors**:
99
-
Only your **AliasedAccount** on the receiving side can execute the `feePaymentBundle`.
100
-
101
-
This restriction is crucial for security, preventing others from executing your **fee bundle**, which could cause your transaction to fail and prevent the **execution bundle** from processing.
102
-
115
+
Only your **AliasedAccount** on the receiving side can execute the `feePaymentBundle`.
103
116
117
+
This restriction is crucial for security, preventing others from executing your **fee bundle**, which could cause your
118
+
transaction to fail and prevent the **execution bundle** from processing.
104
119
105
120
### **Types of Fees**
106
121
107
122
#### Using the Destination Chain’s Base Token
108
123
109
-
The simplest scenario is when you (as the sender) already have the destination chain’s base token available on the source chain.
124
+
The simplest scenario is when you (as the sender) already have the destination chain’s base token available on the
125
+
source chain.
110
126
111
127
For example:
112
128
113
-
- If you are sending a transaction from **Era** (base token: ETH) to **Sophon** (base token: SOPH) and already have SOPH on ERA, you can use it for the fee.
129
+
- If you are sending a transaction from **Era** (base token: ETH) to **Sophon** (base token: SOPH) and already have SOPH
130
+
on ERA, you can use it for the fee.
114
131
115
132
To make this easier, we’ll provide a helper function:
116
133
@@ -130,44 +147,50 @@ contract InteropCenter {
130
147
131
148
#### Using paymaster on the destination chain
132
149
133
-
If you don’t have the base token from the destination chain (e.g., SOPH in our example) on your source chain, you’ll need to use a paymaster on the destination chain instead.
150
+
If you don’t have the base token from the destination chain (e.g., SOPH in our example) on your source chain, you’ll
151
+
need to use a paymaster on the destination chain instead.
134
152
135
-
In this case, you’ll send the token you do have (e.g., USDC) to the destination chain as part of the **feeBundleHash**. Once there, you’ll use it to pay the paymaster on the destination chain to cover your gas fees.
153
+
In this case, you’ll send the token you do have (e.g., USDC) to the destination chain as part of the **feeBundleHash**.
154
+
Once there, you’ll use it to pay the paymaster on the destination chain to cover your gas fees.
136
155
137
156
Your **InteropTransaction** would look like this:
138
157
139
158
140
159
141
160
## **Automatic Execution**
142
161
143
-
One of the main advantages of **InteropTransactions** is that they execute automatically. As the sender on the source chain, you don’t need to worry about technical details like RPC addresses or obtaining proofs — it’s all handled for you.
162
+
One of the main advantages of **InteropTransactions** is that they execute automatically. As the sender on the source
163
+
chain, you don’t need to worry about technical details like RPC addresses or obtaining proofs — it’s all handled for
164
+
you.
144
165
145
-
After creating an **InteropTransaction**, it can be relayed to the destination chain by anyone. The transaction already includes a signature (also known as an interop message proof), making it fully self-contained and ready to send without requiring additional permissions.
166
+
After creating an **InteropTransaction**, it can be relayed to the destination chain by anyone. The transaction already
167
+
includes a signature (also known as an interop message proof), making it fully self-contained and ready to send without
168
+
requiring additional permissions.
146
169
147
-
Typically, the destination chain’s operator will handle and include incoming **InteropTransactions**. However, if they don’t, the **Gateway** or other participants can step in to prepare and send them.
170
+
Typically, the destination chain’s operator will handle and include incoming **InteropTransactions**. However, if they
171
+
don’t, the **Gateway** or other participants can step in to prepare and send them.
148
172
149
-
You can also use the available tools to create and send the destination transaction yourself. Since the transaction is self-contained, it doesn’t require additional funds or signatures to execute.
173
+
You can also use the available tools to create and send the destination transaction yourself. Since the transaction is
174
+
self-contained, it doesn’t require additional funds or signatures to execute.
150
175
151
176
152
177
153
-
Once they see the message, they can request the proof from the **Gateway** and also fetch the **InteropBundles** contained within the message (along with their respective proofs).
178
+
Once they see the message, they can request the proof from the **Gateway** and also fetch the **InteropBundles**
179
+
contained within the message (along with their respective proofs).
154
180
155
181
156
182
157
-
As the final step, the operator can use the received data to create a regular transaction, which can then be sent to their chain.
158
-
183
+
As the final step, the operator can use the received data to create a regular transaction, which can then be sent to
184
+
their chain.
159
185
160
186
161
187
162
188
The steps above don’t require any special permissions and can be executed by anyone.
163
189
164
-
While the **Gateway** was used above for tasks like providing proofs, if the Gateway becomes malicious, all this information can still be constructed off-chain using data available on L1.
165
-
190
+
While the **Gateway** was used above for tasks like providing proofs, if the Gateway becomes malicious, all this
191
+
information can still be constructed off-chain using data available on L1.
166
192
167
193
### How it Works Under the hood
168
194
169
-
We’ll modify the default account to accept interop proofs as signatures, seamlessly integrating with the existing ZKSync native **Account Abstraction** model.
170
-
171
-
172
-
173
-
195
+
We’ll modify the default account to accept interop proofs as signatures, seamlessly integrating with the existing ZKSync
0 commit comments