The Wischain Messenger

The Wischain Messenger contracts facilitate the secure transfer of arbitrary messages between Layer 1 (L1) and Layer 2 (L2) networks, enabling the execution of functions across different chains in a decentralized manner. To send a message from L1 to L2, you utilize the Wischain messenger smart contract deployed on L1, known as L1WischainMessenger. Conversely, to transmit a message from L2 to L1, the corresponding contract deployed on L2, L2WischainMessenger, should be used.

When transactions are executed via the Wischain Messenger contracts on either chain, the resulting transaction sender (CALLER or msg.sender) will be the address of the Messenger Contract on the receiving chain.

In future iterations of the Wischain protocol, transactions initiated from L1 will allow the sender on L2 to be set as the original Externally Owned Account (EOA) on L1. Additionally, this will enable third parties to securely relay signed transactions.

Finalizing Transactions on L1

For any transactions originating from L2, finalization is accomplished using the relayMessageWithProof function in the Wischain Messenger contract. This process, termed “submitting an Execute Withdrawal transaction,” is essential for both sending arbitrary messages and transferring assets through gateways or routers.

When using relayMessageWithProof, you must provide a Merkle inclusion proof that confirms your transaction is part of the trie of “withdrawal” messages, along with other required parameters. While generating this proof and the associated values can be done locally and without permission, the easiest method to obtain these parameters currently is through our backend APIs:

• Wischain Sepolia API: https://sepolia-api-bridge-v2.wischain.io/api/

• Wischain Mainnet API: https://mainnet-api-bridge-v2.wischain.io/api/

• Experimental API: This API is designed for our Bridge UI and is still under development; therefore, it may undergo changes in the future. We will update the documentation as the API stabilizes.

Claiming Transactions on L1

To initiate the claim process, provide the address of the EOA or contract responsible for the original transaction on L2 to the /claimable endpoint. The API will then return all the information necessary to complete the transaction on L1. Here’s an example call:

GET https://sepolia-api-bridge.wischain.io/api/claimable?address=0x....&page_size=10&page=1

The API response will include transaction data in the following format:

{
  "errcode": 0,
  "errmsg": "",
  "data": {
    "result": [
      {
        "hash": "0x................",
        "amount": "",
        "to": "",
        "isL1": false,
        "l1Token": "",
        "l2Token": "",
        "blockNumber": 748,
        "blockTimestamp": null,
        "finalizeTx": {
          "hash": "",
          "amount": "",
          "to": "",
          "isL1": false,
          "blockNumber": 0,
          "blockTimestamp": null
        },
        "claimInfo": {
          "from": "0x..........",
          "to": "0x.........",
          "value": "0",
          "nonce": "9",
          "batch_hash": "0x...........",
          "message": "0x..............",
          "proof": "0x.............",
          "batch_index": "93"
        },
        "createdTime": null
      }
    ],
    "total": 1
  }
}

The claimInfo object within the returned JSON contains all necessary parameters to execute the transaction on L1, including from, to, value, nonce, message, and proof. You will need to supply these values to the relayMessageWithProof function on L1 to finalize the transaction.

It's essential to note that all L2 transactions are grouped into batches. You must wait for the batch containing your transaction to finalize before invoking relayMessageWithProof. The batch_index returned by the /claimable endpoint allows you to track your transaction's progress via the Wischain Rollup Explorer.

Messenger API Functions

For developers, the Wischain Messenger API provides two key functions:

sendMessage:

function sendMessage(
  address target,
  uint256 value,
  bytes calldata message,
  uint256 gasLimit,
  address refundAddress
) external payable;

This function facilitates the transmission of arbitrary data from one chain to another, allowing for cross-chain function execution.

• Parameters:

  • target: The address of the recipient, which can be either an EOA or a smart contract.

  • value: The amount of Ether sent when calling the target contract.

  • message: The arbitrary calldata to be executed.

  • gasLimit: The gas limit necessary for completing the message relay on the respective chain.

  • refundAddress: The address to which any refunded fees will be sent.

relayMessageWithProof:

function relayMessageWithProof(
  address from,
  address to,
  uint256 value,
  uint256 nonce,
  bytes memory message,
  L2MessageProof memory proof
) external;

This function relays messages from L2 to L1 while ensuring the correctness of the transaction through proof verification.

• Parameters:

  • from: The address of the message sender.

  • to: The address of the message recipient.

  • value: The Ether amount passed along with the message.

  • nonce: A nonce to prevent replay attacks.

  • message: The content of the message being relayed.

  • proof: The proof that verifies the validity of the transaction.

By leveraging the Wischain Messenger and its associated APIs, developers can ensure seamless and secure communication between L1 and L2, enabling a robust multi-chain environment.