Skip to content

Commit af19afd

Browse files
TurupawnTurupawn
authored
Merge pull request #19 from scroll-tech/develop
update from main
2 parents 572e2f9 + 5f2227f commit af19afd

File tree

1 file changed

+50
-57
lines changed

1 file changed

+50
-57
lines changed

‎src/content/docs/en/developers/l1-and-l2-bridging/the-scroll-messenger.mdx

Lines changed: 50 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -10,99 +10,90 @@ excerpt: "The Scroll Messenger documentation for arbitrary message passing betwe
1010

1111
import Aside from "../../../../../components/Aside.astro"
1212

13-
The Scroll Messenger contracts allow for sending arbitrary messages from L1 to L2 or vice versa. This enables executing functions on another chain in a secure and permissionless way. To send a message from L1 to L2, use
14-
the messenger smart contract deployed on L1, `L1ScrollMessenger`. To send a message from L2 to L1, use the contract deployed on L2, `L2ScrollMessenger`.
15-
16-
<Aside type="caution" title="">
17-
When sending a transaction through the **Scroll Messenger** deployed on L1 and L2, the resulting transaction sender
18-
(`CALLER` or `msg.sender`) will be the Messenger Contract address deployed on the receiving chain.
19-
<br />
20-
In future Scroll versions, enforced transactions from the L1 will allow setting the sender on L2 as the original EOA
21-
on L1. It will also allow 3rd parties to relay signed transactions securely.
22-
</Aside>
13+
The Scroll Messenger contracts allow for sending arbitrary messages from L1 to L2 or vice versa. This enables executing functions on another chain in a secure and permissionless way. To send a message from L1 to L2, use the messenger smart contract deployed on L1, `L1ScrollMessenger`. To send a message from L2 to L1, use the contract deployed on L2, `L2ScrollMessenger`. You can find the smart contract addresses in the [Scroll Contracts](/developers/scroll-contracts) page.
14+
15+
## Sending a Message
16+
17+
Sending a cross-chain message through the `ScrollMessenger` is performed by calling the [`sendMessage`](#sendmessage) function. In this function you set the `target` address that will receive the message in the other chain, a `value` parameter for ETH transfers and `message` byte array to be sent as `CALLDATA` for smart contract execution. Notice the contract also expects a `gasLimit` parameter that you can safely set to `0` and a `refundAddress` which you can set as the sender EOA. These last two parameters are legacy since L1 to L2 transactions don't need to pay gas and L2 to L1 gas costs are handled differently, as we’ll cover in the next section.
2318

24-
## Finalizing transactions on L1
19+
## Relaying Transactions on L1
2520

26-
Any upcoming transactions from L2 need to be finalized using the `relayMessageWithProof` function on the Scroll Messenger
27-
contract. We call this process "submitting an Execute Withdrawal transaction," and it is required for both sending arbitrary messages and transferring assets through a gateway or the router. When you use `relayMessageWithProof`, you'll have to provide a Merkle inclusion proof showing your transaction is included in the trie of "withdrawal" messages, along with other parameters. Producing this proof and these values can be done locally and permissionlessly, but at the moment, the easiest way to retrieve these parameters is through our backend APIs:
21+
Unlike L1 to L2 transactions, L2 to L1 transactions need to be finalized using the [`relayMessageWithProof`](#relaymessagewithproof) function on the Scroll Messenger contract. We call this process "submitting an Execute Withdrawal transaction", and it is required for both sending arbitrary messages and transferring assets through a gateway or the router. When you use `relayMessageWithProof`, you'll have to provide a Merkle inclusion proof showing your transaction is included in the trie of "withdrawal" messages, along with other parameters. Producing this proof and these values can be done locally and permissionlessly, but at the moment, the easiest way to retrieve these parameters is through our backend APIs:
2822

2923
- Scroll Sepolia API: https://sepolia-api-bridge-v2.scroll.io/api/
3024
- Scroll API: https://mainnet-api-bridge-v2.scroll.io/api/
3125

32-
<Aside type="danger" title="Experimental API">
33-
This API was made for our Bridge UI. It is not yet finalized and may change in the future. We will update this guide
34-
when the API is finalized. Additionally, all examples below use the Sepolia API service -- the calls should be easily
35-
adapted to work on mainnet.
36-
</Aside>
37-
38-
Supply the address of the EOA or contract responsible for initiating the original transaction on L2 to the `/claimable`
39-
endpoint. The API backend will provide you with all the necessary information to successfully conclude the transaction on L1.
40-
Take a look at the following example:
26+
Supply the address of the EOA or contract responsible for initiating the original transaction on L2 to the `/unclaimed` endpoint. The API backend will provide you with all the necessary information to successfully conclude the transaction on L1. Take a look at the following example:
4127

4228
```bash
43-
https://sepolia-api-bridge.scroll.io/api/claimable?address=0x031407eaaffFB4f1EC2c999bE4477E52C81de3c5&page_size=10&page=1
29+
https://sepolia-api-bridge-v2.scroll.io/api/l2/unclaimed/withdrawals?address=0x031407eaaffFB4f1EC2c999bE4477E52C81de3c5&page=1&page_size=10
4430
```
4531

32+
<Aside type="caution" title="The address parameter">
33+
The `address` parameter on the `/withdrawals` endpoint expects the sender EOA or contract address in the case sensitive [EIP-55 Mixed-cased Checksum](https://eips.ethereum.org/EIPS/eip-55) format.
34+
</Aside>
35+
4636
The API should return your transaction data in the following format:
4737

4838
```json
4939
{
5040
"errcode": 0,
5141
"errmsg": "",
5242
"data": {
53-
"result": [
43+
"results": [
5444
{
55-
"hash": "0xa476850306d6ee52b127628ded34dcf2343570873cce9c5383bd497db48d4f9b",
56-
"amount": "",
57-
"to": "",
58-
"isL1": false,
59-
"l1Token": "",
60-
"l2Token": "",
61-
"blockNumber": 748,
62-
"blockTimestamp": null,
63-
"finalizeTx": {
45+
"hash": "0xd56f873c953e798521020d8b6885e7509069fcf0e12bdb1227b840c2d29c6645",
46+
"replay_tx_hash": "",
47+
"refund_tx_hash": "",
48+
"message_hash": "0x65f7d787ff0a3fe7f42b603650afc9c0906f44cd913d52a9e37d1defbe526b6e",
49+
"token_type": 1,
50+
"token_ids": [],
51+
"token_amounts": [
52+
"0"
53+
],
54+
"message_type": 2,
55+
"l1_token_address": "",
56+
"l2_token_address": "",
57+
"block_number": 11517097,
58+
"tx_status": 0,
59+
"counterpart_chain_tx": {
6460
"hash": "",
65-
"amount": "",
66-
"to": "",
67-
"isL1": false,
68-
"blockNumber": 0,
69-
"blockTimestamp": null
61+
"block_number": 0
7062
},
71-
"claimInfo": {
72-
"from": "0x031407eaaffFB4f1EC2c999bE4477E52C81de3c5",
73-
"to": "0x1039057185CFe192d16c03F5656225821A193FD5",
63+
"claim_info": {
64+
"from": "0x707e55a12557E89915D121932F83dEeEf09E5d70",
65+
"to": "0xC96dde523FB7aB544DCe99F78C10272502452Ae7",
7466
"value": "0",
75-
"nonce": "9",
76-
"batch_hash": "0x49a18d72dbceeb957f918947b532db452c031f528e7e6bf329007066638c5e50",
77-
"message": "0xa413686200000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000005686f6c6973000000000000000000000000000000000000000000000000000000",
78-
"proof": "0x69b4ee6cf9a38bed79668ddd347fef2bdff44c3760c9309fa41decfd60202d22ad3228b676f7d3cd4284a5443f17f1962b36e491b30a40b2405849e597ba5fb5b4c11951957c6f8f642c4af61cd6b24640fec6dc7fc607ee8206a99e92410d3079f53171df5c0661d2afe86c4d97b6f34278daf6a0ea9baff5b4fc979d5629a5",
79-
"batch_index": "93"
67+
"nonce": "388896",
68+
"message": "0x32e43a11",
69+
"proof": {
70+
"batch_index": "113627",
71+
"merkle_proof": "0x595e51b1e616792354ed5337d73ab55e8cb62fec3d5b9254e0c5549a6359e07cad3228b676f7d3cd4284a5443f17f1962b36e491b30a40b2405849e597ba5fb5b4c11951957c6f8f642c4af61cd6b24640fec6dc7fc607ee8206a99e92410d3021ddb9a356815c3fac1026b6dec5df3124afbadb485c9ba5a3e3398a04b7ba85e58769b32a1beaf1ea27375a44095a0d1fb664ce2dd358e7fcbfb78c26a19344572901eb2c02c80041fe5b5524ab76baafbca7c7bcad9fcbd8a8f492f14ccfeb887c22bd8750d34016ac3c66b5ff102dacdd73f6b014e710b51e8022af9a1968ffd70157e48063fc33c97a050f7f640233bf646cc98d9524c6b92bcf3ab56f83936fdf2b4de30e14ed4e80b8ad6789e4da1c12dc0da39b4a0d87faf93f62b6843fb096223ed1df0ad0a5e4ad87b3bbeca3ec02bbd30b173a9e8bb06f6cdbdb0f5b57c8b6a31abc39d2ac02c6c49d65e06bd47bdc87a4c26f9e37d04aaa134438cb3e31fffb058537dac499fbd1fad3548af7ccc35028cebfb875e1541f37d5a53490c6ceeb450aecdc82e28293031d10c7d73bf85e57bf041a97360aa2c5d99c4c1bd797081f10d69a340d28e20e54bae159d5eddb976c97b3193a8bd5a38e8afc715bd0872994d0083b471117d24f5be50dd072551f0d41ffe8137346039d94d98dc6e569c87f338c68fa23139bafe238eb1308610d4a9b148fc1955128d4ce7874b09783cef2e7750f7ea24f6090c9ce47f33cf25ca5e16a1207b4a50fda2be1d3b5c807b281e4683cc6d6315cf95b9ade8641defcb32372f1c126e398ef7a1ef973d30ca636d922d10ae577c73bc4fe92699225f30c0c2e9d6727bceb256d"
72+
},
73+
"claimable": true
8074
},
81-
"createdTime": null
75+
"block_timestamp": 1755015985,
76+
"batch_deposit_fee": ""
8277
}
8378
],
8479
"total": 1
8580
}
8681
}
8782
```
8883

89-
The `claimInfo` object under the `result` json returned has all the information needed to execute your transaction on L1. The
90-
parameters needed by the `relayMessageWithProof` are: `from`, `to`, `value`, `nonce`, `message` and `proof`. Supply these to
91-
the `relayMessageWithProof` function on L1 to execute and finalize your transaction on L1.
84+
When the transaction finalizes on L1, `claim_info` object under the `result` json returned will have all the information needed to execute your transaction on L1. The
85+
parameters needed by the `relayMessageWithProof` are: `from`, `to`, `value`, `nonce`, `message` and `proof`. Supply these to the `relayMessageWithProof` function on L1 to execute and finalize your transaction on L1.
9286

9387
<Aside type="tip" title="">
94-
All L2 transactions are bundled into batches – you have to wait for the batch that includes your transaction to
95-
finalize before calling `relayMessageWithProof`. Your transaction batch index is returned in the `batch_index` value
96-
on the `/claimable` endpoint, and you can follow the progress on the [Scroll Rollup
97-
Explorer](https://scroll.io/rollupscan?page=1&per_page=10).
88+
All L2 transactions are bundled into batches, you have to wait for the batch that includes your transaction to finalize before calling `relayMessageWithProof`. Your transaction batch index is returned in the `batch_index` value on the `/unclaimed` endpoint, and you can follow the progress on the [Scroll Rollup Explorer](https://scroll.io/rollupscan?page=1&per_page=10).
9889
</Aside>
9990

10091
## Messenger API
10192

102-
Please visit the [npm library](https://www.npmjs.com/package/@scroll-tech/contracts?activeTab=code) for the complete Scroll contract API documentation.
103-
10493
### sendMessage
10594

95+
See implementation at [L2ScrollMessenger on Github](https://github.com/scroll-tech/scroll-contracts/blob/main/src/L2/L2ScrollMessenger.sol).
96+
10697
```solidity
10798
function sendMessage(
10899
address target,
@@ -125,6 +116,8 @@ Sends arbitrary data from one chain to another. It allows us to execute function
125116

126117
### relayMessageWithProof
127118

119+
See implementation at [L1ScrollMessenger on Github](https://github.com/scroll-tech/scroll-contracts/blob/main/src/L1/L1ScrollMessenger.sol).
120+
128121
```solidity
129122
function relayMessageWithProof(
130123
address from,
@@ -136,7 +129,7 @@ function relayMessageWithProof(
136129
) external;
137130
```
138131

139-
Relay a L2 => L1 message with message proof.
132+
Execute a L2 to L1 message with message proof.
140133

141134
| Parameter | Description |
142135
| --------- | ------------------------------------------------------------ |

0 commit comments

Comments
 (0)