L1 ↔ L2 messaging

​

Overview

• The send_message_to_L1 syscall
• The Starknet Core contract’s sendMessageToL2 function
• L1-L2 Messaging in the Cairo Book

​

L2 → L1 messages

​

L2 → L1 message protocol

1. During the execution of a transaction, a contract on Starknet sends a message from L2 to L1 by calling the send_message_to_L1 syscall.
2. The sequencer attaches the message parameters to the block that includes the syscall invocation. The message parameters include the address of the sender on L2, the address of the recipient contract on L1, and the message data. For example:
   Copy

   Ask AI

   let mut payload: Array<felt252> = ArrayTrait::new();
   let to_address: EthAddress = 1_felt252.try_into().unwrap();
   payload.append(1);
   // potentially add more elements to payload (payload[1], payload[2],  etc.)
   
   send_message_to_l1_syscall(to_address: to_address.into(), payload: payload.span());
   
   

3. The prover proves the state update that includes this transaction.
4. The sequencer updates the L1 state.
5. The message is stored on L1 in the Starknet Core Contract and a counter on the Core Contract increases by one.
6. The processMessage function, which is part of the Starknet Core Contract, emits the LogMessageToL1 event, which contains the message parameters.
7. The message recipient on L1 can access and consume the message by calling the consumeMessageFromL2 function, which includes the message parameters within the transaction. This function, which is part of the Starknet Core Contract, verifies the following:
   • The hashes of the L2 sent message parameters, now stored on the Core Contract, and the L1 received message parameters, are the same.
   • The entity calling the function is indeed the recipient on L1. In such a case, the counter corresponding to the message hash in the Starknet Core Contract decreases by one. For more information, see the consumeMessageFromL2 function in StarknetMessaging.sol.

L2→L1 message mechanism

​

L2 → L1 message structure

​

L2 → L1 message hashing

keccak256(
    abi.encodePacked(
        FromAddress,
        uint256(ToAddress),
        Payload.length,
        Payload
    )
);

​

L1 → L2 messages

​

L1 → L2 message protocol

1. An L1 contract induces a message to an L2 contract on Starknet by calling the sendMessageToL2 function on the Starknet Core Contract with the message parameters. The Starknet Core Contract hashes the message parameters and updates the L1→L2 message mapping to indicate that a message with this hash was indeed sent. The L1 contract records the fee that the sender paid. For more information, see L1 → L2 message fees.
2. The message is then decoded into a Starknet transaction that invokes a function annotated with the l1_handler decorator on the target contract. Transactions like this on L2 are called L1 handler transactions.
   1. The Starknet sequencer, upon receiving enough L1 confirmations for the transaction that sent the message, initiates the corresponding L2 transaction.
   2. The L2 transaction invokes the relevant l1_handler function.
3. The L1 Handler transaction that was created in the previous step is added to a proof.
4. The Core Contract receives the state update.
5. The message is cleared from the Core Contract’s storage to consume the message. Clearing the Core Contract’s storage does the following:
   • incurs a fixed cost of 5,000 L1 gas
   • emits an L1 event logging the message consumption

• L1 sender’s address
• L2 recipient’s contract address
• Function selector
• Calldata array
• Message nonce
  The message nonce is maintained on the Starknet Core Contract on L1, and is incremented whenever a message is sent to L2. The nonce is used to avoid a hash collision between different L1 handler transactions that is caused by the same message being sent on L1 multiple times. For more information, see L1→L2 structure.

​

L1 → L2 message structure

​

L1 → L2 message hashing

keccak256(
    abi.encodePacked(
        uint256(FromAddress),
        ToAddress,
        Nonce,
        Selector,
        Payload.length,
        Payload
    )
);

​

L1 → L2 message cancellation

1. The user that initiated the L1→L2 message calls the startL1ToL2MessageCancellation function in the Starknet Core Contract.
2. The user waits five days until she can finalize the cancellation.
3. The user calls the cancelL1ToL2Message function.

​

L1 → L2 message fees

​

L1 handler transaction

​

Transaction fields

​

Hash calculation

l1_handler_tx_hash = h(
    "l1_handler",
    version,
    contract_address,
    entry_point_selector,
    h(calldata),
    0,
    chain_id,
    nonce
)

• l1_handler is a constant prefix, encoded in bytes (ASCII), as big-endian.
• version is the transaction version. Only version 0 is currently supported.
• chain_id is a constant value that specifies the network to which this transaction is sent.
• h is the Pedersen hash (note that since we’re hashing an array, the # of inputs needs to be appended to the hash).
• 0 indicates that L1 to L2 message fees are charged on L1.

​

Caveats and limitations

• Since L1 handler transactions are not initiated by an account, invoking get_caller_address or similar account-related functions returns the address 0x0.
• Starting from Starknet version 0.14.0:
  • L1 handlers that fail execution will appear in a block as REVERTED, instead of only be written in the feeder gateway’s database as REJECTED. The purpose of this change is to simplify the tracking of messages L1 → L2, and the implementation of getMessageStatus in particular.
  • The l1_gas, l2_gas, and l1_data_gas execution resources of L1 handlers will be bounded as follows:
    • l2_gas will bounded by $10^{8}$ (the same as __validate__’s)
    • l1_gas and l1_data_gas will be bounded by $4 * 10^{4}$ and $2 * 10^{4}$, respectively (to allow for sending one L2 → L1 message)

​

Supported versions